Skip to main content
The Crimsonland reimplementation features a complete deterministic replay system for recording, verifying, and analyzing gameplay sessions.

​
Overview

Replays capture input events with frame-perfect timing, enabling:
  • Verification — Validate gameplay claims and scores
  • Benchmarking — Measure simulation performance
  • Video Rendering — Export to high-quality MP4
  • Parity Testing — Compare against original executable
  • Timeline Analysis — Extract gameplay events

​
Replay File Format

Replays use the .crd (Crimsonland Replay Data) format:
  • Binary msgspec-encoded structure
  • Header with game mode, seed, settings
  • Frame-by-frame input events
  • Claimed final stats (score, kills, etc.)
  • SHA256 hash for integrity

​
Commands

​
List Replays

crimson replay list
Displays all replays under base-dir/replays/ with metadata. Learn more →

​
Play Replay

crimson replay play <file>
Play back a recorded replay with full rendering. Learn more →

​
Verify Replay

crimson replay verify <file>
Headless simulation to verify score claims. Learn more →

​
Render to Video

crimson replay render <file>
Export replay to 60fps MP4 video with audio. Learn more →

​
Benchmark Performance

crimson replay benchmark <file>
Measure simulation throughput (ticks per second). Learn more →

​
Extract Timeline

crimson replay info <file>
Extract gameplay event timeline (kills, perks, deaths).

​
Recording Replays

Replays are automatically recorded during gameplay when using a seeded run: 
crimson --seed 42
# Play a session
# Replay saved to base-dir/replays/
Replay files include:
  • Game mode and settings
  • RNG seed
  • Input events with tick timing
  • Final stats (score, kills, time)

​
Deterministic Simulation

Replays rely on deterministic simulation contracts:
  1. Identical RNG — Same seed produces same random sequence
  2. Float32 Parity — Math operations match original executable
  3. Frame-Perfect Input — Events occur at exact tick indices
  4. No External State — Simulation depends only on seed + inputs
This enables bit-for-bit reproducibility across platforms and game versions.

​
Verification Workflow

​
1. Record Gameplay

crimson --seed 12345
# Complete a survival run

​
2. Verify Score

crimson replay verify replays/survival-12345.crd
Output: 
ok: ticks=36000 elapsed_ms=600000 score_xp=125000 kills=1200
header_claim match=True

​
3. Export Timeline

crimson replay info replays/survival-12345.crd --format json > timeline.json

​
4. Render Video

crimson replay render replays/survival-12345.crd --out run.mp4

​
Use Cases

​
Speedrun Verification

Verify claimed times and scores: 
crimson replay verify speedrun.crd --format json

​
Performance Benchmarking

Measure simulation throughput: 
crimson replay benchmark long-run.crd --mode headless --runs 5

​
Parity Testing

Compare against original game using checkpoint verification: 
crimson replay verify-checkpoints original.crd --checkpoints original.crd.chk

​
Content Creation

Render high-quality gameplay videos: 
crimson replay render highlight.crd --fps 60 --crf 18 --preset slow

​
Debugging

Extract detailed event timeline: 
crimson replay info bug-repro.crd --verbose --player-index 0

​
Replay Storage

Replays are stored in base-dir/replays/: 
base-dir/replays/
├── survival-2024-03-15-123456.crd
├── quest-1.5-2024-03-15-130000.crd
└── rush-2024-03-15-140000.crd
Filename format: <mode>-<timestamp>.crd

​
Advanced Features

​
Checkpoint Sidecars

Store periodic state snapshots alongside replays: 
replay.crd
replay.crd.chk  # Checkpoint sidecar
Used for differential parity testing against original executable.

​
RNG Tracing

Enable detailed RNG call tracing: 
crimson replay verify replay.crd --trace-rng
Captures all RNG calls for debugging desync issues.

​
Partial Replay

Simulate only first N ticks: 
crimson replay verify replay.crd --max-ticks 10000

​
Limitations

  • Replays are tied to game version (breaking changes invalidate old replays)
  • Multiplayer replays require network determinism (experimental)
  • Visual settings (RTX mode) don’t affect simulation but change rendering

​
Replay Schema

Replays use msgspec for fast serialization: 
class ReplayHeader(Struct):
    game_version: str
    game_mode_id: GameMode
    tick_rate: int
    rng_seed: int
    player_count: int
    quest_level: str
    claimed_stats: ClaimedStats

class Replay(Struct):
    header: ReplayHeader
    inputs: list[ReplayInputFrame]
See crimson.replay.types for full schema.

​
Next Steps

List Replays

Browse saved replays

Play Replay

Watch replay playback

Verify Scores

Validate gameplay claims

Render Video

Export to MP4