gb — Game Boy Color emulator core

A Game Boy / Game Boy Color emulator implemented in Luau. Loads actual .gb / .gbc cartridge ROMs and runs them: LR35902 CPU interpreter, CGB PPU rendered into a 160×144 RGBA framebuffer, MBC1/MBC3/MBC5 memory-bank controllers with battery RAM, timers, joypad, and a 4-voice APU.

Passes blargg's cpu_instrs (11/11) and instr_timing hardware-accuracy test ROMs. Boots and plays real CGB cartridges (validated with µCity, a CGB-only MBC5 cart).

require the module and assemble a machine from ROM bytes:

local Gb = require("gb")
local gb = Gb.new(romBytes)        -- romBytes: binary string of the cartridge
gb:runFrame()                      -- advance one video frame (~70224 dots)
gb.ppu.fb                          -- 160*144*4 RGBA byte buffer, row-major
gb:setInput(dpad, btns)            -- active-high masks (see joypad.luau)
gb:saveRam() / gb:loadRam(bytes)   -- battery-backed cart RAM
gb.apu:voices()                    -- live tone descriptors for an output stage
gb:serialText()                    -- captured serial output (test ROMs report here)

Submodules: bus.luau (address space + CGB banking), mbc.luau (cartridge mappers), cpu.luau + cpu_cb.luau (LR35902), timers.luau, ppu.luau (CGB scanline renderer with a decoded-tile cache), joypad.luau, apu.luau, display.luau (framebuffer → runtime texture).

The GameBoy component hosts a machine on an entity: it loads romPath, steps frames in play mode, blits to the gb_screen_mat screen texture, maps keyboard input, voices the APU through the engine's MIDI synth, and persists battery saves in runtime_data.world under gb_saves/<title>.

Test scripts live in /zero/source/gbtest/ — run with luau <path>; bench_cpu.luau measures interpreter throughput, blargg.luau runs the accuracy ROMs.