Skip to main content
This guide walks you through setting up a complete development environment for the Crimsonland project.

​
Prerequisites

​
Required Tools

1

Install uv

Install uv, the fast Python package installer and resolver:
curl -LsSf https://astral.sh/uv/install.sh | sh
2

Clone the Repository

gh repo clone banteg/crimson && cd crimson
Or using git directly:
git clone https://github.com/banteg/crimson.git && cd crimson
3

Install Dependencies

uv automatically manages dependencies from pyproject.toml:
uv sync
This installs:
  • Runtime dependencies (raylib, msgspec, construct, etc.)
  • Development dependencies (pytest, ruff, ty, etc.)

​
Platform-Specific Notes

Current PyPI raylib wheels are X11-oriented on x86_64, so you may need:
sudo apt install xwayland libx11-dev
See electronstudio/raylib-python-cffi#199 for details.

​
Development Tools

The project uses several specialized tools. They’re all installed via uv:

​
Core Development Tools

ToolPurposeInstalled By
pytestTest runner with coveragedependency-groups.dev
ruffFast Python linterRuntime (via CLI)
tyType checkerdependency-groups.dev
ast-grep (sg)Structural code searchExternal (install separately)
prekPre-commit hook managerExternal (install separately)
import-linterImport contract enforcerdependency-groups.dev
justCommand runnerExternal (install separately)

​
Install External Tools

cargo install ast-grep
# or
brew install ast-grep

​
Runtime Configuration

​
Runtime Files Location

By default, saves, config, logs, and replays live in your per-user data directory. To keep everything local to the checkout: 
export CRIMSON_RUNTIME_DIR="$PWD/artifacts/runtime"
Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

​
Assets

The rewrite can load assets from original PAQ archives. Point to them if needed: 
uv run crimson --assets-dir path/to/game_dir
Extract PAQs for inspection: 
uv run crimson extract path/to/game_dir artifacts/assets

​
Verify Installation

Run the full verification suite: 
just check
This runs:
  • ruff check . - Linting
  • lint-imports - Import contract validation
  • ty check src tests - Type checking
  • scripts/check_docs.py - Documentation validation
  • sg scan - ast-grep code scanning
  • sg test - ast-grep rule tests
  • pytest - Full test suite
  • just check-zig - Zig build and tests (if applicable)
The first run will download dependencies and may take a few minutes.

​
Quick Test Run

Verify the game runs: 
uv run crimson --no-intro
This should launch the game, skipping intro logos.

​
Editor Setup

  • Python (ms-python.python)
  • Ruff (charliermarsh.ruff)
  • ast-grep (ast-grep.ast-grep-vscode)

​
Type Checking Integration

The project uses ty (a fast type checker). Configure your editor to use it: 
{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic"
}
Run type checks manually: 
uv run ty check src tests

​
Next Steps

Development Workflow

Learn the contribution workflow

Testing Guide

Run and write tests

Parity Workflow

Understand the parity-first approach

Development Tooling

Explore analysis and utility scripts

Build docs developers (and LLMs) love

Get started for freeTalk to us