Migration guide¶

This guide covers moving a project from the previous CPU-based particles plugin to the current Kanzi Particles. The two plugins share little code: the current plugin is a new GPU-based pipeline built around compute materials and a material-slot model, so migration is a rebuild rather than a port.

Work node by node, not property by property.

What changed, conceptually¶

The previous plugin modelled each behaviour as its own node type: a Particle Box Emitter was a different node from a Particle Sphere Emitter, a Particle Curl Affector from a Particle Force Affector, and so on. Shape and behaviour were baked into the node.

The current plugin collapses the taxonomy: every emitter is a single ParticleEmitter node, every affector a ParticleAffector, every collider a ParticleCollider. What the node does is decided by the materials assigned to its material slots. A box-shaped emitter is a ParticleEmitter with Emission Material set to Emitter_BoxVolume; a sphere-shaped emitter is the same node with Emitter_SphereVolume instead.

This has two practical consequences:

There’s no 1:1 property-rename table. Values that were node properties in the old plugin are now property types on an asset-package material, added explicitly to the node and read by that material’s compute shader.
The right mental model is pick the node, pick the material, set the material’s properties. See Particle system anatomy.

Read that page first before attempting any migration.

Node taxonomy mapping¶

Previous emitter node → current node + material¶

Previous node	Current node	Current Emission Material
`Particle Box Emitter`	`ParticleEmitter`	`Emitter_BoxVolume` (inside box) or `Emitter_BoxSurface` (on box surface).
`Particle Sphere Emitter`	`ParticleEmitter`	`Emitter_SphereVolume` or `Emitter_SphereSurface`.
`Particle Mesh Emitter`	`ParticleEmitter`	`Emitter_MeshSurface`, `Emitter_MeshVertices`, or `Emitter_MeshEdges`. Assign the emitter node’s `Mesh` property to the source mesh. See Emission.
`Particle Trail Emitter`	`ParticleEmitter` (subemitter)	Rebuild as a subemitter driven by events. Source emitter carries `Event_Lifetime` or `Event_VelocityRange`; subemitter uses `Emitter_FromEvents`. See Events and subemitters.
`Particle Custom Emitter`	`ParticleEmitter`	Author a custom emission material. See Writing custom compute materials.

Previous affector node → current node + material¶

Previous node	Current node	Current Affector Material
`Particle Curl Affector`	`ParticleAffector`	`Affector_CurlNoise`.
`Particle Drag Affector`	`ParticleAffector`	`Affector_Drag`.
`Particle Force Affector`	`ParticleAffector`	`Affector_Directional` (constant world-space direction) or `Affector_Gravity` (downward). For per-emitter forces that previously lived on an emitter’s internal “force” settings, use a self-affector: assign to `ParticleEmitter.SelfAffectMaterial` instead of a separate affector node.
`Particle Point Affector`	`ParticleAffector`	`Affector_PointAttractor`.
`Particle Custom Affector`	`ParticleAffector`	Author a custom affector material. See Writing custom compute materials.

Previous collider node → current node + material¶

Previous node	Current node	Current Collider Material
`Particle Wall Collider`	`ParticleCollider`	`Collider_Plane` (infinite plane) or `Collider_Box` (finite box wall). Orientation comes from the node transform.

Property migration¶

Old-plugin node properties do not carry over by name. They fall into three categories:

Shape parameters (box dimensions, sphere radius): now come from the node’s world transform on the ParticleEmitter / ParticleCollider node. Set the node’s scale to control the volume.
Shape parameters with their own property type (Emission.OuterRadius, Emission.InnerConeAngle): added as explicit properties on the node after selecting the material that consumes them. Not auto-added.
Behaviour parameters (gravity strength, drag coefficient, curl frequency): now asset-package property types under the Affector.* namespace, read by the corresponding affector material. Add the property types to the ParticleAffector node; their defaults are set on the property type itself (see Particle editor reference).

Rendering migration¶

The old plugin’s built-in colour-over-lifetime and velocity-colour effects are now particle-rendering material instances under ParticleEmitter.ParticleMaterial. Map by visual intent:

Previous behaviour	Current material
Linear colour ramp over lifetime	`ParticlesColorOverLife` (with `ParticlesColorOverLife_Green` / `_Red` as ready-to-use tinted variants).
3-stop colour ramp over lifetime	`ParticlesColorOverLife3Stop`.
Speed-based colour	`ParticlesVelocityColor`.
Mesh-instanced 3D particles	Assign a mesh to Particle Mesh on the emitter and a conventional Kanzi material to Particle Material. Leaving Particle Mesh unset renders camera-facing 2D billboards with the default 2D particle material. No stock 3D rendering material ships.

Subemitters and events¶

The previous plugin had no general equivalent of the current event / subemitter system. The old Particle Trail Emitter offered a limited subemitter-like behaviour (trail particles following a source), but the general “particles that spawn particles when they die, collide, or cross a lifetime / velocity threshold” capability is new. See Events and subemitters for the full walkthrough.

Suggested migration order¶

Re-read Particle system anatomy and Emission to internalise the slot model.
Identify every previous particle node in your project. Group by intent (one fountain, one explosion, one smoke column) rather than by old node type.
For each effect, create a new ParticleSystem with child ParticleEmitter, ParticleAffector, ParticleCollider nodes as needed. Assign stock materials per the tables above.
Add the asset-package property types each assigned material consumes (check the material’s row in Particle editor reference).
Port custom shaders last: see Writing custom compute materials for the authoring workflow.
Once the new effect visually matches the old one, delete the old nodes.