Nintendo - Game Boy / Color (Gambatte)¶

Background¶

Gambatte is an accuracy-focused, open-source, cross-platform Game Boy Color emulator written in C++. It is based on hundreds of corner case hardware tests, as well as previous documentation and reverse engineering efforts.

The Gambatte core has been authored by

Sinamas

The Gambatte core is licensed under

GPLv2

A summary of the licenses behind RetroArch and its cores can be found here.

BIOS¶

Required or optional firmware files go in the frontend's system directory.

Attention

The 'Use official bootloader' core option must be set to On in order for these BIOS files to be used.

Filename	Description	md5sum
gb_bios.bin	Game Boy BIOS - Optional	32fbbd84168d3482956eb3c5051637f5
gbc_bios.bin	Game Boy Color BIOS - Optional	dbfce9db9deaa2567f6a84fde55f9680

Extensions¶

Content that can be loaded by the Gambatte core have the following file extensions:

.gb
.gbc
.dmg

RetroArch database(s) that are associated with the Gambatte core:

Features¶

Frontend-level settings or features that the Gambatte core respects.

Feature	Supported
Restart	✔
Saves	✔
States	✔
Rewind	✔
Netplay	✕
Core Options	✔
RetroAchievements	✔
RetroArch Cheats	✔
Native Cheats	✕
Controls	✔
Remapping	✔
Multi-Mouse	✕
Rumble	✕
Sensors	✕
Camera	✕
Location	✕
Subsystem	✕
Softpatching	✔
Disk Control	✕
Username	✕
Language	✕
Crop Overscan	✕
LEDs	✕

Directories¶

The Gambatte core's library name is 'Gambatte'

The Gambatte core saves/loads to/from these directories.

Frontend's Save directory

File	Description
*.srm	Cartridge battery save

Frontend's State directory

File	Description
*.state#	State

***Frontend's System directory**

File	Description
palettes/default.pal	Global custom palette
palettes/'content-name'.pal	Per-game custom palette

Geometry and timing¶

The Gambatte core's core provided FPS is 59.7275005696
The Gambatte core's core provided sample rate is [Sample rate]
The Gambatte core's base width is [Base width]
The Gambatte core's base height is [Base height]
The Gambatte core's max width is [Max width]
The Gambatte core's max height is [Max height]
The Gambatte core's core provided aspect ratio is [Aspect ratio]

Custom palettes for Game Boy games¶

The 'GB Colorization' core option must be set to custom.

Create a folder called "palettes" in RetroArch's system directory. Then, you can place custom palette files (.pal) inside the "palettes" folder

You can define different palettes for specific games by creating a .pal file in the "palettes" folder with 'INTERNALROMNAME.pal' or "rom-name.pal". If no specific palette is found for a ROM then the default palette is used.

You can also define a palette to be used for all Game Boy games by creating a .pal file in the "palettes" folder named "default.pal"

Custom palettes can be created from the GUI in standalone Gambatte

Core options¶

The Gambatte core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded.

Settings with (Restart) means that core has to be closed for the new setting to be applied on next launch.

Allow Opposing Directions [gambatte_up_down_allowed] (disabled/enabled)

Enabling this will allow pressing / quickly alternating / holding both left and right (or up and down in some games) directions at the same time.

This may cause movement based glitches to occur in certain games.

It's best to keep this core option disabled.
GB Colorization [gambatte_gb_colorization] (disabled|auto|GBC|SGB|internal|custom)

Enables colorization of Game Boy games, using pre-defined or user-selected color palettes.

'auto': Selects automatically the 'best' (most colorful/appropriate) palette for each individual game, using the following order of preference:
1. Game-specific Super Game Boy palette, if defined and more colorful than game-specific Game Boy Color palette.
2. Game-specific Game Boy Color palette, if defined.
3. Game-specific Super Game Boy palette, if defined.
4. Palette specified by 'Internal Palette' core option.
'GBC': Selects game-specific Game Boy Color palette, if defined. If not, falls back to the Game Boy Color hardware default palette of 'GBC - Dark Green'.

'SGB': Selects game-specific Super Game Boy palette, if defined. If not, falls back to the Super Game Boy hardware default palette of 'SGB - 1A'.

'internal': Selects palette specified by 'Internal Palette' core option.

'custom': Loads user-created palettes from RetroArch's system directory, as described in the 'Custom palettes for Game Boy games' section.

GB Colorization: Off

GB Colorization: auto (in this case, a game-specific SGB palette is auto-selected)

GB Colorization: GBC

Internal Palette [gambatte_gb_internal_palette] (GB - DMG|GB - Pocket|GB - Light|GBC - Blue|GBC - Brown|GBC - Dark Blue|GBC - Dark Brown|GBC - Dark Green|GBC - Grayscale|GBC - Green|GBC - Inverted|GBC - Orange|GBC - Pastel Mix|GBC - Red|GBC - Yellow|SGB - 1A|SGB - 1B|SGB - 1C|SGB - 1D|SGB - 1E|SGB - 1F|SGB - 1G|SGB - 1H|SGB - 2A|SGB - 2B|SGB - 2C|SGB - 2D|SGB - 2E|SGB - 2F|SGB - 2G|SGB - 2H|SGB - 3A|SGB - 3B|SGB - 3C|SGB - 3D|SGB - 3E|SGB - 3F|SGB - 3G|SGB - 3H|SGB - 4A|SGB - 4B|SGB - 4C|SGB - 4D|SGB - 4E|SGB - 4F|SGB - 4G|SGB - 4H|Special 1|Special 2|Special 3)

Selects the internal color palette to use for colorizing Game Boy games when the 'GB Colorization' core option is set to 'internal', or when the 'GB Colorization' core option is set to 'auto' and a game has no pre-defined Super Game Boy/Game Boy Color palette.

'GB' palettes mimic the display characteristics of original Game Boy hardware.

'GBC' palettes are identical to those used by original Game Boy Color hardware when colorizing Game Boy games.

'SGB' palettes are identical to those used by original Super Game Boy hardware when colorizing Game Boy games.

Internal Palette: GB - DMG

Internal Palette: GB - Pocket

Internal Palette: GB - Light

Internal Palette: GBC - Blue

Internal Palette: GBC - Brown

Internal Palette: GBC - Dark Blue

Internal Palette: GBC - Dark Brown

Internal Palette: GBC - Dark Green

Internal Palette: GBC - Grayscale

Internal Palette: GBC - Green

Internal Palette: GBC - Inverted

Internal Palette: GBC - Orange

Internal Palette: GBC - Pastel Mix

Internal Palette: GBC - Red

Internal Palette: GBC - Yellow

Internal Palette: SGB - 1A

Internal Palette: SGB - 1B

Internal Palette: SGB - 1C

Internal Palette: SGB - 1D

Internal Palette: SGB - 1E

Internal Palette: SGB - 1F

Internal Palette: SGB - 1G

Internal Palette: SGB - 1H

Internal Palette: SGB - 2A

Internal Palette: SGB - 2B

Internal Palette: SGB - 2C

Internal Palette: SGB - 2D

Internal Palette: SGB - 2E

Internal Palette: SGB - 2F

Internal Palette: SGB - 2G

Internal Palette: SGB - 2H

Internal Palette: SGB - 3A

Internal Palette: SGB - 3B

Internal Palette: SGB - 3C

Internal Palette: SGB - 3D

Internal Palette: SGB - 3E

Internal Palette: SGB - 3F

Internal Palette: SGB - 3G

Internal Palette: SGB - 3H

Internal Palette: SGB - 4A

Internal Palette: SGB - 4B

Internal Palette: SGB - 4C

Internal Palette: SGB - 4D

Internal Palette: SGB - 4E

Internal Palette: SGB - 4F

Internal Palette: SGB - 4G

Internal Palette: SGB - 4H

Internal Palette: Special 1

Internal Palette: Special 2

Internal Palette: Special 3

Color correction [gambatte_gbc_color_correction] (GBC only|always|disabled)

Enables adjustment of output colors to match the display characteristics of the LCD panel used in original Game Boy Color hardware.

'GBC only': Color correction is only applied when playing Game Boy Color games, or when using a Game Boy Color palette to colorize a Game Boy game.

'always': Color correction is always applied, regardless of which color palette is being used.

Attention

Setting this option to 'always' will result in unexpected/suboptimal output when using 'GB' or 'SGB' internal color palettes, since these are intended for display on a normal TV/monitor rather than a Game Boy Color LCD panel.

Color correction mode [gambatte_gbc_color_correction_mode] (accurate|fast)

Specifies the method to use when performing color correction.

'accurate': Provides a very close approximation of the image displayed on a real Game Boy Color LCD panel.

'fast': Darkens colors in a loose approximation of the image displayed on a real Game Boy Color LCD panel. Has negligible performance impact, and may be used on low-end hardware in cases where the 'accurate' method is too slow.

Color correction: Off

Color correction: fast

Color correction: accurate

Color correction - frontlight position [gambatte_gbc_frontlight_position] (central|above screen|below screen)

Simulates the physical response of the Game Boy Color LCD panel when illuminated from different angles.

'central': Standard color reproduction, corresponding to ambient light hitting the screen at 90°.

'above screen': Increases brightness (gamma), corresponding to sunlight or a ceiling light shining on the screen from above.

'below screen': Reduces brightness (gamma), corresponding to light shining on the screen from below.

Attention

This setting only takes effect when 'Color correction mode' is set to 'accurate'.

Color correction - frontlight position: central

Color correction - frontlight position: above screen

Color correction - frontlight position: below screen

Dark Filter Level (percent) [gambatte_dark_filter_level] (0|5|10|15|20|25|30|35|40|45|50)

Enables selective brightness reduction based upon pixel luminosity. May be used to reduce glare/eye strain. Of particular value when playing games with white backgrounds, which are intended for display on a non-backlit Game Boy Color LCD panel and appear uncomfortably bright when viewed on a modern backlit screen.

Dark Filter Level: 0%

Dark Filter Level: 30%

Emulated hardware (restart) [gambatte_gb_hwmode] (Auto|GB|GBC|GBA)

Choose which hardware is emulated Game Boy, Game Boy Color, or Game Boy Advance.
Use official bootloader (restart) [gambatte_gb_bootloader] (enabled|disabled)

Enables support for using official Game Boy and Game Boy Color bootloaders with startup logos. Check the BIOS section to see what files are needed.

Game Boy bootloader

Game Boy Color bootloader

Mix frames [gambatte_mix_frames] (disabled|accurate|fast)

Enables simulation of LCD ghosting effects by blending the current and previous frames.

'accurate': Blends pixel RGB values with floating point precision.

'fast': Blends pixel RGB values using fast bit manipulation. Causes slight color darkening/shifting (due to rounding errors). May be used on low-end hardware in cases where the 'accurate' method is too slow.

Attention

A number of games generate transparency effects (or additional shades of color) by drawing objects on alternate frames, relying on the LCD ghosting of original hardware to 'smooth out' the result. Notable examples are Wave Race, Ballistic and Chikyuu Kaihou Gun ZAS. In order for these games to render correctly, 'Mix frames' must be set to 'accurate' or 'fast'. More importantly, the rapid flickering that is produced by these games when 'Mix frames' is disabled can lead to a form of screen burn-in on certain types of LCD panel (that of the 3DS in particular).

Mix frames: Off

Mix frames: accurate

Mix frames: fast

GameBoy Link Mode - New config options

Core Option	Description
gambatte_gb_link_mode	Not Connected / Network Server / Network Client
gambatte_gb_link_network_port	56400 to 56420 in increments of 1. 56400 is default
gambatte_show_gb_link_settings	enabled / disabled
gambatte_gb_link_network_server_ip_1	(client only) 0 to 9, 1^st digit of ipv4 address, (eg. 1)
gambatte_gb_link_network_server_ip_2	(client only) 0 to 9, 2^nd digit of ipv4 address, (eg. 9)
gambatte_gb_link_network_server_ip_3	(client only) 0 to 9, 3^rd digit of ipv4 address, (eg. 2)
gambatte_gb_link_network_server_ip_4	(client only) 0 to 9, 4^th digit of ipv4 address, (eg. 1)
gambatte_gb_link_network_server_ip_5	(client only) 0 to 9, 5^th digit of ipv4 address, (eg. 6)
gambatte_gb_link_network_server_ip_6	(client only) 0 to 9, 6^th digit of ipv4 address, (eg. 8)
gambatte_gb_link_network_server_ip_7	(client only) 0 to 9, 7^th digit of ipv4 address, (eg. 0)
gambatte_gb_link_network_server_ip_8	(client only) 0 to 9, 8^th digit of ipv4 address, (eg. 0)
gambatte_gb_link_network_server_ip_9	(client only) 0 to 9, 9^th digit of ipv4 address, (eg. 1)
gambatte_gb_link_network_server_ip_10	(client only) 0 to 9, 10^th digit of ipv4 address, (eg. 0)
gambatte_gb_link_network_server_ip_11	(client only) 0 to 9, 11^th digit of ipv4 address, (eg. 0)
gambatte_gb_link_network_server_ip_12	(client only) 0 to 9, 12^th digit of ipv4 address, (eg. 1)

GameBoy Link Mode - Old config options

Core Option	Description, values
gambatte_gb_link_mode	Mode, Not Connected / Network Server / Network Client
gambatte_gb_link_network_port	Network link port, 56400 to 56420 in increments of 1. 56400 is default
gambatte_gb_link_network_server_ip_octet1	(client only) Network link server address part 1, (0 to 255 in increments of 1. 0 is default.)
gambatte_gb_link_network_server_ip_octet2	(client only) Network link server address part 2, (0 to 255 in increments of 1. 0 is default.)
gambatte_gb_link_network_server_ip_octet3	(client only) Network link server address part 3, (0 to 255 in increments of 1. 0 is default.)
gambatte_gb_link_network_server_ip_octet4	(client only) Network link server address part 4, (0 to 255 in increments of 1. 0 is default.)

Joypad¶

RetroPad Inputs	User 1 input descriptors
	B
	Select
	Start
	D-Pad Up
	D-Pad Down
	D-Pad Left
	D-Pad Right
	A

Compatibility¶

Game	Issue
Command Master	Crashes on start. Unemulated MBC7 mapper.
Game Boy Camera	Crashes on start. Unemulated Pocket Camera mapper.
Game de Hakken!! Tamagotchi - Osutchi to Mesutchi	Crashes on start. Unemulated TAMA5 mapper.
Kirby Tilt 'n' Tumble	Crashes on start. Unemulated MBC7 mapper.
Net de Get: Mini-Game @ 100	Crashes on start. Unemulated MBC6 mapper.

External Links¶

Nintendo - Game Boy (+ Color)¶

Last update: 2023-03-16