explosion

A turbulent fireball with a rising smoke column, thrown debris and a flash of light. One asset, sized in metres, so the same explosion reads as a hand grenade at 1.5 and as a fuel tanker at 6.

The fireball is a sphere carrying a ridged-fBm field from the shared effects WGSL: the field eats the silhouette away as the blast ages while the colour walks white-hot → core → smoke. Around it, an additive burst of embers reads as the flash itself, an alpha-blended column of smoke rises and spreads for the rest of the duration, and solid debris is thrown outward and falls under gravity. A point light fires with the fireball and decays much faster than the fire that threw it.

local blast = asset.ref("@builtin::systems.effects.combat.explosion", "effect")
blast:play { position = { 0, 2, 0 }, params = { scale = 1.5 } }

Parameters

A parameter outside its range is held at the bound and the holding is reported. A name the effect does not declare raises, and names the ones it does.

Cost

Quoted from the cost block of effect.yaml, which is the declaration describe().cost returns and a cost suite reads. That block is the source these numbers are copied from.

The span is the difference between the frame's GPU span with the blast on screen and without it, taken as the best of forty samples at each end (profiler.gpuFrame().frame_span_ms: 5.437 ms idle, 5.546 ms with the blast). The size is the renderer.gpuMemory() delta across the same play — 327,436 bytes of compute state and 371,984 bytes of emitter geometry.

play here is the unpooled reference path: it allocates its emitters on the call and frees them when the blast finishes, so the figures above are what one blast costs on its own.

A finished blast returns its compute state to where it stood, whether it is stopped by hand or left to expire on its own clock. Its emitter geometry can stay allocated afterwards — 288,800 bytes, the two sprite emitters' vertex buffers at 760 bytes per declared slot — so a scene firing blasts in a loop is worth watching through renderer.gpuMemory().

The three emitters allocate for their declared slot counts — 160 embers, 220 smoke, and 26 debris per unit of debrisDensity — and GPU memory follows the declared count, not the live one. A wider blast spends its radius on size and speed rather than on more particles, so the VRAM figure is the same at 1.5 metres and at 12.

What it draws with

The material is one instance shared by every explosion on screen. What separates one blast from another travels on each fireball entity's own instance-data lanes, not in a material per blast. Neither asset declares a texture or a storage buffer, so the effect adds nothing to a frame's bind budget.

The handle

local h = blast:play { position = { 0, 2, 0 }, params = { scale = 3.5 } }
h.duration            -- seconds until it finishes on its own
h.stats()             -- { age, duration, radius, fireballRadius, debrisEmitted,
                      --   emitters, particlesAlive, lightIntensity, finished }
h.stop()              -- end it now and release everything
h.isFinished()

Started with held = true, the blast stands still at time zero and h.seek(t) drives it forward in fixed steps — the same sequence of seeks producing the same frames every time, which is what a screenshot or a probe needs. Seeks run forward only: the emitters simulate in steps and have no reverse, so a target behind the blast's own clock raises. Read an earlier instant by playing again and seeking to it.

Everything a play spawns is marked temporary, so an explosion that goes off while somebody is authoring cannot end up in a saved scene.

See also

• guides { path: "topics/visual-effects" } — finding, playing and parameterising effects.
• man /zero/source/libs/@builtin/assetTypes/effect.assetType — what an effect asset carries.
• @builtin::systems.effects.demo.explosion_showcase — the demo scene, which fires all three sizes on a loop with no setup.