Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Platform:Game Boy

From ReverseEngineering.wiki
Platform
Developer Nintendo
Versions Game Boy / DMG (1989), Game Boy Pocket / MGB (1996), Super Game Boy / SGB (1994), Game Boy Color / CGB (1998)
Endianness little
Website https://gbdev.io/pandocs/
On this wiki Facts · Code · Notes · Topics

Nintendo's 8-bit handheld family: Game Boy (DMG), Game Boy Pocket (MGB), the Super Game Boy SNES adapter and the Game Boy Color (CGB). A Sharp SM83 CPU (8080/Z80-like, little endian) sees a 16-bit address space in which cartridge ROM is switched in 16 KiB banks by a memory bank controller on the cartridge; graphics are 2 bpp 8x8 tiles in 8 KiB of VRAM (16 KiB on CGB).

Overview

  • CPU: Sharp SM83 core, an 8080-like CPU with part of the Z80 extensions (no IX/IY, no shadow registers, its own ldh/swap/stop opcodes). Master clock 4.194304 MHz (CPU cycle = 4 clocks); the CGB adds a double-speed mode (KEY1 0xFF4D).
  • Memory: 8 KiB work RAM (CGB: 32 KiB, banks 1–7 at 0xD000 via SVBK 0xFF70), 127 bytes of high RAM at 0xFF80–0xFFFE, 8 KiB VRAM (CGB: two banks via VBK 0xFF4F).
  • Screen: 160x144 pixels, 4 shades on DMG/MGB, 15-bit colour on CGB. One background layer, one window layer and 40 objects (sprites, 10 per scanline).
  • Cartridge: ROM at 0x0000–0x7FFF, optional RAM at 0xA000–0xBFFF. Larger games use a memory bank controller (MBC) that swaps 16 KiB ROM banks into 0x4000–0x7FFF; see Platform:Game Boy/Memory bank controllers.
  • ROM dumps (.gb, .gbc) are the raw cartridge ROM; the header at 0x0100 is described on Format:Game Boy ROM image.

Identification

  • A ROM image has the 48-byte Nintendo logo at file offset 0x0104 and usually 00 C3 50 01 (nop; jp 0x0150) at the entry point 0x0100. The byte at 0x0143 says whether the game uses CGB features (0x80 or 0xC0).
  • SM83 code is dense in ldh [n], a / ldh a, [n] (E0 nn / F0 nn) accesses to 0xFF00–0xFFFF, e.g. E0 40 for a write to LCDC. A Z80 disassembler decodes those bytes as ret po / ret p, so a Z80 listing full of conditional returns is a sign that the CPU is wrong.
  • At the entry point the boot ROM leaves a model identifier in register A (see Boot and startup). Games that support the Game Boy Color compare A with 0x11 in their first instructions.

Conventions

  • Addresses are 16-bit CPU addresses. Code and data in switchable ROM are named bank:address, e.g. 03:4A10 for CPU address 0x4A10 with ROM bank 3 mapped. This is the notation of RGBDS symbol files and of debuggers such as BGB, Emulicious and SameBoy; on this wiki use data.address with kind: banked on a Build: page of the ROM.
  • ROM file offset of a banked address: bank * 0x4000 + (address - 0x4000) for 0x4000–0x7FFF, and the address itself for bank 0 (0x0000–0x3FFF). This holds for the standard MBCs; MBC1 multi-game carts (MBC1M) are an exception.
  • RAM addresses are written as plain CPU addresses (0xC000–0xDFFF, 0xFF80–0xFFFE); CGB WRAM and VRAM banks are written bank:address too (1:9800 = VRAM bank 1).
  • Registers are named as in Pan Docs and the RGBDS hardware.inc (rLCDC, rSTAT, rDMA…), which the pret disassemblies also use.

Memory map

Range Size Contents
0x0000–0x3FFF 16 KiB ROM bank 0 (fixed on most MBCs): RST vectors 0x00–0x38, interrupt vectors 0x40–0x60, header 0x0100–0x014F
0x4000–0x7FFF 16 KiB Switchable ROM bank (1 and up). Writes here go to MBC registers
0x8000–0x97FF 6 KiB Tile data, 384 tiles (CGB: per VRAM bank)
0x9800–0x9BFF, 0x9C00–0x9FFF 2x 1 KiB Two 32x32 tile maps (CGB bank 1: attribute maps)
0xA000–0xBFFF 8 KiB Cartridge RAM, RTC registers or other mapper hardware
0xC000–0xDFFF 8 KiB Work RAM (CGB: 0xD000 bank switchable)
0xE000–0xFDFF Echo of 0xC000–0xDDFF; officially prohibited
0xFE00–0xFE9F 160 OAM, 40 objects x 4 bytes
0xFEA0–0xFEFF Unusable; value read depends on the model
0xFF00–0xFF7F I/O registers
0xFF80–0xFFFE 127 High RAM (HRAM), usable during OAM DMA
0xFFFF 1 IE interrupt enable

Interrupt vectors: VBlank 0x40, STAT 0x48, timer 0x50, serial 0x58, joypad 0x60; IE 0xFFFF and IF 0xFF0F use bits 0–4 in that order.

I/O registers

The registers a decompiler sees most often:

Address Name Purpose
0xFF00 P1/JOYP Joypad matrix; bits 4/5 select direction or button row
0xFF01, 0xFF02 SB, SC Serial (link cable) data and control
0xFF04–0xFF07 DIV, TIMA, TMA, TAC Divider and timer
0xFF0F IF Interrupt requests
0xFF10–0xFF26 NR10–NR52 Sound channels 1–4 and master control
0xFF30–0xFF3F Wave RAM 32 4-bit samples for channel 3
0xFF40 LCDC LCD control (see Graphics)
0xFF41 STAT PPU mode and STAT interrupt sources
0xFF42, 0xFF43 SCY, SCX Background scroll
0xFF44, 0xFF45 LY, LYC Current scanline and compare value
0xFF46 DMA OAM DMA from 0xXX00
0xFF47–0xFF49 BGP, OBP0, OBP1 DMG palettes
0xFF4A, 0xFF4B WY, WX Window position (WX is X + 7)
0xFF4D KEY1 CGB speed switch
0xFF4F VBK CGB VRAM bank
0xFF50 BANK Any write unmaps the boot ROM
0xFF51–0xFF55 HDMA1–5 CGB VRAM DMA
0xFF68–0xFF6B BGPI, BGPD, OBPI, OBPD CGB palette RAM index and data
0xFF70 SVBK CGB WRAM bank

Graphics

Tiles are 8x8 pixels, 2 bits per pixel, 16 bytes: two bytes per row, top row first. The first byte of a row holds bit 0 of each pixel's colour index, the second byte bit 1; bit 7 is the leftmost pixel. Pixel x of a row = ((lo >> (7-x)) & 1) | (((hi >> (7-x)) & 1) << 1). This is the same layout as SNES 2 bpp tiles (see Platform:Super Nintendo Entertainment System#Tile (character) format).

Tile addressing. Objects always use tile number 0–255 from 0x8000. The background and window use the same mode when LCDC bit 4 = 1; when it is 0 they use a signed index from 0x9000 (tiles 0–127 at 0x9000–0x97FF, 128–255 at 0x8800–0x8FFF).

LCDC 0xFF40 bits: 7 LCD on, 6 window map (0x9800/0x9C00), 5 window on, 4 tile data mode (see above), 3 BG map (0x9800/0x9C00), 2 object size (8x8 / 8x16), 1 objects on, 0 BG/window on (CGB: BG priority master switch).

Tile maps are 32x32 bytes of tile numbers (256x256 pixels, scrolled by SCX/SCY and wrapping). On CGB the same offset in VRAM bank 1 is an attribute byte: bit 7 BG-over-OBJ priority, 6 y-flip, 5 x-flip, 3 tile VRAM bank, 2–0 palette.

OAM holds 40 entries of 4 bytes: Y + 16, X + 8, tile number, attributes (bit 7 BG over OBJ, 6 y-flip, 5 x-flip, 4 DMG palette OBP0/OBP1, 3 CGB VRAM bank, 2–0 CGB palette). In 8x16 mode bit 0 of the tile number is ignored (top tile n & 0xFE, bottom n | 1). Colour 0 of an object is transparent.

DMG palettes (BGP, OBP0, OBP1) map colour index i to a shade in bits 2i+1:2i (0 white … 3 black). CGB palettes are 8 BG + 8 OBJ palettes of 4 colours in two 64-byte palette RAMs reachable only through BGPI/BGPD and OBPI/OBPD; each colour is little-endian BGR555 (0bbbbbgg gggrrrrr), the same encoding as SNES CGRAM.

OAM DMA. Writing n to DMA 0xFF46 copies n00–n9F to OAM in 160 machine cycles. On DMG only HRAM is accessible meanwhile, so nearly every game copies a short wait routine to HRAM at start-up and calls it from the VBlank handler; the RAM buffer it copies from is the game's shadow OAM.

Boot and startup

A 256-byte boot ROM (CGB: 2048 bytes, mapped at 0x0000–0x00FF and 0x0200–0x08FF so the header stays visible) is mapped over the cartridge at power-on. The DMG/MGB boot ROM scrolls the logo from the cartridge header, checks the logo and the header checksum (lock-up on failure), then writes to 0xFF50 and falls through to 0x0100; the SGB boot ROMs skip the checks, and the CGB boot ROM only checks the top half of the logo. The value left in A identifies the hardware: 0x01 DMG or SGB, 0xFF MGB or SGB2, 0x11 CGB or GBA (also in DMG compatibility mode). In CGB mode, B is 0x00 on a CGB and 0x01 on a GBA, which is how GBA-aware games brighten their palettes.

Recovery recipes

  • Find the VBlank handler: follow the jump at 0x0040. It usually calls the HRAM DMA routine (an ldh [0xFF46], a followed by a 40-iteration loop), reads the joypad and increments a frame counter.
  • Find the bank-switch helper: look for writes of a computed value to 0x2000–0x3FFF (ld [0x2000], a = EA 00 20). Games keep the current bank in a HRAM or WRAM variable so interrupts can restore it; that variable tells you which bank a far call targets.
  • Find the shadow OAM: the high byte loaded into A before the DMA routine is the page of a 160-byte RAM buffer (often 0xC000, 0xC100 or 0xC300).
  • Find graphics: tiles are copied to 0x8000–0x97FF, often compressed; break on writes to VRAM in a debugger and follow the source pointer back to ROM.

Topics

  • Memory bank controllers — How the cartridge mappers (MBC1, MBC2, MBC3, MBC5 and others) of the Game Boy switch ROM and RAM banks, by cartridge type byte at header offset 0x0147, with the

Code & repositories

  • https://github.com/gbdev/pandocs @ abeda621759a8e2b322b368eacf4d31ec48eb4df · license: CC0-1.0
    Pan Docs: the community reference for Game Boy, Game Boy Color and Super Game Boy hardware (memory map, I/O registers, PPU, audio, MBCs, cartridge header, boot ROMs, accessories). Markdown sources of https://gbdev.io/pandocs/, CC0.
    Tested on: Read at commit abeda62 (2026-10-16). Cartridge header facts checked against the dmg-acid2 v1.0 and cgb-acid2 v1.1 test ROMs. · checked 2026-10-17; last activity 2026-10-16
  • https://github.com/gbdev/rgbds @ d766efe95d82f0d64dd95dece60b7681c7a14de9 · license: MIT
    Game Boy assembler and linker; rgbfix writes the Nintendo logo, header checksum and global checksum, sets cartridge type, ROM/RAM size and CGB/SGB flags (src/fix/)
    Tested on: source read, not run: source not read in detail; README and repository layout checked · checked 2026-10-18; last activity 2026-10-17; Note: the latest release ships binaries; the wiki links only the source, never the binaries
  • https://github.com/gbdk-2020/gbdk-2020 @ fe33b6b8717b4ebdfa9e7db201ad1d2e5a7761dd · license: GPL-2.0-or-later WITH LicenseRef-GBDK-linking-exception (declared by the contributor; GitHub's detector did not recognize LICENSE)
    C toolchain (SDCC based) for Game Boy / Game Boy Color and other SM83, Z80, 6502 targets; makebin writes the ROM header fields (cartridge type, sizes)
    Tested on: source read, not run: LICENSE overview and README read, source not read in detail · checked 2026-10-18; last activity 2026-10-17; Note: the latest release ships binaries; the wiki links only the source, never the binaries

Pitfalls

  • MBC1 cannot map banks 0x20, 0x40, 0x60 into 0x4000–0x7FFF (the bank-0-to-1 rule), so ROM layouts and bank tables of MBC1 games skip them.
  • VRAM is inaccessible during PPU mode 3 and OAM during modes 2–3; writes are dropped. Code that waits on STAT before a write is doing this on purpose.
  • rst vectors in 0x0000–0x0038 are often used as compact call targets (bank switch, far call, jump tables); a call through rst 0x28 etc. is not an error handler.
  • Echo RAM (0xE000–0xFDFF) mirrors WRAM on real hardware; a pointer into it is a WRAM pointer.
  • Fixed hardware addresses (I/O registers, vectors) are platform facts but cannot be stored as address facts on this wiki, which only accepts addresses for one build; they are kept in the tables above instead.

Evidence & references

Summarized from Pan Docs (gbdev/pandocs, CC0-1.0, commit abeda621759a8e2b322b368eacf4d31ec48eb4df): Memory Map, Hardware Reg List, LCDC, Tile Data, Tile Maps, OAM, Palettes, OAM DMA Transfer, Power Up Sequence and the MBC pages. The pret disassemblies (e.g. pokered, engine/gfx/oam_dma.asm) show the HRAM DMA routine pattern in practice. The recovery recipes are general practice and not taken from a single source.