The Super Game Boy (SGB) lets Game Boy games run on a Super Nintendo. This page covers the whole Pan Docs Super Game Boy chapter: what it adds, how a ROM unlocks and detects it, the packets, every command and its byte layout. It is our own wording of the raw Pan Docs Markdown (CC0, read 2026-11-19, kept in the site’s sample sources with SHA-256 in the sample README); each section names its file. Pan Docs is the only source. Where Pan Docs itself has “???” (it is unsure) this page says so. The header bytes that unlock SGB features are in the cartridge header page; the register values at start-up are on the memory map page.
What the Super Game Boy is
Source: SGB_Functions.md.
A Super Game Boy is an adapter cartridge. The Game Boy cartridge plugs into it and it plugs into the SNES. It holds a Game Boy system on a chip, with its own CPU, video and sound, and a bridge circuit, the ICD2, that translates joypad input, the video signal and control packets between the SNES and the Game Boy. It also holds the system software that runs on the SNES. That software passes on button presses and sends the picture to the TV. Both the player and the game get a little control over the look.
- Normal monochrome games work with no changes. The SGB replaces the four greys with a four-colour palette. The 160 × 144 game screen sits in the middle of the 256 × 224 SNES screen, and the rest is a border bitmap. Built-in menus let the user change palettes and pick one of several borders.
- Colourised screen. A game can give palettes to each of the 20 × 18 character cells. Pan Docs says this suits static pictures such as title screens and status bars. The attribute map cannot scroll and moving objects cannot have their own colours, so animated areas mostly use one palette of four colours.
- SNES objects. Up to 24 extra objects of 16 colours, 8 × 8 or 16 × 16 pixels. The bottom character line of the game screen is masked, because it carries the object positions to the SNES. Pan Docs says later versions of the system software remove much of this, and that the feature is not popular. The command is one of the removed commands.
- Border. The most popular feature: a custom border stored in the cartridge. It uses 4 bits per pixel (16 colours per tile), against 2 bits (4 colours) on the Game Boy.
- Multiple joypads. Up to four joypads on the SNES, each readable by the game, for four players on one cartridge and one screen, with no link cables.
- Sound. Sound effects built into the SNES software, plus direct access to the SNES sound chip or its N-SPC (“Kankichi”) sequencer.
- SNES CPU control. A game can write code or data into SNES memory and run it.
Clock speed
The Game Boy clock is tied to the SNES clock, so the SGB1 runs fast: NTSC about 4.2955 MHz (the SNES master clock is 21.477 MHz), 2.41 % fast; PAL about 4.2563 MHz (21.281 MHz), 1.48 % fast. Sound is slightly high in pitch, especially next to the SNES sequencer, and a game may lower its frequencies when it detects an SGB. The SGB2 has its own 20.972 MHz crystal and runs at the correct speed. A PAL SNES refreshes at 50 Hz, which makes the Game Boy timing correspondingly slower. This agrees with the specifications table.
Unlocking and detecting
Source: SGB_Unlocking.md.
The header
An SGB game needs the Nintendo logo and a correct checksum like any game, and two special entries:
- the SGB flag at
$0146must be$03; - the old licensee code at
$014Bmust be$33.
Without both, the game runs like any monochrome game but cannot use any SGB function. The viewer’s header section shows both bytes and says whether SGB functions are unlocked.
Detecting by registers
Read the start-up value of the C register: $14 means an SGB or SGB2. The A register then separates the two, though the DMG and MGB share A with the SGB and SGB2:
| Console | A | C |
|---|---|---|
| DMG | $01 | $13 |
| SGB | $01 | $14 |
| MGB | $FF | $13 |
| SGB2 | $FF | $14 |
| CGB | $11 | $00 |
| AGB | $11 | $00 |
The SGB2 has no feature that needs separate detection, except for curiosity: Tetris DX shows a different border on an SGB2. Only the SGB2 has a link port. All register values at start-up are in the CPU register tables.
Detecting with MLT_REQ
The traditional way is to send MLT_REQ to enable two or four joypads. A plain Game Boy ignores it. An SGB then returns changing joypad IDs each time the key lines are deselected (see reading several joypads), where a plain Game Boy always returns $0F. Read the ID several times; if it changes, it is an SGB. Then send MLT_REQ again to turn multi-controller mode off if only one pad is needed. It works however many pads are connected. Pan Docs says it is slower and more complicated than the register check and works only when the SGB functions are unlocked by the header.
Command packets
Source: SGB_Command_Packet.md.
Packets travel from the Game Boy to the SNES on bits 4 and 5 of P1 ($FF00), the same bits that choose the button row (which still works as normal). A transfer starts by setting both bits to 0, which resets and starts the ICD2’s packet receiver. Data then goes least significant bit first: a 0 on bit 4 (with bit 5 high) is a 0 bit, and a 0 on bit 5 (with bit 4 high) is a 1 bit.
- Timing. The boot ROM and licensed software hold data and reset pulses low for at least 5 M-cycles and leave both bits high for at least 15 M-cycles after each pulse. The hardware can receive pulses and gaps as short as 2 M-cycles (tested with sgb-speedtest), but Pan Docs advises the usual 5 and 15 for reliability in corner cases nobody has found yet.
- Do not touch P1 in the middle of a transfer. A VBlank handler that reads the buttons every frame must be told not to.
- Wait 60 ms (4 frames) between one packet and the next. The “bomb” tool that erases a user-drawn border can stop the system software looking for packets for 4 frames.
Packet format
A packet is a start pulse, 16 bytes (128 bits) and a stop bit, a 0: 130 bit periods, at least 2600 M-cycles at the advised rate. The first packet of a command:
- one start pulse;
- one header byte: the command code × 8 + the length;
- 15 data bytes;
- one stop bit (0).
The length is the total number of packets, 1 to 7, counting the first. Further packets, if any, are a start pulse, 16 data bytes and a stop bit. Seven packets carry up to 15 + 16 × 6 = 111 data bytes. Bytes with no stated purpose are ignored by the system software; they may have any value but must still be sent.
VRAM transfers
Source: SGB_VRAM_Transfer.md.
Blocks of 4 KiB go to the SNES through the video signal. A command whose name ends in _TRN is sent first as an ordinary packet. The SNES then reads a 4 KiB block from the Game Boy display during the next frame. Pan Docs says the SNES puts the bits and bytes back in the same order as they were at $8000–$8FFF in Game Boy VRAM, so that is where the data should be.
- Preparing the display. The background map must show the tile numbers
$00–$FFin order on the screen:$00–$13on the first line,$14–$27on the next, and so on. The display must be on and not scrolled, objects must not overlap the background tiles, and BGP must be$E4. - Timing. Put the data in VRAM before sending the command packet. The transfer starts at the beginning of the next frame after the packet and ends at the end of the 5th frame after it (not counting the frame in which the packet was sent). The displayed data must not change meanwhile, since the SGB reads it in several chunks.
- Screen garbage. The display shows rubbish during the transfer. Freeze the screen with
MASK_ENfirst. That works only on an SGB, so detect the SGB before sending VRAM data blindly.
SNES palettes
Source: SGB_Color_Palettes.md.
- The SNES gives 8 palettes of 16 colours, each from 32768 colours. Palettes 0 to 3 colour the game screen (only the first 4 colours of each are used). Palettes 4 to 7 are for the border (all 16 colours).
- Format. 16-bit little-endian RGB: bits 4–0 red, 9–5 green, 14–10 blue, bit 15 ignored. The same as the Game Boy Color’s, but the same colour looks different on the SGB and on a Color because of the screen gamma. Pan Docs gives a formula from 24-bit RGB:
(c & $F8) << 7 | (c & $F800) >> 6 | (c & $F80000) >> 19. - Colour 0 is transparent in every palette, so the backdrop colour shows instead. The backdrop is normally the colour most recently given to colour 0, whichever palette that was for. So game palettes have three custom colours and border palettes 15, and colour 0 is shared by all.
- Grey to colour. The SNES reads the Game Boy picture and maps white, light grey, dark grey and black to palette colours 0, 1, 2 and 3. BGP, OBP0 and OBP1 choose which grey each Game Boy colour is, so there is no fixed link. Setting them to
$E4gives a direct 0–3 map. A black-background game can instead mark its background “white” on the Game Boy side (SNES colour 0, shared by all palettes), set colour 0 to black on the SNES side, and give colours 1 to 3 to each palette. - System colour palette memory. Up to 512 palettes of 4 colours can be kept in SNES RAM. They are not tied to the picture but can be copied to the visible palettes a bit faster than by sending palette packets (PAL_SET, PAL_TRN).
Command table
Source: SGB_Command_Summary.md. The header byte of a one-packet command is the code × 8 + 1.
| Code | Name | Does | Section |
|---|---|---|---|
$00 | PAL01 | Set SGB palettes 0 and 1 | palette commands |
$01 | PAL23 | Set SGB palettes 2 and 3 | palette commands |
$02 | PAL03 | Set SGB palettes 0 and 3 | palette commands |
$03 | PAL12 | Set SGB palettes 1 and 2 | palette commands |
$04 | ATTR_BLK | “Block” area designation mode | attribute commands |
$05 | ATTR_LIN | “Line” area designation mode | attribute commands |
$06 | ATTR_DIV | “Divide” area designation mode | attribute commands |
$07 | ATTR_CHR | “1CHR” area designation mode | attribute commands |
$08 | SOUND | Sound on/off | sound |
$09 | SOU_TRN | Transfer sound program or data | sound |
$0A | PAL_SET | Set SGB palettes indirectly | palette commands |
$0B | PAL_TRN | Set system colour palette data | palette commands |
$0C | ATRC_EN | Enable or disable attraction mode | system control |
$0D | TEST_EN | “Speed function” | removed |
$0E | ICON_EN | “SGB function” | system control |
$0F | DATA_SND | SNES WRAM transfer 1 | system control |
$10 | DATA_TRN | SNES WRAM transfer 2 | system control |
$11 | MLT_REQ | Multiple controllers request | multiplayer |
$12 | JUMP | Set the SNES program counter | system control |
$13 | CHR_TRN | Transfer character font data | border |
$14 | PCT_TRN | Set screen data colour data | border |
$15 | ATTR_TRN | Set attribute files from ATF data | attribute commands |
$16 | ATTR_SET | Apply an attribute file | attribute commands |
$17 | MASK_EN | Game Boy window mask | system control |
$18 | OBJ_TRN | SNES OBJ mode | removed |
$19 | PAL_PRI | System palette priority | palette commands |
Pan Docs’ explanation column reads “Speed function” for TEST_EN and “SGB function” for ICON_EN; those are its words and say little. Commands $1A to $1F are covered under undocumented commands.
Palette commands
Source: SGB_Command_Palettes.md.
PAL01, PAL23, PAL03, PAL12 ($00–$03)
One packet. It sends colour data for two palettes. The first palette’s colours 0 to 3 are sent; for the second, only colours 1 to 3, because colour 0 is shared (see the colour 0 rule above).
| Byte | Content |
|---|---|
| 0 | Header: $01 for PAL01, $09 for PAL23, $11 for PAL03, $19 for PAL12 |
| 1–2 | Colour 0, for both palettes |
| 3–4, 5–6, 7–8 | First palette: colours 1, 2, 3 |
| 9–10, 11–12, 13–14 | Second palette: colours 1, 2, 3 |
| 15 | unused |
The palette pairs are 0 and 1, 2 and 3, 0 and 3, and 1 and 2 respectively. Each colour is a little-endian 16-bit value.
PAL_SET ($0A)
Copies four predefined palettes from the system colour palettes to the visible SNES palettes. Before use, fill the system palettes with PAL_TRN and, if attribute files are used, with ATTR_TRN.
| Byte | Content |
|---|---|
| 0 | Header $51 ($0A × 8 + 1) |
| 1–2, 3–4, 5–6, 7–8 | System palette ID for SGB palettes 0, 1, 2 and 3, little-endian |
| 9 | Flags: bit 7 apply an attribute file (the one in bits 5–0, as if by ATTR_SET); bit 6 cancel any MASK_EN freeze; bits 5–0 attribute file number, which must not be above $2C |
| 10–15 | unused |
PAL_TRN ($0B)
Initialises the 512 system colour palettes in SNES RAM. They do not change the picture directly; PAL_SET later copies four of them to visible palettes, and OBJ_TRN would use groups of four as the 16-colour OBJ palettes. The packet is one byte, the header $59, with the rest unused. The data comes by a VRAM transfer: 4 KiB, 512 palettes × 4 colours × 2 bytes, palette 0 colour 0 first, up to palette 511 colour 3. Pan Docs notes the data lands at $3000–$3FFF in SNES memory.
PAL_PRI ($19)
If the player picks another palette set (a built-in one or the custom one) it stays until the smiley is chosen again or the X button is pressed on the SNES controller. If PAL_PRI is enabled, changing the palette set with any PAL_* command except PAL_TRN switches back to the game’s own set, if it was not already active. Pan Docs names Donkey Kong (1994) as a game that appears to use it. The header is $C9; byte 1 bit 0 turns PAL_PRI on (1) or off (0).
Colour attribute commands
Source: SGB_Command_Attribute.md. “Palette number” is one of the SGB palettes 0 to 3. Coordinates are in 8 × 8 character cells of the 20 × 18 game screen. All four “area” commands work on the screen’s attribute map; unused bytes at the end of the last packet are set to 0.
ATTR_BLK ($04)
Colour attributes inside, outside or on the border of one or more rectangles. Packet 1 has the header ($04 × 8 + length, length 1 to 7), then a count of data sets ($01–$12), then data sets of 6 bytes each, continued in the next packet when there are three or more.
| Data set byte | Content |
|---|---|
| 0 | Control code 0–7: bit 0 change colours inside the rectangle; bit 1 change the surrounding character line; bit 2 change colours outside. Bits 3–7 zero. Exception: if only the inside or only the outside is changed, the surrounding line changes to the same colour |
| 1 | Palette numbers: bits 1–0 inside, bits 3–2 the surrounding line, bits 5–4 outside; bits 7–6 zero |
| 2, 3 | X1 (left), Y1 (top) |
| 4, 5 | X2 (right), Y2 (bottom) of the surrounding rectangle |
ATTR_LIN ($05)
Colour for whole horizontal or vertical lines. Header (length 1 to 7), a count of data sets ($01–$6E), then one byte per set. More than 14 sets need further packets. A line runs from one edge of the screen to the other. Where lines overlap, later sets overwrite earlier ones.
Data set byte: bits 4–0 line number (an X or Y coordinate, by bit 7); bits 6–5 palette number 0–3; bit 7 mode, 0 = vertical line, 1 = horizontal line.
ATTR_DIV ($06)
Splits the screen in two and gives each half and the dividing line a palette. One packet.
| Byte | Content |
|---|---|
| 0 | Header, length fixed at 1 |
| 1 | Bits 1–0 palette below or right of the line; bits 3–2 above or left; bits 5–4 for the line itself; bit 6 mode: 0 = split left/right, 1 = split above/below |
| 2 | X or Y coordinate of the line, by the mode |
| 3–15 | unused (zero) |
ATTR_CHR ($07)
Colour for single characters. Header (length 1 to 6), then:
| Byte | Content |
|---|---|
| 1, 2 | Starting X and Y |
| 3–4 | Number of data sets, 1 to 360 |
| 5 | Writing style: 0 = left to right, 1 = top to bottom |
| 6 on | Data sets, 2 bits each, 4 to a byte, set 1 in the top bits and set 4 in the low bits. Each is the palette number of one character |
More than 40 sets continue in further packets. Writing wraps to the next row or column at the screen edge.
ATTR_TRN ($15)
Fills the attribute files (ATFs) in SNES RAM. Each ATF is 20 × 18 colour attributes for the game screen. It does not change the display. An ATF is later copied to the screen with ATTR_SET or PAL_SET. The packet is the header with length 1 and unused bytes. The data is a 4 KiB VRAM transfer: bytes $000–$FD1 hold ATF 0 to 44 (45 × 90 = 4050 bytes); $FD2–$FFF are unused. Each ATF is 90 bytes: 5 bytes (20 × 2 bits) for each of the 18 character lines. The top two bits of the first byte are the attribute (0 to 3) of the first character of the first line, the next two bits the next character, and so on.
ATTR_SET ($16)
Copies an attribute file to the game window. Byte 1 is the ATF number ($00–$2C), with bit 6 meaning “cancel mask”: the screen is switched on again afterwards if MASK_EN had frozen it. Bytes 2 to 15 are unused. The same functions are available in PAL_SET’s flag byte.
Sound commands
Source: SGB_Command_Sound.md.
SOUND ($08)
Starts or stops a built-in sound effect, or sound from built-in tone data. One packet.
| Byte | Content |
|---|---|
| 0 | Header, length 1 |
| 1 | Sound effect A (“port 1”, decrescendo), an 8-bit code |
| 2 | Sound effect B (“port 2”, sustained), an 8-bit code |
| 3 | Attributes: bits 1–0 effect A pitch (0 low to 3 high); bits 3–2 effect A volume (0 high to 2 low, 3 = mute on); bits 5–4 effect B pitch; bits 7–6 effect B volume (0 to 2, 3 not used) |
| 4 | Music score code (must be 0 if unused) |
| 5–15 | unused |
- Mute is active only when both bits 2 and 3 of byte 3 are 1.
- Setting a volume for effect A or B turns mute off.
- Mute on and off fade the sound out and in.
- Mute acts on the background music, which is produced by effect A, effect B and the SNES sound unit. There is no separate “mute off” flag. When the mute flag is set, the volume and pitch of A and B must also be set.
Effects A and B can run together. Effect A uses SNES sound channels 6 and 7. Effect B uses channels 0, 1, 4 and 5. An effect that needs fewer channels uses the upper ones (for example channels 4 and 5 for a two-channel effect B).
Sound effect A codes
Effect A is for “formanto” (percussion-type) sounds. Pitch is the recommended pitch setting; channels is the number used. The code $80 stops effect A.
| Code | Sound | Pitch | Channels |
|---|---|---|---|
| 00 | Dummy flag, retrigger | – | 2 |
| 01 | Nintendo | 3 | 1 |
| 02 | Game over | 3 | 2 |
| 03 | Drop | 3 | 1 |
| 04 | OK … A | 3 | 2 |
| 05 | OK … B | 3 | 2 |
| 06 | Select … A | 3 | 2 |
| 07 | Select … B | 3 | 1 |
| 08 | Select … C | 2 | 2 |
| 09 | Mistake … buzzer | 2 | 1 |
| 0A | Catch item | 2 | 2 |
| 0B | Gate squeaks once | 2 | 2 |
| 0C | Explosion, small | 1 | 2 |
| 0D | Explosion, medium | 1 | 2 |
| 0E | Explosion, large | 1 | 2 |
| 0F | Attacked … A | 3 | 1 |
| 10 | Attacked … B | 3 | 2 |
| 11 | Hit (punch) … A | 0 | 2 |
| 12 | Hit (punch) … B | 0 | 2 |
| 13 | Breath in air | 3 | 2 |
| 14 | Rocket projectile … A | 3 | 2 |
| 15 | Rocket projectile … B | 3 | 2 |
| 16 | Escaping bubble | 2 | 1 |
| 17 | Jump | 3 | 1 |
| 18 | Fast jump | 3 | 1 |
| 19 | Jet (rocket) take-off | 0 | 1 |
| 1A | Jet (rocket) landing | 0 | 1 |
| 1B | Cup breaking | 2 | 2 |
| 1C | Glass breaking | 1 | 2 |
| 1D | Level up | 2 | 2 |
| 1E | Insert air | 1 | 1 |
| 1F | Sword swing | 1 | 1 |
| 20 | Water falling | 2 | 1 |
| 21 | Fire | 1 | 1 |
| 22 | Wall collapsing | 1 | 2 |
| 23 | Cancel | 1 | 2 |
| 24 | Walking | 1 | 2 |
| 25 | Blocking strike | 1 | 2 |
| 26 | Picture floats on and off | 3 | 2 |
| 27 | Fade in | 0 | 2 |
| 28 | Fade out | 0 | 2 |
| 29 | Window being opened | 1 | 2 |
| 2A | Window being closed | 0 | 2 |
| 2B | Big laser | 3 | 2 |
| 2C | Stone gate closes or opens | 0 | 2 |
| 2D | Teleportation | 3 | 1 |
| 2E | Lightning | 0 | 2 |
| 2F | Earthquake | 0 | 2 |
| 30 | Small laser | 2 | 2 |
| 80 | Effect A stop, silent | – | 2 |
Sound effect B codes
Effect B is mainly for looping (sustained) sounds. The code $80 stops effect B.
| Code | Sound | Pitch | Channels |
|---|---|---|---|
| 00 | Dummy flag, retrigger | – | 4 |
| 01 | Applause, small group | 2 | 1 |
| 02 | Applause, medium group | 2 | 2 |
| 03 | Applause, large group | 2 | 4 |
| 04 | Wind | 1 | 2 |
| 05 | Rain | 1 | 1 |
| 06 | Storm | 1 | 3 |
| 07 | Storm with wind and thunder | 2 | 4 |
| 08 | Lightning | 0 | 2 |
| 09 | Earthquake | 0 | 2 |
| 0A | Avalanche | 0 | 2 |
| 0B | Wave | 0 | 1 |
| 0C | River | 3 | 2 |
| 0D | Waterfall | 2 | 2 |
| 0E | Small character running | 3 | 1 |
| 0F | Horse running | 3 | 1 |
| 10 | Warning sound | 1 | 1 |
| 11 | Approaching car | 0 | 1 |
| 12 | Jet flying | 1 | 1 |
| 13 | UFO flying | 2 | 1 |
| 14 | Electromagnetic waves | 0 | 1 |
| 15 | Score up | 3 | 1 |
| 16 | Fire | 2 | 1 |
| 17 | Camera shutter, formanto | 3 | 4 |
| 18 | Write, formanto | 0 | 1 |
| 19 | Show up title, formanto | 0 | 1 |
| 80 | Effect B stop, silent | – | 4 |
SOU_TRN ($09)
Sends sound code or data to the SNES sound unit’s memory (APU RAM). The packet is the header with length 1; the rest is unused. The data goes by VRAM transfer, as a continuous list of packets. All 16-bit values are little-endian.
- Data packet: bytes 0–1 the size N of the data below (if 0, it is a jump packet); bytes 2–3 the destination in APU RAM (typically
$2B00); then N bytes of data. - Jump packet: bytes 0–1 must be
$0000; bytes 2–3 the APU jump address. Pan Docs says$0400safely restarts the built-in SGB N-SPC sound engine.
| APU RAM range | Use |
|---|---|
$0400–$2AFF | Program area (9.75 KB) |
$2B00–$4AFF | Sound score area (8 KB) |
$4DB0–$EEFF | Sampling data area (40.25 KB) |
It can take over the SNES sound chip or reach the SNES MIDI engine, which needs deeper SNES sound knowledge.
System control commands
Source: SGB_Command_System.md.
MASK_EN ($17)
Masks the game window, for example to freeze the picture before a VRAM transfer, so the SNES keeps showing the game while VRAM holds data. Byte 1: 0 cancel the mask (display on), 1 freeze the current picture, 2 blank to black, 3 blank to colour 0. Bytes 2–15 unused. Freezing works only if the SNES has already stored a picture, so wait a frame or two after drawing it. The cancel can also be done by PAL_SET and ATTR_SET. The SGB freezes and unfreezes the screen by itself whenever the LCD is turned off or on.
ATRC_EN ($0C)
Enables (0, the default) or disables (1) attraction mode. Built-in borders other than the Game Boy frame and the plain black one have a screen saver that starts by pressing R, L, L, L, L, R, or after about 7 minutes with the controller untouched (tested with the 144p Test Suite). Pan Docs speculates that the animation may have interfered with rarely used features such as OBJ_TRN or JUMP, and that this command turns it off. Byte 1 is the flag.
ICON_EN ($0E)
Enables or disables the ICON function, possibly meant to switch off SGB or SNES pop-up menus during play. Everything is enabled (0) by default. Byte 1 is a set of disable bits: bit 0 use of the built-in colour palettes (1 = disable); bit 1 controller set-up screen (0 = enable, 1 = disable); bit 2 SGB register file transfer (0 = receive, 1 = disable); bits 3–6 unused. Setting bit 2 stops all further packets and commands. Pan Docs thinks that is useful when a monochrome game is started from the SGB menu of a multi-game cartridge.
DATA_SND ($0F)
Writes bytes straight into SNES work RAM. One packet only, so at most 11 bytes.
| Byte | Content |
|---|---|
| 0 | Header, length 1 |
| 1, 2, 3 | SNES destination address: low, high, bank |
| 4 | Number of bytes to write, $01–$0B |
| 5 on | The data bytes; unused bytes zero |
Free SNES memory, per Pan Docs: bank 0 $1800–$1FFF and bank $7F $0000–$FFFF.
DATA_TRN ($10)
Transfers code or data into SNES RAM. The packet carries the destination address (bytes 1–3: low, high, bank) and the rest is unused. The data is a 4 KiB VRAM transfer ($000–$FFF). Free memory as for DATA_SND. Pan Docs is unsure about two points, marked “???”: the transfer length is fixed at 4 KB, so writing straight to the free 2 KB at bank 0 $1800 is “not a so good idea”, in its words.
JUMP ($12)
Sets the SNES program counter and its NMI (VBlank interrupt) handler.
| Byte | Content |
|---|---|
| 0 | Header, length 1 |
| 1, 2, 3 | New SNES program counter: low, high, bank |
| 4, 5, 6 | New SNES NMI handler: low, high, bank |
| 7–15 | unused |
Pan Docs says Space Invaders uses it when “Arcade mode” is chosen, to run SNES code sent earlier. The SNES CPU is a Ricoh 5A22 with a 65C816 core. Pan Docs adds notes for programmers who want to use a flash cartridge in a Super Game Boy as a storage server: JUMP overwrites the NMI handler even when it is $000000; the system software does not seem to use NMIs; a JUMP target can return to the system software with a 16-bit RTS by a JML to a location in bank 0 that holds the byte $60 (for example any of the stubbed commands); IRQs, COP and BRK are no use because their handlers point into SGB ROM (use SEI WAI); a program that does not return may overwrite all SNES RAM except $0000BB–$0000BD, the NMI vector; and writing $FE to $2140 enters the APU boot ROM, with echo still on.
Multiplayer
Source: SGB_Command_Multiplayer.md.
MLT_REQ ($11)
Asks for input from more than one joypad. Because it gives the Game Boy feedback, it also detects an SGB. Byte 1 (bits 0–1): 0 one player, 1 two players, 3 four players (bit 0 enables, bit 1 selects two or four). Bytes 2–15 unused. In one-player mode the second pad, if any, is used by the SGB system software only. In two-player mode both pads are for the game. The SNES has two pad sockets, so four players need an external “Multiplayer 5” adapter.
Changing the number of players ANDs (current player − 1) with (players − 1). For example, from four players to two while player 4 was active, player 2 becomes active, because 3 AND 1 = 1. The command itself increments the counter several times, so the result may not be as expected. The most frequent case, one player to two or four, always starts with player 1.
Reading several joypads
- Set P14 and P15 (bits 4 and 5 of P1) both high, deselecting both rows. The low four bits of P1 now give the ID of the next joypad:
$xFplayer 1,$xEplayer 2,$xDplayer 3,$xCplayer 4. - Read the joypad state normally. The next pad is selected automatically when P15 goes from low to high (Pan Docs cites a test ROM by CasualPokePlayer for this), so repeat the read until all two or four pads are read.
Border commands
Source: SGB_Command_Border.md.
CHR_TRN ($13)
Sends tile data (“characters”) to the SNES tile memory, normally the border’s background tiles (see PCT_TRN), perhaps also movable SNES sprites. Byte 1: bit 0 which tiles (0 = $00–$7F, 1 = $80–$FF); bit 1 type (0 background, 1 object); bits 2–7 zero. Bytes 2–15 unused. The data is a 4 KiB VRAM transfer holding the bitmaps of 128 tiles. To send more than 128 tiles, call it twice. Pan Docs notes (with “???”) that the background/object bit seems to have no effect and to write to the same VRAM addresses for both.
Each tile is 32 bytes (8 × 8 pixels, 16 colours), 4 bits per pixel: bit planes 0 and 1 interleaved by row, followed by bit planes 2 and 3 interleaved by row. So a tile is two Game Boy tiles: the first gives bits 0–1 (a colour among 0–3 within a four-colour sub-palette), the second bits 2–3 (which group: 0–3, 4–7, 8–11 or 12–15).
PCT_TRN ($14)
Sends the border’s tile map and palettes to SNES memory. The tiles themselves come from CHR_TRN. The packet is the header with length 1 and unused bytes. The 4 KiB data:
| Offset | Content |
|---|---|
$000–$6FF | Background map, 32 × 28 entries of 16 bits (1792 bytes) |
$700–$73F | One extra row of 32 entries (64 bytes), see below |
$740–$7FF | unused |
$800–$85F | Background palettes 4 to 6, 16 little-endian colours each |
$860–$FFF | unused |
A map entry is VH01 PP00 NNNN NNNN: bits 0–9 character number (use $00–$FF only, upper two bits zero); bits 10–12 palette number (use 4 to 6 only); bit 13 priority (use 0); bit 14 X flip; bit 15 Y flip.
- The 32 × 28 entries cover the 256 × 224 pixels of the SNES screen. The 20 × 18 entries in the middle should be a blank tile (solid colour 0), a transparent window for the game. Border data there would cover the game (Mario’s Picross does this, WildSnake to a lesser extent).
- A border for a widescreen television (made after 2006) can use the middle 256 × 176 pixels and leave the top and bottom 24 lines blank, which lets the visible part of a zoomed picture have more variety.
- Border tiles repeat. With a blank tile for the game window and a solid one for any letterbox, a border with all unique tiles needs (256 × 224 − 160 × 144) ÷ 64 + 1 = 537 tiles full-screen, or (256 × 176 − 160 × 144) ÷ 64 + 2 = 346 letterboxed. The SGB’s character RAM for the border holds only 256, so a full-screen border repeats at least 281 and a letterboxed one at least 90.
- Flicker row. Part of a 29th row of the border map can be visible. The system software sets the border layer’s vertical scroll to 0. The SNES shows lines BGxVOFS + 1 to + 224, so the first scanline of the top tile row is hidden and one scanline of the nominally invisible 29th row appears at the bottom. Mostly the SGB hides it by forced blanking, but while it is busy with some packets (fading the border palette, loading a new scene’s palette and attributes), it does not, so the line can flicker on some televisions, even with some built-in borders. To prevent it, add a row of all-black tile entries after the last row (
$8700–$873Fin the VRAM of a PCT_TRN, which is the extra row above), or at least tiles whose top pixel row is blank. Otherwise repeat the last scanline: copy the bottom row (at$86C0–$86FF) into the extra row, flipped vertically (XOR with$8000). - SNES palettes in use. Observed in a low-level emulator (Mesen 2): the system software uses background palette 0 for the game screen, palettes 1, 2, 3 and 7 for menus, and palettes 4, 5 and 6 for the border. A border can therefore use three 15-colour palettes.
Removed commands
Source: SGB_Command_Prototype.md. These do nothing on any retail SGB revision. The descriptions apply to some prototype units only.
OBJ_TRN ($18)
Starts the transfer of object attributes to the SNES OAM. Unlike every other _TRN command it does not use the one-time 4 KiB VRAM transfer. When enabled, data is read continuously, every frame, from the bottom character line of the Game Boy screen. The bottom line is masked so the garbage does not show, and only the upper 20 × 17 characters are used; Pan Docs does not know how the masking is done (frozen, black, or hidden by the border, “???”). Attraction mode does not run while it is on.
| Byte | Content |
|---|---|
| 0 | Header, length 1 |
| 1 | Bit 0 SNES OBJ mode (0 cancel, 1 enable); bit 1 change OBJ colours (0 no, 1 use the numbers below); bits 2–7 zero |
| 2–3, 4–5, 6–7, 8–9 | System colour palette number (0–511) for OBJ palettes 4, 5, 6 and 7, ignored if bit 1 is 0. Each OBJ palette has 16 colours, so four system palettes of 4 are used; the numbers need not be a multiple of four and wrap to 0 past 511 (511 copies palettes 511, 0, 1, 2) |
| 10–15 | unused |
The advised method: “display” Game Boy background tiles $F9–$FF, left to right, as the first seven characters of the bottom character line, not scrolled, not covered by objects, with BGP set properly. SNES OAM data then lives in $70 bytes of the tile memory: $8F90–$8FEF 24 entries of 4 bytes (96 bytes); $8FF0–$8FF5 the high bits, 24 entries of 2 bits (6 bytes); $8FF6–$8FFF unused (10 bytes). The entry format is the SNES PPU’s (Pan Docs points to Fullsnes), with X and Y swapped compared with the Game Boy and byte 3 shifted left by one bit:
| Byte | Content |
|---|---|
| 0 | X position 0–511 (the top bit is stored separately) |
| 1 | Y position 0–255 |
| 2 | Tile number |
| 3 | Bit 7 Y flip; bit 6 X flip; bits 5–4 priority relative to the background (use only 3 on the SGB); bits 3–1 palette number (4 to 7); bit 0 tile page (use only 0) |
Each byte of the high-bit area packs two bits for each of four objects. Bit 0 is the upper bit of object 0’s X coordinate and bit 1 is its size (0 small, 1 large). Bits 2 and 3 are the same pair for object 1, bits 4 and 5 for object 2, and bits 6 and 7 for object 3. In each pair the X bit is the lower bit and the size the higher.
TEST_EN ($0D)
Enables (1) or disables (0, the default) a test mode for the “SGB-CPU variable clock speed function”. Byte 1 is the flag; bytes 2–15 are unused. Pan Docs guesses (“???”) that it may have been meant to find out whether the SNES runs at 50 or 60 Hz, with the result perhaps readable from the joypad register.
Undocumented commands
Source: SGB_Command_Undocumented.md. The information comes from a disassembly of an SGB1 v2 firmware and “should be verified on other SGB revisions”. The firmware explicitly ignores all commands with ID $1E or above. That leaves the undocumented commands $1A to $1D. The handlers of commands $1A to $1F are stubs that contain only an RTS, which is odd since the command processing explicitly ignores $1E and $1F.
Sources
- Raw Pan Docs Markdown (CC0), read 2026-11-19, in
samples/gb/sources/pandocswith SHA-256 in the sample README:SGB_Functions.md,SGB_Unlocking.md,SGB_Command_Packet.md,SGB_VRAM_Transfer.md,SGB_Color_Palettes.md,SGB_Command_Summary.md,SGB_Command_Palettes.md,SGB_Command_Attribute.md,SGB_Command_Sound.md,SGB_Command_System.md,SGB_Command_Multiplayer.md,SGB_Command_Border.md,SGB_Command_Prototype.md,SGB_Command_Undocumented.md. - Super Game Boy – Pan Docs
Not described
Known, not yet covered
- Pan Docs’ drawing of the packet bit timing (an image) is not reproduced; its rules are in the text.
Unknown
- The points Pan Docs marks “???”: the masking method of OBJ_TRN, the effect of the background/object bit of CHR_TRN, the safe use of the free 2 KB in DATA_TRN, and what TEST_EN is for. Also undocumented commands
$1A–$1Don revisions other than the SGB1 v2 that was disassembled.