dota_factory/docs/replay_design.md

Replay — Design

This document captures the design for the replay record/playback feature. It records the decisions made during design discussion; it is a complement to architecture.md. No implementation exists yet — this is the agreed design to implement against.

Goal

Record every play session and allow it to be played back later. Playback is view-only (no interaction) with manual game-speed selection (including pause). Playback is launched via a command-line argument to the executable.

Approach: deterministic command-replay (re-simulation)

We record player intent (commands) plus the inputs needed to reproduce the run, and on playback we re-run the real simulation, injecting the recorded commands at their recorded ticks. We do not record per-tick state snapshots.

This is viable because the simulation is already built for it (see architecture.md: "determinism, replayability ... fall out for free"):

• Fixed 30 Hz tick-based simulation, decoupled from render rate via TickDriver.
• Game speed (0/0.5/1/2/4×) and pause are tick-rate multipliers — they change how many ticks run per frame, never the outcome of a tick. So speed, pause, camera scroll, and selection are pure presentation and are not recorded.
• A single deterministic RNG stream: Simulation::m_rng (one std::mt19937) is passed by reference into WaveSystem and BuildingSystem, the only two consumers. ECS combat/AI/ movement/scrap systems use no RNG. The utility::getRandom* global is not used by the sim.
• Config is immutable after load; a replay is pinned to the config it was recorded with.

A replay run is therefore a pure function of (seed, config, ordered commands).

What we do NOT do (now)

• No per-tick / keyframe state snapshots.
• No backward seek / scrubbing (would require snapshots).
• No save/load. (See "Future direction".)
• No interactive playback (no taking over a replay mid-run).

Replay commands

A replay command is the resolved, serializable intent behind a player action — the data, not the UI gesture. Example: placing a miner records PlaceBuilding{type=Miner, anchor=(3,5), rotation=East}, not the mouse pixel that produced it.

• Commands are at intent level, resolved to tile coordinates / domain ids — independent of window size, camera scroll, and DPI.
• Command payloads reference stable, deterministic domain ids (BuildingId, tile coordinates, choice indices) — never raw entt::entity handles. These ids are sim-allocated deterministically, so a recorded command resolves to the same entity on replay.
• Camera scroll, selection, game speed, and pause are not commands.

Command vocabulary

One command per sim-mutating operation (the complete mutation surface):

• PlaceBuilding
• Demolish
• RotateInPlace
• SetRecipe
• SetShipLayout
• SetSplitterFilters (building-site and belt variants)
• ClearBeltTiles
• ApplySchematicChoice
• Reset / restart — see "Restart is a boundary".

Command representation

Commands use a base class + derived classes (mirroring the existing Event hierarchy idiom, so it is native to this codebase). They are routed through a dedicated command path, not through EventManager (see next section).

Command system: reuse the pattern, not the EventManager singleton

We reuse the pattern of the existing event system (a polymorphic base + small derived types), but the sim-mutating command path is a dedicated, ordered queue, not the EventManager pub/sub bus. Reasons:

1. Determinism / ordering. Sim mutations must apply in a strict, tick-pinned, recorded order. architecture.md deliberately keeps the sim free of EventManager for exactly this reason (determinism, tick-order fidelity, headless testability — why BeamFiredEvent uses a plain vector). Routing commands into the sim via the singleton would break that.
2. Single consumer. A command has exactly one recipient (the Simulation); pub/sub N-handler fan-out is the wrong shape.
3. Recording chokepoint. One place must see every command, stamp its tick, append it to the file, and apply it. A direct queue gives that; a multi-handler bus does not.
4. Headless tests. Tests link only lib and build a Simulation directly; the command type and apply path live in lib and must work with no UI and no singleton.

Structure

• In lib: a Command base class + derived command types, plus a CommandManager (ordered queue) and a single Simulation::apply(command) chokepoint.
• UI fan-in still uses EventManager: widgets emit a UI event as today; a single dispatcher/recorder catches it, builds the lib command, and hands it to the CommandManager. This keeps widgets decoupled (consistent with current architecture).
• Replay skips the UI half and feeds commands straight into the same CommandManager / Simulation::apply chokepoint.

The completeness invariant (enforced structurally)

Every sim mutation must flow through the single CommandManager → Simulation::apply chokepoint. Any path that mutates the sim directly would not be recorded and would silently desync the replay.

This is enforced structurally, not by discipline: the Simulation mutators (tryPlaceBuilding, demolish, setRecipe, …) are made private/non-public so the only way to reach them is apply(command). A stray direct call then fails to compile rather than compiling and silently desyncing.

Recording happens at the apply chokepoint, not at the UI gesture — so only commands that actually reached the sim are recorded, and they replay through the identical apply path. UI-side validation (placement validity, affordability) remains a pre-filter that simply does not produce a command unless the action reaches the sim.

Command timing: drain once per frame, before the tick batch

• During live play, input pushes commands onto the CommandManager queue (not applied synchronously).
• The queue is drained at one defined point: once per frame, before stepping the tick batch. The whole queue is drained in FIFO order (not one-per-tick), so bursts (e.g. laying many belts quickly) apply immediately instead of dribbling across ticks, and it matches the lockstep model wanted later.
• Each drained command is tagged with the current completed-tick count, recorded at drain time (so record-order == apply-order canonically), and applied.

Build-while-paused is preserved

The drain runs every frame including at 0× (the tick batch is simply empty when paused). So a player can place buildings while paused and see the construction sites immediately. This is still fully deterministic: replay applies each command at its recorded tick regardless of the frame cadence that produced it.

On replay, there is no input; the player applies each pre-filled command at its recorded tick through the same drain path, preserving order.

The Qt single-threaded event loop guarantees input events and the onFrame tick-batch never interleave, so the completed-tick count at drain time is unambiguous. (If the sim is ever moved to a worker thread, this needs a lock at the sim boundary.)

Determinism: checksums and verification

We do not verify EnTT iteration order statically. EnTT view iteration is a pure function of the sequence of spawn/destroy/add/remove operations, so on a fixed binary it contributes zero run-to-run nondeterminism. Instead we verify end-to-end determinism with a state checksum, and any divergence (EnTT order, float, container ordering, etc.) surfaces loudly.

What is checksummed (now)

• RNG state only, for now. The mt19937 state is fingerprinted into a 64-bit value.
• The hash can be extended later (entity positions/HP, belt items, building buffers, scalars) without changing the format.

Cadence

• In the replay file: every 30 ticks, and after every command is applied. The per-command checksum pins any divergence to the action that triggered it; the periodic one localizes drift to a ~1 s window. On playback the recomputed checksum is compared; a mismatch reports "desync at tick N".
• In tests: the Catch2 double-run determinism test hashes full sim state every tick (not just RNG). It runs a scripted command sequence twice from the same seed and asserts per-tick checksums match. This keeps the file lean while still catching non-RNG determinism bugs during development.

Known limitation of the RNG-only file checksum (accepted)

An RNG-only checksum only catches divergences that change how much randomness is consumed (wave composition, recipe rolls, scrap). Float or iteration drift that does not alter RNG draw counts passes the checksum undetected. This is acceptable for same-binary Windows replay (no float drift expected on an identical binary; the checksum's real job there is catching determinism bugs). When cross-platform replay becomes a goal, the file hash must be expanded to include entity state.

Cross-platform: Windows-first, portable by construction

The replay file is platform-neutral data; std::mt19937 is bit-identical across platforms, so RNG is not a cross-platform problem. The only real cross-platform issue is floating-point reproducibility — the sim does heavy QVector2D float math, and a 1-ULP difference (compiler / CPU / SIMD / FMA contraction) can flip an in-range comparison and cascade into different ship behavior (the classic lockstep-RTS problem).

Decision: Windows-only first, but make the later swap cheap and bounded by, from day one:

• a per-period state checksum in the file (above), and
• a build/version + config-hash identity tag in the header.

Then cross-platform later is a contained float-hardening pass (/fp:strict, no FMA contraction, possibly fixed-point positions) guided by the checksums — not a redesign of the command-replay architecture.

Note: even a new Windows build of the game can desync old replays for the same float reasons, so the version tag + "warn on mismatch" is needed regardless of cross-platform ambitions.

Seed and config

• Seed: a random seed is generated at the start of each run, outside the sim (e.g. std::random_device in main/reset), so the Simulation stays a pure function of (seed, config, commands). The seed is written to the replay header.
• Config: the header stores a config hash (not a full config snapshot). On playback the current config is hashed and compared; a mismatch warns/refuses. The hash is taken over the actually-loaded config (so editing config files and restarting yields a new, consistent replay).

File format: line-oriented append-friendly text

Non-binary, chosen for readability and crash-safety. Size is a non-issue: the command log is sparse (only ticks with a player action), so even a multi-hour game is tens of KB in any text format.

• A small keyed/header section: seed, config hash, build/version, start timestamp.
• One line per command, e.g. 1234 place miner 3 5 E.
• Periodic checksum lines interleaved, e.g. # checksum 9000 a1b2c3....

Why line-oriented text:

• Append-friendly — the recorder stream-appends as the game runs, so a crash does not lose the replay (a crash is exactly when you would want it). A format that must be rewritten/closed as a whole is rejected for this reason.
• No new dependency — the project has no JSON lib; toml++ is parse-oriented and clunky for a long event stream (fine for the header, awkward as an array-of-tables of thousands of entries).
• Greppable, diffable, tiny.
• Aligns with the project's existing text-serialization idiom (BlueprintSerializer, ShipLayoutBlueprintSerializer).

Recording lifecycle

• Record every run. A new replay file is created at Simulation construction and at each reset().
• Restart is a boundary. Restart (escape menu → restart, which reloads config and resets) closes the current file and opens a new one with a fresh seed and header. One replay file = one contiguous run from tick 0 to game-over/quit.
• Retention: keep everything. Files live in the existing data/ directory, named by timestamp + seed. (No automatic pruning for now.)

Playback

Launched via a command-line argument, e.g. DotaFactory.exe --replay <file>.

main for the --replay path:

1. Read the header → validate config hash and build/version (warn on mismatch).
2. Construct the Simulation from the recorded seed + config.
3. Construct the CommandManager in Replay mode, pre-filled with the whole command list from the file. (Pre-fill memory is trivial; streaming-read is a later optimization if files ever get huge — not needed now.)
4. Run the driver in replay mode: each frame, drain commands due at the reached tick (same drain path as live), step ticks, compare checksums.

Replay mode rules

Reframe: the schematic-choice modal is an input source (the device that produces an ApplySchematicChoice command in live play), exactly like the mouse. Replay's single rule is "disable live input sources", which the modal falls under.

• CommandManager in replay mode: addCommand is a no-op; the queue is pre-filled from the file. Live input therefore produces nothing.
• Only two reactions need explicit gating — the sim-state polls in onFrame that emit SchematicChoicesAvailableEvent and GameOverEvent. In replay these polls do not run, so no modal opens, no auto-pause occurs, and there is no deadlock against the recorded command.
• Everything else falls away for free because it is click-driven, not sim-state-driven: the recipe dialog (RecipeSelectionRequestedEvent), ship-layout dialog (LayoutDialogRequestedEvent), and escape menu are all triggered by player input, which is disabled — so they never open and need no special handling.
• Schematic choice still resolves with no UI: the sim regenerates identical choices deterministically (same seed + prior commands), and the pre-filled ApplySchematicChoice applies itself at its recorded tick through the normal drain path. The tick-tag invariant places it correctly relative to when the choices became pending, in both record and replay.
• Game-over is replaced, not just suppressed: instead of the live restart/quit dialog, playback detects the end condition (command stream exhausted / recorded game-over reached) and stops, showing a passive "replay ended" state.
• Kept in replay: the renderer/view and manual game-speed selection (including pause / 0× and fast-forward via high speed). Playback only ever moves forward.

Future direction (informs the design, not built now)

Save/load and (deterministic lockstep) multiplayer are wanted later. The command bus is the shared foundation; two cheap shaping decisions now keep that path open:

1. Each command carries a source/player id (always "player 0" in single-player). Lockstep multiplayer is just commands from multiple sources merged into one ordered stream.
2. Commands are applied at a defined tick boundary (already required for replay). Multiplayer schedules them a few ticks in the future to hide latency; single-player uses the next drain.

Implications to note:

• Multiplayer makes cross-platform float determinism mandatory and promotes the checksum to load-bearing desync-detection (rather than a test aid) — reinforcing doing the checksum now.
• Save/load is the one feature that needs a different mechanism: either "replay to current tick" on load (reuses 100% of replay machinery; load time grows with game length, though fast-forward usually replays hours in seconds), or a full state-snapshot serializer (EnTT registry + belts + buildings + scalars). The snapshot serializer is also what backward-seek/scrubbing would need. Building the command bus now does not block adding it later; it is explicitly out of scope here.

Summary of decisions

• Approach: A — deterministic command-replay (re-simulation), no snapshots.
• Scope: view-only playback + manual speed selection; launched via CLI argument.
• Commands: base class + derived types, routed through a dedicated CommandManager queue and a single Simulation::apply chokepoint; sim mutators made non-public to enforce the chokepoint. UI fan-in still uses EventManager.
• Timing: queue drained once per frame before the tick batch, whole queue FIFO, each command tick-tagged; build-while-paused preserved.
• Determinism: RNG-state checksum in the file every 30 ticks + after each command; full-state per-tick hashing in the Catch2 double-run test. Known RNG-only blind spot accepted for now.
• Platform: Windows-first; file format + version/config-hash make a later cross-platform pass contained.
• Seed: random, generated outside the sim, written to the header.
• Config: config hash in the header, validated on playback.
• File: line-oriented append-friendly text, kept in data/, one file per run, retain everything.
• Restart: a boundary — new file, new seed.
• Replay mode: CommandManager addCommand is a no-op + pre-filled; gate the two sim-state polls (schematic choices, game-over); passive "replay ended" instead of the game-over dialog; keep view + speed.

Implementation plan

Ordered to de-risk: prove determinism first, then build the command path, then recording, then playback. Each phase is independently testable and leaves the game in a working state. Phases 0 → 1 → 2 → 3 are strictly sequential; Phase 4 tests can start as soon as their subject exists.

Phase 0 — Determinism foundation & verification (no replay yet)

The whole feature rests on a deterministic sim, so prove that before building on it.

• Add a mt19937 state fingerprint (fold its serialized state into a 64-bit value).
• Add a full-state checksum path (positions, HP, velocities, belt items, building buffers, scalars), used by tests; each subsystem contributes via its own appendChecksum(Hasher&) so no state knowledge is duplicated.
• Add a Catch2 double-run determinism test: run a scripted sequence twice from the same seed, assert per-tick full-state checksums match.
• Files: new lib/sim checksum helper; small additions to Simulation, BeltSystem, BuildingSystem, ECS state; new test.
• Exit criteria: the double-run test passes. If it fails, fix the nondeterminism here before proceeding.

Phase 1 — Command model + enforced chokepoint (no recording yet)

Reshape mutations to flow through one path; behaviour unchanged.

• Define Command base + derived types (PlaceBuilding, Demolish, RotateInPlace, SetRecipe, SetShipLayout, SetSplitterFilters, ClearBeltTiles, ApplySchematicChoice, Reset) in lib. Each carries a source/player id (always 0 now) for the future-multiplayer shape.
• Add CommandManager (FIFO queue, drain) in lib, holding a Simulation&.
• Add Simulation::apply(const Command&) dispatching to the existing mutators; then make those mutators non-public so apply is the only entry — compile-enforces the completeness invariant.
• Wire the drain: in GameWorldView::onFrame, call CommandManager::drain() once per frame, before the tick batch; tag each command with the current completed-tick count.
• Refactor every UI mutation site to emit a single CommandRequestedEvent (carrying a shared_ptr<Command>) via the existing EventManager; one dispatcher subscribes and enqueues onto CommandManager.
• Files: new lib command + CommandManager; Simulation.h/.cpp; call sites in GameWorldView.cpp, MainWindow.cpp, SelectedBuildingPanel.cpp; new dispatcher in ui/app.
• Exit criteria: game plays identically (including build-while-paused), determinism test still passes, no widget can call a sim mutator directly (won't compile).

Phase 2 — Recording

• Implement the line-oriented append writer: header (seed, config hash, build/version, timestamp) + one line per command + checksum lines.
• Generate a random seed outside the sim (in main/reset), write to header.
• Compute the config hash over the loaded config.
• Hook the recorder at the apply chokepoint in CommandManager::drain(): append each command (tick-tagged), append an RNG checksum after every command and every 30 ticks.
• Lifecycle: open a new file on Simulation construction and on each reset() (restart = boundary); store in data/, named by timestamp+seed; retain everything.
• Files: new replay writer in lib; main.cpp (seed), config hash helper; CommandManager/Simulation for the tick checksum hook.
• Exit criteria: every run produces a well-formed, growing replay file; a crash mid-run still leaves a valid partial file.

Phase 3 — Playback

• Implement the reader/parser for the format (header + commands + checksums).
• Add the --replay <file> CLI path in main: validate config hash + version (warn on mismatch), construct Simulation from seed+config, construct CommandManager in replay mode (pre-filled, addCommand is a no-op).
• Replay driver: each frame, drain commands due at the reached tick (same drain path), step ticks, keep manual speed/pause, playback only moves forward.
• Gate the two onFrame polls (schematic-choices, game-over) off in replay mode; everything else (recipe/layout dialogs, escape menu) is input-driven and falls away automatically.
• Desync detection: recompute the RNG checksum at each checkpoint, compare to the file, report "desync at tick N" on mismatch.
• Passive end: when the command stream is exhausted / recorded game-over is reached, stop with a "replay ended" overlay instead of the restart dialog.
• Files: new reader in lib; main.cpp; CommandManager (replay mode); GameWorldView.cpp (poll gating, end overlay).
• Exit criteria: a recorded file plays back identically; checksums match throughout.

Phase 4 — Closing tests & polish

• Round-trip test: serialize → parse → assert command equality.
• Replay-equivalence test (headless): record a scripted run, play it back through the same lib path, assert per-tick checksums match end-to-end — the real proof, no UI needed.
• Mismatch-warning UX, end-of-replay overlay polish.

Notes

• Phase 1 is the largest (the mutation-site refactor); Phase 0 is the riskiest (it may surface latent nondeterminism that must be fixed first).
• Still deferred (per this design): snapshots, save/load, backward-seek, cross-platform float hardening, expanding the file checksum beyond RNG.