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.
Contributing

Development

Set up reparticle locally to make and test changes.

Set up

Install Node.js 24 or later and pnpm 10.32.1, then clone the repository:

git clone https://github.com/reparticlejs/reparticle.git
cd reparticle
pnpm install

Run the site

pnpm dev:site

Starts the website with the docs, lab, and examples. Open the URL shown in your terminal.

Run the examples

pnpm dev

Starts the example gallery on its own.

Run these commands from the repository root. Both build the library packages before starting. After changing library code, stop and rerun the command to rebuild it. Restart pnpm dev:site after changing source comments or types to refresh the generated API docs.

Build shaders and API docs

Simulation is written in TypeScript with TypeGPU. Building core generates the WebGL2 shaders. Applications receive the generated shaders; they do not need TypeGPU or a build plugin.

pnpm --filter @reparticle/core build

API pages come from the packages’ exported types and comments. Edit the source, then regenerate the pages:

pnpm --filter @reparticle/site build:api

Do not edit generated shaders or API pages by hand. Both are rebuilt by pnpm build.

See Particle architecture for storage, updates, and resource ownership.

Check your changes

pnpm check

Tests include real WebGL2 simulation and Pixi rendering. pnpm test installs Chromium automatically when needed. CI installs Linux system dependencies separately.

Checks formatting, lint, types, and tests, then builds the project. To fix formatting, run pnpm format.

pnpm install enables Git hooks. Commits check formatting and lint on staged files; pushes run type checks and tests.

Type-aware linting first builds core and pixi so their exported types are available. Turbo reuses those builds when the packages have not changed.

GitHub Actions runs pnpm check on pull requests and pushes to main. Publishing a package from this workspace also runs the full check first. Publishing a prebuilt tarball bypasses package hooks, so run pnpm check before packing a release.