Drawing particles

A particle effect is an asset an author drops onto an entity, exactly as a mesh is. Six pieces, each owned by whoever knows the fact it carries:

⚠ The extraction is the only thing that steps a simulation. ParticleRenderFeature draws what it has been handed and never advances it, deliberately — a renderer that simulated would simulate once per view. So an effect created by hand, outside the component path, is one somebody has to step.

⚠ The opcodes are world-space and there is no emitter transform. PositionInSphere carries a centre, not an offset. What makes one .vxvfx serve twenty entities is VfxSystem.Origin, which the extraction writes from the entity's WorldTransform — and which is read at spawn, so moving an emitter moves where the next particles appear and leaves the live ones where they are. That is what a torch carried across a room does to its smoke.

Anything whose geometry is different every frame and is not a mesh: embers, sparks, smoke, dust, tracers, a trail behind a projectile.

You do not want it for a shadow stage. A camera-facing quad faces a camera, and the expansion happens once for the whole frame against ParticleRenderFeature.View — so a cascade drawing the same quads draws them edge-on to its own light. You do not want it in a velocity stage either: a particle has no previous world matrix, so there is nothing for a motion-vector pass to difference.

One. A stage for them, in the .vxcompositor. Additive or premultiplied, depth-tested but not depth-writing, and nothing culled:

Two. A pass that draws it. A pass of its own rather than a second child of the opaque one, if that pass writes more than one colour target: ParticleSprite returns a single value, and a pipeline built for two attachments leaves the second undefined.

Drawing into the HDR target rather than the swapchain is what puts the particles through the tonemap and the bloom — which is what makes an emissive value in cd/m² mean anything.

Three. Name that stage where the host can find it, and point the feature at the camera:

⚠ ParticleStage is not a CasterStages entry. Those are stages a mesh is extracted into *as well as* the opaque one; this is where emitters are drawn and no mesh ever is. Putting it in the caster list would draw the camera's billboards into every shadow cascade, edge-on to the sun.

⚠ View is not optional in a frame with shadows in it. Left unset the feature takes Views[0], which is whichever view the !ShadowMap node registered first.

⚠ A particle material goes through WorldRenderer.ParticleMaterials, not Materials. A sub-feature has exactly one owner — RootRenderFeature.Add refuses a second — and ParticleRenderFeature.Draw asks its material sub-feature which variant each object resolves to, skipping any object with no answer. A material assigned through the mesh path therefore leaves an effect that expands its quads every frame and draws none of them, silently. The two features hold separate variant caches and separate uniform blocks, which is the honest consequence.

Four. Put the component on an entity — in the editor, or in the scene file:

[AssetType(typeof(VfxEffectContent))] on VfxEmitter.Effect is what makes the inspector row a picker for effects rather than for anything in the project, and what makes a dragged .vxvfx a legal drop. Nothing else is needed: WorldRenderer.Mount builds the source, Register adds the bridge, and the bridge does the rest.

⚠ reach is the bound the frustum culls against, and nothing recomputes it. A particle outside it does not vanish on its own — the whole effect does, because culling is per render object. It has to cover where the drift can get to rather than where the particles are now.

⚠ Leave seed at zero unless the frames have to be reproducible. The bridge derives one from the entity, so two lamps of one effect are two different fires rather than one repeated twice. Writing a seed down is what a test that renders N frames twice wants.

An effect whose output is Vfx/Output/Mesh draws an instance of a mesh per live particle instead of a quad — debris, shards, chunks of rock. It takes one extra field on the emitter and nothing else:

VfxEmitter.Mesh is the emitter's rather than the effect's, for the reason the material is the host's: a .vxvfx says how particles move, and the same debris effect is reused for the rock, the crate and the glass. It is read only where the graph's renderer is a mesh one, so setting it on a billboard effect costs nothing and claims nothing.

Three things happen behind it, and each is a place a mesh effect used to go quiet:

⚠ A mesh effect needs its own material, not the sprite one. ParticleSprite reads a position, a texture coordinate and a colour out of one buffer; ParticleMesh reads a position out of the mesh's buffer and a transform out of an instance stream. WorldRenderer.MeshParticleMaterial is the shipped one and is what VfxExtractionSystem.MeshMaterial is set from — a mesh effect drawn with the sprite material is a pipeline with nothing to bind the instance stream to.

⚠ The geometry goes through the same GeometryResidency the scene's meshes do. A rock drawn as scenery and the same rock drawn as debris are one upload and two claims. What that costs is that a mesh effect waits for its geometry exactly as a MeshRenderable does — it shows up in VfxExtractionSystem.Waiting until the load lands.

⚠ Meshless is the counter to read when nothing appears. A mesh effect draws nothing when its emitter named no mesh and when the host never set Meshes or Residency, and the two frames look identical. Running minus Meshless is what is actually drawing; Dropped is the third case, a mesh that did not fit in the buffer.

⚠ Unlit, deliberately. ParticleMesh returns colour × tint × emissive and nothing else. A shaded mesh particle means a normal, a cluster list and a shadow lookup — which is the surface material path's job — and is owed rather than approximated here.

The effect itself, as the editor writes it — a chain of blocks whose wire is order, not data:

⚠ Centre is an offset from the emitter, not a place in the level — see the origin note above. An effect authored with a level's coordinates in it works for exactly one entity.

⚠ This reader will not take a comment on the line after a flow sequence, which is why the values above are block style. Rate: [6] parses; a comment on the next line does not.

The material, when a project wants something other than the default. WorldRenderer.ParticleMaterial is ParticleSpriteMaterial.Default() — composed the way a non-surface pass has to be, and with every parameter set — so most projects change one number rather than building one:

emissive is in the scene's own photometric units, not a 0..1 opacity: a spark that is to bloom has to be brighter than the bloom's threshold, which in a physically lit frame is in the thousands.

Build the material through ParticleSpriteMaterial.Default(), not with new Material(...), so that "what a particle material starts as" has one answer.

⚠ A parameter no one sets is written as zero, and a shader's declared default only saves you if the generated key carries it. EffectConstants fills each member of a block from the host's value or from ParameterKey.DefaultBytes. Raven reported a default only for scalars until recently — a scalar's is a literal and a vector's is a construction — so ParticleSprite.tint arrived as (0, 0, 0, 0): black, alpha zero, invisible under an additive blend, with every counter reporting a healthy frame. Bloom.texelSize had the same declaration and never showed it, because that renderer writes the parameter every frame. Both carry their defaults now.

An effect built in code, for a game that makes one at run time rather than authoring it. ⚠ Nothing steps this one — that is the extraction's job, and an effect outside the component path has none:

⚠ Integrate last. The updaters above it write velocity and this turns velocity into position; first, every particle moves on the previous step's forces.

The working example is Samples/13-ThirdPersonShooter: Assets/Effects/Embers.vxvfx is the graph, every lamp in Assets/Scenes/Arena.vxscene carries one !VfxEmitter line, and Frame.vxcompositor has the Embers stage and the Sparks pass. There is no per-lamp code at all.

• The lit path — where set 0, set 1 and set 2 come from, which is the same division the particle pipeline reads them under.
• Making everything cast a shadow — the other reason a schema matches attributes by name rather than by location.
• Core/Vixen.Vfx/README.md — the simulation itself: the opcodes, the attributes each one needs, and the GPU path that will one day replace the CPU expansion.