Skip to main content
Set up a development environment to run, modify, or contribute to Crimsonland.

​
Prerequisites

  • Python 3.13 or higher
  • Git
  • uv (recommended) - Install uv

​
Clone the repository

1

Clone from GitHub

Using GitHub CLI (recommended):
gh repo clone banteg/crimson
cd crimson
Or using git:
git clone https://github.com/banteg/crimson.git
cd crimson
2

Run from source

Using uv (recommended):
uv run crimson
This automatically:
  • Creates a virtual environment
  • Installs dependencies
  • Runs the game

​
Project structure

The repository is organized as follows: 
src/
  crimson/          # Game logic — modes, weapons, perks, creatures, UI, replay
  grim/             # Engine layer — raylib wrapper, PAQ/JAZ decoders, audio, fonts
analysis/
  ghidra/           # Name/type maps (source of truth) and raw decompile exports
  frida/            # Runtime capture evidence (state snapshots, RNG traces)
  windbg/           # Debugger session logs
docs/               # 100+ pages: formats, structs, algorithms, parity tracking
scripts/            # 40+ analysis and utility tools
tests/              # 200+ tests: gameplay, perks, physics, replay, parity

​
Development workflow

​
Running tests

Run the test suite: 
uv run pytest
With coverage: 
uv run pytest --cov=crimson --cov-report=term-missing

​
Code quality checks

Run linting: 
uv run ruff check .
Run type checking: 
uv run ty check src
Run AST-grep code scan: 
sg scan
sg test
Run all checks: 
just check
The just command requires just to be installed.

​
Development dependencies

Development dependencies are defined in the dependency-groups section of pyproject.toml:
PackagePurpose
pytestTesting framework
pytest-covCoverage reporting
pytest-mockMocking utilities
syrupySnapshot testing
ruffLinting and formatting
tyType checking
import-linterImport dependency validation
numpyNumerical testing utilities
pylintAdditional linting
mkdocstringsAPI documentation
zensicalDocumentation site generator

​
Running specific components

​
Extract game assets

Extract PAQ archives into a filesystem tree: 
uv run crimson extract path/to/game_dir artifacts/assets
JAZ textures are automatically converted to PNG with alpha.

​
View quest scripts

Print quest spawn scripts: 
uv run crimson quests 1.1

​
Launch debug views

Run debug views and sandboxes: 
uv run crimson view lighting-debug

​
Replay commands

List replays: 
uv run crimson replay list
Play a replay: 
uv run crimson replay play artifacts/runtime/replays/example.crimreplay
Verify replay: 
uv run crimson replay verify artifacts/runtime/replays/example.crimreplay

​
Building the documentation

The project documentation is built with zensical: 
uv tool install zensical
zensical serve
The docs will be available at http://localhost:3000.

​
Pre-commit hooks

Install git hooks for automatic checks: 
prek install -c prek.toml -t pre-commit -t pre-push
  • pre-commit runs fast checks (ruff/import-linter/ty/docs/ast-grep)
  • pre-push runs heavy checks (pytest/build)
Manual runs: 
prek run --stage pre-commit
prek run --stage pre-push

​
Contributing

Before contributing, please read:

​
Key principles

  1. Deterministic parity + evidence-backed correctness - Preserve native-faithful behavior and prove it with captures/replays/tests
  2. Structural simplicity - Prefer deleting complexity over adding layers
  3. UX polish - Only after parity is preserved

​
Verification commands

Before committing: 
just check
Before pushing: 
just check && uv build

​
Local runtime directory

By default, runtime files (saves, config, logs, replays) are stored in your per-user data directory. To keep everything local to the checkout: 
export CRIMSON_RUNTIME_DIR="$PWD/artifacts/runtime"
uv run crimson
See Runtime configuration for more details.

​
Next steps

Runtime configuration

Customize runtime directories and configuration

CLI reference

Explore all available commands

Architecture

Understand the codebase structure

Reverse engineering

Learn about the decompilation process

Build docs developers (and LLMs) love

Get started for freeTalk to us