Kiln

Appearance

Working with agents ​

Kiln is designed around the loop a coding agent runs: change files, ask the tools whether the change is right, fix what they report. This page is that loop, and the files an agent reads.

The loop ​

bash
kiln describe            # traits, systems in run order (reads/writes/after), resources, events
kiln test                # bun test over scenarios/ (headless, deterministic)
kiln replay recordings/x.json        # replay a play session the user recorded (F8 in the game)
kiln run --steps 600 --snapshot Transform,Health --resources Score   # JSON world after N steps
kiln check               # determinism lint (Math.random, Date.now, performance.now)
kiln shot --steps 120 out.png        # one rendered frame from headless Chromium, when you need eyes
kiln docs                # regenerate AGENTS.md
kiln add <plugin>        # vendor a community plugin into src/plugins/ (kiln add --list)

Work in this order:

  1. Write or change files.
  2. kiln describe. Schedule errors (write conflicts, cycles, a bad .after()) show here.
  3. Write a scenario test for the change.
  4. kiln test.
  5. kiln shot only if the change is visual.
  6. kiln docs if exports or the schedule changed.

Every command takes --json and prints errors as error <code>: <message>. The message names the fix, so the usual next step is to do what it says. The full command reference is in CLI.

AGENTS.md ​

Every game has an AGENTS.md at its root, which agents that follow the AGENTS.md convention read before working. It has two parts:

  • The Kiln guide at the top: the API, the phases, the rules the schedule enforces, every plugin, testing, recordings, a TSL cheat sheet and a table of common errors. kiln new writes it from packages/kiln/docs/agents-guide.md. You may edit this part; kiln docs keeps it.
  • This game, below a marker comment, generated by kiln docs from the code: the config, the plugins, the schedule as a table (writes, reads, resources and order for every system, with the file it lives in), every trait with its fields, every relation, prefab, resource, event, system and plugin with its JSDoc, and the names of the scenario tests.
bash
kiln docs            # rewrite the generated section, keep everything above the marker
kiln docs --guide    # also replace the top with the current Kiln guide
kiln docs --check    # exit 1 if AGENTS.md is out of date (for CI)

kiln docs also prints a note for each trait, system, plugin, resource, event or prefab without JSDoc, since that line is what the next agent will read about it.

This site, for agents ​

The guides on this site are also published as plain text, following the llms.txt convention:

  • /llms.txt: an index of every page with its description.
  • /llms-full.txt: every guide page in one file.
  • Each page as Markdown at its own URL with .md appended.

The API reference is generated by TypeDoc from the same JSDoc the code carries, so it is never out of step with the source.

Habits that keep agents fast ​

  • One feature, a few exports. A trait in data.ts, a system in systems.ts, one line in main.ts. Don't spread a feature across a new folder until a file is genuinely long.
  • Read before guessing. kiln describe answers "what runs, in what order, touching what" faster and more reliably than reading the code.
  • Assert on JSON. kiln run --snapshot and scenario tests are exact. Screenshots are for checking that something looks right, not that it happened.
  • Reproduce from recordings. When a user says "I recorded it", run kiln replay before reading code. See Recordings and replay.
  • Keep it deterministic. Randomness from res.mut(Rng), time from ctx.time. kiln check flags the rest. See Determinism.