gameplay-recording-replay

Overview

A deterministic replay artefact is a recorded session of player input or replicated state that can be played back to recreate the original game state. Three reasons games invest in replays:

1. Regression tests. Record a scripted playthrough; replay it in CI; assert the final state matches the original. Catches physics drift, AI determinism breaks, save-format regressions.
2. Bug repros. Players record a session; QA replays it inside the build with the bug; cert teams attach the replay to the ticket.
3. Esports / spectator / clip sharing. Match replays surfaced in-product.

This is a workflow that produces, per engine, a working record/replay setup plus a CI regression test that runs it. The full per-engine record, replay, and CI code lives in references/engine-record-replay-apis.md; this file is the cross-engine decision surface.

The three engine surfaces differ:

Composes with:

• unity-test-framework, unreal-automation-system, godot-gut-tests - the host test framework the replay runs inside.
• multiplayer-state-machine-coverage - Unreal's Replay system shares NetworkReplayStreamer with its multiplayer stack; multiplayer fixtures can replay captured sessions.
• platform-cert-overview-reference - replays are evidence artefacts for cert (Xbox XR-003 title quality, attaching a repro to a CFR).

When to use

• Producing a deterministic regression test for a story playthrough / level traversal / damage script.
• Building an in-product replay feature (spectator mode, instant replay, clip sharing).
• Producing reproducible repro artefacts for cert teams.
• Investigating a determinism regression - "this build diverges from the previous build's replay at frame 4823."

How to use

1. Lock determinism first for the capture level you need - fix the Step 1 sources of non-determinism (fixed timestep, seeded RNG, synchronous loads) before recording anything.
2. Pick the capture level from the Step 2 per-engine contract table - Unity and Godot capture input (which needs determinism); Unreal captures the replication stream (which does not).
3. Record and replay with the engine's API - full working code in references/engine-record-replay-apis.md.
4. Choose the assertion model (final-state hash, per-checkpoint, or per-frame) and wire the replay into a CI regression test (Step 3).
5. Embed a build hash + replay-format version in the replay header so CI can tell a real regression from a stale replay (Step 4).

Inputs

Gather before walking the workflow:

Workflow

Step 1 - Establish determinism

Replays are worthless if the game is non-deterministic. Before any recording work, lock down:

If you can't lock determinism, replay can still be useful as a visual debug artefact, but it won't drive regression assertions.

Step 2 - Record and replay per engine

Each engine captures at a different level, with a different determinism contract. Pick the row that matches your engine, then lift the working record + replay code from references/engine-record-replay-apis.md.

The key split: input-level replay (Unity, Godot) depends on determinism; replication-stream replay (Unreal) does not, because the Unreal simulation already ran on the server and the replay just re-streams its output. This is why Unreal replays handle full multiplayer matches while Unity/Godot replays are for pinned single-player.

Step 3 - Wire replays as CI regression assertions

Per engine, the CI loop is:

1. Check the replay file into the repo under test/replays/.
2. CI job loads the build, plays the replay, hashes the final game state.
3. Compare the hash against the baseline (also in repo).
4. Mismatch → CI fails the build.

The per-engine harness code (Unity [UnityTest] PlayMode fixture, Unreal LatentIt latent command, Godot GUT fixture) is in references/engine-record-replay-apis.md.

Step 4 - Define a fail-safe for replay drift

Real-world replays drift when:

• The game build version changed and the replay was recorded against an earlier version.
• A non-deterministic source slipped in (new async loader, new particle system using Random).
• The save format changed.

The harness must distinguish bug-in-build from replay-stale. Encode the build hash + replay format version in the replay header; CI rejects replays whose replay_format < current_format, then either re-records (acceptable for visual replays) or fails the build (regression test replays).

Worked example - Unity speedrun regression

Inputs:

• Engine: Unity 6.0, Input System v1.8.
• Determinism: Physics at FixedUpdate, 60 Hz; RNG seeded from replay header; AI scripted via deterministic state machines.
• Recording scope: Input-only via InputEventTrace.
• Storage: Assets/Tests/Replays/level1.trace (committed to the repo).
• Length budget: 90 s - fits comfortably in 4 MB buffer (recordFrameMarkers = true per the API page).
• Assertion: SHA-256 hash of GameStateRoot.Serialize() at T=90 s.

Step 1 - physics on FixedUpdate, RNG seeded from replay header, async loads forced synchronous in headless mode.

Step 2 - recorder MonoBehaviour creates InputEventTrace, enables on level start, writes to level1.trace on first level completion.

Step 3 - CI fixture (UTF [UnityTest]) reads the trace, replays it, hashes the final GameStateRoot, compares to the baseline hash committed in Assets/Tests/Baselines/level1.hash.

Step 4 - replay header includes replay_format = 2 and build_hash = <git-sha>. CI fails the build with a clear "replay stale" message when format < 2 rather than silently passing.

Anti-patterns

Limitations

• Input-level replay (Unity) and replication-stream replay (Unreal) are different contracts. Unity replays depend on determinism; Unreal replays reconstruct the server's view and do not. Don't conflate them in a multi-engine team.
• Godot has no first-party replay system per the Godot documentation home; the community pattern in Step 2 is sufficient for deterministic single-player but doesn't generalise to multiplayer.
• Unreal replays bloat with high-bandwidth replication. The .replay file under %LOCALAPPDATA%/<Project>/Saved/Demos grows with replicated-property volume - large open-world games produce GB-scale replays. Use checkpoint-only replays for long sessions.
• Build-version coupling. Replays recorded against build N rarely play correctly on build N+1 if the netcode / save format changed. Treat the replay file as a build-pinned artefact.
• No public common exit-code definition for replay-failed states in either Unity or Unreal - parse the test framework's result file (UTF NUnit XML or Unreal automation JSON) for the failure detail, don't rely on engine exit code.
• No assertion API on Unreal DemoNetDriver replay completion in public docs - the spec / latent-command harness must poll the demo time and time-out. See Replays in Unreal Engine.
• PII in replays. Player chat, gamertags (per Microsoft XR-046 modern-gamertag display rules), and inventory data can land inside replay attachments - strip before sharing with cert / publisher.

References

• Unity Input System InputEventTrace API - com.unity.inputsystem@1.8.
• Replays in Unreal Engine - dev.epicgames.com; recording + storage in Recording Replays, scrubbing in Playing Back Replays.
• Godot documentation home (no first-party replay subsystem) - docs.godotengine.org.
• Microsoft gamertag display / cert rules - certification-requirements.
• Full per-engine record, replay, and CI-assertion code (with their citations): references/engine-record-replay-apis.md.
• Host test frameworks: unity-test-framework, unreal-automation-system, godot-gut-tests.
• Netcode neighbour: multiplayer-state-machine-coverage.
• Cert evidence: platform-cert-overview-reference.