Skip to content
v0.1.0
IntroductionMeet the engine, its two packages, and the requirements for running GPU particles.Quick startCreate an effect, bind its artwork, and add particles to your Pixi stage.Configuration guideUnderstand effect fields, defaults, and their live experiments.Pixi textures & animationBind artwork and configure flipbooks in the Pixi integration.How effects workUnderstand emitters, coordinate spaces, playback, and the simulation lifecycle.CurvesShape properties over time and understand the clocks and units behind each value.DevelopmentSet up the repository, run the site and examples, and check your changes.Particle architectureUnderstand shader generation, particle storage, and resource ownership.OverviewAPI reference@reparticle/coreAPI referenceCurveAPI referenceCURVE_SEGMENTSAPI referenceCurvePointAPI referenceEffectConfigAPI referenceeffectConfigSchemaAPI referenceEffectInputAPI referenceEffectTransformAPI referenceEmitterAPI referenceEmitterConfigAPI referenceemitterConfigSchemaAPI referenceEmitterContextAPI referenceEmitterInputAPI referenceEmitterParametersAPI referenceEmitterPlaybackAPI referenceEmitterStateAPI referenceEmitterStateChangeAPI referenceEmitterStateListenerAPI referenceModifierConfigAPI referenceparseEffectConfigAPI referenceParticleBlendModeAPI referenceParticleLifetimeVisitorAPI referenceParticleSlotsAPI referenceParticleTintAPI referenceprewarmAPI referencepropertyVariationAPI referenceRenderingConfigAPI referenceRenderingInputAPI referencerenderingSchemaAPI referencesampleCurveAPI referenceSampledCurveAPI referenceScalarPropertyAPI referenceSpawnRateAPI referenceSpawnScheduleAPI referenceStopOptionsAPI referenceTransformAPI reference@reparticle/pixiAPI referenceAnimationFramesAPI referenceAnimationPlaybackAPI referenceAnimationSizeAPI referenceEffectInputAPI referenceEmitterParametersAPI referenceParticleBlendModeAPI referenceParticleEffectAPI referenceParticleEffectOptionsAPI referenceParticlePivotAPI referenceParticleRenderingAPI referenceParticleSizeModeAPI referenceParticleStateChangeAPI referenceParticleStateListenerAPI referenceParticleTextureAPI referenceParticleTintAPI referenceRenderingConfigAPI referencevalidateAnimationFramesAPI referenceEmitter: IdUnique emitter identifier within this effect. Use it to look up the emitter and bind its artwork. Renaming it does not change motion.Emitter: CapacityMaximum simultaneous particles for this emitter. When all slots are occupied, excess births are dropped and living particles are preserved. Try 64 to see the stream run out of free slots.Emitter: SeedDeterministic random seed. The same definition and playback steps reproduce the same variation. Changing the seed changes the pattern, not the configured ranges.Playback: PlaybackEmission cycle mode, duration, and duration spread. Once emits for one cycle; loop repeats. Restart to observe randomized cycle timing.Playback: Start DelayDelay before emission starts, with random variation around that delay. Restart to observe the timing.Playback: Start OffsetPrewarm the effect by advancing simulation before displaying its first frame. This performs real simulation work in fixed 1/60-second steps. Compare zero with two seconds.Transform: TransformEmitter position, rotation, and uniform scale relative to the effect. Adjust these together to place and size the emitter.Transform: SpaceWorld particles stay behind when the effect moves. Local particles follow its transform. The experiment moves the whole effect so the difference is visible.Transform: Inherit VelocityAmount of emitter movement velocity added to newborn particles. Zero adds none; one inherits the full measured velocity. Existing particles keep their own motion.Appearance: OrientationChoose fixed rotation, alignment with the initial direction, alignment with current movement, or integrated angular velocity. The rectangular artwork makes the orientation visible.Appearance: Stretch With VelocityScale Y stretch by particle speed, using a fixed 60 FPS shutter factor. It needs nonzero stretchY; it does not stretch particles by itself.Emission: RateBirths requested per second and their random rate spread. Capacity limits how many particles can stay alive. Changing spread restarts playback; numeric rate changes apply live.Emission: ShapeSpawn from a point, a filled circle, a box, or a 2D cone. Each shape has its own valid fields. Change the JSON type and dimensions together.Emission: Shape typeSelect the shape. Point has no dimensions; circle uses diameter; box and cone2d use width and height. The preview supplies dimensions for the selected shape.Emission: Shape diameterCircle diameter and its random variation. Births sample the filled circle; each dimension accepts a constant or an emitter-lifetime curve.Initial properties: DirectionPoint-emitter direction and the full angular spread around it, in radians. Zero spread produces a straight stream; 2π distributes directions all around.Rendering: RenderingBlend mode controls how particles combine with the scene: normal, add, multiply, or screen. Tint applies emitter-wide red, green, blue, and alpha multipliers. One leaves a channel unchanged; zero removes it. Changes affect existing particles immediately.Effect: VersionConfiguration format version. The current schema accepts only 1. This is a compatibility marker, not a visual setting.Effect: EmittersNonempty list of emitters. Each must have a unique ID, capacity, seed, emission settings, and required initial values. Add another emitter to combine effects.Emission: Shape dimensionsWidth and height of a box or cone emitter, with independent spread for each dimension. Constants and emitter-lifetime curves are supported. This experiment uses a box.Initial properties: LifetimeSeconds each particle remains alive. Longer lifetimes require more capacity at the same emission rate. Accepts a number or a curve sampled at birth using normalized emitter lifetime. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Initial properties: SpeedInitial velocity magnitude. Changing it affects new particles; modifiers change velocity afterward. Accepts a number or a curve sampled at birth using normalized emitter lifetime. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Initial properties: SizeParticle size in manual texture sizing mode. Initial size is multiplied by overLifetime.scale. Accepts a number or a curve sampled at birth using normalized emitter lifetime. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Initial properties: RotationInitial particle rotation. Positive angles turn counterclockwise. It is added to orientation and lifetime rotation. Accepts a number or a curve sampled at birth using normalized emitter lifetime. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Initial properties: Angular VelocitySpin speed used by angular-velocity orientation. Integrated over simulation time. Accepts a number or a curve sampled at birth using normalized emitter lifetime. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Initial properties: StretchAdditional horizontal and vertical stretch at birth. Zero keeps the original dimension; one doubles it. Each axis accepts a number or an emitter-lifetime curve. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Initial properties: ColorBirth color as red, green, and blue channels from 0 to 1. Each channel accepts a number or an emitter-lifetime curve. Lifetime color and rendering tint multiply this color afterward. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Initial properties: AlphaInitial opacity, multiplied by lifetime alpha, emitter tint, and display-object alpha. Accepts a number or a curve sampled at birth using normalized emitter lifetime. Spread adds independent random variation around each birth value. Zero keeps that value unchanged.Over lifetime: ScaleMultiplies the particle’s initial size. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1.Over lifetime: StretchHorizontal and vertical stretch added to birth stretch as particles age. Constants and particle-lifetime curves are supported.Over lifetime: RotationAdded to the particle’s initial rotation. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1.Over lifetime: Angular VelocityMultiplies the particle’s initial angularVelocity. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1.Over lifetime: ColorRed, green, and blue multipliers over each particle’s lifetime. Use curves to change color from birth at time 0 to expiration at time 1.Over lifetime: AlphaMultiplies the particle’s initial alpha. A number stays constant; a curve follows each particle from birth at time 0 to expiration at time 1.Modifiers: AccelerationConstant force along the rotated local up direction. Changes velocity every simulation step.Modifiers: DragVelocity damping. Positive strength slows particles; directional mode damps only the selected axis.Modifiers: RadialForce away from a center, with distance falloff. Negative magnitude attracts particles.Modifiers: VortexTangential force around a center, with distance falloff. Change the sign to reverse circulation.Curves: CurvesShape particle opacity over its lifetime. Edit point times, values, and tangents, then apply the curve to the preview. Time runs from birth (0) to expiration (1). A tangent controls the slope through a point.Artwork: Size ModeManual uses initial particle size. Auto uses texture-frame dimensions and treats initial size as a multiplier. The same numeric size therefore has a very different effect.Artwork: FlipMirror artwork horizontally, vertically, or both, without changing particle motion.Artwork: PivotHorizontal and vertical particle pivot offsets. Adjust both axes together to change the anchor used for particle geometry.Artwork: AnimationAnimation playback mode and FPS. Loop modes use FPS; once modes span particle lifetime. None freezes the first frame.Artwork: Animation SizeReference width and height for animation geometry. The first frame’s original size is used when omitted. This sets a consistent aspect across the sequence.
Reference

@reparticle/core

Classes

Class Description
EffectTransform Shared transform from effect-local coordinates to world coordinates. Reflect local X when handedness is -1, then rotate, scale, and translate. Rotation is in degrees, counterclockwise on a canvas whose Y axis points down.
Emitter Coordinate one emitter’s playback, CPU slot metadata, and GPU simulation. Particle state stays in GPU textures; CPU metadata controls birth admission and expiration without readbacks. The renderer owns the GL context.
EmitterPlayback Frame-based emission clock, independent of individual particle ages. Lifecycle: prespawn (delay) → spawning → postspawn (draining) → sleeping. Loop boundaries stay in spawning. The caller reports when particles have drained through finish(); this class does not track particle counts.
ParticleSlots Allocate fixed GPU slots using CPU lifetime metadata, without texture readbacks. Births from one step share an age and form a batch sorted by lifetime. This lets expiration consume each batch from the front instead of scanning capacity. Living slots are never overwritten; requests beyond available capacity are dropped.
SampledCurve Samples a constant or authored curve once, then interpolates between cached values during playback. Times are normalized: 0 is the start, 1 is the end.
SpawnRate Evaluate births per second over emitter lifetime, not individual particle age. A seeded spread offset is sampled once and stays fixed across evaluations. SpawnSchedule converts the resulting rate into a whole-particle request.
SpawnSchedule Convert a particles-per-second rate into whole-particle requests per step. Fractional births carry into later steps; whole births above capacity are dropped. ParticleSlots separately decides how many requests fit in currently free slots.

Interfaces

Interface Description
Curve Parsed scalar curve with at least one point and strictly increasing times. Point times lie in [0, 1], but points at both endpoints are not required.
CurvePoint Parsed curve point: time is normalized lifetime, value uses the property’s units, and tangent is the slope (change in value per unit of normalized time). The same tangent applies on both sides of the point; it defaults to zero when omitted from JSON and is always present after parsing.
EffectConfig Parsed effect definition with schema defaults applied. Contains at least one emitter with a unique ID and an effect-level modifier list. Rendering settings contain shared appearance only; artwork belongs to the renderer.
EffectInput Authoring input before defaults and validation.
EmitterConfig Validated emitter data, including the shared rendering contract.
EmitterContext Renderer-owned resources borrowed by an emitter’s GPU simulation. Simulation and rendering share a context so particle textures can be consumed directly on the GPU. Destroying the emitter does not destroy these resources.
EmitterInput Emitter authoring input before defaults and validation.
EmitterParameters Input patch for changing an existing emitter through setParameters(). Omitted fields retain their current values; a supplied modifier list replaces the whole list. Only fields exposed by the runtime schema can be changed.
EmitterStateChange One queued playback transition, identified by the emitter’s configured ID.
RenderingConfig Serializable rendering settings with defaults applied. Shared by every renderer.
RenderingInput Authoring form of the shared rendering settings.
StopOptions Options for stopping births immediately, rather than retiring after the current loop.
Transform Transform from effect-local coordinates to world coordinates. Apply local-X reflection, rotation, uniform scale, then translation. Coordinates use canvas orientation: +X points right and +Y points down.

Type Aliases

Type Alias Description
EmitterState Emitter playback phase, independent of its emission gate and particle count.
EmitterStateListener Receive transitions in order, without an initial event when subscribing. Updates deliver notifications after simulation work; stop/reset also flush transitions. Changes made inside a listener wait until the current batch ends. A callback may observe a newer emitter.state than event.state when several transitions occurred during one update, including prewarm.
ModifierConfig Parsed acceleration, drag, radial, or vortex modifier with defaults applied. Narrow by type to access fields specific to that modifier. The same definition type is used for emitter-level and effect-level modifier lists.
ParticleBlendMode -
ParticleLifetimeVisitor Synchronous callback used by ParticleSlots.forEachLifetime() for each live slot. Values come from CPU allocation metadata; visiting does not read GPU textures or allocate a per-particle record. Traversal follows birth batches, not draw order.
ParticleTint -
ScalarProperty Constant scalar or parsed curve. A number keeps the same value at every time. The owning property determines units, whether time follows the emitter or a particle, and whether the evaluated value is an absolute value or a multiplier.

Variables

Variable Description
CURVE_SEGMENTS 64 intervals require 65 curve samples, including both endpoints.
effectConfigSchema Zod Mini schema for effect JSON. Use .parse() or .safeParse() to validate. Only implemented configuration features are accepted. Compose schemas with functions from zod/mini; validation errors expose an issues array.
emitterConfigSchema Zod Mini schema for one emitter, including defaults and strict field validation.
renderingSchema Zod Mini schema for shared appearance settings. Artwork is supplied separately by the renderer.

Functions

Function Description
parseEffectConfig Validate parsed JSON before GPU allocation and return independent configuration data.
prewarm Simulate an effect’s start offset before its first visible frame. The caller supplies the normal simulation step, including delay and playback handling, so prewarming can also complete a once-playing emitter.
propertyVariation Produce repeatable variation in [-1, 1] for a particle property.
sampleCurve Bake a constant or validated curve into 65 evenly spaced float32 values. Includes both endpoints: time 0 at index 0 and time 1 at index 64. Playback interpolates between adjacent samples instead of evaluating Hermite curves each frame. Constants produce the same value at every sample.