Core Priorities
Contributions must align with these priorities in order:Deterministic Parity + Evidence-Backed Correctness
If rules conflict, preserve native-faithful behavior and prove it with captures, replays, or deterministic tests.
Project Structure
Source Code
src/crimson/- Game logic (modes, weapons, perks, creatures, UI, replay)src/grim/- Engine layer (raylib wrapper, PAQ/JAZ decoders, audio, fonts)
Analysis
analysis/ghidra/- Name/type maps (source of truth) and raw decompilesanalysis/frida/- Runtime capture evidence (state snapshots, RNG traces)analysis/windbg/- Debugger session logs
Documentation
docs/- 100+ pages: formats, structs, algorithms, parity tracking
Testing
tests/- 200+ tests: gameplay, perks, physics, replay, parityscripts/- 40+ analysis and utility tools
Verification Philosophy
Prove It Works
Every contribution affecting gameplay behavior should include evidence:- Capture verification - Frida captures from original binary compared against rewrite
- Replay verification - Deterministic replay files that produce identical outcomes
- Deterministic tests - Unit/integration tests that lock in discovered behavior
Key Principles
f32 Fidelity Over Readability
- Keep decompiled
float32constants and rounding behavior exactly as-is when it affects simulation - Do not normalize constants like
0.6000000238418579 -> 0.6unless tests/captures prove no behavioral change - Be suspicious of any “cleanup” that changes: float constants, operation ordering, RNG consumption, branch conditions
Validate at Edges, Trust Inside
- Validate/parse at boundaries (IO/CLI/JSON/msgpack/network messages)
- Inside the domain, assume validated typed objects are correct: Fail fast on impossible states
- Do not hide errors with defaults/fallbacks
- Keep objects typed during computation. Convert to dict/builtins only at edges
Types Are Design
- If
ty/typing complains, fix the schema/boundary/model - Avoid casting to
Anyor duct-taping with.get()/getattr()to dodge typing
Fix Root Causes
- Do not add “just in case” guards to silence crashes/divergences
- No extra
Nonechecks, broad tolerances, fallback defaults, epsilons, or off-by-one guards - Trace mismatches to bedrock: float rounding/order, misread decompile, wrong table/enum mapping
Getting Started
Development Setup
Install tools and configure your environment
Development Workflow
Learn the contribution workflow and best practices
Testing Guide
Run tests and verify your changes
Code Style
Follow project coding standards