A ROM image holds the code and data that drive this hardware. This page says what the picture unit, sound unit, timer, joypad, serial port and interrupts do, as far as someone reading a ROM or its disassembly needs to know it; the bits of each register are on the register bit layouts page. It is our summary of the raw Pan Docs Markdown (CC0, read 2026-11-19; kept in the site’s sample sources), each section naming its source file. Pan Docs is the only source; nothing here was checked on hardware. This page is the summary. The detail is on seven pages: picture unit in depth (PPU timing, the pixel FIFO, the OAM bug, STAT), sound in depth, timer, HALT and power (timer glitches, the halt bug, interrupt timing, power saving), DMA, joypad and serial, palettes and colourisation, Super Game Boy and Game Boy Printer.
Picture unit (PPU)
Source: Graphics.md, Rendering.md, Tile_Data.md, Tile_Maps.md, OAM.md, Window.md, Scrolling.md, Palettes.md, LCDC.md.
The screen is 160 × 144 pixels. Pixels are not set one by one: they are grouped into 8 × 8 tiles. A tile holds no colour, only a colour index 0–3 per pixel (2 bits per pixel). The index is turned into a shade by a palette; in an object, index 0 is transparent. There are three layers, back to front: the background (a grid of tile references that scrolls as a whole), the window (a second background-like rectangle on top, with no transparency, of which only the top-left position can be set, for example for a status bar) and the objects (movable pieces of one or two stacked tiles; several can be combined to make a larger sprite).
Tile data
Tile data lives at $8000–$97FF: 16 bytes per tile, so 384 tiles (768 with the Color’s second VRAM bank). They form three blocks of 128 tiles: block 0 $8000–$87FF, block 1 $8800–$8FFF, block 2 $9000–$97FF. Objects always use IDs 0–255 over blocks 0 and 1 (the “$8000 method”, unsigned). The background and window use the same method if LCDC bit 4 is 1; if it is 0 they use the “$8800 method”, where IDs 0–127 are in block 2 and 128–255 in block 1 (signed, with base $9000).
Each row of 8 pixels takes 2 bytes: the first byte holds the low bit of each pixel’s colour index, the second the high bit, bit 7 being the leftmost pixel. Example from Pan Docs: the bytes $3C $7E give the row 0 2 3 3 3 3 2 0.
Tile maps
Two 32 × 32 maps of 1-byte tile IDs sit at $9800–$9BFF and $9C00–$9FFF; either can serve the background or the window (LCDC bits 3 and 6). A map is 256 × 256 pixels, of which 160 × 144 show; the visible area wraps around the map edge. The background scrolls with SCY/SCX; the window cannot scroll and always starts at the top-left tile of its map, its screen position being (WX − 7, WY). In Non-CGB Mode LCDC bit 0 turns the background and window off.
In Color mode VRAM bank 1 holds, at the same addresses, one attribute byte for each map entry in bank 0 (the attribute at 1:9800 belongs to the tile at 0:9800 only):
| Bit | Name | Meaning |
|---|---|---|
| 7 | Priority | 1 = colour indices 1–3 of this tile are drawn over objects, whatever the object’s own priority bit says. |
| 6 | Y flip | 1 = drawn vertically mirrored. |
| 5 | X flip | 1 = drawn horizontally mirrored. |
| 4 | not named | Ignored by the hardware but can be written and read. |
| 3 | Bank | 0 = tile from VRAM bank 0, 1 = from bank 1. |
| 2–0 | Color palette | Which of the 8 background palettes to use. |
Objects and OAM
OAM ($FE00–$FE9F) holds 40 objects of 4 bytes. At most 10 can be shown per line. Object tiles come from blocks 0 and 1 with unsigned numbering.
| Byte | Meaning |
|---|---|
| 0 | Y position + 16. Y = 0 hides the object; 16 puts it at the top of the screen; 144 aligns an 8 × 16 object, and 152 an 8 × 8 one, with the bottom; 160 or more hides it. |
| 1 | X position + 8. X = 0 or 168 and above hides the object, but it still counts towards the 10-per-line limit (it is better to hide an object by its Y). |
| 2 | Tile index. In 8 × 16 mode (LCDC bit 2) the low bit is ignored: the top tile is index AND $FE, the bottom index OR $01. In Color mode the bank is chosen by bit 3 of byte 3. |
| 3 | Attributes: bit 7 priority (1 = background and window colours 1–3 are drawn over this object), bit 6 Y flip, bit 5 X flip, bit 4 DMG palette (0 = OBP0, 1 = OBP1; Non-CGB Mode only), bit 3 VRAM bank (Color only), bits 2–0 CGB palette, which of the 8 object palettes (Color only). |
The recommended way to fill OAM is to build the table in work RAM and copy it with OAM DMA; direct writes work only in HBlank and VBlank (modes 0 and 1). Each line’s OAM scan checks LY against every object’s Y (using the size from LCDC bit 2) in order from $FE00 and takes the first 10 that fit, so even off-screen objects use up places (keep unused objects at Y = 0 or Y ≥ 160; Y ≤ 8 also works for 8 × 8 objects).
Drawing priority
When opaque pixels of two objects overlap: in Non-CGB Mode the one with the smaller X wins, ties going to the earlier OAM entry; in Color mode only OAM order counts, earlier winning. Object-to-object priority is settled first, giving one “object pixel”; only then is its “background over object” bit checked, so a high-priority object with that bit set masks lower ones even if theirs is clear. In Color mode, background against object is decided like this: if the background colour index is 0, the object wins; otherwise if LCDC bit 0 is clear, the object wins; otherwise if both the map attribute bit 7 and the object attribute bit 7 are clear, the object wins; otherwise the background wins.
Window behaviour
Source: Window.md. The window shows (if enabled) when WX is 0–166 and WY is 0–143. The PPU keeps a “Y condition”: cleared at each VBlank and set at the start of a line when WY equals LY. It also counts pixels on each line, starting with a 7-pixel lead for the discarded fine-scroll pixels. When the count equals WX, the Y condition is true and LCDC bit 5 is set, background drawing restarts from the current row of the window map and that row number advances. The row advances only on lines where the window actually starts, so a hidden window resumes from the row it would have shown anyway, giving a vertical stretching effect. For the cleanest results change WX, WY and LCDC in VBlank; to hide the window for part of the screen, set WX high instead of clearing LCDC bit 5. Pan Docs notes that on the Color, clearing LCDC bit 5 resets the Y condition, and describes two monochrome bugs (WX = 166, and a stray colour-0 pixel when the window is disabled but would have started on a tile boundary).
Timing and PPU modes
Source: Rendering.md. A frame is 154 lines; the first 144 are drawn top to bottom. A dot is one 4.194 MHz tick (4 per normal-speed M-cycle, 2 per double-speed one, so dots do not change with CPU speed). A frame takes about 16.74 ms, slightly slower than 60 Hz. Changing parameters between lines gives “raster effects”, such as a wavy scroll.
| Mode | Action | Duration | Video memory the CPU can use |
|---|---|---|---|
| 2 | Searching for objects on this line | 80 dots | VRAM, Color palettes |
| 3 | Sending pixels to the LCD | 172–289 dots | none |
| 0 | Waiting for the end of the line | 376 minus mode 3’s length | VRAM, OAM, Color palettes |
| 1 | Waiting for the next frame (VBlank) | 4560 dots (10 lines) | VRAM, OAM, Color palettes |
Memory the PPU is using is closed to the CPU: writes are ignored and reads return garbage, usually $FF. Mode 3 lasts at least 160 + 12 = 172 dots (12 for two tile fetches at the start, one of which is discarded) and is stretched by three penalties, which shorten mode 0 by the same amount: scrolling (SCX mod 8 dots at the start), the window (6 dots) and each object drawn on the line (6 to 11 dots, 11 for an object at OAM X = 0).
Sound unit (APU)
Source: Audio.md, Audio_Registers.md, Audio_details.md.
The APU runs on the same master clock as the CPU and PPU (about 2.4 % fast on the SGB1, which raises the pitch by as much; the SGB2 corrects it) and is not affected by CGB double speed. It has four channels, each a generator plus a DAC. Channels 1 and 2 are pulse channels with four fixed pulse widths; channel 3 plays a 32-sample, 4-bit wave from wave RAM; channel 4 makes pseudo-random noise with a linear-feedback shift register. The channel outputs are mixed into a left and a right signal, scaled by NR50, passed through a high-pass filter (which removes the constant offset of silent channels) and sent to the headphone jack or the single speaker, which merges both sides. A fifth, analogue input, VIN, can come from the cartridge; no licensed game used it, and the Advance omitted it.
| Channel | Sweep | Frequency | Wave form | Length timer | Volume |
|---|---|---|---|---|---|
| 1 (pulse) | sweep | period counter | duty | counts to 64 | envelope |
| 2 (pulse) | — | period counter | duty | counts to 64 | envelope |
| 3 (wave) | — | period counter | wave RAM | counts to 256 | output level |
| 4 (noise) | — | period counter | LFSR | counts to 64 | envelope |
- Triggering a channel (bit 7 of its
NRx4) turns it on, unless its DAC is off, and restarts its wave; pulse channels keep their phase unless the APU is turned off. Most parameter changes act at once, a few need a retrigger. - Length timer. If enabled, it ticks at 256 Hz from the value it was set to and turns the channel off at 64 (channels 1, 2, 4) or 256 (channel 3).
- Envelope. Channels 1, 2 and 4 have an initial volume, a direction and a pace; envelopes tick at 64 Hz and step the volume every 1–7 ticks.
- Frame sequencer (“DIV-APU”). A counter advances when DIV bit 4 (bit 5 in double speed) falls from 1 to 0, 512 times a second. Every 8th tick steps the envelopes (64 Hz), every 2nd the length timers (256 Hz) and every 4th the channel 1 sweep (128 Hz). Writing DIV can make it advance faster.
- DACs. A channel’s DAC is on when
NRx2 & $F8is not 0 (channel 3: NR30 bit 7). It turns digital 0–15 into analogue 1 to −1 (note the negative slope). A disabled DAC fades to 0 (“digital 7.5”). Switching a DAC or a panning bit, or changing NR50, causes a pop, which a sound driver avoids by never turning DACs off. - Mixer filter. The high-pass filter is more aggressive on the Advance than on the Color, and on the Color than on the DMG.
The register bits are in the sound group.
Timer
Source: Timer_and_Divider_Registers.md. Three registers make a programmable timer (not the MBC3’s real-time clock): DIV counts at 16384 Hz and is cleared by any write; TIMA counts at the rate TAC selects (4096, 262144, 65536 or 16384 Hz) and, on overflowing past $FF, reloads from TMA and requests the timer interrupt, so TMA sets the divider ratio; TAC bit 2 enables TIMA. See the bit layouts.
Joypad
Source: Joypad_Input.md. Eight buttons in a 2 × 4 matrix, read through P1 ($FF00): choose the action buttons or the directions with bits 5 and 4 (0 selects), then read bits 3–0, where 0 means pressed. A high-to-low change on a selected line requests the joypad interrupt, which in practice ends STOP standby (interrupt details).
Serial port (link cable)
Source: Serial_Data_Transfer_(Link_Cable).md. Two consoles exchange one byte at a time. The one that generates the clock is the master; the other is the slave. A transfer shifts the byte in SB out, bit 7 first, while the incoming bits are shifted in, so both consoles swap bytes. The master starts with SC = $81, the slave sets SC = $80 first; both get a serial interrupt and SC bit 7 clears at the end. The clock is 8192 Hz on the monochrome Game Boy, and on the Color 8192, 16384, 262144 or 524288 Hz. An external clock can have any speed, even “one bit a month”, and the monochrome Game Boy is reported to accept up to 500 kHz.
- Timeouts. With an external clock the transfer does not end until the last bit arrives, so a program should use a timeout counter.
- Disconnects. On a disconnected cable the master reads 1 bits, so it receives
$FF. A disconnect during a transfer pulls the input up over about 20 µs (measured on a CGB rev E only), which at the highest speed can last more than one byte. - Synchronisation. The master should wait a little after each transfer so the slave can prepare. The slave must set its start bit before the master starts, or the two can swap the internal and external clock roles for each byte.
Interrupt handling
Source: Interrupts.md (the five sources are on the memory map page). IME, an internal flag, gates all handlers: ei sets it (after a one-instruction delay, so ei directly followed by di lets nothing through), di clears it, reti sets it and returns, and entering a handler clears it. It is off when the game starts. A handler runs when IME is set and an IE bit and its IF bit are both set: the CPU clears that IF bit and IME, waits 2 M-cycles, pushes PC (2 M-cycles) and jumps to $40, $48, $50, $58 or $60 (1 M-cycle), 5 M-cycles in all. If several are pending the lowest bit wins. A handler that wants to be interrupted by others executes ei itself.
Colour palette hardware and double speed
Source: Palettes.md and CGB_Registers.md. The Color’s palette memory and its index and data registers, the double-speed switch and the VRAM DMA are described register by register on the bit layouts page. Colours are 15-bit, 5 bits per component. Pan Docs warns that the Color’s screen is not lit, so the brightest value shows as light grey, and its pigments mix oddly (raising one component raises the others), so colours chosen on an sRGB monitor look different; on an early Advance the values $00–$07 look black, and it suggests converting with GBA ≈ GBC × 3/4 + $08 per component after detecting the Advance (A = $11 with B bit 0 set).
Game Genie and GameShark
Source: raw Pan Docs Shark_Cheats.md (samples/gb/sources/pandocs-more, CC0, read 2026-11-19). Both are adapters that plug between the console and the game cartridge.
Game Genie (ROM patches)
A code is nine hexadecimal digits written ABC-DEF-GHI (A is the first digit, I the ninth). The digits mean:
| Digits | Meaning |
|---|---|
AB | the new data byte |
FCDE (digit order F, C, D, E) | the memory address, XORed with $F000 |
GI | the old data byte, XORed with $BA and rotated left by two bits |
H | unknown, “maybe checksum and/or else” (Pan Docs) |
The address should lie in the ROM area $0000–$7FFF. The adapter permanently compares the address and old data with the address and data the game is reading, and replaces the data by the new data when they match; this (more or less) prevents patching the wrong memory bank. Pan Docs adds a question mark about whether external RAM could be patched too. Newer devices reportedly allow only the first six digits to be given, and three codes can be active at once. Pan Docs links the Game Genie manual (a PDF on digitpress.com) as reference; it was not read. Worked example (ours, from the field table, not from Pan Docs): the digits 1 2 3 4 5 6 7 8 9 give new data $12; the address is digits F, C, D, E = 6 3 4 5 = $6345, XOR $F000 = $9345, which lies above the ROM area, so such a code would not be a valid ROM patch.
GameShark (RAM patches)
A code is eight hexadecimal digits. Pan Docs draws them as a bit diagram with three fields: the SRAM bank (digits 0–1), the new value (digits 2–3) and the address (digits 4–7), the low byte of the address first, as its example shows. Example from Pan Docs: the code 010238CD switches to SRAM bank $01 and writes $02 at address $CD38 (bank $01, value $02, address bytes 38 CD → $CD38).
As far as it is understood, the patching is done by hooking the game’s original VBlank interrupt handler and rewriting the RAM values every frame. The downside is that this steals CPU time, and that it cannot patch program code in ROM. Between 10 and 25 codes can be used at once. (All of this paragraph is Pan Docs’ wording, which itself says “as far as it is understood”.)
The Game Boy Color approval process
Source: raw Pan Docs GBC_Approval_Process.md (same folder, CC0, read 2026-11-19). It is a business process, not hardware, and is here for completeness of the Pan Docs chapter list. Pan Docs’ account:
- The Game Boy Color hardware colours a monochrome game automatically, with one 4-colour palette for backgrounds and two 3-colour palettes for objects (see palettes). Because first-party Super Game Boy features had been under-used (Pan Docs cites an article by Christine Love), Nintendo required Game Boy Color games to look more colourful than this automatic colouring and kept itself in the loop at three points of development.
- The Mario Club division judged whether colour was used appropriately: variety of colours within a scene and between scenes; colours suited to the art style (for example objects distinguishable, trees coloured like trees); and contrast between foreground and background to bring out saturation.
- First point, the written design document: for original games and ports alike, it had to explain and illustrate how colour would be used, give a project schedule, the estimated ROM and RAM size and whether the ROM would be dual-compatible (also runs on the original Game Boy) or Game Boy Color only. Ports of monochrome games (Pan Docs’ examples: Tetris DX, Link’s Awakening DX and the MacVenture series by ICOM) also needed concept pre-approval, which original games did not, and the proposal had to explain what new gameplay content (levels, characters, items) the port adds apart from colour.
- Second and third points: at the 50 percent milestone and near completion the publisher submitted a ROM image to Mario Club for feedback on colour and other design aspects.
- References named by Pan Docs: “F the Super Game Boy: Kirby’s Dream Land 2” by Christine Love; “The Making of Snoopy Tennis” by Alexander Hughes; and the “License Agreement for Game Boy (Western Hemisphere)” (an archived contract); none was read here.
Sources
- Raw Pan Docs Markdown (CC0), read 2026-11-19, in
samples/gb/sources/pandocswith SHA-256 in the sample README:Graphics.md,Tile_Data.md,Tile_Maps.md,OAM.md,OAM_DMA_Transfer.md,Window.md,Rendering.md,Scrolling.md,Palettes.md,LCDC.md,Audio.md,Audio_Registers.md,Audio_details.md,Timer_and_Divider_Registers.md,Joypad_Input.md,Serial_Data_Transfer_(Link_Cable).md,Interrupts.md,CGB_Registers.md. - Graphics, Rendering, Audio, Interrupts – Pan Docs
Not described
Known, not yet covered
- This page is a summary. The pixel FIFO and OBJ penalty algorithm, accessing VRAM and OAM, the OAM corruption bug, the STAT line, Timer Obscure Behaviour, HALT and the halt bug, interrupt timing, the rest of Audio details (including Game Boy Advance audio and the obscure behaviour), OAM DMA and VRAM DMA, the joypad and serial details, the compatibility palettes, the whole Super Game Boy chapter, the Game Boy Printer and power saving are written on the seven deeper pages listed above (progress-gb-hardware, 2026-11-19).
- The infrared chapter, the 4-player adapter and the external connector pin-outs are on DMA, joypad and serial. The Game Genie and GameShark cheat devices (
Shark_Cheats.md) and the Game Boy Color approval process (GBC_Approval_Process.md) are written on this page, under Game Genie and GameShark and The Game Boy Color approval process.
Unknown
- The points Pan Docs itself marks as to do or unverified, for example mid-line toggling of LCDC bit 1 on the DMG, the DIV behaviour after a speed switch, and interrupts during the speed-switch pause (what Pan Docs, SameBoy, the Mooneye tests and the wiki say about these two is on timer, HALT and power).