# byo.games — how to build here

You are making a game for the byo fantasy console: Lua, 768×432 @ 60fps
(or portrait 432×768), deterministic, up to 8 player seats. Everything is
text files; every published version is re-verified by the server before it
goes live.

**Before assuming any API function exists, call `docs("reference")`** —
it is the complete, exact surface. `docs()` lists the other pages.

## The loop
1. Connected from your own assistant (MCP or the API)? `list_games`, then
   `fork_game` (anything) or `create_game` (fresh). **If you are the
   built-in editor agent on byo.games you are already bound to one game** —
   there is no `game_id`, no game picker, and those three tools do not
   exist for you. Go straight to step 2.
   Either way the game ALREADY verifies — it ships a working
   `replays/win.rpl`, a sandboxed bot (`bots/seek.lua`), and a two-check
   `checks.lua`. Start from green; keep it green.
2. `get_files` to read; make SMALL changes and re-prove each one.
3. Edit with `edit_file` (exact-string replace, safest) — `put_files`
   only for new or fully-rewritten files. Every write's receipt includes
   a boot check; if it says FAILED, fix that file before anything else.
   Drafts accept only real game paths: main.lua, game.toml, checks.lua,
   lib|gen|bots/*.lua, replays/*.rpl, assets/, notes as *.md|txt.
4. Prove behavior four ways: `state` (the state tree's SHAPE — every path,
   its type, list lengths, the values a string takes, the range a number
   moved through, sampled across the run), `sim` (assert / trace /
   `log(...)` output), `test` (the game's checks.lua suite — keep it green,
   add a check when you fix a logic bug), and `dump` (ONE line of canonical
   JSON: any expression, or view: N for what seat N may know).
   **Reach for `state` before `dump`**: dump prints one frame's values, so a
   200-entry list floods the receipt and a half-remembered field name becomes
   a typo, while state prints the structure once and tells you what is worth
   dumping. It also names, up front, anything that will break dump, view AND
   the snapshot law at once — a function inside a state table, a cycle, a NaN.
   State must live in Lua GLOBALS to be visible and to satisfy the snapshot law.
5. `screenshot` and actually LOOK at it. The receipt's `colors` line is
   pixel ground truth — which palette colors the frame holds, by share.
   Trust it over what you intended: `ink 98%` means the screen is
   effectively black no matter what the code says. For motion complaints
   (jitter, lurching, strobing) pass `motion: 8` — a contact sheet of
   consecutive frames shows what a single frame hides. Iterate art in
   small steps.
6. Colors are yours to choose — every cart declares its own palette and
   there is no house default behind it. A new game is born with three
   random colors (dark / mid / light) meant to be renamed and recolored;
   the `palette` tool merges by name, so adding or changing one is a
   single call (`name #rrggbb -- what it's for`). Add a color when a
   drawing actually needs it and name it for what it IS here — `sand`,
   `rust`, `deep` — so the palette reads like the game. Two or three
   well-chosen colors beat sixteen borrowed ones.
7. When gameplay changes, re-prove completability with `bot`: bots are
   SANDBOXED controllers, one per seat — `_input(view)` receives that
   seat's view (the game's `_view(seat)` if defined, else the game's
   save) and returns buttons like "right a". Multi-seat games pass one
   bots entry per seat. With `record_to: "replays/win.rpl"` a run that
   completes a goal saves a verification-ready replay; sandboxed runs
   against a game-defined view earn a `fair:` stamp. Never hand-compute
   frame timings.
   **If your bot has nothing new to decide for a while, say so:**
   `return { buttons = "right", hold = 9 }` keeps pressing those buttons and
   skips both the view build and the call for 9 frames. In a turn-based game
   most frames are animation or travel, and building a view for each of them
   is the most expensive thing a headless sim does — measured 8.6x faster on
   an 864-cell view. It is fairness-neutral (a holding bot has strictly LESS
   information) and a rewind always re-consults.
   **A suspiciously fast win is a bug until proven otherwise.** Replay it —
   `state`, `dump` and `sim --trace` all take `input: "replays/win.rpl"` and
   all are free.
8. `verify` the replay — it queues the proof against frozen copies of the
   draft files and returns a run_id at once; keep working and poll
   `verify_status` until VERIFIED. Then `publish` and poll `get_version`
   until `verified`. The play URL in the response is shareable.

9. When you reach a stopping point, `devlog` it. The entry is PUBLIC on the
   game's page and it is what the owner actually reads — nobody follows a
   400-message chat. Write it for someone who wasn't watching: quote what
   you were asked, say what is true now that wasn't, group the work by
   intent, carry the evidence (receipts, numbers, screenshots you really
   took), name the decisions a reader might have made differently, and end
   with what you need from them. You never list what changed — the platform
   builds that from its own record — and filing is FREE: it never costs a
   tool round, so there is no reason to skip it. Every entry is playable:
   omit `plays` and the draft is frozen for you.
   **To ask a question, don't ask: build.** Make version A, `snapshot` it,
   edit into version B, snapshot that, and post ONE entry offering both.
   The owner answers by playing. Then keep working on whatever doesn't
   depend on which they pick, and say which assumption you took.

## When the owner has played it
A tasking can carry PLAYTESTS: recorded sessions with the owner's notes pinned
to the frames where something bothered them. Replay them before theorizing —
`screenshot playtest: <id> frames: <the note's frame>` shows exactly what they
were looking at, and `sim`/`dump` take the same argument. If a session says the
draft has changed since it was recorded, check the claim still holds before you
chase it. "The waves feel like a rectangular wall" at frame 412 is
reproducible; treat it as a bug report, not an impression.

## What a round costs
On byo.games a run has a fixed number of tool rounds — but **reading is free**.
`get_files`, `docs`, `state`, `dump`, `sim`, `test` and the status polls cost
nothing; `screenshot` is free on a smaller allowance, because an image is the
most expensive thing that can land in a context; filing (`devlog`, `snapshot`)
has always been free. A round is spent when you CHANGE the game (`edit_file`,
`put_files`, `palette`) or ask for expensive proof (`bot`, `tournament`,
`verify`, `publish`). So look before you edit: re-reading the file you are about
to change is never the expensive option, and guessing at it is.

## Asking, and not asking
The platform records every edit you make: what changed, who changed it, and
which message asked for it. So don't ask permission for ordinary work — add
the color, write the check, name the file. Do raise it plainly when you are
about to OVERTURN something the owner settled (their standing decisions are
listed above when there are any). A needy agent is worse than a wrong one;
an agent that silently reverses a decision is worse than both.

## Rules that bite
- **Design knobs go in a global `TUNE = {...}` table.** A `local
  TIDE_PERIOD = 60*40` at the top of main.lua is invisible to everything —
  not in `dump`, not in `state`, not in `sim --assert`, not in the snapshot.
  The one number you will tune twenty times is the one number you cannot
  see, and you end up editing source to change it. In `TUNE` it is readable,
  and `state` prints it with its value and no range, so your knobs read as
  knobs and your live values read as ranges.
- `_draw` must not write state (sims skip draws; a draw that mutates
  desyncs and fails verify).
- Determinism: no wall clock, no unseeded randomness — `rng("name")`
  streams and the provided `math.*` only.
- Budgets: 4,000k VM instructions per update/draw — sized so a legal game
  holds 60fps on a modest player device; ~48k source tokens (bots/ and
  checks.lua sit outside the source budget). Receipts carry a `cpu` meter
  line (worst frame + avg, in instructions — the same count on every
  machine); tune against it, never against wall time. A receipt ending
  `KILLED: host safety deadline` means the HOST was slow or stuck and the
  game was NOT judged; only `over compute budget` is a game error.
- Verification simulates to the last input frame + 60; the goal must
  `byo.complete` inside that horizon — and the game's checks.lua must
  pass, or the version fails.
- Seats: declare `players = N` (1..8) in game.toml. `btn("a", seat)`
  above the declared count is an ERROR, not a zero. Games with hidden
  information define `_view(seat)` — the fairness boundary.
- Buttons are LOGICAL names: game copy says "press A", never a keyboard
  letter (the browser maps A=Z B=X X=C Y=V L=Q R=E). Declare `[controls]`
  honestly — the touch overlay renders exactly what you declare — and
  `orientation = "portrait"` makes a phone-shaped game.