Skip to main content
The Crimsonland rewrite is a behavioral parity reimplementation of the classic 2003 Windows build (v1.9.93) in Python + raylib. The goal is to match the original game logic, timings, RNG sequences, float32 math precision, UI layout quirks, and gameplay rules as closely as practical.

​
Architecture

The rewrite follows a clean two-package split:
  • src/crimson/ — Game logic layer (modes, simulation, UI, persistence, data tables)
  • src/grim/ — Engine/platform layer (raylib wrapper, assets, rendering, audio)
This mirrors the original grim.dll vs crimsonland.exe boundary while staying idiomatic for Python.

​
Current State

The rewrite is a playable full game with:
  • Complete boot flow (splash, company logos, main menu)
  • All game modes: Survival, Rush, Quests (tiers 1-5), Tutorial, Typ-o-Shooter
  • Full weapon/creature/perk content
  • Terrain/sprite/decal rendering
  • Music and gameplay SFX
  • Local multiplayer (2-4 players)
  • Online multiplayer with rollback netcode
  • Deterministic simulation supporting seeded runs and verifiable replays
  • Original game secrets and Easter eggs

​
Key Features

​
Deterministic Simulation

The rewrite implements a fully deterministic gameplay pipeline that supports:
  • Seeded runs — Use --seed N for reproducible gameplay
  • Replay recording — All gameplay can be recorded to .crd files
  • Headless verification — Replays can be verified without rendering
  • Differential testing — Compare rewrite behavior against original exe captures

​
Float32 Parity

The original game uses x87 FPU with 53-bit precision mode and float32 storage. The rewrite preserves:
  • Native float32 constants from decompilation
  • Operation ordering that affects rounding boundaries
  • Explicit float32 store/truncation points
See Float32 Parity Policy for details.

​
Replay System

The rewrite includes a comprehensive replay system: 
# Record gameplay
uv run crimson --seed 42  # automatically records

# Play back replay
uv run crimson replay play replay.crd

# Verify replay headlessly
uv run crimson replay verify replay.crd

# Extract timeline for analysis
uv run crimson replay info replay.crd --format json

# Render to video
uv run crimson replay render replay.crd --fps 60

​
Module Organization

The codebase is organized into logical subsystems:

Crimson Module

Game logic, modes, and simulation

Grim Module

Engine layer and platform services

Replay Module

Deterministic replay system

Perks Module

Perk runtime architecture

​
Systems

The rewrite implements four major systems:

Gameplay System

Player movement, weapons, creatures, and combat

Rendering System

Terrain, sprites, effects, and UI

Audio System

Music, SFX, and audio routing

Input System

Keyboard, mouse, gamepad, and multiplayer input

​
Parity Verification

The project uses multiple strategies to verify parity:
  1. Static analysis — Ghidra decompilation as source of truth
  2. Runtime evidence — Frida/WinDbg captures of original behavior
  3. Differential testing — Headless comparison of state checkpoints
  4. Fixture tests — Known-good outputs from original exe
See Parity Status for current verification state.

​
Bug Fixes

The rewrite fixes several bugs in the original game by default. These can be re-enabled with --preserve-bugs for parity testing:
  • Bonus drop suppression comparing amount to weapon ID
  • Greater Regeneration having no effect
  • Bandage applying a health multiplier instead of heal
  • Multiple co-op asymmetry bugs
  • Mini-Rocket Swarmers spread collapse
See Original Bugs Preserved for the complete list.

​
Tech Stack

  • Python 3.13+ — Modern Python with type hints
  • raylib (pyray) — Cross-platform graphics and audio
  • msgspec — Fast serialization for replays and state
  • Construct — Binary format parsing (PAQ, JAZ)
  • pytest — 200+ tests covering gameplay and parity
  • uv — Fast Python package management

​
Quick Start

# Run the game
uvx crimsonland@latest

# Or from source
gh repo clone banteg/crimson && cd crimson
uv run crimson

# With original assets
uv run crimson --assets-dir path/to/game_dir

# Deterministic run
uv run crimson --seed 42

# Re-enable original bugs
uv run crimson --preserve-bugs

​
Next Steps

Architecture

Explore the module structure

Game Loop

Understand the frame pipeline

Deterministic Pipeline

Learn about deterministic simulation

Parity Status

Check current parity state

Build docs developers (and LLMs) love

Get started for freeTalk to us