GBX v1.0

a Game Boy / Game Boy Color ROM image format

by taizou (web / email / twitter)

Spec v1.0 finalised: 22nd February 2018 / Document revision 2: 28th May 2023

1. Background

As of early 2018, the current and only standard for Game Boy and Game Boy Color ROM images (.GB/.GBC) was simply a raw binary dump of the cartridge ROM.

Game Boy emulators therefore base cartridge type detection largely on the internal ROM header. In licensed games, this is always populated per Nintendo's specs. But in unlicensed games, it often isn't. Likewise for some licensed special carts, notably multicarts.

Until now, emulators have had to rely on heuristics to work out if they're dealing with something non-standard. This was workable when only a few such cartridges had been dumped and emulated, but now many more have been discovered (numbering in at least the low hundreds), with more unique mappers and copy protection schemes, it's becoming increasingly unwieldy.

Even when a game in actuality uses a standard mapper, when the internal header is incorrect, the only way to make most emulators recognise it is to hack that header, thus destroying the integrity of the original data.

GBX is a fairly simple file format which aims to solve this problem by allowing this information to be specified somewhere outside of the ROM data itself.

2. File format

A GBX ROM image file consists of the following:

  1. ROM data (any size)
  2. Footer (currently 64 bytes)

File extension: .gbx

GBX is intended to be fairly unintrusive and low-overhead, since it'll most likely be a niche proposition at this late stage in Game Boy emulation, especially given that plain binary dumps are satisfactory for almost all licensed releases.

Specifically, a footer was chosen instead of a header because:

The intention is that this format will be used only where required. In other words, if the game is licensed and the internal header is correct, a plain binary is still perfectly adequate - there'd be little benefit in mass-updating licensed ROM sets to use GBX.

3. Footer

The footer defines any cartridge metadata required for emulation.

Offset from end of ROM data (hex) Use Type/value More info
Cartridge information
00-03 Mapper identifier Any string of up to 4 bytes No strict limitations on what a mapper identifier can be, but something readable in ASCII is recommended.
If the identifier is less than 4 bytes, the remaining bytes should be 00.
See section 4 below for an initial set of mapper identifiers.
04 Battery flag 00 = not present 01 = present
05 Rumble flag 00 = not present 01 = present
06 Timer flag 00 = not present 01 = present
07 Not used
08-0B ROM size in bytes 32-bit unsigned big-endian integer Any number may be specified here, but it's reasonable for an emulator to reject a size that is not valid for the specified mapper.
0C-0F RAM size in bytes 32-bit unsigned big-endian integer As above
10-2F Eight mapper specific variables 8 x 32-bit anything May be used in any way by a mapper that requires some further information to be specified e.g. if it has some configurable features or component that may or may not be present.
GBX metadata
30-33 Footer size in bytes 32-bit unsigned big-endian integer.
For this version it should be 40 hex / 64 decimal.
34-37 Major version number 32-bit unsigned big-endian integer.
For this version it should be 1.
This number will only be increased if a change introduces a backwards incompatibility.
e.g. if a program supports v1.x and it finds a 2 here, it should probably reject the file.
38-3B Minor version number 32-bit unsigned big-endian integer.
For this version it should be 0.
Minor versions should always be backwards compatible. A size change should not qualify as a backwards incompatibility.
3C-3F Signature GBX! in ASCII

The "GBX metadata" section - the values at 30-3F in this version - will always be placed at the end of the footer block in future versions, meaning you can always read the last 4 bytes of a file to determine if it's GBX format, and the preceding 12 to determine if it's a supported version and how big the footer is.

Note the footer is not intended to store metadata about the game itself, such as title, release date or publisher, whether it has Super Game Boy or Game Boy Color support, etc.

Revision as of 26th March 2018

The original version of this spec released on 22nd February 2018 mistakenly specified all numbers should be little-endian. However my intent, reflected in the provided example as well as initially released emulators and ROMs, was that these numbers should be big-endian.

I've updated the spec to reflect this but decided not to increase the version number, as the original wording was an error and contradicts itself.

Layout

MMMM FFFF RRRR SSSS  MMMM = mapper, FFFF = flags, RRRR = romsize, SSSS = ramsize
1111 2222 3333 4444  mapper-specific variables
5555 6666 7777 8888  mapper-specific variables
SSSS MMMM VVVV GBX!  SSSS = footer size, MMMM = major version, VVVV = minor version, GBX! = signature

Valid example (hex)

4D 42 43 35  01 01 00 00  00 10 00 00  00 00 20 00  MBC5, ram+rumble, 1M ROM, 8K RAM
00 00 00 00  00 00 00 00  00 00 00 00  00 00 00 00  empty mapper-specific variables
00 00 00 00  00 00 00 00  00 00 00 00  00 00 00 00  empty mapper-specific variables
00 00 00 40  00 00 00 01  00 00 00 00  47 42 58 21  64 byte footer, minor v1, major v0, signature

4. Mapper identifiers

This is NOT an exhaustive list of mappers, just a list of those known and supported at the time of this document's creation.

An up to date list of mappers will be maintained here for now.

Note the term "mapper" here is used in the NES emulation sense, e.g., any circuitry onboard the cartridge controlling mapping of ROM & RAM and potentially other components such as a rumble motor or tilt sensor. Game Boy cartridges usually contain a custom ASIC (commonly known as "MBC" after the five standard Nintendo chips) for this purpose.

Identifier Name
Nintendo
ROM ROM only
MBC1 Nintendo MBC1
MBC2 Nintendo MBC2
MBC3 Nintendo MBC3
MBC5 Nintendo MBC5
MBC7 Nintendo MBC7 (Tilt sensor cart)
MB1M Nintendo MBC1 multicart
MMM1 Nintendo/Mani MMM01
CAMR Nintendo Game Boy Camera (Pocket Camera)
Licensed 3rd-party
HUC1 Hudson HuC1
HUC3 Hudson HuC3
TAM5 Bandai TAMA5
Unlicensed
BBD BBD
HITK Hitek
SNTX Sintax
NTO1 NT older type 1
NTO2 NT older type 2
NTN NT newer
LICH Li Cheng
LBMC "Last Bible" multicart
LIBA Liebao Technology

Document revisions

The following revisions have been made to correct errors in this document without affecting the spec:

  1. 26th March 2018 - Fixed numbers mistakenly specified as being little-endian instead of big-endian
  2. 28th May 2023 - Fixed example footer annotation mistakenly referring to "64k" instead of "64 bytes"

🦁