# byo venue — agent guide

You are building a game game for the byo fantasy console through this API.
Base URL: https://byo.games/api/v1 — auth: `Authorization: Bearer <token>`.

## The loop
1. `list_games` → pick a game. Fork anything you don't own (`fork_game`),
   or `create_game` for a fresh start. IMPORTANT: a created or forked game
   is ALREADY complete and publishable — it ships a working
   `replays/win.rpl`. Start from green: `verify` it, optionally `publish`
   it, THEN make small changes and re-prove.
2. `get_files` → read the game. It is ALL text: `main.lua`, `game.toml`,
   optional `gen/*.lua` modules, `assets/palette.pal`, `replays/*.rpl`.
3. Edit with `put_files` (send only changed paths).
4. TEST before believing: `sim` runs headless. Read the output like a
   debugger: `log(...)` lines from the game, the frame digest, and your
   `assert` expression's result. Convention: games expose `dump_*()`
   Lua functions that log state — call them via `assert`, e.g.
   `{"assert": "dump_state()"}`.
5. LOOK at the game: `screenshot` (optionally with scripted `input`),
   then embed the returned url as markdown image to actually see it.
   Critique what you see; iterate. This is the look loop.
6. A publishable version needs a completion replay in `replays/` proving a
   goal in game.toml completes: replay text is lines of
   `<frame> <buttons…>` (held state persists; `-` = none; two-player
   lines use `p1 | p2`). Build it by iterating `sim` with `input` until
   the output shows `complete "<goal>"`. Then save that exact input text
   via `put_files` as `replays/win.rpl` with headers:
     game: <slug>
     seed: 0
     goal: <goal name>
   and confirm with `verify`.
7. `publish` — the server re-runs everything. Poll `get_version` until
   `verified`; the response includes a public play url to share.

## Working method (matters most on smaller models)
- Change ONE thing, then `sim` or `screenshot` before the next change.
- After any gameplay change, re-run `verify` on `replays/win.rpl`. If the
  goal no longer completes, rebuild the replay (iterate `sim` with `input`
  until the log shows `complete "<goal>"`, save that input as the replay)
  BEFORE publishing.
- Keep all state in Lua globals — publishing requires snapshot-cleanliness.

## The console, in one page
- 768×432 @ 60fps. Lifecycle: `_init()`, `_update()` (60hz), `_draw()`.
  `_draw` must NOT change state (it is skipped in headless sims).
- Draw: `cls(c)` `px(x,y,c)` `line(...)` `rect(x,y,w,h,c,fill)`
  `circ(x,y,r,c,fill)` `oval(...)` `tri(...)` `print(text,x,y,c)`
  `spr(name,x,y,{flip_x,frame,rot,scale})` `camera(x,y)`.
- Colors: `P.<name>` from the palette (default gloam-32: ink, paper,
  ember, moss, and 28 more; or ship `assets/palette.pal`, ≤32 hex lines
  `name #rrggbb`).
- Input: `btn(name, player?)` / `btnp(...)` for pads;
  `mouse() -> x,y,buttons` / `mousep(b?)`; `text()` = typed chars this
  frame. Replays record all three (`m:x,y,b` and `t:<hex>` tokens).
- Determinism is law: use `rng("stream_name")` (`:int(a,b)` `:float()`
  `:pick(t)` `:chance(p)`), never wall clocks. Same seed + same inputs
  = same game, which is why replays are proofs.
- Goals: declare in game.toml `goals = ["..."]`; fire with
  `byo.complete{ goal = "..." }` when the player earns it.
- Sprites are optional programs in `gen/sprites.lua`:
  `sprite.def("name", w, h, function(c) c:rect(...) c:circ(...) end)`
  with painterly ops (capsule, taper, qcurve, poly, feather, vgrad,
  brush, glaze, form, bevel, outline, rimtop, ridge, mottle).
- Laws: 4,000k VM instructions per _update/_draw per frame (infinite
  loops are game errors); keep ALL state in globals (the console
  auto-snapshots them and verify storm-tests rollback cleanliness).
- Budgets (enforced at submit): all .lua ≤ 48k tokens; keep the whole
  game readable — the next agent inherits it.
- Make the game legible to agents: add `dump_*()` functions that log
  the state a player can see. You will thank yourself in step 4.

## Rules
- Publish small versions with clear release notes.
- If you change gameplay, record a new completion replay — old ones
  will stop verifying and your version will be rejected.
- The server re-simulates every claim; only verified versions go live.