Pokémon FireRed PC Port

FireRed running natively on Linux and Windows, checked frame for frame against the real GBA build.

Role
Project lead · Solo, with Claude Code
Period
Oct–Nov 2026
Stack
C · SDL3 · Python · Make · libmgba · MinGW-w64 · GitHub Actions · Claude Code
Runs on
Local only, no cloud
Links
Technical article: the engineering in full

The code is private. The pret decompilation it builds on is unlicensed, so the port stays build-from-source for personal use, with no public repo or binaries until a legal review.

At a glance

Problem
Every mature native Pokémon port is Emerald. No playable native FireRed port existed, and a port that only looks right can hide silent data and timing bugs.
My contribution
Set the brief, the design direction and the scope calls; directed Claude Code through every milestone, reviewing and signing off each before it merged.
Outcome
The full game plays natively from New Game to the post-game, matching the GBA build iteration for iteration, with saves that load in emulators both ways.

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 .word is 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 a ptr macro that is .4byte on 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 -9 at any step leaves a loadable file.
One frame of 228 lines, to scale: lines 0 to 159 are visible and drawn one at a time, lines 160 to 227 are VBlank. Zoomed in: at line 160 the VBlank DMAs, the game's VBlank handler and the timers run and the frame goes to the screen; at line 161 the game's logic runs and then waits; the driver then steps lines 162 to 227 and 0 to 159, drawing each visible line.0160227visible lines 0–159VBlank 160–227line 160VBlank DMAs and handler,timers, frame to the screen→line 161the game's logic runs,then waits for VBlank→lines 162–227, 0–159stepped by the driver;visible lines drawn one by one
Fig. 1 · One frame in the port's frame driver: the full 228 lines to scale, and the start of VBlank zoomed in. Registers are read line by line, so mid-frame effects come out right.
  • 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.0 tag 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.0 tag. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.