Contents6 sections
Layout
Spatial Compiler accepts .pyrofx.toml and .pyro.toml for the same spec.
Origin at the center of the box floor, +Y up. Omitted fields take defaults; unknown keys are errors. The fireball example:
# A ground burst that swells, rolls and rises. One-shot.
[meta]
name = "fireball"
notes = "Ground burst that swells, rolls and rises"
[domain]
size_m = [12, 16, 12]
voxel_m = 0.08
duration_s = 4.0
[[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
[solver]
# Burning needs air, so the ball burns at its rolling surface instead of all at once.
air_limit = 0.88
burn_rate = 10
smoke_fade = 1.1
[look]
exposure = 1.2
[export]
pacing = "front"
Sections
| Section | Holds |
|---|---|
[meta] | name, seed (for every random choice) and free-text notes. |
[domain] | The simulated box uses size_m, voxel_m (cell edge at final, doubled in draft), duration_s, sim_fps, substeps, open_faces, ground and ambient_k. If the simulation box is too large, the compiler refuses the run with BOX_TOO_BIG_FOR_DEVICE and names the key to change, such as domain.voxel_m. |
[[emitters]] | One or more sources: see Emitters. |
[[forces]] | Optional placed forces: see Forces. |
[[obstacles]] | Optional solids: see Obstacles. |
[solver] | Burning, buoyancy, cooling, fade, swirl, turbulence, wind and drag, shared by all emitters. |
[look] | Exposure, smoke density, smoke and dust colors (linear; 0.2 reads as mid grey). |
[[views]] | Cameras. Default: side-on (pitch_deg = 0), self-framing (fit = "auto"). Each view writes its own sheets. |
[export] | Sheet grid and tile size, channels, format (png8, png16 or exr), pack, pacing (see Frame timing) and the loop settings. |
Solver precision
solver.precision sets the number size for gas velocity.
| Value | Means |
|---|---|
"half" (default) | 16 bit, faster. Rounding adds back some divergence; stored_divergence reports it. |
"full" | 32 bit. Exact, but slower and larger. |
solver.pressure_accuracy (default 0.01, range 0.00001 to 0.5) is the target leftover divergence. The solve stops early only when it stalls, and PRESSURE_LOOSE reports that. Use "full" for targets finer than the default.
[solver]
precision = "full"
pressure_accuracy = 0.001
Loops
The two passes of a loop share one solver.
Set [export] loop = true, loop_blend_frames and warmup_s (time to reach steady state). domain.duration_s is the loop length; the emitter runs with end_s = 1000.
See Values over time.
Frame timing
Set either export.frames for a frame count or export.output_fps for evenly spaced frames at a given rate. Set export.sheet_px to the longest side of a sheet in pixels. Omit export.grid to let the compiler fit the tiles.
[export]
frames = 96
sheet_px = 1024
The frame count can extend beyond a single sheet. The Godot pool plays each sheet in sequence. See the 60 fps smoke column example.
export.pacing sets when each frame is written. "even" (default) spaces the frames evenly over the clip, each at the nearest solver step, so an engine that plays frames at a fixed rate keeps the baked (precomputed) timing. "front" gives the fast early phase more frames, for one-shots only (a loop needs "even"). layout.json lists every frame's time in frame_times_s.
Questions
What happens if a pyrofx simulation box is too large?
The compiler refuses the run with BOX_TOO_BIG_FOR_DEVICE and names the key to adjust, such as domain.voxel_m.
When should I use full solver precision in a pyrofx spec?
Use full 32 bit precision when targeting pressure_accuracy finer than the 0.01 default, since half precision adds rounding divergence.
How do I configure a looping pyrofx animation?
Set export.loop to true with loop_blend_frames and warmup_s, use even pacing and set emitter end_s to 1000.