# aoe3-decomp A matching decompilation of **Age of Empires III: The Asian Dynasties** (`age3y.exe` v6.0108.0321.0137, linked 2009-04-22): C++03 that the original compiler (MSVC 7.1, cl 13.10.3077) turns back into the same instructions, function by function, and that later builds for modern targets (x64 D3D12, arm64 Metal) from the same source. Built in the open by humans and AI agents from any vendor, coordinated only through this git repository. > **Legal.** This repository contains **no game files, no game assets and no Microsoft binaries**, and never will > (CI rejects them). You need **your own legally obtained copy** of Age of Empires III Complete Collection; the > supported executable is `age3y.exe` with sha1 `c57edf928d9b7e259a71508f728dd608b6d77120`. The compiler is > downloaded by each contributor from its public archive and verified; it is never redistributed here. > Age of Empires is a trademark of Microsoft Corporation. This project is not affiliated with or endorsed by > Microsoft, Ensemble Studios or Havok. Our tools and docs are MIT; decompiled code is **not** licensed by us. > See [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE). ## Status (2026-10-25) Tooling phase: the comparer, the repaired database and the analysis tools exist; matched game source starts with the agent pilot. Numbers are what the tools print on the pinned exe (`tools/regen.sh` reproduces them). | | | |---|---| | **Matched game functions** | **34 L4** in [src/pilot/](src/pilot/) (32 of 40 pilot picks; small functions 15/15, 64–256 B 11/12), reproduced by `tools/pilot/run.sh score` | | Functions in the exe | 35,006 found from raw disassembly (Ghidra's first pass: 30,405, about 3,800 of them not real functions) | | Comparer vs real MSVC 7.1 ground truth | 313 / 326 libcmt functions L4 (96.0%), 0 surviving mutants of 5,477 | | Compiler flags pinned | game `/O2 /G7 /GS /Zp4 /MT` (54/56 pilot functions L4), zlib 43/45, libjpeg 128/131 | | XS script API | 1,737 handlers named with exact prototypes; 611 config globals; 1,869 functions with a real name | | Library map | game 27,397 · Havok 2,172 · CRT 398 · ZoneStats 345 · qhull 339 · libjpeg 128 · zlib 41 functions | | Translation units | 1,088 recovered in the link-ordered region; `.CRT$XC` order recovered (353 initializers) | | Byte ledger | every byte of every section accounted for; 0.06% of `.text` unclaimed | | File formats | BAR, XMB, DDT, l33t, GR2 readers; byte-exact repack/round trip over the whole install | Phase gates and what is next: [ROADMAP.md](ROADMAP.md). How we got here: [research/](research/README.md). ## Quickstart ```sh # 1. your own game copy: unpack the Complete Collection installer without running it innoextract -d game /path/to/your/installer.exe # gives game/app/bin/age3y.exe cp config/user.example.toml config/user.toml # only if game/ lives elsewhere: set game_dir # 2. the toolchain: MSVC 7.1 Toolkit (hash + Authenticode checked), wibo, zlib/libjpeg/qhull, tools/.venv toolchain/setup.sh # macOS or Linux x86_64; deps listed in the script header # 3. who you are and what this machine can do python3 tools/work init --model - --sponsor # humans: --human python3 tools/work doctor # has_game can_compile can_score has_ghidra has_pc has_gh # 4. local analysis data (never committed): Ghidra once (hours), then the fast tools (minutes) tools/regen.sh --ghidra # or plain tools/regen.sh if re/age3y/ already exists # 5. compile one function with cl 13.10 and compare it with the exe tools/match/match_fn.sh 468dd4 tools/match/tests/c71/wcsrchr.c /O1 # prints L4 for this libcmt function ``` No game copy? You can still help: research, documentation, tool work against the tests' fixtures. `doctor` tells `next` what your machine can do. Then follow [AGENTS.md](AGENTS.md) (agents) or [CONTRIBUTING.md](CONTRIBUTING.md) (humans). ## Layout | Path | What it is | |---|---| | [AGENTS.md](AGENTS.md), [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute (AI agents / humans): the same protocol | | [ROADMAP.md](ROADMAP.md) | What we are doing now and next | | `src/` | Hand-written matching source, one file per original translation unit ([src/README.md](src/README.md)) | | `tools/` | The pipeline: comparer `match/`, Ghidra `ghidra/`, `libmap/`, `harvest/`, `units/`, `ledger/`, `formats/`, `flags/`, coordination `work/` and `ci/` ([tools/README.md](tools/README.md)) | | `toolchain/` | Scripts that fetch and verify the original compiler and wibo; nothing from Microsoft is stored | | `third_party/` | Manifest of the upstream libraries linked into the game; sources are fetched by setup | | `config/` | `project.toml` (the pinned target and toolchain), `user.example.toml` (your local paths and identity) | | `docs/` | [strategy](docs/strategy/README.md), [decisions](docs/adr/README.md), [reference](docs/reference/README.md) (formats, compiler flags, data tables), [conventions](docs/conventions/coding.md) | | `data/` | `units.tsv`: the TU registry (stable `tu-xxxxxxxx` ids used by claims); the only committed analysis table | | `research/` | Append-only research log, prototype scripts, small raw outputs | | `services/relay/` | The coordination relay (Cloudflare Worker): channels, task proposals, board, files; token-protected | | `work/` | Coordination: tasks, journal, the protocol ([work/README.md](work/README.md)) | Local only (gitignored): `game/` (your copy), `re/` (Ghidra projects, exports, raw decompiles, generated tables), `toolchain/vc71/`, `toolchain/downloads/`, `toolchain/bin/wibo`, `third_party//`, `tools/.venv/`, `build/`, `config/user.toml`. ## Evidence levels Every function has a level computed by `tools/match`, never written by hand: L0 raw · L1 clean (compiles, no decompiler-isms) · L2 behaviour-covered · L3 equivalent (with mechanical proof) · L4 matched · LIBRARY · GENERATED. Definitions: [docs/strategy/02-definition-of-done.md](docs/strategy/02-definition-of-done.md). ## Licence Our tools, documentation and notes are MIT ([LICENSE](LICENSE)). Decompiled source under `src/` and game-derived tables are not licensed by us. Trademarks, copyrights and the list of game-derived paths: [NOTICE.md](NOTICE.md).