recorder
Query recorded play sessions to debug what happened. Powerful, but needs your game instrumented.
What it’s for
When your game records a play session to a journal file, this namespace lets your assistant read it back after the fact. Instead of re-running the game and hoping the bug repeats, you point it at a recording and ask what happened: which objects were active, what an event fired, and how a value moved over time.
A session is a set of objects (each with a stable key), a set of tagged variables per object, a timeline of events, and change-points for every variable. The tools walk that data from the outside in: list the sessions on disk, describe one to learn its object keys and variable tags, then drill into a specific event, a value-over-time delta, or a raw change series.
This is the workflow for post-mortem debugging: locate the moment something went wrong, then inspect the surrounding state as of that timestamp. It is read-only and works only if your game is instrumented to write recordings; unlike asset dumps, which snapshot static assets on disk, the recorder answers questions about a live run that already finished.
Examples
Find the moment something broke
Locate the newest recording, learn its shape, then jump straight to the first error event.
You: In my last play session, find where the player's vehicle threw an error.
call("recorder.list_sessions", {limit: 1})
→ {sessions:[{id:"2026-07-03_1841", path:"...Recordings/2026-07-03_1841.rec"}]}
call("recorder.describe_session", {session:"2026-07-03_1841"})
→ {objects:[{key:"Vehicle_0", ...}], variables:[...], eventCount: 914}
call("recorder.find_events", {session:"2026-07-03_1841",
severityMin:"Error", key:"Vehicle_0"})
→ {events:[{t: 42.18, name:"physics:desync", props:{...}}]}
Done. First error is physics:desync on Vehicle_0 at t=42.18.
Summarize how a value moved
Scope to a single round, then get the endpoints, net delta, and extrema of one variable.
You: Over round 2, how did the vehicle's speed change?
call("recorder.list_segments", {session:"2026-07-03_1841"})
→ {segments:[{type:"round", index: 2, tMin: 30.0, tMax: 78.4}]}
call("recorder.summarize_change", {session:"2026-07-03_1841",
key:"Vehicle_0", tag:"speed", from: 30.0, to: 78.4})
→ {start: 1.2, end: 0.0, min: 0.0, max: 46.7, mean: 22.1, changes: 388}
Done. Speed peaked at 46.7 m/s near mid-round, then dropped to zero at the finish.
Inspect the state at the bad moment
Feed the error timestamp back in to read the as-of value of the tags you care about.
You: What were the vehicle's throttle and velocity right when it desynced?
call("recorder.get_state", {session:"2026-07-03_1841",
key:"Vehicle_0", t: 42.18, tags:["throttle","velocity"]})
→ {values:{throttle: 0.94, velocity:[12.1, -3.4, 8.0]}}
Done. At t=42.18 throttle was 0.94 and velocity ~14.9 m/s.