Record, replay, and continue experiments

There are two different histories to inspect. The kart followed one physical trajectory, but the planner considered many trajectories before choosing it. World replay answers “what moved?” The exploration record answers “what futures were considered?” A saved physical state and a saved planner checkpoint answer two further questions: where to restart the world, and where to resume a search. Keep these objects separate and the recording controls become much easier to use.

Begin with Getting started with the control laboratory if you have not run the lab yet. Controls, planners, and diagnostics explains the diagnostics, and Experiments, comparisons, and performance explains synchronized comparisons from a shared root. This page covers the timeline dock below the world and the Save / Open menu. Choose World motion for executed frames, Planner decisions for search records, and Events & notes to find or annotate a moment.

Choose what you want to preserve

Object	What it preserves	How you use it
World recording	Initial world and captured physical frames, applied actions, decision IDs, segment labels, and markers.	Seek or play actual movement; start a separate run with Create run from this frame.
Exploration record	A recorded decision’s search tree, its root snapshot, branch actions, and associated diagnostics.	Inspect alternatives and reconstruct one branch with Replay branch.
World snapshot	One authoritative native world, including all future-affecting environmental state.	Save state / Load state; requires the matching scene.
Planner checkpoint	The controller’s resumable search state plus its authoritative root and saved settings.	Save planner checkpoint / Load checkpoint; then Step, or Advance Wave population for a Wave checkpoint.

The world state includes positions, velocities, angles, angular velocities, body flags, tether connections and lengths, pickup positions and respawn timers, task counters, environmental randomness, and any registered mutable extension fields. The scene owns static geometry and physical parameters. Those definitions are included once in a run archive rather than copied into each recorded frame.

World replay does not restore the planner’s population, its internal random stream, warm-start memory, or wall-clock scheduling. A picture of a kart at a bend cannot tell you which candidate action sequences its planner was halfway through evaluating. That is what the separate planner checkpoint is for.

Replay actual world movement

World recording starts with the initial state and captures each executed physics frame during planned control, real-time control, manual keyboard input, and single-frame manual actions. In Drive mode, neutral input still permits recorded physics motion: releasing a key does not stop a falling or coasting vehicle. It continues when Tree → Off is selected. The world slider counts stored samples, including the initial state and any explicit restoration samples; its index is not necessarily the simulation tick.

1. Pause a running experiment, then drag the slider in World motion. Seeking also pauses continuous control. The playback status changes to Replay and shows the selected frame’s bodies, task counters, and visual animation.

2. Press Play world to animate the recording. Choose ¼×, ½×, 1×, 2×, or 4× from the speed selector. Pause replay stops playback; reaching the last frame also stops it. Playing again at the end starts from the beginning.

3. Use the camera, Follow agent, and diagnostic layers while watching. Playback reads stored states; it does not run physics or ask the planner to reconstruct the movement. Rendering can skip displayed samples at higher playback speeds without removing them from the recording.

4. Press Return to live to return to the paused authoritative world. This does not resume control. Press Run or Step when ready.

The lab displays the matching recorded decision tree and planning diagnostics when that decision is available. For device-backed recordings it can load an older tree from storage. A frame without a retained tree still has complete world motion. Do not interpret a missing search overlay as a missing world state.

In a live session, return to its authoritative world before running or driving. An opened saved run is read-only: its Run and Step controls remain unavailable. Use Create run from this frame to turn a recorded frame into an editable, paused experiment.

Continue from a selected frame

Pause replay on the desired frame and press Create run from this frame. The lab saves the original run, then starts a distinct paused run from that frame’s packed world state and applicable configuration, including the reward settings in force at that point. Its planner starts fresh. Press Step action, Execute trajectory, or Run, as appropriate for the selected controller.

The original recording retains the future you just watched. The new run records its parent run and source frame, so you can find that relationship in Saved runs. Creating the branch reads the selected frame without expanding the entire recording into memory.

Restoring a physical world does not reproduce the planner’s random stream, population, or episode memory. Use a planner checkpoint to continue a saved search. Use a comparison from the same selected world to measure alternative future behavior under explicit configurations.

Inspect thinking traces and replay an alternative

The slider in Planner decisions selects a recorded decision. Moving it pauses control and changes the displayed search tree and diagnostics. It does not by itself move the physical bodies to that decision’s root. Use the world slider when you want the corresponding executed movement.

With Planner decisions selected, Rollout paths visible, and Inspect mode active, click near a recorded branch position in the viewport to choose a node, or enter its ID in Node. The click picker searches within 1.5 world units of recorded controlled-body positions. Node IDs belong to the selected tree, so select the decision first.

Press Replay branch to preserve the current run and create a separate run from the tree’s native root and applicable configuration. The worker executes the action sequence along the ancestry leading to that node, records its physical frames in a segment named Search branch / node …, then pauses at the resulting world. The new run records its source decision and node. Use Play world to watch that alternative or Step to plan from its endpoint. Branch replay reconstructs physics; ordinary world playback only reads recorded states.

FMC, Wave Jump, and direct Wave exploration provide native ancestry trees. iCEM and MPPI provide candidate clouds and world motion but do not export search trees. Their lack of branches does not prevent recording or replaying their executed actions.

Tree control	Effect
Pruned	Record the search, removing orphan leaves while protecting current walkers, elites, and the ancestry they require. This is the default.
Full	Keep all recorded search nodes within each decision; tree memory grows more quickly.
Off	Disable exported search trees; executed world frames still record. Wave Jump retains at least pruned ancestry internally to recover its selected trajectory.
Keep all decisions	For an in-memory run, retain decisions until the separate 64 MiB tree budget is reached instead of retaining a recent window.

Changing Tree stages a configuration edit. Apply and restart saves the current run and starts the replacement with the selected recording policy. Keep all decisions changes retention going forward; it cannot bring back decisions already discarded.

By default the in-memory exploration record keeps at most 32 recent decisions and at most 64 MiB of tree arrays and roots. A single tree larger than that budget is rejected. With Keep all decisions, reaching the budget stops control with an export message rather than silently evicting old decisions. A device-backed run stores recorded trees on disk while keeping a bounded recent window in memory; the Keep all checkbox does not turn that window into unlimited RAM.

The renderer limits path drawing to roughly 50,000 segments. A large tree can therefore contain more branches than are drawn. This display limit does not prune the underlying tree or alter native simulation.

Save and open portable files

Open Save / Open for the Recordings, Scene, World snapshot, and Planner checkpoint groups. The descriptions distinguish a portable run, scene JSON, one physical state, and resumable controller search. The Run name field names the active run; the save status reports Saving…, Saved on this device, or Save failed.

File	Save / open controls	Contents and boundary
.fgcs	Save state / Load state	Compact native world snapshot, with format header, scene fingerprint, and payload checksum. No scene JSON, recording, or planner population.
.fgclab	Export run / Open run for an in-memory recording	Version 2 JSON archive containing scene, controller settings, seed, world motion, segment/event metadata, and retained exploration entries. Older version 1 tree-only archives still import.
.fgcrec	Export run / Open run for a device-backed recording	Version 3 chunked archive with scene/settings metadata, compressed world frames, and stored tree/checkpoint objects. Import creates a new device recording.
.fgcp	Save planner checkpoint / Load checkpoint	Version 1 checkpoint envelope containing scene, controller settings, seed, decision counter, world root, and the selected controller’s checkpoint.

Save a world snapshot

Pause control and press Save state to download the authoritative world’s .fgcs file. Save state does not save the frame currently displayed by replay. It asks the simulation worker for its current state. To save a replay frame, seek to it, press Create run from this frame, wait for the new paused world, and then press Save state. Saving a snapshot does not itself pause a running simulation, so pause first when the exact capture point matters.

Use Load state with the same compiled scene. Successful loading preserves the current run and starts a paused replacement from the snapshot with a fresh planner and a Restored snapshot segment. A snapshot contains environmental randomness and task progress but neither static scene definitions nor planner memory. Scene changes can invalidate its fingerprint; restore the matching scene JSON or open a complete run archive when transferring an experiment between sessions.

Export or reopen a run

Pause control, then press Export run. The active recording type determines the extension: .fgclab for memory, .fgcrec for device storage. A memory archive contains only the search decisions still retained, while its world motion covers the recorded session. Device export waits for queued writes and includes stored objects. It gathers compressed chunks into the portable file without expanding the entire recording, but still needs memory for those compressed chunks.

Press Open run, choose either supported run file, and wait for the scene to load. The current run is preserved before replacement. The importer opens the recorded scene and motion for read-only inspection. Choose a frame and press Create run from this frame to start an editable experiment; opening the archive does not authorize control of its recorded endpoint. A version 1 tree-only archive has no executed world stream to play; inspect its retained decisions instead.

New run and checkpoint settings include controller parameters, seed, Clock, and Worker threads. Older files may omit the execution settings; check the active configuration before creating a run from an imported experiment. Camera pose, keyboard state, layer visibility, and playback speed are also interface state, not restored physical state.

The memory importer accepts archive versions 1 and 2 and limits JSON text to 192 MiB. The device importer accepts version 3, limits the file to 1 GiB, and checks chunk order, sizes, shapes, and checksums before keeping the imported run. Motion payloads use CRC32; native .fgcs snapshots use their native checksum and scene validation. These checks catch corruption and incompatibility, not malicious authorship. Keep the matching engine build for reproducible continuation and planner checkpoints; exported world motion itself is read directly for playback.

Keep long runs on the device

Device recording is enabled by default. The run writes to this browser’s IndexedDB database; there is no account or remote upload. Changing the storage policy is a draft configuration change, applied with Apply and restart.

World samples are stored in chunks of 256 frames. Full chunks queue immediately; incomplete chunks flush every five seconds and when the page becomes hidden. Save recording flushes the incomplete chunk and waits for writes. Watch for Saved on this device before closing a valuable run: an abrupt close can lose recently unflushed frames. Saving an in-memory run transfers it to device storage in bounded chunks.

The lab preserves the current nonempty run before replacing it through restart, import, saved-run opening, checkpoint restoration, or replay branching. It waits for final recording output and storage writes. Repeated saves update the same session rather than adding duplicate library entries.

Storage uses gzip when browser compression is available and raw bytes otherwise, with CRC32 checks on decompression. Ordinary scrubbing keeps a target cache of eight durable chunks, fetching older chunks asynchronously. Unsaved chunks and protected current/read chunks can temporarily increase memory use. The world readout distinguishes KiB resident from the number of frames stored; resident memory is not the full on-disk archive size.

Press Saved runs to flush the current recording and open the device library. Entries show run names, stored frame counts, and update times, with branches identified by their parent and source frame. Rename the active run in Save / Open before saving it. Open loads that recording in read-only playback and closes the dialog. Delete removes its metadata and chunks; deletion is disabled for the currently active recording. Open a different run or reset first if you intend to delete that one. The dialog’s × closes it.

Browser storage belongs to an origin: changing host, protocol, or port can show a different library. It is subject to browser quota and eviction. Export a .fgcrec file for a portable copy, and use Open run to import it elsewhere. Importing a device archive requires writable local browser storage.

Recording budgets and write failures

The default in-memory motion recorder has its own 64 MiB payload budget, separate from the exploration budget. It stops recording/control at capacity and does not evict early world frames. Its packed frame size is 4 * (scene_words + action_dim + 1) bytes: world data, action values, and a decision ID. The one-kart circuit uses 80 bytes per sample, plus the initial snapshot and container overhead. Rendering assets are not stored in every frame.

Device recording removes that fixed total motion-payload limit, but bounds pending resident data. The guard is the larger of 32 MiB and twice the eight-chunk cache size for the current frame layout. If writes fall behind, the lab pauses with Recording storage cannot keep up. Wait for writes, then continue. Let pending writes finish and save before continuing. An actual storage write failure marks that recording as failed; later appends do not silently pretend to persist. If a replacement cannot save, the original world and draft stay available, paused. Choose Retry after resolving storage trouble, Export for a recovery file, Cancel to abandon replacement, or Continue without saving to explicitly accept proceeding without a completed device save. Export alone does not approve replacement, and the lab does not silently delete older runs to make space. These payload limits do not include all JavaScript, compression, export-buffer, native, or GPU memory.

Resume the planner rather than only its world

Press Save planner checkpoint after the world is ready. This pauses control and waits for a complete incremental iteration boundary, then downloads .fgcp. For a device-backed run it also stores the checkpoint object with the recording. The save operation aligns the planner root with the paused authoritative world. If real-time planning was targeting a future root, that search can restart at the paused world before it is checkpointed.

Press Load checkpoint, choose the file, and wait for the restoration message. The lab reloads its scene and controller settings. Step then continues the saved search rather than beginning an unrelated search from the visible pose. For Wave Jump saved during trajectory execution, it continues the unexecuted remainder of that trajectory. Checkpoints preserve controller-specific data: FMC’s population, ancestry, elites, and random state, or the shooting controllers’ partial rollouts, optimizer state, randomness, and warm-start sequences. Use the same compatible engine/backend and controller implementation for checkpoint continuation.

Wave Jump checkpoints retain its FMC search state while searching. During execution, they retain the selected trajectory, current action index, and remaining physics frames alongside the world state. Loading resumes from that position without repeating completed actions or starting another search before the trajectory ends. A scene, reward, controller, or world-state change discards the queued trajectory; ordinary Pause experiment preserves it.

A checkpoint made after Advance Wave population preserves that active Wave population. On load, the message explicitly says to use Advance Wave population to continue it. This is different from requesting an ordinary planned Step. Checkpoints do not contain the entire prior replay timeline; loading starts a new recording with a labeled restoration segment. Opening a .fgcrec with stored checkpoint objects does not automatically resume one of them: the explicit UI resume workflow uses the downloaded .fgcp file.

Mark an event and practice a complete replay

Delivery, pickup, gate, and terminal-event counters generate markers when their values increase during normal captured movement. Segment restorations are labeled separately so a restored counter is not mistaken for a newly achieved event. A terminal event reports termination; it does not by itself establish a collision. Reward-change markers retain the settings boundary: playback displays recorded rewards and does not recompute earlier outcomes with today’s reward weights. Open Events & notes and choose Jump to event… to pause control/playback and seek to a marker. The menu shows the most recent 500 events; earlier frames remain available on the slider.

To annotate a moment, seek to it, type an Event note, and press Add marker. While viewing live motion, the marker uses the latest recorded frame. Notes are limited to 120 characters and default to Marker when empty. Markers appear in exports; flush a device recording after adding notes to persist its metadata.

For a short end-to-end check, select the racing preset, choose reproducible mode and six Action frames, then Apply and restart. Press Step action twice. You now have the initial sample plus twelve captured physical frames. In World motion, seek to the first sample: the kart returns visually to its starting pose and the lap counter is zero. Play the short recording, then seek back and press Create run from this frame. The original run is saved, and a separate paused run begins at the selected world’s tick.

Open Save / Open and save a world snapshot. Step, then load that snapshot: the restored pose and checkpoint progress return. Export the resulting run and reopen it for read-only playback. Find the original run and its child in Saved runs. This exercise checks world restoration; an uncheckpointed planner need not choose the same subsequent actions. For measured alternative futures from one selected world, continue with Experiments, comparisons, and performance.