Rebuilding Spore's SporeApp.exe (2008, PC) as readable C++ that compiles to exactly the retail machine code,
one function at a time, with the original compilers (Visual C++ 2008 SP1, and the Visual C++ Toolkit 2003 for Havok
and RenderWare). Every function is annotated with the original address it rebuilds (// @ 0x00XXXXXX).
- Progress: noahbpeterson.github.io/spore-decomp (charts, modules,
contributors), or
PROGRESS.mdin the repository. - Contribute: below, then
AGENTS.mdfor the full loop and the rules (written for people and AI agents alike).
This repository contains no game code or data. Pull requests are checked against retail fingerprints (sizes,
address positions and hashes, no code). Anything derived from your own copy of the game stays in work/, which git
ignores, and must not be distributed.
Over 23,000 functions already have complete C++ source whose compiled bytes still differ from the original, about 500 of them by only one to four bytes. Pick one, change the source until its bytes are identical, and open a pull request.
You need Python 3.10+, Wine and msitools (macOS or Linux; on Windows, use WSL), and your own copy of Spore (Steam).
python3 -m venv .venv && .venv/bin/pip install pefile capstone pycryptodome
sh tools/ci/setup_toolchain.sh # the original compilers, from Microsoft's installers, hash-checked
.venv/bin/python tools/contrib/make_image.py "<Spore>/SporeBin/SporeApp.exe" # must print IMAGE OK
.venv/bin/python tools/contrib/task.py --list # fewest tries first, then smallest
.venv/bin/python tools/contrib/task.py 0x00ee9260 # one function: its file, flags, note and source
.venv/bin/python tools/contrib/check.py 0x00ee9260 # MATCH, or an instruction diff against the originalOn MATCH, check.py updates the bookkeeping files itself; open a pull request with your change. One function (or a
few) per pull request, using the template.
If you are an AI agent: read AGENTS.md first and follow it. The short version:
- Only
src/game/,match/slices/andmatch/include/may change. Never commit anything fromwork/. - No inline assembly,
__declspec(naked)or raw bytes, and no constants written as addresses of invented globals: the check rejects all of these. - Before trying new source shapes, look up the difference in
docs/codegen.md. After six to eight levers without a match, update the function'snonmatching.txtnote with what you tried, and move on. - Once a pull request is marked ready, do not add commits to it; put new work in a new pull request.
Every pull request runs the Byte-match check. It compiles every function your change can affect and compares
it with the retail fingerprints, and it fails if anything that matched before stops matching. You can run the same
check locally:
.venv/bin/python tools/ci/gate.py <manifest.txt ...> --known tools/ci/known_failures.txt.
src/game/: the rebuilt game, one source file per original object file, plus generated class headers insrc/game/include/match/slices/: functions still being decompiled or not yet moved intosrc/game/tools/contrib/: the contributor tools (task.py,check.py,make_image.py);tools/ci/: the pull-request checkdocs/codegen.md: how the 2008 and 2003 compilers turn source into the shapes you see in a diffsrc/resource/: portable C++17 reimplementation of the file formats (DBPF, RefPack, name hash)tests/: unit tests, plus corpus tests over your installedData/whenSPORE_DATAis settools/difftest/: Unicorn harness that calls original functions by addresstools/ghidra/: PyGhidra scripts (discovery, naming, decompile, xrefs)symbols/names.txt: recovered names with provenance
Building the file-format library and its tests:
cmake -S . -B build -G Ninja && cmake --build build
SPORE_DATA="<Spore>/Data" ctest --test-dir build --output-on-failureEquivalence testing (tools/difftest/) also needs pip install unicorn. Ghidra project setup (about 20 min): see
docs/PLAN.md.
Released under the GNU General Public License, version 2 (GPL-2.0-only); see LICENSE.
Third-party components and the status of binary-derived artifacts are described in
THIRD_PARTY.md.