Fission SDK · C++ technical reference
Particle-file commands, defaults, value formats, runtime behavior, graph syntax, and emitter integration for the C++ renderer.
Particle definitions use command = value; statements. Whitespace is generally tolerated, but command names and enum strings are case-sensitive. Unknown commands assert in development builds. Defaults below are the values constructed by fsCParticleData before any file is parsed.
imageFileName = particles/gfx/spark.png;
alphaMode = add;
particleLifeMs = 1200;
emitterLifeMs = 0;
maxParticles = 24;
emitSpeed = 12.0;
emitPosXY = 0, 0 rndRangeXY = 20, 8;
velocityXY = 0, 90 rndRangeXY = 25, 10;
scale = 0.5 rndRange = 0.15;
scaleDelta = -0.25 rndRange = 0.05;
colourGraph = ffffff00, ffffffff, 150, ffffff00, 1050;| Syntax | Meaning |
|---|---|
| ; | Terminates every command, including multi-line graph commands. |
| x, y | Two floating-point values used for positions, velocities, UV motion, and pivots. |
| value rndRange = r | Legacy scalar form: choose a per-particle value approximately uniformly from value − r through value + r. Use a non-negative range. |
| x, y rndRangeXY = rx, ry | Vector form: independently randomize X and Y around the supplied centre. Use non-negative ranges. |
| initial, value, duration, … | Graph form: linearly interpolate from the initial value to each following value over that pair's duration in milliseconds. |
| RRGGBBAA | Exactly eight hexadecimal characters: red, green, blue, alpha. |
| Group | Commands |
|---|---|
| Content | imageFileName, animFileName, particleFileName, sfxFileName |
| Emitter | pulse, maxParticles, emitSpeed, emitterLifeMs, prerun |
| Particle lifetime | particleLifeMs, collectable, collectableType, linkToEmitter |
| Position and motion | emitPosXY, velocityXY, velocityDeltaXY, velocityUV, pivot |
| Appearance | alphaMode, colour, colourGraph |
| Oscillation | oscillationX, oscillationY, optional rndRangeOT |
| Scale | scaleParam, scale, scaleDelta, scaleXParam, scaleX, scaleXDelta, scaleYParam, scaleY, scaleYDelta |
| Rotation | angleParam, angle, angleDelta |
| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| imageFileName | asset path string | none | Creates sprite particles when no nested particle or animation takes priority. A comma in the value selects multi-image mode; brushes are assigned round-robin when the cache is created. |
| animFileName | asset path string | none | Loads animation data and creates animated particles unless particleFileName is also present. Static alphaMode, colour, and pivot setup is not passed to the animation-particle constructor. |
| particleFileName | particle .txt path | none | Creates particles that contain their own emitter. This has creation priority over animFileName and imageFileName. An optional image or animation becomes the nested particle's visible root. |
| sfxFileName | audio asset path | empty | Plays the effect once for every particle reset/emission. Sound is suppressed during prerun simulation. |
| alphaMode | enum string | normal | Sprite blend mode. Valid values: none, normal, add, subtract. Invalid values assert. |
| colour | RRGGBBAA | ffffffff | Static sprite tint. Exactly eight hex characters. A colourGraph, when present, updates the rendered colour over time. |
| pivot | x, y position units | 0, 0 | Adds a local translation to sprite rendering, effectively moving the sprite's pivot. Applied by the sprite-particle path. |
| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| pulse | boolean | false | When true, each fill pass requests the entire cached particle set at once. With a cloud emitter, cache size is taken from the spawn-cloud pixel count rather than maxParticles. |
| maxParticles | integer count | 0 | Maximum cached/live particles for a normal emitter. Zero creates no cache. In pulse cloud mode this value is overridden by the cloud size. |
| emitSpeed | float; particles/s | 0.0 | Accumulates particles to emit per second. Fractional rates are supported. A one-particle emitter with emitSpeed = 1 has a dedicated immediate-fill case. |
| particleLifeMs | integer ms | 0 | Zero means an emitted particle does not expire. Positive values deactivate it at expiry. Negative values use abs(value) as the update limit, finalise scale/angle there, and participate in special one-particle active-state handling. |
| emitterLifeMs | integer ms | 0 | Zero makes the emitter run forever. A non-zero value stops new emission after the emitter's elapsed time reaches the value; already-active particles continue updating. |
| prerun | integer ms | 0 | Before normal display, simulates the emitter in 32 ms updates for approximately this duration. Useful for starting a continuous effect in a populated state; emission SFX is muted during the simulation. |
| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| collectable | integer count | 0 | Initial remaining-collectable count exposed by the emitter. A non-zero value also requests hit-test-capable brush loading and causes the component to add collectable interaction during finalisation. |
| collectableType | string label | empty | Application-facing category returned when a collectable particle is queried. The particle engine does not interpret the string. |
| linkToEmitter | boolean | false | True keeps particles under the emitter entity's render transform, so existing particles follow it. False updates the spawn position from the entity while rendering particles in the parent coordinate space. |
| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| emitPosXY | x, y; position units | 0, 0 | Local emission centre. Optional rndRangeXY independently spreads X and Y around the centre. A parent-entity emission source or spawn cloud overrides the normal random-position path. |
| velocityXY | x, y; units/s | 0, 0 | Initial linear velocity. Optional rndRangeXY is sampled independently for every reset particle. |
| velocityDeltaXY | x, y; units/s² | 0, 0 | Rate added to velocity each second—acceleration or deceleration. Optional rndRangeXY randomizes it per particle. |
| velocityUV | u, v; UV/ms | 0, 0 | Texture-coordinate movement for sprite particles. The implementation adds this value once per millisecond, wraps positive values above 1 by subtracting 1, and enables texture wrapping. |
| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| scale | float + optional rndRange | 1.0 | Legacy uniform/X starting scale. With no scaleY command, Y mirrors X. |
| scaleDelta | float/s + optional rndRange | 0.0 | Legacy uniform/X scale rate. Added over time in units per second. |
| scaleParam | graph | none | Absolute scale graph for X and, when no Y parameter exists, both axes. Alias of scaleXParam. |
| scaleX | float + optional rndRange | 1.0 | Legacy X starting scale. Same storage as scale. |
| scaleXDelta | float/s + optional rndRange | 0.0 | Legacy X scale rate. Same modifier as scaleDelta. |
| scaleXParam | graph | none | Absolute X scale graph. Same storage as scaleParam. |
| scaleY | float + optional rndRange | 1.0 when created | Creates an independent Y scale parameter; after this, Y no longer mirrors X. |
| scaleYDelta | float/s + optional rndRange | 0.0 | Creates/updates the independent Y scale rate. |
| scaleYParam | graph | none | Creates an independent absolute Y scale graph. |
| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| angle | degrees + optional rndRange | 0.0° | Legacy starting rotation. Converted to radians internally. Positive file angles are negated when the local render matrix is built. |
| angleDelta | degrees/s + optional rndRange | 0.0°/s | Legacy angular rate, sampled per particle when a range is supplied. |
| angleParam | degree graph | none | Absolute repeating angle graph. Each value is written in degrees and converted internally. |
angleParam = 0,
20, 1500,
10, 1000,
0, 500,
-20, 1500,
0, 1500;| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| colourGraph | RGBA graph | none | Starts at the first RRGGBBAA value, then interpolates to each following colour over its paired duration in milliseconds. Evaluation repeats at the sum of the durations. |
colourGraph = ffffff00,
ffffffff, 150,
ffffffff, 700,
ffffff00, 350;| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| oscillationX | offset graph | none | Adds a repeating X-position offset. The parser consumes but ignores the first scalar token and constructs a zero starting offset; subsequent value/duration pairs define the curve. |
| oscillationY | offset graph | none | Equivalent repeating Y-position offset. |
| rndRangeOT | amplitude, time multipliers | absent | Optional final clause inside either oscillation command. Positive values randomize that particle's amplitude and/or graph-time multiplier; zero leaves the corresponding multiplier at 1. |
oscillationX = 0,
-10, 1000,
0, 1000,
10, 1000,
0, 1000,
rndRangeOT = 0.8, 0.2;| Parameter | Type / units | Default | Explanation and constraints |
|---|---|---|---|
| particleFile | asset path string | Required | Variable-table key read by fsCParticleEmitterComponent. The file must exist; it is loaded through fsCParticleDataManager and used to construct the emitter. |
| PAR prefix | entity convention | registered | Entity prefix associated with fsCParticleEmitterComponent, the normal emitter component. |
| PRC prefix | entity convention | registered | Entity prefix associated with fsCParticleCloudEmitterComponent, which derives a spawn-cloud image from the particle path and entity name. |
The PRC component first searches a localized level layers folder, then the ordinary layers folder, using the entity name without its suffix. If neither level-layer candidate is found, it falls back to a PNG beside the particle file. Opaque pixels become spawn points; sequence clouds keep pixel-colour ordering while ordinary clouds store positions.
| Check | What to verify |
|---|---|
| Syntax | End every command with a semicolon. Use exactly eight RRGGBBAA hex characters for colours. |
| Content source | Supply an image, animation, or nested particle appropriate to the intended particle type; remember nested particles take creation priority. |
| Capacity and rate | Use maxParticles > 0 and emitSpeed > 0 for ordinary emission. Treat pulse as cloud-emitter-only. |
| Lifetime | Use emitterLifeMs = 0 for continuous emission and particleLifeMs = 0 only when particles should not expire. |
| Graphs | Give colour, scale, angle, and oscillation graphs a positive total duration. |
| Ranges | Use non-negative rndRange and rndRangeXY values; they are half-ranges around the configured centre. |
| Multi-image lists | Add a trailing comma when more than one image name is supplied, so the final name is consumed. |
| Runtime cost | Remember sfxFileName plays per particle, and choose linkToEmitter based on whether emitted particles should keep following the entity. |
Primary files reviewed; update this guide when loader or emitter behavior changes:
libs/fsRenderer/src/particles/fsCParticleDataLoader.cpplibs/fsRenderer/src/particles/fsCParticleData.{h,cpp}libs/fsRenderer/src/particles/fsCParticleDataInstance.cpplibs/fsRenderer/src/particles/fsCParticleEmitter.cpplibs/fsRenderer/src/particles/fsIParticle.cpplibs/fsRenderer/src/particles/fsCParticleParameter.cpplibs/fsRenderer/src/particles/fsCParticleParameterModifier.cpplibs/fsRenderer/src/particles/fsCParticle{Scale,Rotate}Parameter.cpplibs/fsRenderer/src/components/fsCParticle{,Cloud}EmitterComponent.cpplibs/fsAppCore/src/fsCGraph.h