Context
The pret project decompiled Pokémon FireRed into C that builds a byte-matching GBA ROM. Emerald, its sibling, has several native PC ports. FireRed had none that was playable: the planning survey (October 2026) found one abandoned attempt, which reached Professor Oak's speech.
I wanted FireRed running natively on Linux and Windows, faithful to the GBA version, as a base for the things I actually want to play with friends: Nuzlocke runs, a randomizer and, later, Soul Link online.
The planning phase put "fully playable" at six to fifteen months of full-time work for one experienced C developer. The hard part isn't getting it to run. It's knowing it runs correctly: 64-bit pointer corruption, frame timing and graphics bugs all produce a game that seems to work.
What I built
How the port works
- The game's own code, compiled natively. The C sources are compiled for x86-64 almost unchanged; no CPU is emulated. The game keeps writing to its hardware registers, video memory and sprite tables, which are now plain arrays.
- A clean-room virtual GBA behind them, written from the GBATEK hardware documentation: a scanline renderer (windows, blending, affine sprites, mosaic), DMA, timers and interrupts, the BIOS calls, and a file-backed flash chip.
- A frame driver in the game's wait for VBlank. Logic runs as if at scanline 161; when the game waits, the driver steps the remaining scanlines, renders each with the registers as they are at that moment, and runs the HBlank work and the VBlank handler where the hardware would. Mid-frame effects come out right without the game knowing.
- 32-bit addresses kept valid on a 64-bit machine. On x86 the assembler's
.wordis 2 bytes, not 4, and a map header grows from 28 to 48 bytes. The executable loads below 4 GiB so the scripts' 4-byte pointers still work, only tables that C reads as structs widen (through aptrmacro that is.4byteon the GBA), and a clang-AST pass routes every pointer/integer cast through checked helpers. Relocation and DWARF layout checkers fail the build on anything they miss. - The game's own sound engine, with its assembly sequencer and mixer translated to integer-exact C (about 1,200 lines) and a from-scratch model of the GBA's FIFO and four PSG channels. SDL3 plays it with rate control that holds the queue at 2.5 frames.
- Emulator-compatible saves through a generated pack/unpack boundary,
written with an atomic four-step commit and a backup: a
kill -9at any step leaves a loadable file.
- An SDL3 front-end: window, keyboard and gamepad, pacing at the GBA's 59.73 Hz, settings, crash reports, error dialogs, an Arch package and a Windows zip.
How it's verified
The test oracle is the GBA ROM built from the same commit, run headless in libmgba. Every milestone had to match it:
- frames compared pixel by pixel at named checkpoints, and game state (party, bag, flags, position) compared by memory;
- a lag trace recorded on the GBA and replayed natively, so the two match iteration for iteration, random numbers included;
- the full game as 20 chapters of recorded input, joined by in-game saves, each chapter's save file checked against the GBA's. Battles were searched on the oracle for the input timing a route needed, not ground by hand;
- a dev warp on both sides into all 425 maps, cut from 35–42 minutes to 146 seconds by forking each map's run from a shared snapshot;
- a fuzzer with play-shaped random input, coverage feedback and a shrinker that retimes each finding so the oracle can replay it;
- ASan and UBSan over the full-game run.
What the GBA forgives
The most interesting bugs are things the hardware quietly survives. Fixes were measured on the oracle first, so the port does what the GBA does:
- Null pointers read the BIOS. On the GBA, address 0 is the BIOS region: reads return harmless bytes and writes vanish. Natively the summary screen, the PC storage system and MOVE ITEMS segfaulted.
- Brock's defeat text expands to 377 bytes and overruns its buffer on the GBA too, into an unused array. Natively it overwrote the pointer to the script that runs after the battle.
- A lag frame inside
Random(), between its load and store of the RNG state, undoes the VBlank handler's calls. The lag trace had to learn to flag it.
The technical article covers the frame driver, the pointer model, the lag trace, sound, saves and the playthrough in detail.
How I worked with Claude Code
Claude Code (Claude Opus 5.5) did the research, wrote the plans and almost all of the code, and ran the checks; all 245 commits carry its co-author line. My part was deciding what to build, how far to go, and when a milestone was done:
- The brief. A true source port of the decompiled code, with no embedded emulator, starting from a study of the existing Emerald ports.
- The 64-bit model. I had pokeemerald-wasm added to the survey. Its cast-rewriting technique is how the port checks every pointer cast.
- The process. Every milestone ran as a written plan, one commit per step and a closing report, and nothing reached the main branch until I signed it off.
- The scope calls. How the full-game run splits and reorders into chapters, which hard-to-reach features get injected test scenarios instead of played input, and which of three lag-trace designs to build.
- Holding the line. No
v1.0tag until real testers have played it, and no public code or binaries until a legal review. - The direction after the port. Every extra optional and off by default, so the vanilla game stays exactly as it was; Nuzlocke enforced by the game, with each rule toggleable; graphics filters only if they look good, which I checked on the captures before choosing which to ship.
Scope
- No external testers yet, so there's no
v1.0tag. The milestone that gets testers is planned but on hold until I have them. - Two small timing differences remain in the windowed build, among them a one-frame flash on entering a cave, because the port doesn't model how long the game's logic takes inside a frame.
- Link features (trades, link battles, wireless) are stubbed.
Decisions and trade-offs
- Compiling the game's own C code against a clean-room virtual GBAover forking an existing Emerald PC port, or wrapping an emulatorThe Emerald ports proved the design works, but their code is GPL/MPL-derived or unlicensed and carries known bugs, and an embedded emulator isn't a port. Writing the hardware layer from GBATEK keeps the port's own code clean and the game code nearly untouched.cost · The graphics, sound, DMA, timers and BIOS all had to be written from the hardware documentation: about 14,500 lines of platform code.
- Keeping the GBA's 32-bit addresses, with every pointer cast routed through checked helpersover widening the game's script bytecode to 8-byte pointers by handOne Emerald port needed 766 hand edits for 8-byte bytecode and kept regressing. Here the executable loads below 4 GiB, so 4-byte addresses stay valid, and a clang-AST rewriter (the technique from pokeemerald-wasm) wraps all the casts in helpers that abort on truncation.cost · Windows needs a fixed low image base and a startup check, and the rewriter adds about 11 seconds to a clean build.
- Testing against the real GBA build of the same commit, running in libmgbaover checking by eye or against the retail ROMPointer corruption, frame timing and graphics bugs all give a binary that looks fine. A same-source oracle separates porting bugs from pret's intentional fixes, and a recorded lag trace keeps the random number generator in step, so differences show up as hard failures.cost · A whole test harness of its own: an oracle runner, a 2.6 GiB result cache, and check runs of 13 minutes (full) to 38 minutes (all chapters) cold.
- Replaying the GBA's recorded lag in testsover modelling how many CPU cycles the game's logic takesThe GBA runs late on under 1 % of frames, but its VBlank handler calls Random(), so a lag frame in the wrong place sends the RNG and every wandering NPC elsewhere. Recording where each lag frame falls among the logic's calls, and replaying it natively, makes long replays exact without a cycle model.cost · The windowed build has no trace to follow, so two small timing differences remain there, such as one frame under the wrong palette when entering a cave.
- A save boundary generated from both builds' DWARF debug infoover hand-written conversion, or a native-only save formatNative structs have 8-byte pointers and different padding, but saves had to stay compatible with emulator .sav files. A generator flattens every save block to its leaves (8,400+ fields) and emits 341 copy spans plus 438 static asserts, so a struct change the table doesn't know about fails the build.cost · The game saves through GBA-layout staging buffers, pointers are stored as zero, and the table has to be regenerated whenever a save struct changes.
- The full game as 20 chapters joined by in-game savesover one continuous replay from power-onEach chapter can be rerun and bisected on its own, and the chain exercises Save and Continue twenty times, with each chapter's save checked against the GBA's.cost · There is no single power-on-to-credits run; the save chain stands in for it by showing the same state at every link.
Results
The full-game milestone closed seven days after the first port commit. The game plays from New Game to the post-game, matching the GBA build iteration for iteration in every chapter.
- Game time replayed by input, New Game to post-game
- 8 h 21 min
- Checkpoints matching the GBA over that run
- 1,295
- Maps pixel-exact after a warp
- 425 / 425
- Sound tests equal to the GBA's mixer output
- 732 / 732
- Commits, first port commit to settings screen
- 245 in 10 days
- Plays the whole game by recorded input alone: eight badges, the Elite Four, the Hall of Fame, the Sevii Islands and Trainer Tower
- Saves are byte-compatible with emulator .sav files: a save made natively loads in mGBA, and the other way round
- Every build gives the same frame hash: three Linux containers, an Arch package, a Windows zip and a real Windows CI runner
- The original GBA ROM still builds byte-identical: every game-file edit sits behind #ifdef PORTABLE, and a hash guard checks all 649 objects
- Optional comforts, off by default: instant text, fast-forward, color correction, display filters and a settings screen drawn in the game's own font
What I learned
- With an AI agent doing the implementation, the work that mattered most was deciding what "correct" means and making it checkable. The oracle turned "looks right" into a pass or a fail, so I could review results instead of reading every line.
- Written plans, one commit per step and a report at the end meant any fresh session could pick up from the repository alone, and I always knew what I was signing off.
- The GBA forgives a lot: reads through null pointers, buffer overruns and divisions by zero all quietly "work" on the hardware. A faithful port has to reproduce that behaviour, not fix it.