Map Anchor 3 APIs for 2D lab

Now let me pull the specific API sections: input, layer/draw, camera, timestep/update rate, and the agent/eval channel docs.

Confirmed: 120 Hz fixed timestep at Anchor/engine/engine/src/anchor.c:339 (#define PHYSICS_RATE (1.0 / 120.0)). Now the input, layer/drawing, camera sections in FRAMEWORK_API_QUICK.md and ENGINE_API_QUICK.md.

Good, confirmed key name scheme. Now the "edges are update-only" rule and eval channel functions (engine_step, engine_snapshot, agent_tap) in ENGINE_API_QUICK.md and AGENT.md.

This confirms rule #3's edge queries note: "edge queries are update-only" — key/mouse/input pressed/released called from draw() raise a Lua error on desktop. Now let's look at AGENT.md for the eval channel details, engine_snapshot, agent_tap, and CLAUDE.md gotchas around colors/%d.

Confirmed: Anchor/engine/reference/plan.md:48 mentions the %d+float gotcha explicitly. Let me pull surrounding context there.

This confirms the fix already applied for a %d+float crash found in HUD text (e.g. string.format('%d', physics3_get_body_count()) where a Lua number without math.floor broke %d). Now let's check .claude/launch.json conventions and check for spring ceiling gotcha mentioned in ENGINE_API_QUICK (SPRING_MAX_FREQUENCY 12).

Findings: Anchor 3 platformer controller-lab orientation

All paths below are relative to C:\Users\a327e\Desktop\a327ex\ unless given in full.

1. Minimal game directory layout

Files needed to be driven by anchor drive start/eval/stop <game-dir> (the Python workflow CLI's drive subcommand, Anchor\workflow\lib\drive.py):

• main.lua — required. Must end with require('anchor')({...}) and, if the game is split, require('boot') as its last line.
• anchor/ — a copy of the framework (init.lua, class.lua, input.lua, layer.lua, camera.lua, color.lua, …; 30 files, same set in playground\anchor\ and ABAgames\knightvspawns\anchor\). Required — require('anchor') resolves into this folder.
• boot.lua — optional. Only needed if you split one-time work out of main.lua (see below). Playground has none; a sketch keeps everything in main.lua and that's fine (Anchor\engine\docs\AGENT.md:192-193).
• anchor.exe in the game dir — not required for the engine-repo dev flow. Anchor\workflow\lib\drive.py:29: ENGINE_BIN = engine/engine/build/anchor.exe, a fixed path — drive.start() (drive.py:140-160) always launches the shared engine binary with the game dir as cwd, never a per-game copy. Horse Game (ABAgames\knightvspawns\anchor.exe, anchor-steam.exe) tracks its own exe copies only because it's a standalone shipped game outside the engine repo — that's a distribution artifact, not a dev requirement.
• No init.lua of your own — init.lua lives inside anchor/ (the framework copy) and is not something a game authors; anchor\init.lua:135 is the function(config) returned by require('anchor'), called from your main.lua.

run.bat contents, quoted exactly:

Playground (Anchor\engine\playground\run.bat):

@echo off
cd /d "%~dp0"
..\engine\build\anchor.exe .

Horse Game (ABAgames\knightvspawns\run.bat):

@echo off
rem Folder-agnostic runner: derives the game name from this folder's name, so a
rem copied/renamed fork runs without editing this file (same pattern as
rem snkrx-template / ricochet-template).
cd /d "%~dp0.."
for %%I in ("%~dp0.") do set "GAME=%%~nxI"
"%~dp0anchor.exe" "%GAME%"

The Horse Game pattern is deliberately folder-agnostic (its own comment says so) — that's the intended way to fork a new game dir: copy a template/existing game dir, rename it, and run.bat still works.

Definition-only main.lua + boot.lua split (Anchor\engine\docs\AGENT.md:138-217, confirmed live in ABAgames\knightvspawns\main.lua:29-32 and boot.lua:1-8):

require('anchor')({ width = 480, height = 270, title = 'kvp', boot = { 'boot.lua' } })
require('boot')     -- assets, layers, binds, state — runs once, cached by require
-- everything below: definitions, reloadable

main.lua holds only functions, UPPER_CASE/literal-table constants, class() definitions, colors, requires. boot.lua holds asset loads, layer_new, bind, state tables/scalars, springs/timers/cameras, the startup call sequence. On save, main.lua re-runs in the globals (functions rebind, class() tables merge in place into live instances); boot.lua never re-runs (cached by require).

New game dir creation: no scaffold/anchor new command exists (confirmed — Anchor\workflow\anchor.py:15-266 has no such subcommand). The normal path is forking a template (snkrx-template/, ricochet-template/, emoji-template/, each with its own .claude/CLAUDE.md) or copying playground/ directly, per the top-level C:\Users\a327e\Desktop\a327ex\.claude\CLAUDE.md "Templates" line and the Horse Game run.bat comment above.

Ambiguity worth flagging, not guessed away: Anchor\engine\docs\SURFACE.md:9-17 documents anchor <game folder> as the way to open a visible window. But the only anchor CLI actually on this machine is the Python workflow tool (Anchor\workflow\anchor:1-3, symlinked as anchor), whose argparse subcommands (anchor.py:15-266) are doctor/install/runs/end/continue/.../framework/drive/check — there is no subcommand that launches a windowed game instance. So a bare anchor playground as shown in the top-level CLAUDE.md's bash example does not correspond to any command implemented in this repo's Python CLI; the actual mechanism for a visible run on this Windows machine is each game's run.bat, which invokes engine\build\anchor.exe directly. I did not find a resolving alias — treat "how a person literally runs anchor <game-dir>" as undocumented/unverified here rather than assume it works.

2. Fixed timestep

• 120 Hz fixed physics/input/update timestep, set at Anchor\engine\engine\src\anchor.c:339: #define PHYSICS_RATE (1.0 / 120.0).
• dt passed to update(dt) is this fixed unscaled PHYSICS_RATE (constant every call) — documented at framework\anchor\init.lua:95-107: "the dt parameter... is the UNSCALED fixed physics timestep (PHYSICS_RATE). If you want scaled dt..., compute dt * time_scale locally, or call engine_get_dt()."
• Render rate: capped at 60 Hz by default, with 2 fixed updates per rendered frame (docs\ENGINE_API_QUICK.md:564: engine_set_fixed_step(on) -- 2 fixed updates + 1 rendered frame per iteration; docs\AGENT.md:120-121: an agent-driven frame is pump_sdl_events → 2× fixed_update_step → render_frame_pass). render_uncapped = true in the init table opts out of the 60 Hz cap for non-pixel-art games (docs\FRAMEWORK_API_QUICK.md:27-34).
• Callback signatures: function update(dt) and function draw() — globals the C engine calls directly each frame, no other args (docs\FRAMEWORK_API_QUICK.md:106-116; example playground\main.lua:194 / :279).

3. Input

• bind(action, control) — control strings are 'key:<name>' / 'mouse:<n>' (docs\FRAMEWORK_API_QUICK.md:158; live examples playground\main.lua:64-68: bind('spawn_ball','key:b'), bind('reset','key:r'), bind('shockwave','key:space'), bind('debug','key:f1'), bind('grab','mouse:1')).
• input_down(action) -> bool, input_pressed(action) -> bool (this-tick edge), input_released(action) -> bool, plus input_axis, input_vector — docs\FRAMEWORK_API_QUICK.md:166-170.
• Raw (always available, no bind needed): key_is_down(key), key_is_pressed(key), key_is_released(key) — docs\ENGINE_API_QUICK.md:574-590, examples docs\ENGINE_API.md:3623-3651.
• Exact key-name strings, from key_name_to_scancode at Anchor\engine\engine\src\anchor.c:4780-4871:
  • Letters: single lowercase letter, e.g. "a", "d", "w", "s", "e" (case-insensitive on input; scancode_to_key_name at anchor.c:4876-4909 always emits lowercase).
  • "space" (line 4794); arrows: "left", "right", "up", "down" (4802-4805); shift: "lshift", "rshift", or bare "shift" which defaults to left (4808-4810).
  • So for this lab: bind('left','key:a'), bind('right','key:d'), bind('jump','key:space'), bind('run','key:shift'), or bind('left','key:left')/bind('right','key:right') for the arrow-key variant.
• Edges are update-only rule: docs\ENGINE_API_QUICK.md:578-580 — "key/mouse/input pressed/released called from draw() RAISE on desktop ('edge queries are update-only') — they were silently always-false there. Web: one console warning." All jump/attack edge logic must live in update(dt), never draw().

4. Drawing on a 2D layer

• layer_new(name, filter?, w?, h?) -> layer (stores in layers[name]) — docs\FRAMEWORK_API_QUICK.md:246-254. Resolution/scale for the whole game is set once via require('anchor')({ width=, height=, scale=, filter= }) (framework\anchor\init.lua:9-20; live example playground\main.lua:17-23: width=960, height=540, scale=2, filter='smooth').
• Rect drawing: layer_rectangle(lyr,x,y,w,h,color) filled, layer_rectangle_line(lyr,x,y,w,h,color,line_width?) outlined — docs\FRAMEWORK_API_QUICK.md:263-264. Origin rule (docs\FRAMEWORK_API_QUICK.md:257-260): rectangles and text use TOP-LEFT (x,y); images/sprites/circles use CENTER (x,y). A kinematic player box drawn with layer_rectangle should keep its stored position as the top-left corner to match, or convert consistently.
• Lines: layer_line(lyr,x1,y1,x2,y2,width,color) — same block, line 268.
• Text: layer_text(lyr, text, font, x, y, color), where font may be a font table or a registered name string (docs\FRAMEWORK_API_QUICK.md:279-283). Fonts are loaded with font_register(name, path, size, filter?) -> font (docs\FRAMEWORK_API_QUICK.md:196-203; example playground\main.lua:76: font_register('main', 'assets/monogram.ttf', 32)). Font caveat, not "ASCII-only" as commonly assumed: Anchor\engine\engine\src\anchor.c:1761-1762 pre-warms only ASCII 32..127 (FONT_FIRST_CHAR/FONT_NUM_CHARS) at load, but anchor.c:2096-2098 documents that "non-ASCII glyphs re-rasterize lazily on next use" — so non-ASCII text works, just with a first-use rasterization cost, not a hard restriction. For debug HUD text (plain ASCII) this is a non-issue either way.
• Colors: color(r,g,b,a) -> color / color_new(...), a plain {r,g,b,a} table with a __call metamethod returning the packed rgba integer (docs\FRAMEWORK_API_QUICK.md:645-656). No engine-provided named palette — games define their own convention, e.g. playground\main.lua:31-32,42-50: bg_variants, ground_color = color(105,110,125), etc. Gotcha: colors are callable and must be invoked (some_color()), not passed as the bare table, when handed to draw functions — docs\ENGINE_API_QUICK.md:581.
• 2D camera (for vertical player-follow): camera_new(w?, h?) -> camera, camera_update(c, dt), camera_follow(c, target, lerp?, lerp_time?, lead?) (target can be an entity, a plain {x,y} table, or nil to stop), camera_set_bounds(c, min_x, max_x, min_y, max_y), camera_attach(c, layer, parallax_x?, parallax_y?) / camera_detach(c, layer) — docs\FRAMEWORK_API_QUICK.md:344-361. Standard draw flow (docs\FRAMEWORK_API_QUICK.md:329-341):

function draw()
  layer_rectangle(game_layer, 0, 0, width, height, bg_color())
  camera_attach(main_camera, game_layer)
  -- draw entities to game_layer here (world space)
  camera_detach(main_camera, game_layer)
  layer_render(game_layer)
  layer_render(ui_layer)
  layer_draw(game_layer)
  layer_draw(ui_layer)
end

For vertical-only follow, call camera_follow(cam, player) once (or every update) and let camera_update(cam, dt) (called in update(dt)) do the lerp; camera_set_bounds can pin the x-axis if you want vertical-only tracking. camera_attach/camera_detach is the "offset the world" mechanism — it pushes/pops the camera's transform onto the given layer around your world-space draw calls; a separate ui_layer drawn without attach/detach stays screen-space for debug text (as playground\main.lua:288-297 does with ui_layer).

5. Hot reload

• Rule: a reloadable file holds only definitions; one-time work lives in files the init table names as boot — docs\SURFACE.md:66-77, docs\AGENT.md:138-217.
• What re-runs on save: main.lua (and any non-framework required module) — functions rebind (call sites resolve names at call time), UPPER_CASE/literal-table constants go live, class() tables are reconciled (new methods merge into the old class table so live instances pick them up) — docs\AGENT.md:152-156.
• What survives: anything boot.lua created, because require('boot') is cached and never re-executes — asset handles, layers, binds, state tables/scalars, springs/timers/cameras (docs\AGENT.md:140-150, 198-217).
• Not reloadable at all: the framework copy itself (anchor/ — e.g. layer.lua captures raw bindings at load), boot files, packaged builds — docs\AGENT.md:174-176.
• Assets (textures/sounds/shaders) also hot-reload in place into the same GL handle — docs\AGENT.md:177-188.
• Pattern for state that must survive a module reload without a boot file: REGISTRY = REGISTRY or {} guards (docs\AGENT.md:206-207), and an optional on_reload(path) hook the game can define, run after every successful reload, to re-derive caches or re-run one-time registration in place (docs\AGENT.md:169-171, 214-216).
• Visible instances: saves watched at 2 Hz; a game error shows a traceback overlay over the last good frame instead of freezing (docs\SURFACE.md:71-72, docs\AGENT.md:159-162). Agent instances: reload only on explicit engine_reload() call, for determinism (docs\AGENT.md:163-166).
• For the lab: put the tile grid construction, the player instance, layer/camera creation, and bind() calls in boot.lua; keep the update/draw methods, movement-tuning constants, and class defs in main.lua so tuning a jump constant hot-reloads without resetting the player's position.

6. Eval channel

• Surface: anchor drive start <game-dir>, anchor drive eval <game-dir> '<lua>' (or --file f.lua), anchor drive stop <game-dir>, plus status/log — declared at Anchor\workflow\anchor.py:171-176, implemented in Anchor\workflow\lib\drive.py (start() line 140, evaluate() line 183, stop() line 195), documented in docs\AGENT.md:36-51.
• engine_step(n) -> n — advances n rendered frames (2 fixed updates each); agent instances only (docs\ENGINE_API_QUICK.md:568; docs\AGENT.md:71).
• engine_snapshot(path) — writes the current frame as a PNG to path on demand (docs\AGENT.md:75). The agent_tap/agent_shot kit convenience (framework\anchor\agent.lua) defaults its own snapshots to replays/shots/<frame>.png (docs\AGENT.md:43).
• agent_tap(direction_or_control) and siblings agent_click, agent_wait_until(pred, max_steps), agent_dump, agent_globals, agent_shot — all from the agent kit loaded by the framework, framework\anchor\agent.lua, listed at docs\AGENT.md:80-82; example usage agent_tap("right") (docs\AGENT.md:42).
• Setting/reading player state from a test script: there is no dedicated player-state API — an eval is arbitrary Lua run in the live instance's globals, and an expression's return values come back over the channel (docs\AGENT.md:64-66: "An expression (knight.x, #pawns, engine_state()) returns its values"). So a controller-lab test script just does player.x = 100; player.vy = -200 then engine_step(30) then return player.x, player.y, player.grounded — as long as the game exposes player (or whatever) as a reachable global, the same convention playground\main.lua uses for the_ground, balls, crates.
• Also useful for driving the controller directly like a person would: input_inject_key(name, down), input_inject_mouse_move(x,y), input_inject_mouse_button(n,down), input_inject_text(s) — go through the real SDL pump so update-time edge queries (input_pressed) see them as genuine input (docs\AGENT.md:72-74).
• engine_state() returns frame/step/time/dt/agent/visible/recording/sizes — note the field is frame, not frame_num (docs\AGENT.md:76).

7. Gotchas that bite this lab specifically

• Edge queries are update-only (docs\ENGINE_API_QUICK.md:578-580): key_is_pressed/input_pressed/mouse-pressed/-released raise a Lua error if called from draw() on desktop. All jump-buffer/one-shot logic must be in update(dt).
• Colors are callable: pass some_color(), not the bare color table, to any layer_* draw call (docs\ENGINE_API_QUICK.md:581, docs\FRAMEWORK_API_QUICK.md:656).
• string.format('%d', ...) on a float value is a real, previously-hit bug in this exact codebase: Anchor\engine\reference\plan.md:48 records "Windowed fixes from the first run: %d+float in HUD text" as a fix made during playground development. playground\main.lua:291-292 now guards this with math.floor(fps or 0) before formatting. Any debug-text HUD in the lab (fps, player velocity, tile coords) needs the same math.floor() wrap before %d.
• Draw origin split: rectangles/text are top-left-anchored, images/sprites/circles are center-anchored (docs\FRAMEWORK_API_QUICK.md:257-260) — easy to double-offset an image if you subtract half-size expecting a top-left convention.
• Springs raise above frequency 12 instead of the old silent divergence into a screen-filling sprite (docs\ENGINE_API_QUICK.md:582-583; top-level engine .claude/CLAUDE.md:96) — relevant if camera smoothing is done with spring_pull instead of camera_follow's built-in lerp.
• Loud failures generally: any binding taking an engine handle now raises a typed Lua error instead of segfaulting on a wrong-typed argument (docs\ENGINE_API_QUICK.md:576-577) — useful for catching a bug where you pass a raw table instead of a layer handle.
• Reload-survival discipline: anything created outside boot.lua (e.g., a player = player() line left at main.lua's top level) re-runs and resets on every save — keep entity construction, layer/camera setup, and bind() calls in boot.lua only (docs\AGENT.md:140-150, 198-217).
• Framework-copy drift: a game's own anchor/ folder can diverge from framework\anchor\; if a function isn't where the docs say, the game's local copy is ground truth (top-level .claude/CLAUDE.md, "Structure" section). Use anchor framework status|diff|upgrade|stamp <game-dir> (Anchor\workflow\anchor.py:165-169) to manage that copy rather than hand-copying files.

8. .claude/launch.json / preview conventions

Only one launch.json exists anywhere on the machine: C:\Users\a327e\Desktop\a327ex\.claude\launch.json, and it configures a single entry, "renderer-web" (a Python serve-web.py static server for the site's renderer) — nothing game-related, and no such file exists under Anchor\engine\, Anchor\engine\playground\, or ABAgames\knightvspawns\. There is no launch.json-based preview convention for Anchor games. The documented convention instead (top-level .claude/CLAUDE.md, "Building and Running") is: never run the windowed executable yourself — the user runs it via their own run.bat; an agent (Claude) exercises a game only through anchor drive start/eval/stop (the eval channel described in section 6). For this lab, verification should be built as anchor drive eval <game-dir> '...' scripts (per docs\AGENT.md's scripted-run pattern), not as a browser/preview pane.