Documentation Index Fetch the complete documentation index at: https://mintlify.com/banteg/crimson/llms.txt
Use this file to discover all available pages before exploring further.
The Crimsonland project includes 40+ analysis and utility scripts to support reverse engineering, parity verification, and development workflows.
Build Automation (Just) The project uses just as a command runner. All common tasks are defined in justfile.
Common Commands just --list # Show all available commands just check # Run full verification suite just test # Run pytest just test-cov # Run pytest with coverage reports just extract # Extract PAQ archives to filesystem just docs-build # Build documentation site
See justfile for 50+ available commands.
pytest Primary test runner:
uv run pytest # Run all tests uv run pytest tests/test_ * .py # Run specific test file uv run pytest -k "pattern" # Run tests matching pattern uv run pytest --cov-report=html # Generate HTML coverage report
See Testing Guide for detailed usage.
Syrupy (Snapshot Testing) Captures and verifies complex data structures:
uv run pytest --snapshot-update # Update snapshots after intentional changes
Ruff (Linter) Fast Python linter:
uv run ruff check . # Check all files uv run ruff check --fix . # Auto-fix safe issues uv run ruff check --fix --show-fixes . # Show what was fixed
Configuration in pyproject.toml:
Line length: 120
Enabled rules: B007, B017, B023, B904, COM812, I001, PGH003, PT017, RUF012, RUF100, S113, S607, TRY004, UP035
ty (Type Checker) Fast Python type checker:
uv run ty check src tests # Check source and tests just ty # Shorthand for above just ty-tests # Check tests only
import-linter Enforces architectural boundaries:
uv run lint-imports # Validate import contracts
Contracts defined in pyproject.toml:
grim must not import crimsonPerk implementations isolated from selection logic
ast-grep (Structural Search) Structural code search and transformation:
sg scan # Run configured rules sg test # Test ast-grep rules sg run -p 'pattern' -r 'fix' src # Apply transformation
For Zig code:
sg run -c sgconfig.local.yml -l zig -p '_PATTERN' -r '$FIX' crimson-zig/src
prek (Pre-commit Hooks) Manages git hooks:
prek install -c prek.toml -t pre-commit -t pre-push # Install hooks prek run --stage pre-commit # Run pre-commit checks manually prek run --stage pre-push # Run pre-push checks manually
Extract original game archives:
just extract # Extract to artifacts/assets/ uv run crimson extract < sr c > < ds t > # Custom paths
JAZ textures are automatically converted to PNG with alpha.
Sprite atlas analysis:
just atlas-scan # Scan and generate usage map just atlas-export-all # Export all frames just atlas-export < imag e > < gri d > # Export specific atlas
Font Samples Generate font rendering samples:
just font-sample # View font samples uv run crimson view fonts # Same as above
Analysis Scripts (40+) Located in scripts/, these tools support reverse engineering and analysis.
Ghidra Analysis
IDA Pro (Windows)
# Unix only just ghidra-exe # Analyze crimsonland.exe just ghidra-grim # Analyze grim.dll just ghidra-sync # Sync name/type maps
Scripts in analysis/ghidra/scripts/:
ApplyNameMap.java - Apply name mappingsApplyDataMap.java - Apply data structure layoutsExportAll.java - Export decompiles just ida - export-exe # Export crimsonland.exe metadata just ida - export-grim # Export grim.dll metadata just ida - decompile - exe # Decompile crimsonland.exe just ida - decompile - grim # Decompile grim.dll
Runtime instrumentation for capturing native behavior:
Gameplay Captures
Quest Analysis
UI Tracing
Demo/Trial Analysis
just frida - gameplay - state - capture # Capture state snapshots just frida - gameplay - diff - capture # Differential capture
Captures go to $CRIMSON_FRIDA_DIR (default: C:\share\frida). just frida - quest - build-dump # Dump quest build data just frida - quest - spanking - count # Track spanking events
just frida - game - over - panel - trace # Trace game over panel state just frida - panel - state - resolution - sweep # Resolution sweep
just frida - demo - trial - overlay # Trace trial overlay just frida - demo - idle - threshold # Trace idle threshold
Frida Import/Reduce (Unix) Import Windows captures to Unix for analysis:
just frida-copy-share # Copy from /mnt/c/share/frida just frida-import-raw # Import to analysis/frida/raw/ just frida-reduce # Generate summaries just game-over-panel-reduce # Reduce panel trace just panel-state-resolution-reduce # Reduce resolution sweep just demo-trial-validate # Validate trial overlay just demo-idle-summarize # Summarize idle threshold
Code Analysis Scripts just entrypoint-trace # Trace call graph from entrypoint just function-hotspots # Identify frequently called functions just dat-hotspots # Analyze data access patterns just schema-inventory # Inventory data schemas just save-status # Analyze save file structure just weapon-table # Extract weapon table just spawn-templates # Generate spawn templates
Duplication Detection just dup-report # Generate code duplication report just dup-report out= < fil e > min= < line s > # Custom output and threshold
Uses pylint with R0801 rule (duplicate-code).
Zensical (Docs Site Generator) uv tool install zensical # Install globally zensical serve # Serve docs locally just docs-build # Build static site just docs-check # Validate docs structure just docs-zensical-fix # Auto-fix formatting issues
Documentation Validation uv run scripts/check_docs.py # Validate docs structure and links
Replay analysis and verification:
uv run crimson replay list # List replay files uv run crimson replay play < fil e > # Play back replay uv run crimson replay verify < fil e > # Verify determinism uv run crimson replay verify-checkpoints < fil e > # Compare to sidecar uv run crimson replay benchmark < fil e > # Benchmark throughput uv run crimson replay render < fil e > # Render to video
WinDbg (Windows) Debugger for native binary:
just windbg - server # Start WinDbg server just windbg - client # Connect WinDbg client just windbg - tail # Tail WinDbg log (Unix)
Logs saved to game directory for offline analysis.
PE Analysis (Unix) Portable Executable metadata:
just pe-info # Show PE metadata just pe-info target=grim.dll # Analyze DLL just pe-imports # Show import table
Uses rabin2 from radare2 .
For Zig runtime development:
just zig-build # Build Zig project just zig-run # Run Zig binary just zig-test # Run Zig tests just zig-wasm # Build WebAssembly just check-zig # Full Zig verification
Utility Scripts Select utility scripts in scripts/:
Script Purpose atlas_scan.pyScan sprite atlases for usage atlas_export.pyExport atlas frames to PNG check_docs.pyValidate documentation structure extract_weapon_table.pyExtract weapon stats to table gen_spawn_templates.pyGenerate creature spawn templates entrypoint_trace.pyTrace call graph from entrypoints function_hotspots.pyIdentify hot functions dat_hotspots.pyAnalyze data access patterns schema_inventory.pyInventory data structures save_status.pyAnalyze save file structure zensical_fix_md.pyAuto-fix Markdown formatting
Python (uv)
Rust (cargo)
System (apt/brew)
Tools (uv tool)
All Python tools are installed via uv sync: uv sync # Install everything
Includes:
pytest, ruff, ty, import-linter
syrupy, pytest-mock, pytest-cov
Frida analysis scripts (Unix)
cargo install ast-grep # Structural search cargo install prek # Pre-commit hooks cargo install just # Command runner
# Linux sudo apt install radare2 # PE analysis tools # macOS brew install radare2 brew install just # Alternative to cargo brew install ast-grep # Alternative to cargo
uv tool install zensical # Documentation site generator
Next Steps
Testing Guide Learn how to run and write tests
Verification Process Complete verification workflow
Parity Workflow Understand parity-first development
Code Style Follow project coding standards