civ5decomp

How to contribute

Each function in the game's engine is a small puzzle: write C++ that the original compiler (Visual C++ 2008 SP1, whole-program optimisation) turns into exactly the same bytes. You can solve them by hand, with an AI agent, or both.

1. Set up (once)

  1. Own Civilization V on Steam (the final November 2014 build).
  2. Install Python 3.10+, Ghidra 10.3.2 with Java 17+, and the Visual C++ 2008 SP1 compiler (exactly 15.00.30729.01; see CONTRIBUTING.md for where to get it).
  3. Clone the repository and run setup. It finds the game through Steam, checks that your exe is the exact build we match against, finds Ghidra and the compiler, and runs a test match: 
    python tools/c5d.py setup
python tools/c5d.py analyze      # one-time Ghidra database, can take an hour or more

2. Sign in and get a token

Sign in with GitHub on the account page, accept the contributor terms, choose how your name appears on the leaderboard (or stay anonymous), and create an API token. Then:

python tools/c5d.py remote login --server https://this-site --token c5d_…

3. Claim, solve, report

python tools/c5d.py remote claim --n 3          # reserves 3 functions (4 h lease)
# each one gets build/tasks/<addr>/TASK.md with everything you need
python tools/c5d.py --worker w1 match --addr 0x00540240 -v
python tools/c5d.py remote report 0x00540240 --model claude-opus-5-5 \
    --tokens-in 41000 --tokens-out 2600 --tokens-cached 12000 --tries 2
                                                 # re-checks locally, then reports

Say which model or tool wrote the function (set a default with "model" in config.local.json) and, if you have them, the tokens it used. That's what feeds the Squad and Cost sections of the report.

To let an agent do the work, point it at a TASK.md (or set agent_cmd in config.local.json and run c5d agent). Workers run in parallel safely: each uses its own --worker build folder.

4. Open a pull request

Commit your src/auto/f_<addr>.cpp and symbols/auto/f_<addr>.txt files and open a pull request. A reported match shows as awaiting verify until the maintainer's nightly run rebuilds everything and confirms it; then it counts on the leaderboard. If it isn't verified within 14 days (no pull request, or it wasn't merged), the function goes back in the pool for others; you still get the credit if your PR is merged later, unless someone else reports it first.

House rules