Emission

Emission is how a ParticleEmitter spawns particles. It is split across two material slots:

  • EmissionMaterial: where and how each new particle is initialised. Runs once per spawn and fills in position, velocity, scale, and lifetime.

  • EmissionCountMaterial: how many particles to spawn this frame. Runs once per frame and writes the count into an indirect-emit buffer that EmissionMaterial then dispatches against.

This page catalogs the stock materials for both slots, explains the Maximum Amount cap and how to bind it, and points at the related pages for events and rendering.

Note

Before the property sliders described below appear in the Properties panel, you must add the matching Emission.* property types to the emitter node (+ Add Property → search “Emission”). Plugin-defined properties such as Maximum Amount are present automatically; asset-package properties are not. See Getting started with Kanzi Particles.

Emission materials

Stock EmissionMaterial assets live under ParticlesAssetPackage/Materials/Particles/. Pick one, import it into your project (see Setting up Kanzi Particles), and assign it to the emitter’s Emission Material slot.

Every shape emitter exposes the same common property contract — lifetime, scale, initial velocity, rotation, angular velocity, and density — with consistent names and defaults, plus a shape-specific size parameter. A default-configured emitter spawns a uniform sphere of velocity directions at unit scale and unit density; cone, fountain, and equatorial-disc patterns all fall out of the velocity inner/outer angle properties (see Common property contract below).

Shape emitters

Each shape emitter carries a Volume bool that selects between surface emission (spawn on the boundary) and volume emission (spawn throughout the interior). Point is the exception — a zero-extent spawn with no Volume toggle.

Tip

Every shape below also ships as a drop-in prefab under Asset Packages → ParticlesAssetPackage → Prefabs (BoxEmitter, SphereEmitter, DiscEmitter, TorusEmitter, PointEmitter). The prefab wraps the emission material, an EmissionCount_Schedule, and a ParticleEmitter with every property below already lifted to the prefab root — no manual material import. See Starting with templates.

Box

Emits from the surface or interior of a box. Box Extents are half-extents per axis, so (0.5, 0.5, 0.5) is a unit box.

Sphere

Emits from the surface or interior of a sphere. Radius sets the size.

Disc

Emits from an annulus in the emitter’s local XZ plane. Outer Radius and Inner Radius define the ring. With Volume off, particles spawn on the inner/outer edges; with it on, they fill the annular face.

Torus

Emits from the surface or interior of a torus lying in the emitter’s local XZ plane. Major Radius is the distance from the torus centre to the tube centre; Minor Radius is the tube radius.

Point

A zero-extent spawn at the emitter origin — every particle originates from a single point and the velocity angle properties shape the spray. Replaces the legacy Cone and Fountain materials:

  • Cone of half-angle θ: Initial Velocity Outer Angle = θ, Initial Velocity Inner Angle = 0.

  • Fountain / hose nozzle: Initial Velocity Inner Angle = θ₁, Initial Velocity Outer Angle = θ₂.

  • Equatorial spray: both angles ≈ π/2.

Common property contract

All five shape emitters expose these properties. Each Variance value is a symmetric ± band applied per particle.

Property

Type

Default

Notes

Lifetime / Lifetime Variance

float

1.0 / 0.0

Particle lifetime in seconds.

Scale / Scale Variance

vec3

(1,1,1) / (0,0,0)

Per-particle scale.

Initial Velocity Strength / … Variance

float

1.0 / 0.0

Speed magnitude band.

Initial Velocity Direction

vec3

(0, 0, 1)

Cone axis, emitter-local. Normalised in the shader; (0,0,0) is treated as (0,0,1).

Initial Velocity Inner Angle

float (rad)

0

Inner edge of the annular spherical cap, clamped to [0, π].

Initial Velocity Outer Angle

float (rad)

π

Outer edge, clamped to [0, π]. The default π gives a full uniform sphere.

Initial Velocity Orient To Normal

bool

true

Surface emission only: reinterprets Direction in a frame where +Z is the spawn surface normal. Ignored when Volume = true.

Initial Rotation / … Variance

vec3 (rad)

(0,0,0)

Starting Euler orientation around emitter-local X/Y/Z.

Initial Angular Velocity / … Variance

vec3 (rad/s)

(0,0,0)

Spin rate around emitter-local X/Y/Z.

Density

float

1.0

Per-particle mass = Density × volume(Scale). There is no Density Variance — mass variance flows through Scale Variance.

Velocity directions are sampled uniformly over the spherical cap between Initial Velocity Inner Angle and Initial Velocity Outer Angle (cosine-weighted for correct solid-angle coverage). Examples: (0, π) = uniform sphere, (0, θ) = solid cone of half-angle θ, (θ₁, θ₂) = hose-nozzle fountain, (π/2−ε, π/2+ε) = thin equatorial disc.

Event-driven emitters

Used when the emitter is acting as a subemitter: its spawn position and timing come from events written by another emitter’s GenerateEventsMaterial. Pair with EmissionCount_FromEvents (see below) and bind Emission.SourceEventBuffer / Emission.SourceParticleDataBuffer to the source emitter. See Events and subemitters for the full wiring.

FromEvents

Spawns each particle at the position of the source particle that generated the event (the hit position when the event came from a collision, otherwise the parent’s current position). Beyond the spawn position, FromEvents also exposes the full Common property contract — the spawned child gets its own velocity, scale, rotation, lifetime, and density just like a shape emitter, so a default-configured FromEvents behaves like an Emitter_Point placed at the event position.

In addition to the common contract, FromEvents exposes a parent-inheritance overlay that lets a child mix in the parent particle’s own state. See Parent inheritance (FromEvents only) below.

Initial Velocity Orient To Normal is reinterpreted for FromEvents: the “normal” is the parent particle’s velocity vector, so when the flag is on, the cone built from Initial Velocity Inner Angle / Outer Angle opens around the direction the parent was moving — sparks that fan out behind a primary particle, splashes that follow the impact trajectory. A zero parent velocity falls back to local +Z.

Sparks_FromHit

Scatters spark particles from collision hit points, with variance on lifetime and scale and a configurable bias toward the surface normal.

Key properties: Lifetime, Lifetime Variance, Particle Scale, Scale Variance, Scatter Speed, Normal Bias.

Parent inheritance (FromEvents only)

A FromEvents child has access to its parent particle (the one that generated the event) and can pull individual values from it. Each inheritable property has a paired float weight whose default is 0 — at the defaults the child is purely local, identical to an Emitter_Point at the event position. Raise a weight to mix the parent’s same-named value into the spawned child.

Blend formula per property (default form, additive):

Final = Parent × FromParent + LocalSample

Where LocalSample is the value the common contract would have produced on its own. To inherit the parent’s value verbatim under the additive form, set the corresponding FromParent weight to 1 and zero the local contribution. Velocity and scale use different forms — see the exceptions below the table.

Inheritance weight

Parent field read

Type

Initial Velocity Strength From Parent

parent speed (length(velocity))

float weight applied to scalar speed

Lifetime From Parent

parent total lifetime

float weight applied to float

Scale From Parent

parent scale

float weight on a multiplicative factor (vec3)

Initial Rotation From Parent

parent rotation

float weight applied to vec3

Initial Angular Velocity From Parent

parent angular velocity

float weight applied to vec3

Variance is purely local — the parent is a single concrete state, not a distribution, so there is no parent-side variance.

Note

Velocity is direction-vs-speed split. Initial Velocity Strength From Parent only blends the parent’s speed into the child’s speed. The child’s direction always comes from the local cone sample around either Initial Velocity Direction or the OrientToNormal frame. To inherit the parent’s direction too, turn Initial Velocity Orient To Normal on so the cone axis becomes the parent’s velocity direction; combine with a narrow Initial Velocity Outer Angle for tight inheritance, a wide one for fan-out around the parent’s path.

Note

Scale is multiplicative. Scale is a multiplier on a 1-unit base, so the natural blend is on a factor:

Final = LocalSample × mix(1, ParentScale, ScaleFromParent)

Scale From Parent = 0 keeps pure local scale; = 1 makes the child’s scale local × parent. Because the local Scale default is (1, 1, 1), setting Scale From Parent = 1 alone is enough to make the child match the parent’s scale exactly — no zeroing of the local term required.

Worked example: death-spawn velocity inheritance. A primary emitter generates an Event_Lifetime event on death (defaults fire on death). A FromEvents subemitter spawns one child per event. To make each child continue along the parent’s death trajectory — sparks that fly off in the direction the parent was moving — set:

  • Initial Velocity Orient To Normal = true (cone axis = parent direction)

  • Initial Velocity Inner Angle = Initial Velocity Outer Angle = 0 (no spread)

  • Initial Velocity Strength From Parent = 1.0

  • Initial Velocity Strength = 0 (and … Variance = 0)

The child inherits the parent’s velocity verbatim. Widen the outer angle to fan children out behind the parent. Lower the weight (e.g. 0.5) to inherit only half the parent’s speed.

Worked example: spawn-time variance with parent bias. A burst of debris that mostly scatters locally but carries a hint of the parent’s speed:

Initial Velocity Strength             = 3.0
Initial Velocity Outer Angle          = π
Initial Velocity Strength From Parent = 0.2

Each child gets a uniform-sphere direction at speed 3 plus 20% of the parent’s speed along the same direction.

Emission-count materials

Stock EmissionCountMaterial assets live alongside the emission materials. Assign one to the emitter’s Emission Count Material slot, then add the Emission.* property it reads.

Schedule

The unified time-based count material. A cycle of length On Duration + Off Duration runs on the emitter: during the on-phase it accumulates at Rate particles/second, and at the start of each cycle an optional Impulse At Cycle Start burst fires. Subsumes the legacy PerSecond, Periodic, and Burst materials.

Reads: Emission.Rate, Emission.RateVariance, Emission.OnDuration, Emission.OffDuration, Emission.ImpulseAtCycleStart, Emission.ImpulseVariance, Emission.Seed.

Preset configurations:

Behaviour

Settings

Replaces

Steady stream

Rate = R, On Duration = 0, Off Duration = 0

PerSecond

Periodic stream

Rate, On Duration, Off Duration

Periodic

Recurring burst

Impulse At Cycle Start = N, On Duration = 0, Off Duration = T

Burst (N every T s)

One-shot at spawn

Impulse At Cycle Start = N, Off Duration = a large value (e.g. 1e10)

(new)

Algorithm. Each frame: roll the effective rate r = Rate ± RateVariance; advance a cycle timer cycleTimer = (cycleTimer + dt) mod (OnDuration + OffDuration); if the timer wrapped — or on the first frame — fire the impulse ImpulseAtCycleStart ± ImpulseVariance; if in the on-phase (cycleTimer < OnDuration, or always when both durations are 0) accumulate r × dt. Whole particles are emitted and the fractional remainder carries to the next frame.

Variance and Seed. Rate Variance is rolled per frame; Impulse Variance is rolled per cycle. Both draw from a per-emitter RNG seeded by Seed. Two emitters with the same Seed produce identical, repeatable sequences; give them different Seed values to decorrelate.

Note

One-shot at spawn needs no sentinel toggle — a very large Off Duration simply means the cycle never repeats within the effect’s lifetime, so the cycle-start impulse fires exactly once. This mirrors the “Max” convention used by the Event_* predicates.

PerEvent

Spawns Particles Per Event particles for every event received from a bound source emitter. Use together with an event-driven EmissionMaterial (Sparks_FromHit, FromEvents).

Reads: Emission.ParticlesPerEvent.

FromEvents

Spawns one particle per event received, multiplied by Particles Per Event (1 for a 1:1 mapping). Canonical count material for subemitters.

Reads: Emission.ParticlesPerEvent.

Sizing MaximumAmount

Every ParticleEmitter has a Maximum Amount property that sizes its GPU particle pool. It is a hard upper bound on live particles: once the pool is full, emission stalls until older particles die and free up slots.

For smooth emission, keep Maximum Amount ≥ expected peak live-particle count. Because the peak depends on the emission-count material, it is convenient to bind Maximum Amount to an expression over the Emission.* properties so the cap tracks the rate.

Recommended binding target: ParticleEmitter.MaximumAmount. Suggested source expressions per count material:

Count material

Suggested MaximumAmount expression

Notes

Schedule (steady / periodic)

{./Emission.Rate} * {./Emission.Lifetime}

Covers a full refresh of the pool at the current rate. An off-phase lowers the average but not the peak.

Schedule (recurring burst)

{./Emission.ImpulseAtCycleStart}

One burst’s worth. Add headroom if bursts overlap (short Off Duration relative to Lifetime).

PerEvent / FromEvents

See notes

The peak depends on the source emitter’s event rate, not on this emitter’s own properties. Size against expected events/sec × particles-per-event × lifetime; the source emitter’s binding recipe gives the event rate.

Tip

Worked example: Schedule emitter as a steady stream. Set Emission.Rate to 500 and Emission.Lifetime to 2 s. Create a binding on the emitter with Target = ParticleEmitter.MaximumAmount and Source Expression = {./Emission.Rate} * {./Emission.Lifetime}. Maximum Amount tracks to 1000 and follows any runtime change to either input.

For deeper guidance on balancing Maximum Amount against memory and bandwidth cost, see Sizing MaximumAmount.

See also