Start your own static recompilation project. You bring a game you own. This repository gets you to something that builds and boots.
If you are an AI agent, read AGENTS.md instead. Same
material, written as instructions you can run unattended.
The Retro Porting Toolkit is a set of static recompilers.
A static recompiler reads a game's binary. A binary is compiled machine code: the numbers the console's processor ran, not readable source. The recompiler translates that machine code into source code in an ordinary programming language. A normal compiler then builds the result into an application for your computer.
The technique does not require any one output language. The projects here emit C. What comes out is the game's own logic as code, so the game is the program you run.
This is not emulation. An emulator reads the game's instructions and acts them out one at a time while you play. A recompiled port did that translation once, before you played anything.
These ports do still carry a small emulator, kept as a fallback for code the recompiler could not translate ahead of time. How much it covers, and what happens when it does not, is different on every console. AGENTS.md has the detail per toolchain.
There are toolchains for twelve consoles, and 67 games have been ported with them.
This repository is the on ramp. It holds no recompiler and no game data. It holds the shortest honest path per console from "I want to port this" to "it builds".
You supply the game file. Nothing here distributes game data, and nothing here will help you find any. A recompiled binary contains translated game code, so ports ship as source and every user builds their own.
How far you get depends on the console.
| Console | Scaffolding | Realistic first step |
|---|---|---|
| PlayStation | Yes, a scaffold script | One command creates the project, probes your disc, and can build it |
| NES, SNES, Game Boy Advance, Game Boy, Genesis, Master System, Virtual Boy, DS | None | Copy a working port's structure and change what is game specific |
| CD-i, GameCube, Xbox | Not applicable | Research projects. Not a route to a playable port |
PlayStation is the fast one, because psxrecomp ships
tools/new_project_layout/. On the other eight you assemble the same tree by
hand.
Once a console's framework is mature, adding a game is quick. The Street Fighter Alpha 3 team cites about five minutes of game-specific work from disc to a running native build.
The months went into building each console's framework, and they go into taking one game from booting to feeling finished. On a mature toolchain you repeat neither of those per game.
Genesis has no scaffold, so nothing here will tell you a Genesis port is five minutes of work.
You need git, cmake 3.20 or newer, ninja, a C++20 compiler and python3.
On Windows use MSYS2 MinGW rather than MSVC. You do not need a BIOS dump.
Builds use a bundled open source OpenBIOS.
git clone https://github.com/mstan/psxrecomp.git
cd psxrecomp
git submodule update --init --recursive
sh tools/new_project_layout/setup_project.sh \
--disc /path/to/your/game.cue \
--dir ~/srcRun it without --yes and it asks you the rest: project name, player count,
launcher interface, netplay, CI, box art, and whether to generate and build
now. Say yes to generate and build and it hands you a tree that runs.
Your disc is not copied into the new repository by default. The script reads it
where it sits and writes only the small boot executable into disc/.
The flags and the generated files are in playstation/. The
authority is the framework's own
docs/GAME_PROJECT_SETUP.md.
Paste this to an AI coding agent. Change the path first.
I want to recompile a PlayStation game I own into a native build on this
machine. The disc image is at /absolute/path/to/game.cue, with its .bin
tracks beside it. I own it. Do not try to obtain it from anywhere.
Read these first, in this order:
https://retroportingtoolkit.com/docs/agents/start-here
https://github.com/RetroPortingToolKit/recomp-starter/blob/main/AGENTS.md
https://github.com/mstan/psxrecomp/blob/master/docs/GAME_PROJECT_SETUP.md
Then check https://retroportingtoolkit.com/all/games to see whether this game
is already ported. If it is, say so and stop.
Otherwise follow the PlayStation path in AGENTS.md. Run the scaffold with
--yes, and pass --generate and --enable-build so that it actually produces a
build.
Rules:
- Do not create a GitHub repository. Pass --no-github.
- Do not commit disc images, BIOS dumps, or anything under generated/.
- Do not edit generated code. Fix the seeds or game.toml instead.
- Check the prerequisites first. Tell me what is missing rather than working
around it.
- Report the dispatch miss count after every run. Anything above zero means
stop and fix it.
- Stop and ask me whenever something needs eyes or ears: whether it boots,
whether the picture is right, whether the sound is right.
The catalogue check stops the most wasteful outcome, which is an agent rebuilding a port that already ships. The last rule keeps you in the loop at the only points where you are needed.
other-consoles/ covers the eight toolchains with no
scaffold: which port to copy for each console, what the per game recompiler
input is called there, and what you have to change.
The walkthroughs live on the site, so they can carry screenshots and stay
current: https://retroportingtoolkit.com/blog. tutorials/
lists them with one line each on which one you want.
A build is not a port. Once it boots you have to play it and fix what you find.
Code the analysis never found shows up late, not at startup, because that is the first moment the game calls it. On PlayStation the runtime records the address and stops, so you get a report naming the exact place. The answer is another pass round the seed loop.
That iteration is the work. Only a person can finish it, because only a person can say the game plays right.
- The documentation: https://retroportingtoolkit.com/docs
- What static recompilation is: https://retroportingtoolkit.com/docs/start/what-is-static-recompilation
- Existing ports, in case yours is already done: https://retroportingtoolkit.com/all/games
- The whole documentation section in one fetch, for an agent: https://retroportingtoolkit.com/llms-full.txt
This starter kit is MIT. The toolchains it points at are licensed separately
and not all the same way, so check each repository. psxrecomp is PolyForm
Noncommercial 1.0.0. That is not an open source licence. Read it before you
plan anything commercial.