Project deep-dive

Game Port Factory

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.

Overview

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).

3 CPUs, one verified game (6502 · Z80 · 6809)
101 Rooms in the Dizzy port, on a 64K machine
5/5 Build artifacts reproduced byte for byte from a clean clone
10 Platform profiles, from the ZX81 to the Dreamcast
380 Commits in ten weeks
The Castle's Dungeon: the Tandy CoCo 2 port beside the ZX Spectrum original Denzil's Pad in the tree-house village: CoCo 2 port and ZX Spectrum original The Dragon's Lair: CoCo 2 port and ZX Spectrum original Brickfall running on the Commodore 64 Brickfall running on the ZX Spectrum 48K
Fantasy World Dizzy · the Castle's Dungeon · CoCo 2 port (left) vs ZX Spectrum original (right) (click to expand)

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.

The Castle's Dungeon: the Tandy CoCo 2 port beside the ZX Spectrum original Denzil's Pad in the tree-house village: CoCo 2 port and ZX Spectrum original The Dragon's Lair: CoCo 2 port and ZX Spectrum original Brickfall running on the Commodore 64 Brickfall running on the ZX Spectrum 48K

Two proving grounds

Brickfall: one game, three CPUs

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.

Fantasy World Dizzy: a real port

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.

How a port is verified

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"]
        

Who does the work

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"]
        

Design decisions

Route work by verifiability, not difficulty The question for every task is not "is this simple enough for a small model?" but "is there a cheap, deterministic check that proves the output right?" If there is, the work goes down a tier. If there is not (strategy, design cuts, art direction), it stays at the top, because a weak model that hits a wall produces confident wrong output, and the cheap attempt plus the expensive fix costs more than never delegating.
A harness that cannot fail is worse than none Every check runs each scenario twice in fresh emulators and must produce identical traces, then corrupts one expected value and must notice. Builders also mutate the game's own code on purpose to prove the checks catch it. That exercise found a real blind spot: a missed-ball threshold was invisible when sampling every fifth step, so the suite gained a scenario that samples every step.
The original is the oracle An existing game was never built to be tested, so the harness treats it as a black box: keys go in through the emulator's input ports, state comes out of RAM addresses found with a 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.
Resumable by construction Nothing important lives in a conversation. Findings, memory maps and dead ends (always with the reason) go into the port's notes; reusable decisions become recipes that state the precondition under which they are safe. Ending a session without a handoff counts as destroying its value. The result is that a new session, human or agent, starts in about a minute.
Ship the tools, not the game The Dizzy port is built from the original game's source files, which are copyrighted and not mine to share. Every file in the repo is classified as ours, supplied by the user, or generated. A single bootstrap command verifies the user's files by hash, regenerates everything derived from them into ignored paths, and checks the result against a published hash list. The hard case was text: hand-edited source mixing my code with the game's dialogue. It is split into public templates holding keys into the user's own text, with a round-trip test proving the split loses nothing.
An agent's report is a claim, not a result Every success or failure reported by a delegated agent is re-run independently before it is acted on. That habit caught real problems in both directions: a release gate flagging a "leak" that was really a stale binary, a task chain ordered backwards, and an early export scan that trusted file extensions and let an extensionless emulator snapshot through. The gates now inspect content, and every publish audits the full history, not just the latest tree.

Tech Stack

Factory & tools

  • Rust (CLI, harness, extractors, packers)
  • TOML state on disk
  • Shell glue

Targets

  • 6502 assembly (acme)
  • Z80 assembly (sjasmplus)
  • 6809 assembly (lwasm)

Emulation

  • VICE binary monitor
  • MAME + Lua scripting
  • XRoar

AI

  • Claude Code + tiered subagents
  • Local vision model (Ollama) for sprite readability

Try it

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.

Back to portfolio