DOCS // pyrofx

Bake and wire

Call bake with a .pyro.toml spec and an output folder, then wire to write a Godot 4 scene with the six-way shader. check, schema and sweep support the loop.

Contents5 sections
  1. Overview
  2. Tools
  3. Variants ()
  4. Workflow
  5. Questions

Overview

Bake a spec into a folder inside your Godot project, then wire it into a Godot 4 scene.

MCP calls
bake {"spec": "<name>.pyro.toml", "out": "<dir>", "quality": "final"}
wire {"bake_dir": "<dir>", "scene": "<path>.tscn"}

wire installs flipbook_6way.gdshader and pyro_sheet.gd, sets texture imports and writes a scene: a quad in meters, origin on the ground. It autoplays; set autoplay = false to drive time_s yourself. set: ["node=particles"] writes a GPUParticles3D for many copies.

To see a finished bake in Godot without running wire first, download a sample project with the official fire and fireball already wired in. Open the folder and press Play. You do not need an API key to watch them.

Download the Godot 4 sample

Bake the same spec twice and you get the same sheets back. Same spec, same result

Tools

schema {}
Every field, range, default, warning and metric as JSON. The source of truth.
check {"spec": "<spec>"}
Validates without baking. Errors name the key and the valid key or range.
bake {"spec": "<spec>", "out": "<dir>", "quality": "draft" | "final", "seed": n, "set": [...]}
Bakes the spec. Draft doubles the cell size and warns GRID_REDUCED.
sweep {"spec": "<spec>", "set": ["key=v1,v2"], "out": "<dir>"}
Bakes up to 16 draft variants of the spec. Each variant is a whole bake with its own report, and the sweep returns one report for them all. See Variants.
wire {"bake_dir": "<dir>", "scene": "<path>.tscn"}
Installs the shader and writes a Godot 4 scene.

set takes section.key=value overrides. emitters.fuel=3 sets every emitter; emitters.0.fuel=3 sets the first. Full schemas: MCP tools.

Variants (sweep)

Each set entry with a value list, such as solver.buoyancy=1,2,3, makes one variant per value.

  • Several value lists multiply: a=1,2,3 with b=x,y gives 6 variants.
  • An entry with a single value is a plain override on every variant.
  • A bracketed list, such as a=[1,2], counts as one value.
  • The first entry varies slowest, so variant_00 is a=1, b=x and variant_01 is a=1, b=y.
  • A sweep has at most 16 variants. A sweep of more than 16 exits 1 with BAD_ARGS and bakes nothing.

Each variant is written as a whole bake, with its own bake_report.json, to a folder from variant_00 through variant_15. The sweep returns one report that lists every variant.

Variants compile several versions at once so you can compare them: each variant is from $0.025, starting at $0.10 for 4 variants, and a variant that asks for more work costs more in the same way. The estimate lists each variant's price before you run. A sweep that fails part way is charged only for the variants it recovered, and nothing if none are recovered. See Billing.

Workflow

  1. Copy the nearest example and call check on it.
  2. Bake at draft quality; fix each warning’s key.
  3. Open preview_strip.png and judge the look.
  4. sweep up to 16 variants to compare values.
  5. Bake at final quality until "ok": true and warnings is empty, then wire.

See Godot effect pool.

Questions

How do I bake a pyrofx spec and wire it into Godot?

Run bake with your spec and output folder, then run wire to install the shader, script and Godot scene.

How many variants can a pyrofx sweep compile at once?

A sweep compiles up to 16 draft variants in one run, writing each variant to its own folder with a report.

Can I preview a finished pyrofx bake in Godot without an API key?

Yes, download the Godot sample project with fire and fireball already wired in, open the folder and press Play.