GB Recompiled

GB Recompiled turns Game Boy and Game Boy Color ROMs into portable C projects. It analyzes LR35902 code, emits generated C, and links that code with a shared SDL2 runtime for video, audio, input, persistence, and hardware timing.

Generated desktop runtime	Exact-ROM port with host-native Challenge Mode

The project contains no ROMs. Use only ROM images that you are legally allowed to use.

• Decodes and analyzes banked LR35902 programs, then emits reviewable C and machine-readable metadata.
• Generates self-contained desktop projects with DMG/CGB execution, common cartridge mappers, SDL video/audio/input, battery saves, RTC data, and savestates.
• Falls back safely to the interpreter when static analysis did not compile a target.
• Exposes opt-in exact-ROM APIs for native function replacement, semantic data access, deterministic data mods, and host-native presentation.
• Ships differential, replay, frame/audio capture, benchmark, and external-test tooling so claims can be tied to reproducible evidence.

This is an experimental recompiler, not a whole-catalogue compatibility claim. Hardware accuracy and game coverage remain active work, and successful code generation does not guarantee that every scene will run correctly.

Prebuilt gbrecomp archives are available on the GB Recompiled 0.1.0 release:

To build from source, install CMake 3.20 or newer, Ninja, SDL2 development files, and a C11/C++20 compiler:

git clone https://github.com/arcanite24/gb-recompiled.git
cd gb-recompiled
cmake -G Ninja -B build .
ninja -C build

Generate, build, and run a project from a locally supplied ROM:

./build/bin/gbrecomp path/to/game.gb -o output/game
cmake -G Ninja -S output/game -B output/game/build
ninja -C output/game/build
./output/game/build/game

The same flow accepts .gbc ROMs. Passing a directory instead creates a shared multi-ROM launcher; use --list-games and --game <id> for scripted launches. Runtime controls and diagnostic flags are documented in Runtime usage.

The repository includes a ROM-free Pokémon Crystal flagship port that exercises the project beyond generic hardware emulation. It adds reviewed semantic views, transactional save edits, native Pokédex and PC surfaces, deterministic data mods, an Encounter Lens extension, and controller-configurable Challenge Mode.

Users provide the exact supported US/Europe Rev 1 ROM locally. The port verifies that input before generating any private ROM-derived output. Its checked routes and native features are release evidence, not a whole-game compatibility claim; the source-only alpha is currently verified end to end on macOS arm64, with other hosts documented as best-effort.

Read the Crystal Recompiled overview or the distribution boundary.

ROM -> decoder and analyzer -> IR + metadata -> generated C project
                                              + versioned runtime snapshot
                                              -> host compiler -> executable

The generated path and interpreter share runtime devices, so differential mode is useful for finding compiler/runtime divergence but is not an independent hardware oracle. Repository tests cover isolated invariants; external suites, SameBoy comparisons, and deterministic frame/audio/state evidence provide separate validation layers.

Run the repository-owned suite with:

cmake -G Ninja -B build-tests . -DBUILD_TESTS=ON
ninja -C build-tests
ctest --test-dir build-tests --output-on-failure

• Accuracy — current external-test evidence and limitations
• Game Boy Color status — implemented CGB behavior and remaining gaps
• Runtime usage — controls, persistence, diagnostics, and profiling
• Native replacement SDK — exact-ROM hooks and fail-closed manifests
• Port modules — semantic access and host presentation
• Data-mod packages — deterministic ROM-free overlays
• Android — single-ROM Android generation and APK workflow
• Project backlog — prioritized remaining work

Contributors and coding agents should read AGENTS.md before changing analysis, code generation, or hardware behavior.

GB Recompiled is available under the MIT License. Dear ImGui remains under its upstream license in the vendored runtime snapshot.

Game Boy is a trademark of Nintendo. This project is not affiliated with or endorsed by Nintendo.