aoe3-decomp
Age of Empires III: The Asian Dynasties, decompiled back to C++ that compiles to the original game's exact machine code, and ported to native macOS from that same source.
Progress
Every number below is counted from the repository's main branch. A function only counts as matched when recompiling its source reproduces the original bytes, and review checks that again before it merges.
Counted 2026-10-26 at commit main.
What a matching decompile is
The game shipped as a compiled Windows program, age3y.exe. We write C++ by hand, function by
function, and compile it with the same compiler the game was built with: Microsoft Visual C++ .NET 2003 (7.1,
cl 13.10.3077), run natively on macOS. A function is matched when the compiler turns our
source into exactly the instructions in the original executable.
1. Read
Analysis tools recover each function's machine code, the classes it uses and the source file it came from.
2. Write
An agent writes plain C++03 that this 2003-era compiler accepts, using real names from the game's own debug strings where they exist.
3. Match
A custom comparer checks the compiled result against the original, instruction for instruction.
4. Prove it
Review recompiles every function and plants a deliberate one-token bug, which has to break the match. Only then does it merge.
The macOS port
The matched source is the ground truth, and the port never changes it. It works the way an emulator layer does, by replacing what the game calls instead of the game itself. The game asks for Direct3D 9, Win32 windows, DirectSound and so on; on a Mac, those calls are answered by new code that speaks Metal, SDL3 and Core Text. The same source still compiles to the original bytes for Windows.
| Layer | What it replaces | Status |
|---|---|---|
| Direct3D 9 on Metal | The game's renderer device, its resources and render states, plus shader translation for every shader model the game uses (vs/ps 1.1 to 3.0) | on main |
| Win32 on SDL3 | Windows, the message pump, input, timers, files, the registry, threads and synchronisation | on main |
| GDI text on Core Text | Fonts, glyph rasterisation, text drawing and bitmap blits for the game's UI text | on main |
| DirectSound on miniaudio | Sound buffers, 3D positional audio and the game's EQ filter | on main |
| Memory allocator | The game's Rockall heap | on main |
| 64-bit builds of game code | Layout checks that assume 32-bit pointers, so the game's own files can compile for arm64 | next |
| Voice streaming, network, video | DirectShow, sockets and Bink | planned |
Every layer has its own tests: pixel-exact rendering checks, sample-exact audio mixes and thread stress tests under sanitizers. Each also has planted-bug checks that the tests must catch.
Where it's going
Link the original
Enough matched code to link a Windows build of the game from source.
Prove behaviour
Replay recorded games and check the rebuilt game behaves exactly like the original.
First frame on Metal
The game's real data drawn on a Mac through the port layers.
Playable on macOS
A native Apple Silicon build you can play a skirmish in. A Windows x64 / Direct3D 12 build follows.
The long-term vision
Once the game runs natively, the plan is to build on top of it without touching the faithful version. The byte-identical rebuild stays exactly as it is, and a separate modded build adds three things:
A mod layer
A documented, versioned modding interface that is as extensive as possible: units, civilisations, techs, UI, maps, AI, camera and scripting. Its scope is set by reference mods modelled on the kinds of mods people love for the other Age of Empires games.
An in-game mod browser
Browse, install and update mods from many authors without leaving the game, signed in with an AoE3 decomp account.
Online play again
The game's original online service is long gone. Our own service, running on Cloudflare Workers, will speak the game's original online protocol, which the decompile itself is recovering, so the multiplayer screens work again.
Recorded in the project's design decision on mods and online play. This comes after a playable macOS build.
How the work happens
Most of the work is done by AI agents in two teams, each sponsored by a person: briannastatic and Mylogo. They coordinate only through the git repository. An agent claims a piece of work as a git ref, so two agents can never take the same piece. It hands off with a written note of what it did and learned, and every change goes through the same automatic review. Lessons learned while matching (compiler quirks, source shapes that reproduce a tricky instruction sequence) are written down and shared, so each new agent starts where the last one left off.
Anyone can contribute. The rules are in AGENTS.md and CONTRIBUTING.md.