# Twin Snakes Native Port

A **static recompilation** of Metal Gear Solid: The Twin Snakes (GameCube, 2004)
into native Windows and Linux builds.

The game's PowerPC code is translated ahead of time into C, compiled with a
normal host compiler, and linked against a runtime that reimplements the
GameCube SDK on SDL3 and Vulkan. At runtime there is no PowerPC, no interpreter
and no JIT: the game's own logic runs as native machine code, so behaviour,
saves and physics match the original disc exactly.

**Status: phase 0 of 6** — symbol recovery. Not playable, not close. See
[MILESTONES.md](MILESTONES.md) for the plan and [HANDOFF.md](HANDOFF.md) for
where the work actually stands.

---

## Progress

<!-- progress:begin (generated by tools/progress.py --readme) -->

🟩⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ **functions named** — 1,078 / 18,485 (5.8%)

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 **function boundaries recovered** — 18,485 / 18,485 (100.0%)

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜⬜ **SDK entry points named** — 206 / 336 (61.3%)

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜ **SDK call sites covered** — 6,155 / 7,078 (87.0%)

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 **GX surface the game uses** — 81 / 81 (100.0%)

**The SDK boundary, by component.** This is the surface the
runtime has to replace, so it is the measure that governs the
work. These are the entry points the engine actually calls,
and how many of each are identified:

| component | | identified |
|---|---|---|
| `GX` | 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 +64 | 94 |
| `other` | 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 +6 | 36 |
| `maths` | 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 +4 | 34 |
| `OS` | 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 | 20 |
| `CARD` | 🟩🟩🟩🟩🟩🟩🟩🟩🟩 | 9 |
| `DVD` | 🟩🟩🟩🟩🟩 | 5 |
| `PAD` | 🟩🟩🟩🟩 | 4 |
| `EXI/SI` | 🟩🟩 | 2 |
| `VI` | 🟩🟩 | 2 |
| *still unidentified* | ⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ +100 | 130 |

An entry point that is not yet named cannot be attributed to a
component — that is what being unnamed means — so the last row
is counted together rather than spread across the others.

<!-- progress:end -->

Every square is counted from `config/symbols/` and the recovered function
boundaries, not typed by hand.

## Provenance

**This project does not use, reference, or incorporate any leaked source code.**

Metal Gear Solid 2's source code — the engine this game is built on — was leaked
publicly in 2026, and Konami is pursuing legal action over it. **That material
is not used here, in any form, at any point.** It has not been read, consulted,
or referred to, and it never will be. This is a standing prohibition in the
project's rules, not a preference.

The same applies to any leaked copy of Nintendo's Dolphin SDK.

**The binary analysed here is a GameCube build.** The Twin Snakes is a remake of
Metal Gear Solid, developed by Silicon Knights on an engine adapted from Metal
Gear Solid 2 and substantially reworked for the GameCube — a different console,
a different SDK, and a different compiler. What is on the disc is therefore
GameCube machine code built against Nintendo's Dolphin SDK, and that is what
every method below is matching against: Dolphin SDK byte signatures, and symbol
maps published by decompilation projects for *other GameCube games*. Nothing in
the toolchain takes, or could take, a PlayStation 2 codebase as a reference.

Everything in this repository is derived by our own analysis of a legally owned
copy of the game, by **full decompilation and recompilation**:

1. I extract my own disc and hash its executables.
2. Those executables are disassembled and analysed — function boundaries,
   control flow, data-versus-code — with open tools: Ghidra, `decomp-toolkit`,
   and my own scripts.
3. Nintendo SDK functions are identified by **byte-signature matching against
   public clean-room decompilation projects**, which recover the SDK's public
   API by analysis of retail binaries. Those projects' symbol *names* are the
   community's own naming, not anyone's source code.
4. The recovered machine code is translated to C by
   [DolRecomp](https://github.com/ExpansionPak/DolRecomp), compiled, and linked
   against an SDK runtime **written from scratch** for this project.

**How the analysis was done, precisely.** Every step above is automated static
analysis of a retail GameCube binary I own: disassembly, boundary recovery,
byte-signature matching, and mechanical translation to C by a tool. No leaked
proprietary source, no confidential material, and no internal documentation
from Konami, Nintendo or Silicon Knights was referenced, consulted or used at
any point, by me or by any tool in the chain. The SDK reimplementation in
`runtime/` is written from scratch against observed behaviour and the public
documentation of the hardware.

I do not describe this as a *clean-room* reimplementation, because that term
means something specific — one team documents behaviour without the second team
ever seeing the original — and that is not the process here. This is direct
reverse engineering of a binary I own, which is what CDPA s.50B and the US
interoperability cases permit, and it is described as what it is. Where a
name comes from a decompilation project that does describe itself as clean
room, that is recorded per symbol.

Every symbol name, address and structure layout here was produced by that
process. Where a name comes from a public decompilation project, it is recorded
in [THIRD_PARTY.md](THIRD_PARTY.md) with its upstream and commit.

**[docs/decompilation-process.md](docs/decompilation-process.md) documents every
stage end to end** — inputs, tools, commands, outputs and how each stage's
output is verified. Every symbol in `config/symbols/` additionally carries an
origin column recording which stage produced it, so the claim above is
checkable per symbol rather than in the aggregate.

## What is not in this repository

**No game code. No game assets. Ever.**

- No `main.dol`, no `.rel`, no disc image, no extracted textures, audio or video
- No generated C — it is produced at build time from your own disc and is
  never committed
- No memory-card saves, no ripped data of any kind
- No SDK headers, no proprietary symbol files, no object files, no libraries.
  The tree is source I wrote, my own recovered symbol maps, and build scripts;
  it holds no compiled artefact of any kind, from any party

The repository contains our own code, our own configuration, and symbol names.
You supply your own disc; the build hashes what you give it and refuses anything
that does not match.

## What you need

Two disc images of a copy of the game **you own**. GameCube discs cannot be read
by a PC drive; they are dumped on a Wii with CleanRip.

Supported: `.iso`, `.gcm`, `.rvz`, or an extracted folder.

The bring-up target is the PAL release, disc ID `GGSPA4`. US (`GGSEA4`) and
Japanese (`GGSJA4`) support comes later — every address in the project is tied
to a specific build.

## Legal notice

**Not affiliated with, endorsed by, or associated with Konami, Nintendo, or
Silicon Knights.** "Metal Gear Solid", "The Twin Snakes" and "Konami" are
trademarks of Konami Digital Entertainment; "Nintendo" and "GameCube" are
trademarks of Nintendo. They are used here only to identify the game this
software interoperates with.

**No game code or data is distributed here.** This repository contains no
executable, no assets, no decompiled source and no generated code from the
game. You must supply your own legally obtained copy; the build hashes it and
refuses anything else. Nothing here will run without it.

**This is an interoperability project.** Its purpose is to allow a game you own
to run on hardware you own, by reimplementing the console's SDK in code written
from scratch. It does not circumvent any technical protection measure, and it
does not substitute for the game.

**Nothing here derives from leaked source code.** See Provenance above. Every
symbol carries an origin recording which analysis produced it.

### Legal basis relied on

This project is reverse engineering for interoperability, and it relies on the
following. Each is stated with how this project meets its conditions, so the
claim can be checked rather than taken on trust.

**United Kingdom — a statutory right, not a defence**

- **CDPA 1988 s.50B** — decompilation is lawful to obtain information necessary
  to create an independently written program that interoperates. The conditions
  are met: the information is necessary (the SDK's API must be known to
  reimplement it), it is not otherwise readily available (no public
  decompilation of this game exists), and it is not used to create a program
  substantially similar to the game — the runtime reimplements the *console's
  SDK*, and is no substitute for the game itself.
- **CDPA 1988 s.50BA** — observing, studying and testing a program to determine
  the ideas and principles underlying it is lawful.
- **CDPA 1988 s.296A** — any term purporting to prohibit the above is void.

**European Union**

- **Directive 2009/24/EC Art. 6** (decompilation for interoperability) and
  **Art. 5(3)** (observe, study, test); **Art. 8** makes these unwaivable.

**United States**

- **17 U.S.C. §102(b)** — copyright does not extend to any procedure, process,
  system or method of operation. The addresses, sizes and API names published
  here are facts about a system, not expression. **Feist v. Rural** (1991):
  facts are not copyrightable.
- **17 U.S.C. §107** — fair use. **Sega v. Accolade** (9th Cir. 1992) and
  **Sony v. Connectix** (9th Cir. 2000): intermediate copying during reverse
  engineering is fair use where necessary to reach unprotected functional
  elements. Consistent with both, **no decompiled output is distributed here**.
- **Google v. Oracle** (2021) — reimplementing an API so independently written
  code can interoperate is transformative fair use. That is what this runtime
  does.
- **17 U.S.C. §1201** is not engaged: nothing here circumvents any technical
  protection measure. It reads a disc image you already have.

**I am not a lawyer and none of this is legal advice.** Citing a provision is
not the same as being covered by it. Each one holds only for as long as I keep
this project
behaving the way I have described. I have written up the reasoning, the
conditions in full, and an honest account of where I am exposed anyway in
[docs/legal-position.md](docs/legal-position.md) — including the parts that do
not favour me.

**If you hold rights in this game** and think something here goes further than
what I have set out above, open an issue or write to me. I would rather hear it
from you and fix it than find out any other way, and anything that oversteps
comes out.

## Licence

**GPL-3.0.** The runtime reuses code from Dolphin, which is GPL, and the
recompiler is GPL-3 already. See [THIRD_PARTY.md](THIRD_PARTY.md) for the
licence position of every dependency.

## Building

```sh
tools/bootstrap.sh          # fetch pinned dependencies into extern/
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

Dependencies are fetched, never vendored: `extern/` is git-ignored and every
upstream is pinned by commit in [deps.lock](deps.lock).

## Documents

| | |
|---|---|
| [twin-snakes-native-port-design.md](twin-snakes-native-port-design.md) | The design. Architecture, the translated/native boundary, the phase plan. |
| [MILESTONES.md](MILESTONES.md) | Phase order, exit criteria, per-phase checklists. |
| [HANDOFF.md](HANDOFF.md) | Current state, what is next, and every finding — including the wrong ones. |
| [docs/decompilation-process.md](docs/decompilation-process.md) | Every stage from disc to binary: inputs, commands, verification, provenance. |
| [THIRD_PARTY.md](THIRD_PARTY.md) | Licence, pin and role for each dependency. |
| [docs/legal-position.md](docs/legal-position.md) | What protects this work, the conditions attached, and where it is exposed. |