{"slug": "recompiling-game-boy-games-for-the-sega-master-system", "title": "Recompiling Game Boy Games for the Sega Master System", "summary": "A developer built gb2sms, a proof-of-concept static recompiler that converts Game Boy ROMs into Sega Master System cartridge images, with Tetris booting, playing at full speed, clearing lines and producing music on Sega hardware. DeepSeek V4.1 Flash wrote the initial pipeline — the ROM disassembler, SM83-to-Z80 translation and first recompiled images — while Claude Opus 5.5, running in Claude Code, handled bug-finding, writing Lua scripts for the Mesen emulator, lockstep comparisons against a Game Boy emulator and profilers. The work exploits the fact that about 82% of Sharp SM83 opcodes are byte-identical to Zilog Z80 opcodes and that ROM ($0000-$7FFF) and work RAM ($C000-$DFFF) map to identical addresses, leaving video and sound as the areas needing shim code.", "body_md": "The Game Boy and the Sega Master System have a lot more in common than their\nmarketing departments would have liked. I spent the weekend building **gb2sms**,\na proof-of-concept static recompiler that takes a Game Boy ROM and produces a\nMaster System cartridge image. Tetris now boots, plays at full speed, clears lines\nand makes music on a Sega console.\n\nI didn't write it alone. Two AI models did most of the typing, each on the part it was better at.\n\n**DeepSeek V4.1 Flash** did the original work: the first version of the\npipeline, from the ROM disassembler and SM83-to-Z80 translation to the first\nrecompiled images. It's fast and cheap, and for code where the target is clear,\nlike \"decode this instruction set\" or \"convert this tile format\", it got on\nwith it.\n\nIt struggled with debugging. Once a bug needed a hypothesis tested against an emulator trace, rejected, and replaced with a better one, it would get stuck in loops of \"Hmm... Hmm!\", circling the same idea without making progress.\n\n**Claude Opus 5.5**, running in Claude Code, took over for the difficult parts,\nmostly bug-finding. A recompiler fails quietly. Nothing crashes where the\nmistake is: the game runs off into the wrong memory a few thousand\ninstructions later. Finding the cause meant writing new tools as it went:\nLua scripts for the Mesen emulator to watch memory writes and record the last\ninstructions before a crash, lockstep comparisons against a Game Boy emulator,\nand profilers to see where the frame time went. All the bugs below were found\nthat way.\n\nMy job was to set the goal, decide what counted as \"working\", and keep checking the results on real emulators instead of trusting the tests. As you'll see, that turned out to matter.\n\nThe Game Boy's CPU, the Sharp SM83, is a cut-down cousin of the Zilog Z80, which\nis what the Master System uses. About **82% of the opcodes are byte-identical**.\nThe memory maps line up surprisingly well too:\n\n|  | Game Boy | Master System | What it means | \n|---|---|---|---|\n| CPU | SM83 @ 4.19 MHz | Z80 @ 3.58 MHz | 82% of opcodes identical | \n| ROM | `$0000-$7FFF` | `$0000-$7FFF` | identical | \n| Work RAM | `$C000-$DFFF` | `$C000-$DFFF` | identical | \n| VRAM | memory-mapped at `$8000` | behind I/O ports | needs a shim | \n| Sound | 2 square, wave, noise | 3 square, noise | wave channel has to be faked | \n\nSo before writing any shim code, the CPU, RAM and ROM model already sits at the same addresses. The real work is in the two places where the hardware differs: video and sound.\n\n``` php\nROM.gb -> map.py     code/data map: follows vectors, RST targets, jump tables\n       -> recomp.py  SM83 -> Z80 translation, relocation, stubs\n       -> shim.py    GB I/O shadow -> SMS VDP / PSG / joypad / interrupts\n       -> game.sms\n```\n\nThe hardest part is **telling code from data**. If you translate a byte that's\nreally part of a table, you corrupt the table. If you miss a piece of code, its\nGame Boy bytes stay in place and run as Z80 instructions that mean something\nelse. GB `ld a,[nn]` (`$FA`) happens to be Z80 `jp m,nn`, and that's a very\nefficient way to end up running VRAM. `map.py` runs a fixpoint traversal and\nlearns the specific idioms games use for dispatch: inline `rst $28` tables,\n`ld hl,T / add hl,bc / jp hl`, and handler arrays reached through `jp (hl)`.\n\nMost instructions translate one-for-one in place. Anything that grows when\ntranslated, such as `ldh` (high-page I/O) or `ld a,[hl+]`, either becomes an\nRST call to a shim or, if it's hot, the whole region gets moved somewhere with\nmore room and the original location is left holding a three-byte jump.\n\nMy favourite bug came from my own test harness. The port rendered the title screen with black vertical bars all over it:\n\nMy tile-diff tool reported **0 of 12,288 bytes wrong**. My pixel-diff tool was\nhappy as well. The problem was that I'd written the tile and palette conversion\nfor the **Game Gear / Mega Drive** formats, and I'd written the checking tools\nwith the same wrong idea of the format. Everything matched because everything\nwas wrong in exactly the same way.\n\nOn a Master System in mode 4:\n\n`(lo, hi)` maps straight across as `lo, hi, 0, 0`.`--BBGGRR`), not two bytes per colour.`$D0` terminator, or uninitialised VRAM draws 64\nsprites of noise.\nThe only way to catch it was a tiny test ROM whose correct output is obvious, run on a real emulator (Emulicious). With the fix in, the title screen comes up with all four greys correct:\n\n(The junk down the right and bottom is the area outside the Game Boy's 160x144 window, which isn't masked yet.)\n\nThe lesson is one I'll keep: **a reference model written by the same person as\nthe implementation isn't a reference.**\n\n`ld bc,$FFE0 / add hl,bc`, which is -32. The recompiler saw `$FFE0`,\ndecided it was a pointer into high RAM and moved it, so every line clear\nwrote rows over the port's own code. The fix follows each constant to where\nit's first used. Added to `hl`, it's a number. Dereferenced, it's a pointer.`$0066` isn't spare.`ldh` shim. A rewrite using `ex (sp),hl`,\nplus direct addressing in relocated code, took the menu from 49% to 100% of\nGame Boy speed.\nThe Game Boy APU is emulated at the register level. The game's writes land in a shadow copy, and once per frame the difference is converted into SN76489 PSG commands: frequency dividers, volume envelopes, and a noise channel that steals a tone voice for loud drums. The Game Boy's wave channel has no Master System equivalent, so for now it plays as a square wave at the fundamental.\n\nThe numbers look good: against the Game Boy, the title music has an envelope correlation of 0.96. But that only measures timing and loudness, meaning the notes start and stop in the right places. It says nothing about whether it sounds nice, and it doesn't. Have a listen.\n\nNeither clip is a hardware recording. The Game Boy clip renders Tetris's own APU register writes through a model of the Game Boy sound chip. The Master System clip is the recompiled ROM running in a Z80 simulator, with every byte it sends to the PSG rendered through a model of the SN76489.\n\n**Game Boy (reference)**\n\n**Master System (the port)**\n\n**Side by side**: Game Boy in the left ear and the port in the right, lined up\non the start of the title music. Headphones help.\n\nYes, the Master System version sounds rough. Here's what you're hearing:\n\nWhat I can say is that the port does what it was designed to do. The bytes the recompiled ROM sends to the sound chip match the offline converter note for note. The problem is the design, not the port, and the sound needs another pass.\n\nTetris works: the title, the menus, the attract demo and gameplay with line clears, all at full speed, and it stays instruction-for-instruction in step with the Game Boy for thousands of main-loop iterations. Alleyway, the second test game, is surfacing the next set of general problems: STAT interrupts, the window layer (the Master System doesn't have one), and a game that clears memory where my port keeps its code.\n\nThe real goal isn't Nintendo's back catalogue. It's homebrew and GB Studio games, so people can put their own Game Boy projects on a Master System. Tetris is just the most thoroughly understood test corpus there is.", "url": "https://wpnews.pro/news/recompiling-game-boy-games-for-the-sega-master-system", "canonical_source": "https://www.dmcmillan.co.uk/blog/recompiling-game-boy-games-for-the-sega-master-system", "published_at": "2026-11-21 12:51:26+00:00", "updated_at": "2026-11-21 13:15:01.443369+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "ai-tools", "large-language-models"], "entities": ["gb2sms", "Game Boy", "Sega Master System", "Sharp SM83", "Zilog Z80", "DeepSeek V4.1 Flash", "Claude Opus 5.5", "Claude Code"], "also_reported_by": [], "takeaway": "When statically recompiling between instruction sets, a fixpoint traversal that follows vectors, RST targets and jump tables is needed to separate code from data, since a missed code byte left in place can execute as a valid but wrong instruction (GB $FA is Z80 jp m,nn).", "recommendation": {"advice": "Split work by model strength: give clear translation tasks to a fast, cheap model like DeepSeek V4.1 Flash, and route hypothesis-driven debugging to a stronger model that writes its own emulator tracing and lockstep comparison tools.", "playbook": "agent-architecture", "playbook_url": "https://wpnews.pro/playbooks/agent-architecture"}, "alternates": {"html": "https://wpnews.pro/news/recompiling-game-boy-games-for-the-sega-master-system", "markdown": "https://wpnews.pro/news/recompiling-game-boy-games-for-the-sega-master-system.md", "text": "https://wpnews.pro/news/recompiling-game-boy-games-for-the-sega-master-system.txt", "jsonld": "https://wpnews.pro/news/recompiling-game-boy-games-for-the-sega-master-system.jsonld"}}