What goes in, what comes out
- In a .pyro.toml spec
- A TOML file that describes the simulated box, one or more emitters, the solver, the look, the camera views and the export settings. Every field you leave out takes its default.
- Out sheets
- Flipbook sheets with many animation frames packed into one image, ready for a game engine. Two sheets carry the six lighting directions, and two more carry flame color, motion and depth.
- Out previews
- A preview strip and a contact sheet for an agent to open, and an animated preview that plays the clip at true speed in any browser.
- Out JSON report
bake_report.jsonlists every file, the clip metrics and any warnings, and each warning names the setting to change.
The docs list every file a bake writes and every report field.
Six example bakes
Pyro ships six examples, and all six bake at final quality with no warnings. Each card shows an excerpt of the example spec.
fire.pyro.toml LOOP
A steady ground fire about a meter and a half across, which loops.
[[emitters]]
shape = "disc"
position_m = [0, 0.15, 0]
size_m = 0.7
start_s = 0.0
end_s = 1000
fuel = 6
temperature_k = 1500
smoke = 0.2
velocity_mps = 1.5
direction = "up"
fireball.pyro.toml ONE-SHOT
A ground burst that swells, rolls and rises.
[[emitters]]
shape = "sphere"
position_m = [0, 0.7, 0]
size_m = 1.2
start_s = 0.0
end_s = 0.18
fuel = 5
temperature_k = 1900
smoke = 1.5
velocity_mps = 7
smoke_column.pyro.toml ONE-SHOT
A burst of dark smoke that climbs, spreads and thins away.
[[emitters]]
shape = "sphere"
position_m = [0, 0.8, 0]
size_m = 1.0
start_s = 0.0
end_s = 0.8
fuel = 0
temperature_k = 700
smoke = 6
velocity_mps = 3
direction = "up"
smoke_plume.pyro.toml LOOP
Dark smoke rising from a wreck and leaning downwind, which loops.
[solver]
cooling = 0.25
smoke_fade = 0.45
swirl = 0.8
turbulence = 0.2
turbulence_size_m = 1.2
turbulence_where = "moving"
wind_mps = [1.2, 0, 0]
drag = 0.3
dust_ring.pyro.toml ONE-SHOT
The ring of dust a blast kicks out along the ground.
[[emitters]]
shape = "ring"
position_m = [0, 0.3, 0]
size_m = 1.5
start_s = 0.0
end_s = 0.15
fuel = 0
temperature_k = 293
smoke = 0
dust = 12
velocity_mps = 14
direction = "radial"
impact.pyro.toml ONE-SHOT
A shell hitting dry ground, with a brief flash, earth thrown up and outward and a little smoke, from three emitters in one box.
# The flash. Little fuel and a short burn, so its heat does not carry the dust up as a column.
[[emitters]]
shape = "sphere"
position_m = [0, 0.3, 0]
size_m = 0.4
start_s = 0.0
end_s = 0.06
fuel = 3
temperature_k = 1900
smoke = 2.0
velocity_mps = 6
direction = "radial"
To start a new effect, copy the nearest example and change it, because every example already avoids the warnings its kind of effect tends to raise.
Godot 4: the six-way shader and wire
The six-way shader, flipbook_6way.gdshader, lights the smoke from the scene's sun and ambient light on six sides and adds the flame as HDR light of its own. It blends frames along the motion vectors and fades against scene depth.
spatial-compiler wire installs the shader in a Godot project, writes texture import settings and writes a ready scene for a bake. Put the bake folder inside the project first, then run:
spatial-compiler bake <name>.pyro.toml --out <dir>
spatial-compiler wire <dir> --scene <path>.tscn
The scene's root is a quad sized in meters, with its origin on the ground under the effect. Instance the scene where the effect happens, and it plays on its own.
The agent loop
- Copy the nearest example and run
spatial-compiler checkon it. Each error names the key and the nearest valid key or the range. - Bake at draft quality and read the
warningsin the report, then change the key each hint names. - Open
preview_strip.pngand judge the look, because the numbers cannot say whether it looks like fire. - Use
spatial-compiler sweepto compare two or three values of a key on one sheet. - Bake at final quality until the report shows
"ok": trueand no warnings, then wire the bake into Godot.
Verified setup
Pyro is verified on one Windows PC with an NVIDIA GeForce RTX 2070 Super, on Vulkan. 19 tests pass there, and the six examples bake at final quality.