babylon.quarks - v1.0.0
    Preparing search index...

    Class ParticleSystem

    A particle system, the counterpart of a Unity Shuriken system or a Niagara emitter: it spawns particles from an emitterShape, gives them start values, runs its behaviors on them every step and hands them to a BatchedRenderer to draw.

    The system lives at its emitter, a Babylon node: move, parent or disable that to place the effect. Add the system to a renderer with renderer.addSystem(system); the renderer advances it every frame on a fixed 60 Hz step and batches it with systems that draw alike.

    Curves and random values are quarks.core generators (ConstantValue, IntervalValue, PiecewiseBezier, Gradient, ...); a curve's x is the system's time over its duration for start values and emission, and the particle's age over its life inside behaviors.

    Implements

    Index
    alignToDirection: boolean = false

    Whether each particle starts turned along the direction its shape sends it (Unity's Align To Direction): a mesh particle's +Z is pointed along the velocity, a billboard's top is turned toward it in the emitter's XY plane. The start rotation is applied on top. A particle with no speed is left as it is. False by default.

    beamEnd?: BeamEnd

    Where a RenderMode.Beam system's quads end, see BeamEnd. Unset (the default), a beam has no length and draws nothing. Not saved in the effect JSON: it is where this instance is aimed at runtime. Copied by clone: a point as a copy, a node as the same node.

    behaviors: Behavior[]

    Modules run on every particle each step, in order (ColorOverLife, SizeOverLife, forces, ...).

    cullingMode: CullingMode = 'always'

    What this system does while off screen, see CullingMode. 'always' by default.

    emissionBursts: BurstParameters[]

    Bursts of particles at set times in each cycle. Default none.

    emissionOverDistance: ValueGenerator | FunctionValueGenerator

    Particles emitted per world unit the emitter moves (Unity's Rate over Distance). Default 0.

    Particles emitted per second, read over the system's time. Default 10.

    emissionState: EmissionState

    Emission progress: time in the cycle, burst and distance counters.

    The node the system lives at; move, parent or disable it to place or hide the effect.

    emitterShape: EmitterShape

    Where particles are born and which way they start (Unity's Shape module). Default a SphereEmitter.

    emitterVelocity: Vector3 = ...

    The emitter's velocity over the last step, which InheritVelocity reads.

    ignoreStopAction: boolean = false

    Skips the stopAction while true, so a tool can play an effect over and over (an editor's preview, a gallery, a pool of reused copies) and still save the stop action it was authored with, as Unity applies stop actions only in Play mode. The finished event fires either way. False by default; never saved, cloned or loaded.

    looping: boolean

    Start the cycle again when duration ends instead of stopping emission. Default true.

    maxParticles?: number

    Most particles alive at once (Unity's Max Particles); emission past it is dropped. Undefined means no limit, as does a negative or NaN count given to the constructor; a fraction is rounded down. With a ringBufferMode, new particles replace the oldest instead.

    motionScale: number = 1

    What world-space forces are multiplied by this step: the mean of the axes of the scale the scalingMode applies (the emitter's own in 'local', its world scale in 'hierarchy', 1 in 'shape') in a world-space system, 1 in a local-space one, whose emitter matrix scales them already. Updated before every simulation step.

    neededToUpdateRender: boolean

    Set when a render setting changed, so the renderer moves the system to a matching batch. The system's setters set it; set it yourself after changing getRendererSettings directly.

    onlyUsedByOther: boolean

    The system emits nothing of its own and only spawns what an EmitSubParticleSystem on another system sends it (a Unity sub emitter). Default false.

    particles: Particle[]

    The particle pool; the first particleNum are alive.

    paused: boolean

    Set by pause: the renderer skips the system's simulation while true.

    prewarm: boolean

    Start a looping system as if it had already run one full cycle (Unity's Prewarm), so a fire or a mist is full from its first frame. Default false.

    rendererEmitterSettings: RendererEmitterSettings

    The render mode's own settings: TrailSettings for a trail (startLength and the trail flags), StretchedBillBoardSettings for a stretched billboard (speedFactor, lengthFactor), MeshSettings or nothing otherwise. Setting renderMode replaces it with that mode's defaults.

    ringBufferMode: RingBufferMode

    What a full system does with new particles (Unity's Ring Buffer Mode): drop them, or replace the oldest, which wait frozen or looping until then; see RingBufferMode. 'disabled' by default. Takes effect only with maxParticles.

    rotationAxis: RotationAxis = 'z'

    The axis a number rotation turns a mesh particle about, see RotationAxis. 'z' by default; 'emission' picks it per particle at birth, as Unity does for a mesh particle when its Shape module is on.

    scalingMode: ScalingMode = 'local'

    What the emitter's scale does to the system, see ScalingMode. 'local' by default.

    Colour and alpha each particle starts with, multiplied with the texture. Default opaque white.

    Seconds before the system first emits, rolled on each restart. Default 0.

    Seconds each particle lives, rolled at birth. Default 5.

    Rotation each particle starts with. An angle in radians turns a billboard in its plane and a mesh about its rotationAxis. A rotation generator (EulerGenerator, AxisAngleGenerator, RandomQuatGenerator) is the mesh's full rotation; on a billboard, stretched, horizontal or vertical billboard or beam it contributes only the turn about Z (an Euler generator's Z angle, or the twist about Z of the others), and X and Y are ignored. Default 0.

    Size each particle starts with in world units; a Vector3Generator sizes each axis (Unity's 3D Start Size). Default 1.

    Speed each particle starts with along the direction its shape gives it, in units per second. Default 0.

    startTileIndex: ValueGenerator

    Flipbook cell each particle starts on, counted across rows, see uTileCount. Default 0.

    stopAction: StopAction

    What the system does once it has finished (Unity's Stop Action): nothing, disable its emitter, or dispose it; see StopAction. 'none' by default.

    As in Unity, the action waits for the system's sub emitters: it runs once the system has finished and none of the systems it emits into, nor theirs, has a particle left (see isAlive), so disabling or disposing a parent does not cut its sub emitters' particles short. A sub emitter target (onlyUsedByOther) takes no stop action of its own: it is empty between its parent's bursts, and its parent decides when the effect is done.

    worldSpace: boolean

    Simulate in world space (Unity's Simulation Space: World): particles stay where they were born when the emitter moves. False keeps them in the emitter's space, so they move with it. Default false.

    catchUpBudgetMs: number = 2

    Time per frame a system coming back into view may spend on the steps it missed, in milliseconds, when it is advanced without a renderer. The BatchedRenderer shares its own budget among all its systems instead. Steps that do not fit are dropped, not deferred.

    maxPrewarmSeconds: number = 10

    A performance guard on prewarm, for every system: the most of a cycle it simulates before the first frame, in seconds. A longer cycle is warmed up over its last maxPrewarmSeconds only, with the burst waves before that counted as fired, so a long looping effect does not stall its first frame. 10 by default; raise it in an app whose effects have longer cycles and particles that live longer than that. It is not an effect's own warm-up time, which is prewarmTime, and is not saved with one.

    • get alphaTest(): number

      Alpha below which a fragment is discarded (Unity's Alpha Clip Threshold), 0…1; 0 (the default, or the material's alphaCutOff) discards nothing but fragments under 0.01, which no blend mode can show except additive ones with a bright colour. Switching it on or off rebuilds the batch's material; a change between non-zero cutoffs on a system alone in its batch is written to the material in place.

      Returns number

    • set alphaTest(cutoff: number): void

      Alpha below which a fragment is discarded (Unity's Alpha Clip Threshold), 0…1; 0 (the default, or the material's alphaCutOff) discards nothing but fragments under 0.01, which no blend mode can show except additive ones with a bright colour. Switching it on or off rebuilds the batch's material; a change between non-zero cutoffs on a system alone in its batch is written to the material in place.

      Parameters

      • cutoff: number

      Returns void

    • get applyFog(): boolean

      Whether the scene's fog applies to the particles, as it does to any other mesh; true by default. Additive particles fade toward black rather than the fog colour. Saved in the effect JSON only when switched off.

      Returns boolean

    • set applyFog(apply: boolean): void

      Whether the scene's fog applies to the particles, as it does to any other mesh; true by default. Additive particles fade toward black rather than the fog colour. Saved in the effect JSON only when switched off.

      Parameters

      • apply: boolean

      Returns void

    • get applyImageProcessing(): boolean

      Whether the particles' material applies the scene's image processing (exposure, contrast, tone mapping, vignette, colour curves, colour grading, dithering of scene.imageProcessingConfiguration), as Babylon's own particle systems and materials do; true by default. A scene whose configuration does nothing leaves the colour as it is, and one applied by a post process gets the colour in linear space. Particles that multiply the frame (ALPHA_MULTIPLY) are a factor rather than light and are not tone mapped.

      As in Babylon, the processing runs on each particle before it is blended: tone mapping clamps an HDR colour to the displayable range, and an additive particle picks up what the configuration does to black (a contrast below 1, colour curves or an opaque vignette lift it). The configuration is the scene's; there is no per-system one.

      Switched off, the material writes its colour as authored, and leaves it in gamma space under a post process, which still processes the frame the particles are in. To keep particles out of a post process, draw them with a camera the pipeline is not attached to. Saved in the effect JSON only when switched off.

      Returns boolean

    • set applyImageProcessing(apply: boolean): void

      Whether the particles' material applies the scene's image processing (exposure, contrast, tone mapping, vignette, colour curves, colour grading, dithering of scene.imageProcessingConfiguration), as Babylon's own particle systems and materials do; true by default. A scene whose configuration does nothing leaves the colour as it is, and one applied by a post process gets the colour in linear space. Particles that multiply the frame (ALPHA_MULTIPLY) are a factor rather than light and are not tone mapped.

      As in Babylon, the processing runs on each particle before it is blended: tone mapping clamps an HDR colour to the displayable range, and an additive particle picks up what the configuration does to black (a contrast below 1, colour curves or an opaque vignette lift it). The configuration is the scene's; there is no per-system one.

      Switched off, the material writes its colour as authored, and leaves it in gamma space under a post process, which still processes the frame the particles are in. To keep particles out of a post process, draw them with a camera the pipeline is not attached to. Saved in the effect JSON only when switched off.

      Parameters

      • apply: boolean

      Returns void

    • get blending(): number

      Babylon alpha mode the particles blend with: Constants.ALPHA_ADD (the default) for glows, Constants.ALPHA_COMBINE for smoke and anything alpha blended. Systems that differ are batched apart.

      Returns number

    • set blending(blending: number): void

      Babylon alpha mode the particles blend with: Constants.ALPHA_ADD (the default) for glows, Constants.ALPHA_COMBINE for smoke and anything alpha blended. Systems that differ are batched apart.

      Parameters

      • blending: number

      Returns void

    • get blendTiles(): boolean

      Cross-fade between a flipbook's cells instead of cutting from one to the next (Unity's Flip-Book Blending); the last cell fades into the first. Default false. Needs a sheet (uTileCount or vTileCount above 1); trails cut their cell on the CPU and do not blend.

      Returns boolean

    • set blendTiles(v: boolean): void

      Cross-fade between a flipbook's cells instead of cutting from one to the next (Unity's Flip-Book Blending); the last cell fades into the first. Default false. Needs a sheet (uTileCount or vTileCount above 1); trails cut their cell on the CPU and do not blend.

      Parameters

      • v: boolean

      Returns void

    • get depthTest(): boolean

      Whether particles are hidden behind nearer geometry; false draws them over everything (Unity's ZTest Always), for overlays and effects seen through walls. Default true, or the material's disableDepthTest inverted. Systems that differ are batched apart.

      Returns boolean

    • set depthTest(depthTest: boolean): void

      Whether particles are hidden behind nearer geometry; false draws them over everything (Unity's ZTest Always), for overlays and effects seen through walls. Default true, or the material's disableDepthTest inverted. Systems that differ are batched apart.

      Parameters

      • depthTest: boolean

      Returns void

    • get depthWrite(): boolean

      Whether particles write depth, so later draws are hidden behind them. Until it is set (here, as a parameter or by a material's disableDepthWrite), it follows transparent, as a Unity particle material's ZWrite follows its surface type: an opaque or cutout system writes depth, so a mesh's far faces never show through its near ones and cut-out leaves stand in front of each other; a transparent one does not. Systems that differ are batched apart.

      Returns boolean

    • set depthWrite(depthWrite: boolean): void

      Whether particles write depth, so later draws are hidden behind them. Until it is set (here, as a parameter or by a material's disableDepthWrite), it follows transparent, as a Unity particle material's ZWrite follows its surface type: an opaque or cutout system writes depth, so a mesh's far faces never show through its near ones and cut-out leaves stand in front of each other; a transparent one does not. Systems that differ are batched apart.

      Parameters

      • depthWrite: boolean

      Returns void

    • get emissionMultiplier(): number

      Runtime multiplier on how many particles the system emits: bursts, emission over time and over distance alike. Unlike setQualityFactor, which only ever thins an effect, it may go above 1 to make a stronger version of the same effect. The two multiply. 1 by default; a negative or NaN value counts as 0. Not saved in the effect JSON; copied by clone.

      Returns number

    • set emissionMultiplier(multiplier: number): void

      Runtime multiplier on how many particles the system emits: bursts, emission over time and over distance alike. Unlike setQualityFactor, which only ever thins an effect, it may go above 1 to make a stronger version of the same effect. The two multiply. 1 by default; a negative or NaN value counts as 0. Not saved in the effect JSON; copied by clone.

      Parameters

      • multiplier: number

      Returns void

    • get erosion(): ParticleErosion | undefined

      Alpha erosion, see ParticleErosion: the particle's alpha decides how much of the shape is left rather than how transparent it is, so a ColorOverLife alpha curve dissolves the shape through a noise mask or wipes it through a gradient one — and an effect told to stop can fade out that way. Undefined (the default): alpha is plain transparency. Fields left out take their defaults; assign a new object to change it. Saved with the material in the effect JSON.

      Returns ParticleErosion | undefined

    • set erosion(erosion: ParticleErosionOptions | undefined): void

      Alpha erosion, see ParticleErosion: the particle's alpha decides how much of the shape is left rather than how transparent it is, so a ColorOverLife alpha curve dissolves the shape through a noise mask or wipes it through a gradient one — and an effect told to stop can fade out that way. Undefined (the default): alpha is plain transparency. Fields left out take their defaults; assign a new object to change it. Saved with the material in the effect JSON.

      Parameters

      Returns void

    • get gradientMap(): ParticleGradientMap | undefined

      Colour ramp the map is recoloured through (a gradient map), see ParticleGradientMap: a channel of the map, or its luminance, picks a colour along U of the ramp; the particle colour still tints the result. One greyscale or channel-packed texture then serves every palette. Undefined (the default), or without a ramp: none. Assign a new object to change it. Saved with the material in the effect JSON.

      Returns ParticleGradientMap | undefined

    • set gradientMap(gradientMap: Partial<ParticleGradientMap> | undefined): void

      Colour ramp the map is recoloured through (a gradient map), see ParticleGradientMap: a channel of the map, or its luminance, picks a colour along U of the ramp; the particle colour still tints the result. One greyscale or channel-packed texture then serves every palette. Undefined (the default), or without a ramp: none. Assign a new object to change it. Saved with the material in the effect JSON.

      Parameters

      Returns void

    • get instancingColors(): Float32Array<ArrayBufferLike> | undefined

      The mesh particles' vertex colours, r, g, b, a per vertex from 0 to 1, or none. A mesh particle's colour at a vertex is its own times the vertex's, as Unity draws a particle mesh that has vertex colours, so a mesh can fade out toward its ends. The values are linear and taken as they are: unlike the particle colour, given in gamma space, they are not converted, as Unity takes them in its Linear colour space and glTF stores COLOR_0. A set that does not hold four values per vertex is left out, with a warning. Systems whose colours are not the same array are batched apart.

      Returns Float32Array<ArrayBufferLike> | undefined

    • set instancingColors(colors: Float32Array<ArrayBufferLike> | undefined): void

      The mesh particles' vertex colours, r, g, b, a per vertex from 0 to 1, or none. A mesh particle's colour at a vertex is its own times the vertex's, as Unity draws a particle mesh that has vertex colours, so a mesh can fade out toward its ends. The values are linear and taken as they are: unlike the particle colour, given in gamma space, they are not converted, as Unity takes them in its Linear colour space and glTF stores COLOR_0. A set that does not hold four values per vertex is left out, with a warning. Systems whose colours are not the same array are batched apart.

      Parameters

      • colors: Float32Array<ArrayBufferLike> | undefined

      Returns void

    • get instancingGeometry(): Float32Array

      The mesh particles' positions, three values per vertex. Setting it restarts the system. A new geometry with a different vertex count drops UV sets, normals, vertex colours and indices that no longer fit it: the first UV set falls back to zeros, the second to none, the normals to +Z, the colours to none, the indices to the vertex sequence. Assign instancingUVs, instancingUVs2, instancingColors and instancingIndices after it.

      Returns Float32Array

    • set instancingGeometry(geometry: Float32Array): void

      The mesh particles' positions, three values per vertex. Setting it restarts the system. A new geometry with a different vertex count drops UV sets, normals, vertex colours and indices that no longer fit it: the first UV set falls back to zeros, the second to none, the normals to +Z, the colours to none, the indices to the vertex sequence. Assign instancingUVs, instancingUVs2, instancingColors and instancingIndices after it.

      Parameters

      • geometry: Float32Array

      Returns void

    • get instancingIndices(): | Uint32Array<ArrayBufferLike>
      | Uint16Array<ArrayBufferLike>

      The mesh particles' triangle indices into instancingGeometry. Mesh systems that share positions but not indices (sub-meshes of one vertex buffer) are batched apart.

      Returns Uint32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike>

    • set instancingIndices(
          indices: Uint32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike>,
      ): void

      The mesh particles' triangle indices into instancingGeometry. Mesh systems that share positions but not indices (sub-meshes of one vertex buffer) are batched apart.

      Parameters

      • indices: Uint32Array<ArrayBufferLike> | Uint16Array<ArrayBufferLike>

      Returns void

    • get instancingUVs2(): Float32Array<ArrayBufferLike> | undefined

      The mesh particles' second UV set, read by textures on UV channel 1; see UVChannel.

      Returns Float32Array<ArrayBufferLike> | undefined

    • set instancingUVs2(uvs: Float32Array<ArrayBufferLike> | undefined): void

      The mesh particles' second UV set, read by textures on UV channel 1; see UVChannel.

      Parameters

      • uvs: Float32Array<ArrayBufferLike> | undefined

      Returns void

    • get layers(): { mask: number }

      The camera layer mask the particles draw for (Babylon's mesh.layerMask), as system.layers.mask. Default 0x0fffffff, every camera's default mask. Systems that differ are batched apart.

      Returns { mask: number }

      • mask: number

        The mask; setting it moves the system to a matching batch.

    • get mapUV(): TextureUV | undefined

      How the main map is laid over the particle, see TextureUV: its UV channel, tiling and offset (Unity's Tiling / Offset) and a scroll on the renderer's clock (Unreal's Panner), for flowing energy, lava or a smear running along a mesh. A scrolled or tiled map should repeat. On a sprite sheet (UV channel 0) the layout applies to the sheet's UV, so a scroll or tiling there runs into the neighbouring cells. Undefined (the default), or the identity: the map as drawn. Fields left out take their defaults; assign a new object to change it. Saved with the material in the effect JSON.

      Returns TextureUV | undefined

    • set mapUV(uv: Partial<TextureUV> | undefined): void

      How the main map is laid over the particle, see TextureUV: its UV channel, tiling and offset (Unity's Tiling / Offset) and a scroll on the renderer's clock (Unreal's Panner), for flowing energy, lava or a smear running along a mesh. A scrolled or tiled map should repeat. On a sprite sheet (UV channel 0) the layout applies to the sheet's UV, so a scroll or tiling there runs into the neighbouring cells. Undefined (the default), or the identity: the map as drawn. Fields left out take their defaults; assign a new object to change it. Saved with the material in the effect JSON.

      Parameters

      Returns void

    • get material(): ParticleMaterialSource | null

      A Babylon material the system takes its draw settings from (on a loaded system, the material record of its file): its texture (albedoTexture, diffuseTexture, emissiveTexture or opacityTexture), alpha mode, depth flags, alpha test and reflection texture. The material itself is not drawn with; particles always use quarks' own shaders. Null leaves the settings as they are.

      Returns ParticleMaterialSource | null

    • set material(material: ParticleMaterialSource | null): void

      A Babylon material the system takes its draw settings from (on a loaded system, the material record of its file): its texture (albedoTexture, diffuseTexture, emissiveTexture or opacityTexture), alpha mode, depth flags, alpha test and reflection texture. The material itself is not drawn with; particles always use quarks' own shaders. Null leaves the settings as they are.

      Parameters

      Returns void

    • get materialColor(): Color4Like

      The material's colour (Unity's material Color and Tint Color): it multiplies every particle's colour, alpha included, as it is drawn. Given in gamma space like the particles' colours, it is brought into the shader's working space on its own, so under the scene's image processing it multiplies in linear space, as Unity's Linear colour space does. Unlike tint it belongs to the effect: saved in the effect JSON, and systems with different material colours draw from different batches, though with the same shader. Default white. Set it from any Color4Like, such as a Babylon Color4; the value is copied, and the one returned is a copy.

      Returns Color4Like

    • set materialColor(color: Color4Like): void

      The material's colour (Unity's material Color and Tint Color): it multiplies every particle's colour, alpha included, as it is drawn. Given in gamma space like the particles' colours, it is brought into the shader's working space on its own, so under the scene's image processing it multiplies in linear space, as Unity's Linear colour space does. Unlike tint it belongs to the effect: saved in the effect JSON, and systems with different material colours draw from different batches, though with the same shader. Default white. Set it from any Color4Like, such as a Babylon Color4; the value is copied, and the one returned is a copy.

      Parameters

      Returns void

    • get materialColorScale(): number

      What materialColor is multiplied by, alpha included, once it is in the shader's working space: an intensity that brightens the material in linear space under the scene's image processing, where a colour above 1 in gamma space would grow by its power curve. Unity's legacy particle shaders double their Tint Color in linear space: a material colour of that tint with a scale of 2. At least 0; default 1.

      Returns number

    • set materialColorScale(scale: number): void

      What materialColor is multiplied by, alpha included, once it is in the shader's working space: an intensity that brightens the material in linear space under the scene's image processing, where a colour above 1 in gamma space would grow by its power curve. Unity's legacy particle shaders double their Tint Color in linear space: a material colour of that tint with a scale of 2. At least 0; default 1.

      Parameters

      • scale: number

      Returns void

    • get maxParticleSize(): number

      Largest size a billboard or stretched particle is drawn at, as a fraction of the viewport height (Unity's Max Particle Size, 0.5 there); unlimited by default. Keeps a close particle from filling the screen. Meshes and trails ignore it.

      Returns number

    • set maxParticleSize(size: number): void

      Largest size a billboard or stretched particle is drawn at, as a fraction of the viewport height (Unity's Max Particle Size, 0.5 there); unlimited by default. Keeps a close particle from filling the screen. Meshes and trails ignore it.

      Parameters

      • size: number

      Returns void

    • get minParticleSize(): number

      Smallest size a billboard or stretched particle is drawn at, as a fraction of the viewport height (Unity's Min Particle Size); 0 by default. Keeps distant sparks from vanishing. Meshes and trails ignore it.

      Returns number

    • set minParticleSize(size: number): void

      Smallest size a billboard or stretched particle is drawn at, as a fraction of the viewport height (Unity's Min Particle Size); 0 by default. Keeps distant sparks from vanishing. Meshes and trails ignore it.

      Parameters

      • size: number

      Returns void

    • get particleColor(): boolean

      Whether the particle's colour (its start colour, Color over Life and the like, alpha included, times a mesh's vertex colours) is drawn, as a shader that reads the vertex colour draws it: Unity's particle and sprite shaders, Unreal's Particle Color node. Off, a particle is drawn in the texture times the material colour alone, its alpha too, which the alpha test and the blend then read, as Unity's mesh shaders draw one (Legacy Diffuse and its family, Mobile, Unlit and Standard, measured in Unity 6: a particle tinted or faded draws as a white one). Every render mode. True by default.

      Returns boolean

    • set particleColor(particleColor: boolean): void

      Whether the particle's colour (its start colour, Color over Life and the like, alpha included, times a mesh's vertex colours) is drawn, as a shader that reads the vertex colour draws it: Unity's particle and sprite shaders, Unreal's Particle Color node. Off, a particle is drawn in the texture times the material colour alone, its alpha too, which the alpha test and the blend then read, as Unity's mesh shaders draw one (Legacy Diffuse and its family, Mobile, Unlit and Standard, measured in Unity 6: a particle tinted or faded draws as a white one). Every render mode. True by default.

      Parameters

      • particleColor: boolean

      Returns void

    • get playbackSpeed(): number

      Multiplier on the time this system is advanced by (Unity's Simulation Speed): 2 runs the effect twice as fast, 0 freezes it without pausing the renderer. 1 by default; saved in the effect JSON only when it differs. A negative or NaN speed is read as 0, and the clock does not run backwards.

      Returns number

    • set playbackSpeed(speed: number): void

      Multiplier on the time this system is advanced by (Unity's Simulation Speed): 2 runs the effect twice as fast, 0 freezes it without pausing the renderer. 1 by default; saved in the effect JSON only when it differs. A negative or NaN speed is read as 0, and the clock does not run backwards.

      Parameters

      • speed: number

      Returns void

    • get premultipliedMap(): boolean

      Whether the texture's colour is already multiplied by its alpha (Unity's Alpha Blended Premultiply takes its texture so), and may carry light where its alpha is 0, such as a soft glow. With premultiplied blending the colour is then drawn times the vertex colour and alpha only, as Unity draws it, and the texture's alpha only lets the frame through; other blend modes ignore it. False by default.

      Returns boolean

    • set premultipliedMap(premultiplied: boolean): void

      Whether the texture's colour is already multiplied by its alpha (Unity's Alpha Blended Premultiply takes its texture so), and may carry light where its alpha is 0, such as a soft glow. With premultiplied blending the colour is then drawn times the vertex colour and alpha only, as Unity draws it, and the texture's alpha only lets the frame through; other blend modes ignore it. False by default.

      Parameters

      • premultiplied: boolean

      Returns void

    • get prewarmTime(): number

      How much of the cycle prewarm simulates before the first frame, in seconds (Niagara's Warmup Time), on a looping system like prewarm itself. 0, the default, warms up a whole cycle, as Unity's Prewarm does; a shorter time warms up the cycle's last part only, with the bursts before it counted as fired, which is enough for an effect whose particles live shorter than its cycle and keeps a long cycle's first frame cheap. Longer than the cycle or than maxPrewarmSeconds, it is cut to them. Kept at 0 or above.

      Returns number

    • set prewarmTime(seconds: number): void

      How much of the cycle prewarm simulates before the first frame, in seconds (Niagara's Warmup Time), on a looping system like prewarm itself. 0, the default, warms up a whole cycle, as Unity's Prewarm does; a shorter time warms up the cycle's last part only, with the bursts before it counted as fired, which is enough for an effect whose particles live shorter than its cycle and keeps a long cycle's first frame cheap. Longer than the cycle or than maxPrewarmSeconds, it is cut to them. Kept at 0 or above.

      Parameters

      • seconds: number

      Returns void

    • get renderAlignment(): RenderAlignment

      The axes a mesh particle's rotation is measured in and a billboard's quad is laid along (Unity's renderer Render Alignment): 'simulation' by default (the system's simulation space, as quarks always drew meshes; billboards face the camera), 'view' to lay each mesh along the camera's axes so a flat quad faces the camera, 'world' for the world axes, 'local' for the emitter's axes even in a world-space system. A 'world' or 'local' billboard lies in those axes' XY plane instead of facing the camera. Applies to the Mesh and BillBoard render modes; the other modes ignore it. Systems that differ are batched apart. See RenderAlignment. Saved in the effect JSON only when not 'simulation'.

      Returns RenderAlignment

    • set renderAlignment(alignment: RenderAlignment): void

      The axes a mesh particle's rotation is measured in and a billboard's quad is laid along (Unity's renderer Render Alignment): 'simulation' by default (the system's simulation space, as quarks always drew meshes; billboards face the camera), 'view' to lay each mesh along the camera's axes so a flat quad faces the camera, 'world' for the world axes, 'local' for the emitter's axes even in a world-space system. A 'world' or 'local' billboard lies in those axes' XY plane instead of facing the camera. Applies to the Mesh and BillBoard render modes; the other modes ignore it. Systems that differ are batched apart. See RenderAlignment. Saved in the effect JSON only when not 'simulation'.

      Parameters

      Returns void

    • get renderFace(): RenderFace

      Which faces of a mesh particle are drawn (Unity's Render Face): 'both' by default, 'front' to cull the back faces of a closed mesh, 'back' to see only its inside. Applies to the Mesh render mode; the other modes draw both faces. See RenderFace. Saved in the effect JSON only when not 'both'.

      Returns RenderFace

    • set renderFace(face: RenderFace): void

      Which faces of a mesh particle are drawn (Unity's Render Face): 'both' by default, 'front' to cull the back faces of a closed mesh, 'back' to see only its inside. Applies to the Mesh render mode; the other modes draw both faces. See RenderFace. Saved in the effect JSON only when not 'both'.

      Parameters

      Returns void

    • get renderingGroupId(): number

      Babylon rendering group the particles draw in (mesh.renderingGroupId), 0 by default. Use it to draw an effect after the scene's other transparent meshes, or before an overlay group.

      Returns number

    • set renderingGroupId(group: number): void

      Babylon rendering group the particles draw in (mesh.renderingGroupId), 0 by default. Use it to draw an effect after the scene's other transparent meshes, or before an overlay group.

      Parameters

      • group: number

      Returns void

    • get renderOrder(): number

      The batch mesh's alphaIndex: among the transparent meshes of one rendering group, lower draws first, whatever the distance (Unity's Order in Layer). Default 0. Systems that differ are batched apart.

      Returns number

    • set renderOrder(renderOrder: number): void

      The batch mesh's alphaIndex: among the transparent meshes of one rendering group, lower draws first, whatever the distance (Unity's Order in Layer). Default 0. Systems that differ are batched apart.

      Parameters

      • renderOrder: number

      Returns void

    • get rim(): MeshRim | undefined

      Rim (Fresnel) term on mesh particles — a glowing edge (mode: 'add') or an outline ('mix'), see MeshRim. Undefined (the default) draws none. Fields left out of an assigned rim take their defaults; assign a new object to change it, editing the returned one does not reach the renderer. Saved with the material in the effect JSON. Other render modes ignore it.

      Returns MeshRim | undefined

    • set rim(rim: Partial<MeshRim> | undefined): void

      Rim (Fresnel) term on mesh particles — a glowing edge (mode: 'add') or an outline ('mix'), see MeshRim. Undefined (the default) draws none. Fields left out of an assigned rim take their defaults; assign a new object to change it, editing the returned one does not reach the renderer. Saved with the material in the effect JSON. Other render modes ignore it.

      Parameters

      Returns void

    • get ringBufferLoopRange(): Vector2Like

      The part of its life a particle plays again in 'loopUntilReplaced' (Unity's Loop Range): at the end of its life it goes back to x and plays to y, as fractions of its life, 0 to

      1. (0, 1), the default, replays its whole life. Both ends are read clamped into 0..1 and in order, however the vector was set. A range of no length, such as (0.5, 0.5), holds the particle still at that point of its life; behaviors that act by age stop with it, those that act per second (rotation speed, forces) still run. Set it from any {x, y}, such as a Babylon Vector2; the value is copied clamped and in order.

      Returns Vector2Like

    • set ringBufferLoopRange(value: Vector2Like): void

      The part of its life a particle plays again in 'loopUntilReplaced' (Unity's Loop Range): at the end of its life it goes back to x and plays to y, as fractions of its life, 0 to

      1. (0, 1), the default, replays its whole life. Both ends are read clamped into 0..1 and in order, however the vector was set. A range of no length, such as (0.5, 0.5), holds the particle still at that point of its life; behaviors that act by age stop with it, those that act per second (rotation speed, forces) still run. Set it from any {x, y}, such as a Babylon Vector2; the value is copied clamped and in order.

      Parameters

      Returns void

    • get seed(): number | undefined

      Seed for this system's own random generator. Set, every roll the system makes while it steps (spawn positions, interval values, random colours and rotations, burst probability) comes from a generator started from this seed, and restarted with it on restart: the effect plays out identically every time, on every machine running the same minor version — for replays, lock-step multiplayer and reproducible tests. A minor may draw in a different order (see STABILITY.md). Systems this one emits into roll on its generator too. Unset (the default), rolls come from the global source (setRandomSource in quarks.core). Saved in the effect JSON when set. The behaviors roll on the same generator, and the ones with their own randomness (a TurbulenceField's noise) are built from their own seed, so the whole effect is covered.

      Returns number | undefined

    • set seed(seed: number | undefined): void

      Seed for this system's own random generator. Set, every roll the system makes while it steps (spawn positions, interval values, random colours and rotations, burst probability) comes from a generator started from this seed, and restarted with it on restart: the effect plays out identically every time, on every machine running the same minor version — for replays, lock-step multiplayer and reproducible tests. A minor may draw in a different order (see STABILITY.md). Systems this one emits into roll on its generator too. Unset (the default), rolls come from the global source (setRandomSource in quarks.core). Saved in the effect JSON when set. The behaviors roll on the same generator, and the ones with their own randomness (a TurbulenceField's noise) are built from their own seed, so the whole effect is covered.

      Parameters

      • seed: number | undefined

      Returns void

    • get simulationResidual(): number

      Time the display is ahead of (positive) or still ahead of the simulation (negative: the simulation ran a hair early), in seconds; 0 while paused. Its magnitude never exceeds one step.

      The simulation runs on a fixed 1/60 step so that emission and lifetimes stay in phase; without it a slow emitter flickers when the frame rate wobbles. But frames do not arrive on that grid: a display running at anything other than exactly 60 Hz leaves some frames with no step at all (half of them at 120 Hz, three in five at 144 Hz) and others with two, so the particles would be drawn stuttering even while the frame rate is perfect. Renderers close the gap by advancing what they draw along each particle's velocity by this much. That reproduces the straight-line part of the motion exactly, the same term the next step would integrate, so the simulation stays fixed-step while the picture moves continuously.

      Returns number

    • get softFarFade(): number

      Distance in world units in front of the scene at which a soft particle is fully opaque, at least 0. Default 1 (Unreal's Depth Fade distance): the particle fades over the last unit before the scene. A value at or below softNearFade cuts the particle off at that distance instead of fading it. A live parameter, like softNearFade.

      Returns number

    • set softFarFade(v: number): void

      Distance in world units in front of the scene at which a soft particle is fully opaque, at least 0. Default 1 (Unreal's Depth Fade distance): the particle fades over the last unit before the scene. A value at or below softNearFade cuts the particle off at that distance instead of fading it. A live parameter, like softNearFade.

      Parameters

      • v: number

      Returns void

    • get softNearFade(): number

      Distance in world units in front of the scene at which a soft particle is fully faded out, at least 0. Default 0. A live parameter: changing it on a system alone in its batch keeps the batch and its material (see VFXBatchSettings).

      Returns number

    • set softNearFade(v: number): void

      Distance in world units in front of the scene at which a soft particle is fully faded out, at least 0. Default 0. A live parameter: changing it on a system alone in its batch keeps the batch and its material (see VFXBatchSettings).

      Parameters

      • v: number

      Returns void

    • get softParticles(): boolean

      Fade particles out as they near the scene behind them (Unity's Soft Particles, Unreal's Depth Fade), between softNearFade and softFarFade. Needs a depth texture on the renderer, see BatchedRenderer.setDepthTexture; without one particles draw hard. Default false.

      Returns boolean

    • set softParticles(v: boolean): void

      Fade particles out as they near the scene behind them (Unity's Soft Particles, Unreal's Depth Fade), between softNearFade and softFarFade. Needs a depth texture on the renderer, see BatchedRenderer.setDepthTexture; without one particles draw hard. Default false.

      Parameters

      • v: boolean

      Returns void

    • get sortingFudge(): number

      How far behind other transparent objects the system is sorted, in world units: Unity's renderer Sorting Fudge. The renderer draws its transparent systems back to front by the distance from the camera to the centre of each one's bounds, among the scene's transparent meshes; this is added to that distance, so a positive fudge draws the system before (under) others nearer than it plus the fudge, and a negative one after (over) them, however near. An author uses it to keep a glow under the smoke and the smoke over the sparks whichever way the camera turns. Systems with different fudges draw from different batches. See quarksTransparentSortCompare. Default 0: by distance alone.

      Returns number

    • set sortingFudge(fudge: number): void

      How far behind other transparent objects the system is sorted, in world units: Unity's renderer Sorting Fudge. The renderer draws its transparent systems back to front by the distance from the camera to the centre of each one's bounds, among the scene's transparent meshes; this is added to that distance, so a positive fudge draws the system before (under) others nearer than it plus the fudge, and a negative one after (over) them, however near. An author uses it to keep a glow under the smoke and the smoke over the sparks whichever way the camera turns. Systems with different fudges draw from different batches. See quarksTransparentSortCompare. Default 0: by distance alone.

      Parameters

      • fudge: number

      Returns void

    • get sortMode(): SortMode

      The order this system's batch draws its particles in (Unity's Sort Mode), 'none' by default. Alpha blended smoke wants 'distance'; additive effects need nothing. Sorting covers the whole batch, so systems with different modes are batched apart. See SortMode.

      Returns SortMode

    • set sortMode(mode: SortMode): void

      The order this system's batch draws its particles in (Unity's Sort Mode), 'none' by default. Alpha blended smoke wants 'distance'; additive effects need nothing. Sorting covers the whole batch, so systems with different modes are batched apart. See SortMode.

      Parameters

      Returns void

    • get time(): number

      Seconds into the current emission cycle. Setting it jumps emission to that point, as Unity's Simulate(t) does for the emission clock: the bursts before it count as fired, the ones after are due again; particles alive stay, and behaviors are not reset. A value that is not a finite, non-negative number is 0; one past the duration wraps on a looping system and is the duration otherwise. A system whose emission has ended stays ended: restart plays it again.

      Returns number

    • set time(time: number): void

      Seconds into the current emission cycle. Setting it jumps emission to that point, as Unity's Simulate(t) does for the emission clock: the bursts before it count as fired, the ones after are due again; particles alive stay, and behaviors are not reset. A value that is not a finite, non-negative number is 0; one past the duration wraps on a looping system and is the duration otherwise. A system whose emission has ended stays ended: restart plays it again.

      Parameters

      • time: number

      Returns void

    • get timeDilation(): number

      A runtime multiplier on playbackSpeed that is not part of the effect: what a timeline, a slow-motion moment or a game's pause menu sets on a system it plays, like Unreal's Custom Time Dilation or Unity's VisualEffect.playRate. The system runs at playbackSpeed * timeDilation. 1 by default; never saved, cloned or loaded. A negative, NaN or infinite value is read as 0. A QuarksPrefab sets it to its timeScale on the systems of its tracks.

      Returns number

    • set timeDilation(dilation: number): void

      A runtime multiplier on playbackSpeed that is not part of the effect: what a timeline, a slow-motion moment or a game's pause menu sets on a system it plays, like Unreal's Custom Time Dilation or Unity's VisualEffect.playRate. The system runs at playbackSpeed * timeDilation. 1 by default; never saved, cloned or loaded. A negative, NaN or infinite value is read as 0. A QuarksPrefab sets it to its timeScale on the systems of its tracks.

      Parameters

      • dilation: number

      Returns void

    • get tint(): Color4Like | undefined

      Multiplies every particle's colour, alpha included, as it is drawn: a colour or a fade driven from code for this instance (Unity's custom per-instance data, Unreal's user parameters). With erosion, alpha is the erosion level, so this wipes the shape in and out. The particles' own colours are untouched, so clearing it restores them, and systems with different tints still batch together. Its alpha fades the particles in every blend mode that blends by coverage (see blendCategory). Unset (the default): none. Not saved in the effect JSON; copied by clone. Set it from any Color4Like, such as a Babylon Color4; the value is copied, so later edits to the object passed in do not reach the system until it is set again.

      Returns Color4Like | undefined

    • set tint(value: Color4Like | undefined): void

      Multiplies every particle's colour, alpha included, as it is drawn: a colour or a fade driven from code for this instance (Unity's custom per-instance data, Unreal's user parameters). With erosion, alpha is the erosion level, so this wipes the shape in and out. The particles' own colours are untouched, so clearing it restores them, and systems with different tints still batch together. Its alpha fades the particles in every blend mode that blends by coverage (see blendCategory). Unset (the default): none. Not saved in the effect JSON; copied by clone. Set it from any Color4Like, such as a Babylon Color4; the value is copied, so later edits to the object passed in do not reach the system until it is set again.

      Parameters

      Returns void

    • get transparent(): boolean

      Whether the particles draw in the transparent pass, blended by blending; false draws them opaque, with blending off. Default true, or the material's needAlphaBlending. Systems that differ are batched apart.

      Returns boolean

    • set transparent(transparent: boolean): void

      Whether the particles draw in the transparent pass, blended by blending; false draws them opaque, with blending off. Default true, or the material's needAlphaBlending. Systems that differ are batched apart.

      Parameters

      • transparent: boolean

      Returns void

    • get uTileCount(): number

      Columns of the flipbook in texture (Unity's Texture Sheet Animation tiles). With vTileCount, a particle draws one cell, picked by startTileIndex and FrameOverLife. A whole number of at least 1; anything else is 1. Default 1. Trails take their cell on the CPU, so a trail's texture is cut the same way.

      Returns number

    • set uTileCount(u: number): void

      Columns of the flipbook in texture (Unity's Texture Sheet Animation tiles). With vTileCount, a particle draws one cell, picked by startTileIndex and FrameOverLife. A whole number of at least 1; anything else is 1. Default 1. Trails take their cell on the CPU, so a trail's texture is cut the same way.

      Parameters

      • u: number

      Returns void

    • Calls callback on each event: 'emitEnd' when emission ends, 'finished' when the last particle of an ended system dies, 'particleDied' per particle (with event.particle), and 'destroy' on dispose.

      A 'particleDied' event and the particle on it are reused: read what you need inside the callback and keep neither, since the particle's slot goes to the next one spawned. In trail mode a particle dies when its trail is gone, so with a trail lifetime the event comes after the head stopped, once the last sample has faded.

      A callback added or removed while an event is firing takes effect from the next event; the callbacks of the one firing are all called.

      Parameters

      Returns void

    • Removes every particle alive and nothing else (Unity's Clear): emission goes on from where it is, paused stays paused, and the bursts and the random generator are not rewound. The sub emissions the removed particles were driving end with them; the child systems' own particles stay, and particleDied is not fired.

      Returns void

    • Drops every trail's recorded samples and keeps the particles (Unity's TrailRenderer.Clear): each ribbon starts over from where its particle is now. For a teleport: pause, move the emitter, play (so the move is not spread over the next frame's steps as motion) and call this, and no ribbon is drawn across the jump. Does nothing on the other render modes.

      Returns void

    • Removes the system from its renderer, disposes its emitter node (and the nodes under it) and fires destroy. A disposed system cannot be played again. Calling it twice is harmless.

      Returns void

    • World-space axis-aligned bounds of everything this system draws, padded for particle size, into min and max. False when the system has no particles, or none have been measured yet; the caller should then treat it as visible. Measured in full every few simulated steps and carried, padded for the motion since, in between: conservative, and at most a frame behind the display.

      Parameters

      Returns boolean

    • Whether the system still has particles or emission to come (Unity's IsAlive): not isFinished, or, with withSubEmitters (the default), any system it emits into through an EmitSubParticleSystem, and theirs, still has particles.

      Parameters

      • withSubEmitters: boolean = true

      Returns boolean

    • Clears every particle and starts the system from the beginning: emission time 0, bursts and the start delay rolled again, behaviors reset, and a seeded system's generator restarted, so it replays the same effect. Also unpauses it.

      Returns void

    • Scales how many particles the system emits, from 0.1 to 1 (values outside are clamped), for lower quality settings or a crowded frame; the renderer's adaptive performance sets it. It multiplies with emissionMultiplier. Default 1.

      Parameters

      • qualityFactor: number

      Returns void