Particle system anatomy

A Kanzi Particles effect is built from four node types arranged in a strict hierarchy, each of which takes one or more compute materials in its material slots. This page introduces the node types, the slot pattern they share, and the rules for how they compose. Every other topic page in Working with… builds on this model: read it first.

The four node types

Node	Role
ParticleSystem	Container for one particle effect. Owns simulation-wide settings (framerate, integrator) and hosts emitter, affector, and collider children.
ParticleEmitter	Spawns particles and renders them. Almost every aspect of its behaviour (where particles appear, how many appear, how they are drawn, what events they emit) is driven by the materials assigned to its slots.
ParticleAffector	Modifies every live particle in the system each frame. Typical uses: gravity, wind, drag, directional force, kill zones.
ParticleCollider	Prevents particles from entering a shape, with configurable bounce and friction.

All four nodes become available under Create after you load the Kanzi Particles plugin into your Kanzi Studio project. See Setting up Kanzi Particles.

The material-slot pattern

Every behavioural concern in Kanzi Particles is expressed as a compute material assigned to a slot on one of the nodes above. A compute material is an ordinary Kanzi material whose material type uses a compute shader in place of the usual vertex/fragment stages. The plugin ships a library of stock compute materials in the ParticlesAssetPackage Kanzi Studio project: import the ones you need into your project (see Setting up Kanzi Particles) and assign them to slots.

This gives two levels of customisation:

• Pick a stock material. Choose from the catalogs in Emission, Affectors, Colliders, Events and subemitters, and Particle rendering materials. No shader work required.

• Author your own compute material. Copy a stock material type, replace its compute shader, and expose the uniforms you want designers to tune. See Writing custom compute materials.

The slots themselves are plain ResourceID properties of type Material on the node. Setting a slot is the same UI gesture as setting any other material reference.

ParticleSystem

The container node. Holds simulation-wide settings and parents the emitter, affector, and collider nodes that make up the effect.

Plugin-defined properties:

• Framerate: simulation steps per second. Higher values improve accuracy at increased cost.

• Integration Method: Euler or Verlet. Verlet conserves energy better and is the default.

• Sorting Camera Override: optional path to a camera used for depth-sort key computation. If empty, uses the scene’s default camera.

ParticleSystem has no material slots of its own. Materials are assigned on the child nodes.

ParticleEmitter

A source of particles. Every ParticleEmitter owns a fixed-size GPU particle pool sized by Maximum Amount and takes materials in five slots that together define the emitter’s full behaviour.

Material slots:

• EmissionMaterial: where and how a new particle is initialised (position, velocity, initial scale, initial lifetime). One invocation per spawn.

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

• SelfAffectMaterial: an optional affector that runs only over this emitter’s own particles each frame, before the particle-system-wide affectors.

• GenerateEventsMaterial: optional. Runs once per live particle per frame and writes events (e.g. on death, on hit, while in a lifetime range) into the emitter’s event buffer. Subemitters consume these; see Events and subemitters.

• ParticleMaterial: the render material used to draw the particles.

Other plugin-defined properties:

• Maximum Amount: upper bound on live particles. Sizes the GPU buffer. If the total live particles would exceed this value, emission stalls once the cap is hit. See Sizing MaximumAmount.

• Particle Mesh: optional mesh instanced per particle. Leave unset to render camera-facing 2D billboards using the default 2D particle material; assign a mesh to render each particle as that mesh.

• Sorting Type: Identity, Depth, Reverse Depth, or Unsorted. See Sort type selection.

• Event Buffer, Particle Data Buffer: read-only output buffers populated by the engine. Other emitters read from them via binding to act as subemitters.

The plugin-defined properties are always present on every ParticleEmitter. The asset-package properties read by the assigned materials (Emission.AmountPerSecond, Emission.OuterRadius, and so on) are not auto-added: you add the ones the selected material needs to the emitter node explicitly. Emission lists the expected properties per stock material.

ParticleAffector

Applies a per-frame force or transformation to every particle in the enclosing ParticleSystem, regardless of which emitter spawned it. Use multiple ParticleAffector children to stack effects (e.g. gravity plus wind plus a kill zone).

Material slots:

• AffectorMaterial: the compute shader that, for each particle, mutates state through accessor helpers (add an acceleration / force, set velocity, kill, etc.). Runs once per particle per frame, after SelfAffectMaterial and before integration.

A ParticleAffector has no plugin-defined tuning properties of its own: its behaviour is driven entirely by the chosen affector material and the corresponding Affector.* properties added to the node. See Affectors.

The affector node’s transform is available to the shader via getAffectorTransform(), so you can reposition the affector in the scene to change its region of influence (e.g. move a KillZone or recentre a PointAttractor).

For an affector that runs only over one emitter’s particles, use that emitter’s SelfAffectMaterial slot instead of a separate ParticleAffector node.

ParticleCollider

Defines a collision volume that every particle in the system is tested against after integration. The collider’s transform positions and orients the shape.

Material slots:

• ColliderMaterial: the compute shader that implements the geometric hit test. The collider template handles the physical response (reflect velocity, apply bounce and friction, advance remaining sub-step time); the material only answers “did this particle penetrate my surface, and if so, where and along what normal?”

Plugin-defined properties:

• Bounce: coefficient of restitution [0..1]. 0 is inelastic, 1 is perfectly elastic. Default 0.5.

• Friction: tangential velocity damping [0..1]. 0 is frictionless, 1 is full stop along the surface. Default 0.1.

Asset-package properties control the collider shape dimensions (Collider.Radius, Collider.Height, Collider.Angle) and are added per the selected ColliderMaterial. See Colliders.

How the nodes compose

Parent/child rules:

• ParticleSystem is the root of an effect. It can be placed anywhere under Scene that accepts a 3D node.

• ParticleEmitter, ParticleAffector, and ParticleCollider must be children of a ParticleSystem. A ParticleSystem has one or more ParticleEmitter children and zero or more of the other two.

• A ParticleSystem may contain another ParticleSystem as a descendant (useful for grouping). Any non-particle node (EmptyNode, Model3D, and so on) is also permitted between particle nodes in the tree; the particle system treats every non-particle node as a transparent grouping wrapper even if it has rendering or other behaviour of its own. A typical use is grouping a source emitter with its subemitter so the pair moves together; see Events and subemitters.

• Effects that involve a subemitter reading another emitter’s events are still a single ParticleSystem: you do not need separate systems. The subemitter is a second ParticleEmitter child of the same ParticleSystem, bound to the first emitter’s EventBuffer.

Scope rules:

• A ParticleAffector affects every particle in its enclosing ParticleSystem, across all emitters. For single-emitter scope, use that emitter’s SelfAffectMaterial slot.

• A ParticleCollider affects every particle in its enclosing ParticleSystem.

• Scope stops at a nested ParticleSystem. Emitters, affectors, and colliders inside a child ParticleSystem are not in scope of the parent: the child system has its own pools and its own affector / collider set. Use nested systems when you want independent simulations; use grouping nodes (see above) when you want one simulation that travels together.

• ParticleEmitter particle pools are per-emitter: two emitters in the same system do not share a pool, and each has its own Maximum Amount.

A minimal scene tree

The smallest useful scene tree with one emitter, one gravity affector, and a ground-plane collider:

Scene
└── ParticleSystem
    ├── ParticleEmitter        (EmissionMaterial, EmissionCountMaterial, ParticleMaterial assigned)
    ├── ParticleAffector       (AffectorMaterial = Gravity)
    └── ParticleCollider       (ColliderMaterial = Plane)

A subemitter setup (e.g. sparks on collision) adds a second emitter and a grouping node so the source emitter and its subemitter can move together:

Scene
└── ParticleSystem
    ├── EmptyNode
    │   ├── ParticleEmitter    (source; EmissionMaterial, EmissionCountMaterial,
    │   │                        GenerateEventsMaterial = OnHit)
    │   └── ParticleEmitter    (subemitter; EmissionCountMaterial = FromEvents,
    │                           EmissionMaterial = Sparks_FromHit, bound to source.EventBuffer)
    ├── ParticleAffector
    └── ParticleCollider

See Events and subemitters for the full binding recipe.

See also

• Emission

• Affectors

• Colliders

• Events and subemitters

• Writing custom compute materials

• Particle rendering materials