Project deep-dive
Port games between systems with AI agents. · Prove every step.
A resumable workflow and toolkit for porting games from one system to another (vintage computers, consoles, DOS PCs), built so that AI agents can do most of the work and a machine check proves each result. It started with 8-bit computers: an original game on three CPUs, and Fantasy World Dizzy from the ZX Spectrum to the Tandy CoCo 2.
Porting a game to a different system, whether an 8-bit computer, a console or a DOS PC, is long, stop-start work, and it has two problems that make it a hard fit for AI agents. Sessions happen weeks apart, and an agent arrives with no memory of the last one. And the only real test, "does it still play the same?", normally needs a person watching two screens.
Game Port Factory solves both. A small Rust CLI, gpf,
keeps the whole project state on disk: a seven-stage model, a task graph where every task
carries the cheapest model tier that can do it and a command that proves it was done right,
and a handoff note that lets a cold session resume exactly where the last one stopped. A
differential harness, gpfdiff, replaces the person
at the screen: it runs the port and a reference in emulators, injects the same input, reads
the game state straight out of RAM at every step and compares the two.
Target machines are described as data, not remembered: ten platform profiles so far, from the ZX81 and the NES to DOS PCs and the Dreamcast, each listing its CPU, display, colour, sound and storage. The factory uses them to plan the order of ports by what actually carries over between two machines: code between CPUs of the same family, art between similar displays, often neither. I started with 8-bit computers because they are small enough to finish and hard enough to matter.
Two ports put it to work so far. Brickfall is a small game I designed for the purpose, written three times in three assembly languages (6502, Z80, 6809), each checked step by step against a Rust reference model. Fantasy World Dizzy is the real test: the full 1989 Spectrum adventure reimplemented in 6809 assembly for a 64K Tandy CoCo 2, with tape and floppy builds and a bot that plays the game's route on the original and the port side by side. The public repository contains none of the original game, yet anyone who supplies their own copy of its source files can rebuild the port and get output that matches mine byte for byte.
A personal project to find out how far a disciplined AI-agent workflow can go on a genuinely hard, multi-month engineering problem. The Dizzy port is still in progress (197 of 252 tracked tasks done).
Fantasy World Dizzy © The Oliver Twins / Codemasters, 1989. Shown to illustrate an unofficial, non-commercial port; no game data is distributed with this project. Brickfall is an original game written for this project.
A small paddle-and-bricks game I designed for the purpose, so the method could be proven with no copyright question. Its rules live once, in a platform-neutral recipe with a Rust reference model. It is written three times: for the Commodore 64 (6502), the ZX Spectrum (Z80) and the Tandy CoCo 2 (6809, running at 60 Hz instead of 50 Hz). All three produce exactly the same state, step by step, as the model across eleven scripted scenarios, and the harness checks that on every build. The art and sound differ per machine; the game underneath does not.
The 1989 ZX Spectrum adventure, reimplemented in 6809 assembly for a 64K Tandy CoCo 2, with tape and floppy builds. The CoCo draws the Spectrum's one-bit art at the same 256 × 192 resolution; the colour fringes are NTSC artifact colour, as on a real CoCo connected to a TV. A bot plays the same route plan on both machines, and the recording is re-aligned at the start of every route segment, so the two sides stay on the same step of the route even though each machine moves at its own pace within it. This clip is the opening: the Castle's Dungeon.
Every port is compared against an oracle. For a game I wrote, the oracle is a reference model. For an existing game, it is the original binary itself, driven from outside: the harness presses keys through the emulator's own input ports, starts the clock when a RAM value shows the game has really begun, and reads declared memory addresses at every step.
%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '15px', 'fontFamily': 'Inter, ui-sans-serif, sans-serif', 'lineColor': '#a5b4fc', 'primaryTextColor': '#e2e4ea', 'primaryColor': '#1e2330', 'primaryBorderColor': '#6366f1', 'secondaryColor': '#252b3b', 'tertiaryColor': '#181c26', 'background': '#0d0f14', 'clusterBkg': '#181c26', 'clusterBorder': '#374151', 'titleColor': '#e2e4ea'}}}%%
flowchart TD
subgraph oracle["Oracle"]
A["Recipe\nrules + state contract"] --> B["Reference model (Rust)\nfor a game we wrote"]
C["Original binary\nfor an existing game"] --> D["Black-box capture\nkeys in, RAM fields out,\nready gate on observed state"]
end
B --> G[("Golden traces")]
D --> G
subgraph port["Port under test"]
P["6502 / Z80 / 6809 build"] --> E["Emulator backend\nVICE · MAME (ZX) · MAME (CoCo)"]
end
E --> H["gpfdiff check\nsame input, state read every step"]
G --> H
H --> K{"Two runs identical?\nCanary rejected?"}
K -->|no| X["Exit 2: environment problem\n(not a port bug)"]
K -->|yes| R{"Traces match?"}
R -->|yes, or a named deviation| OK["PASS / EXPECTED"]
R -->|no| F["Exit 1: first differing step,\nfield, expected vs got"]
I ran the project as a lead with a small team of AI agents in Claude Code. The top-tier session plans, decides and reviews; cheaper models do the execution, and only against a check they cannot talk their way past.
%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '15px', 'fontFamily': 'Inter, ui-sans-serif, sans-serif', 'lineColor': '#a5b4fc', 'primaryTextColor': '#e2e4ea', 'primaryColor': '#1e2330', 'primaryBorderColor': '#6366f1', 'secondaryColor': '#252b3b', 'tertiaryColor': '#181c26', 'background': '#0d0f14', 'clusterBkg': '#181c26', 'clusterBorder': '#374151', 'titleColor': '#e2e4ea'}}}%%
flowchart LR
L["Lead session\nstrategy, design, review"] -->|clear spec + verifier| BU["Builder (mid tier)\nwrites tools and their tests"]
L -->|batch + verify command| GR["Grunt (low tier)\nruns harness batches"]
L -->|question| SC["Scout (low tier)\nprior art, sources, notes"]
BU --> RV["Report = a claim"]
GR --> RV
SC --> RV
RV -->|re-run independently| L
L --> HO["Handoff + notes\non disk for the next session"]
watch tool ("press a key, see which bytes move"). The timeline starts on an observed state, never a frame count, because a gate that fires two frames early makes every later sample wrong. Scenarios are written in milliseconds so a 50 Hz original and a 60 Hz port line up, and known platform differences are declared with a reason instead of hidden.
The getting started guide walks through all of this in about half an hour, including breaking the game on purpose to watch the harness catch it.
Build the tools and check your setup
git clone https://github.com/N0t4R0b0t/game-port-factory.git && cd game-port-factory cargo build --release --manifest-path gpf/Cargo.toml cargo build --release --manifest-path factory/tools/gpfdiff/Cargo.toml factory/tools/gpfdiff/target/release/gpfdiff doctor --platform all
Verify Brickfall on two machines
make -C ports/brickfall-c64/target check # 11 scenarios, bit-exact, run twice make -C ports/brickfall-zxspectrum48/target check # same traces, MAME backend
Build Dizzy from your own copy of the game's source
cd ports/dizzy-coco2 tools/bootstrap.sh --d3 /path/to/your/source --roms /path/to/coco-roms --verify # ... all 5 artifacts match docs/BUILD-HASHES.txt
No game data is in the repository. The bootstrap checks every file you supply by hash and never downloads anything.