Platform:Game Boy
| 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/stopopcodes). 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
0xD000viaSVBK 0xFF70), 127 bytes of high RAM at0xFF80–0xFFFE, 8 KiB VRAM (CGB: two banks viaVBK 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 at0xA000–0xBFFF. Larger games use a memory bank controller (MBC) that swaps 16 KiB ROM banks into0x4000–0x7FFF; see Platform:Game Boy/Memory bank controllers. - ROM dumps (
.gb,.gbc) are the raw cartridge ROM; the header at0x0100is described on Format:Game Boy ROM image.
Identification
- A ROM image has the 48-byte Nintendo logo at file offset
0x0104and usually00 C3 50 01(nop; jp 0x0150) at the entry point0x0100. The byte at0x0143says whether the game uses CGB features (0x80or0xC0). - SM83 code is dense in
ldh [n], a/ldh a, [n](E0 nn/F0 nn) accesses to0xFF00–0xFFFF, e.g.E0 40for a write toLCDC. A Z80 disassembler decodes those bytes asret 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
0x11in their first instructions.
Conventions
- Addresses are 16-bit CPU addresses. Code and data in switchable ROM are named bank:address, e.g.
03:4A10for CPU address0x4A10with ROM bank 3 mapped. This is the notation of RGBDS symbol files and of debuggers such as BGB, Emulicious and SameBoy; on this wiki usedata.addresswithkind: bankedon aBuild:page of the ROM. - ROM file offset of a banked address:
bank * 0x4000 + (address - 0x4000)for0x4000–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 (anldh [0xFF46], afollowed 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,0xC100or0xC300). - 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,0x60into0x4000–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
STATbefore a write is doing this on purpose. rstvectors in0x0000–0x0038are often used as compact call targets (bank switch, far call, jump tables); a call throughrst 0x28etc. 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.