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:
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:
| Engine | Recording surface | Stability of public docs |
|---|---|---|
| Unity | Input System's InputEventTrace (input-level) | Public - com.unity.inputsystem@1.8 API (opens in new window) |
| Unreal | Replay System (replication-stream level) - DemoRec / DemoPlay / DemoStop | Public - Replays in Unreal Engine (opens in new window) |
| Godot | No first-party replay - community pattern: deterministic RNG seed + recorded InputEvent script | Community - Godot documentation does not ship a replay subsystem [author opinion, per docs.godotengine.org (opens in new window)] |
Composes with:
When to use
How to use
Inputs
Gather before walking the workflow:
| Input | Where | Why |
|---|---|---|
| Engine + version | Project | Determines which API surface applies |
| Determinism baseline | Game design - is fixed-tick physics on? RNG seeded? AI deterministic? | Replays only work when the game's per-frame outputs are functions of (state + input) |
| Recording scope | Input-only? Full replication stream? | Trades off file size against determinism guarantees |
| Target storage location | Application.persistentDataPath, %LOCALAPPDATA%/<Project>/Saved/Demos, etc. | Where replay files land |
| Replay length budget | Seconds / minutes | InputEventTrace buffer sizing |
| Assertion model | Final-state hash? Per-frame? Checkpoint-only? | Drives the test harness shape |
Workflow
Step 1 - Establish determinism
Replays are worthless if the game is non-deterministic. Before any recording work, lock down:
| Source of non-determinism | Lock-down |
|---|---|
Variable timestep / Time.deltaTime | Run physics on FixedUpdate (Unity) / TickGroup (Unreal) with a fixed delta |
Unseeded Random | Seed every RNG at session start; record the seed in the replay header |
| Async load timing | Force synchronous load during replay (SceneManager.LoadScene sync; AssetRegistry::Tick to drain) |
| Multithreaded game logic | Pin to one thread or commit to ordered consumption of results |
| Frame-rate-dependent FX | Tag visual-only systems and skip them in headless replay runs |
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.
| Engine | Capture level | Default storage | Determinism contract |
|---|---|---|---|
| Unity | Input events (InputEventTrace, buffer-sized) | Application.persistentDataPath / repo test/ | Needs Step 1 - replay reproduces input; state matches only if the sim is a pure function of state + input |
| Unreal | Replication stream (DemoNetDriver + NetworkReplayStreamer) | %LOCALAPPDATA%/<Project>/Saved/Demos | Reconstructs the server's streamed view - does not require local determinism |
| Godot | Input events + RNG seed (community pattern) | FileAccess path of choice | Same contract as Unity - needs Step 1 |
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:
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 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:
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
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Recording input without seeding RNG | Replay diverges by frame ~30 | Step 1 - every RNG seeded; seed in replay header |
InputEventTrace without Dispose() | Memory leak per API page (opens in new window) - "must be disposed of … or they will leak memory on the unmanaged (C++) memory heap" | Always using / Dispose() |
InputEventTrace without recordFrameMarkers = true | Replay reissues events back-to-back instead of respecting timing per API page (opens in new window) | Set recordFrameMarkers = true before Enable() |
| Comparing per-frame state instead of checkpoints | False-positive failures from float-precision drift | Hash at coarse-grained checkpoints (every N seconds or per level) |
| Treating Unreal replays as deterministic input replays | They're replication-stream replays - different determinism contract per Replays page (opens in new window) | Document the contract; don't assume input-level determinism |
| Storing replay format version implicitly | Replay-stale failures get misdiagnosed as bugs | Embed replay_format + build_hash in the header |
| Replays committed without their baselines | Asserting nothing | Commit replay.trace + baseline.hash as a pair |
| Replays > 30 min in CI | Replay run time dominates total job time | Split into checkpointed mini-replays |
| Replay scrubbing in test fixtures | Many engines don't expose deterministic scrubbing for tests | Linear playback only in regression fixtures; scrubbing is a feature, not a test surface |
| Replays storing PII | Saved player names / chat messages in attached repros | Strip PII from replay headers before sharing |
Limitations
References
Deep reference for gameplay-recording-replay SKILL.md - the full working record, replay, and CI-assertion code for Unity, Unreal, and Godot. Consult after Step 1 (determinism) is locked, when wiring the actual capture for your engine.
Unity - InputEventTrace
Per the InputEventTrace API page (opens in new window), InputEventTrace "captures input events into an unmanaged memory buffer". Critically: traces "must be disposed of (by calling Dispose()) after use or they will leak memory on the unmanaged (C++) memory heap".
Recording:
using UnityEngine.InputSystem.LowLevel;
public class SessionRecorder : MonoBehaviour
{
private InputEventTrace _trace;
void Start()
{
// 4 MB buffer; grow up to 64 MB; default device = all
_trace = new InputEventTrace(bufferSizeInBytes: 4 * 1024 * 1024,
growBuffer: true,
maxBufferSizeInBytes: 64 * 1024 * 1024);
_trace.recordFrameMarkers = true; // per the API page
_trace.Enable();
}
public void StopAndSave(string path)
{
_trace.Disable();
_trace.WriteTo(path); // binary on-disk format
}
void OnDestroy()
{
_trace?.Dispose(); // required per the API page
}
}Per the same API page: "Enable recordFrameMarkers to insert boundary events between frames, allowing proper temporal spacing during playback" - without it, the replay will reissue events back-to-back rather than respecting original frame timing.
Replay:
public void Replay(string path)
{
var trace = new InputEventTrace();
trace.ReadFrom(path); // per the API page
var controller = trace.Replay(); // returns ReplayController
controller.PlayAllEventsAccordingToTimestamps();
// or controller.PlayAllFramesOneByOne() for headless step
}Per the API page, Replay() "begins event reconstruction, returning a ReplayController object" - the controller exposes play / pause / scrub / step methods.
Determinism caveat. InputEventTrace captures the input but not the game state. A replay reproduces the same input events in the same order - if the game's per-frame output is a pure function of state + input + fixed delta + seeded RNG (Step 1), the resulting state matches. If not, the replay diverges.
CI regression assertion (UTF [UnityTest] PlayMode fixture):
[UnityTest]
public IEnumerator Level1_Speedrun_Replay_MatchesBaseline()
{
var trace = new InputEventTrace();
trace.ReadFrom("Assets/Tests/Replays/level1.trace");
var ctl = trace.Replay();
ctl.PlayAllEventsAccordingToTimestamps();
yield return new WaitForSeconds(60f); // length of replay
var hash = GameStateHasher.Compute(GameStateRoot);
Assert.AreEqual("baseline-hash-here", hash);
trace.Dispose(); // per the API page
}Unreal - Replay System
Per Replays in Unreal Engine (opens in new window), Unreal's replay system captures the replicated state stream via the DemoNetDriver and persists via NetworkReplayStreamer. Default storage per the Recording Replays page (opens in new window): %LOCALAPPDATA%/<Project>/Saved/Demos.
Console commands (per the same page):
| Command | Effect |
|---|---|
DemoRec <FriendlyName> | "Initiate replay recording" - emits a .replay file under Saved/Demos |
DemoStop | Stop recording / playback |
DemoPlay <FriendlyName> | Play back a previously recorded replay |
The <FriendlyName> argument is the replay's identifier - per the same page "helps distinguish between multiple recording sessions".
Programmatic recording (per the Recording Replays page (opens in new window)):
// In-game: start recording
GEngine->Exec(GetWorld(), TEXT("DemoRec MyMatch_v1"));
// Stop
GEngine->Exec(GetWorld(), TEXT("DemoStop"));
// Play back
GEngine->Exec(GetWorld(), TEXT("DemoPlay MyMatch_v1"));For lower-level control, use FNetworkReplayStreamer directly (per the same page) - the streamer exposes start / stop / pause / goto-time methods and is the abstraction DemoNetDriver wraps.
Time-shifting and scrubbing are supported per the Playing Back Replays page (opens in new window) - playback isn't strictly forward-only; replays can be scrubbed to arbitrary timestamps.
Determinism semantics differ from Unity. Unreal records the output of the network replication layer, not raw input. The replay reconstructs the server's view as it was streamed to clients - it does not require the local game simulation to be deterministic (the simulation already happened on the server). This is why Unreal replays are practical for full multiplayer matches whereas Unity InputEventTrace replays require pinning deterministic single-player.
CI regression assertion (in an unreal-automation-system test):
LatentIt("Level1 replay reaches baseline checkpoint",
[this](const FDoneDelegate& Done)
{
GEngine->Exec(GetWorld(), TEXT("DemoPlay Level1_Baseline"));
// poll for replay end via DemoNetDriver state, then
// hash GameState and compare to baseline
StartReplayWatchdog(Done);
});Godot - community deterministic pattern
Godot has no first-party replay subsystem comparable to InputEventTrace or DemoNetDriver [author opinion, per the Godot documentation home (opens in new window) which does not surface a testing/replay section]. The community pattern is deterministic RNG seed + recorded InputEvent script:
# recorder.gd
extends Node
var _events: Array = []
var _rng_seed: int
func _ready():
_rng_seed = randi()
seed(_rng_seed)
func _input(event: InputEvent):
_events.append({
"tick": Engine.get_physics_frames(),
"event": event.duplicate(),
})
func save_to(path: String) -> void:
var f := FileAccess.open(path, FileAccess.WRITE)
f.store_var({"seed": _rng_seed, "events": _events})
f.close()# player.gd - replay
extends Node
var _events: Array
var _cursor := 0
func load_from(path: String) -> void:
var f := FileAccess.open(path, FileAccess.READ)
var data = f.get_var()
seed(data["seed"])
_events = data["events"]
func _physics_process(_dt):
while _cursor < _events.size() \
and _events[_cursor]["tick"] <= Engine.get_physics_frames():
Input.parse_input_event(_events[_cursor]["event"])
_cursor += 1Replay reissues InputEvents on the same Engine.get_physics_frames() tick they were captured. Combined with seed(...) re-applied from the header and fixed physics/common/physics_ticks_per_second, this gives equivalent determinism to Unity's InputEventTrace pattern.
CI regression assertion - test harness in godot-gut-tests:
extends GutTest
func test_level_1_speedrun_replay_matches_baseline():
var player := preload("res://src/replay_player.gd").new()
player.load_from("res://test/fixtures/level1_baseline.replay")
add_child(player)
await get_tree().create_timer(10.0).timeout
var final_state := %Game.get_state_hash()
assert_eq(final_state,
"abc123…baseline-hash…",
"Replay produced same final state hash as baseline")