rgbds/man/rgbfix.1

.\" SPDX-License-Identifier: MIT
.\"
.Dd July 31, 2025
.Dt RGBFIX 1
.Os
.Sh NAME
.Nm rgbfix
.Nd Game Boy header utility and checksum fixer
.Sh SYNOPSIS
.Nm
.Op Fl hjOsVvw
.Op Fl C | c
.Op Fl \-color Ar when
.Op Fl f Ar fix_spec
.Op Fl i Ar game_id
.Op Fl k Ar licensee_str
.Op Fl L Ar logo_file
.Op Fl l Ar licensee_id
.Op Fl m Ar mbc_type
.Op Fl n Ar rom_version
.Op Fl o Ar out_file
.Op Fl p Ar pad_value
.Op Fl r Ar ram_size
.Op Fl t Ar title_str
.Op Fl W Ar warning
.Op Ar
.Sh DESCRIPTION
The
.Nm
program changes headers of Game Boy ROM images, typically generated by
.Xr rgblink 1 ,
though it will work with
.Em any
Game Boy ROM.
It also performs other correctness operations, such as padding.
.Nm
only changes the fields for which it has values specified.
Developers are advised to fill those fields with 0x00 bytes in their source code before running
.Nm ,
and to have already populated whichever fields they don't specify using
.Nm .
.Pp
The input
.Ar asmfile
can be a path to a file, or
.Cm \-
to read from standard input.
.Pp
Note that options can be abbreviated as long as the abbreviation is unambiguous:
.Fl \-verb
is
.Fl \-verbose ,
but
.Fl \-ver
is invalid because it could also be
.Fl \-version .
Options later in the command line override those set earlier.
Accepted options are as follows:
.Bl -tag -width Ds
.It Fl C , Fl \-color-only
Set the Game Boy Color\(enonly flag
.Pq Ad 0x143
to 0xC0.
This overrides
.Fl c
if it was set prior.
.It Fl c , Fl \-color-compatible
Set the Game Boy Color\(encompatible flag:
.Pq Ad 0x143
to 0x80.
This overrides
.Fl c
if it was set prior.
.It Fl \-color Ar when
Specify when to highlight warning and error messages with color:
.Ql always ,
.Ql never ,
or
.Ql auto .
.Ql auto
determines whether to use colors based on the
.Ql Lk https://no-color.org/ NO_COLOR
or
.Ql Lk https://force-color.org/ FORCE_COLOR
environment variables, or whether the output is to a TTY.
.It Fl f Ar fix_spec , Fl \-fix-spec Ar fix_spec
Fix certain header values that the Game Boy checks for correctness.
Alternatively, intentionally trash these values by writing their binary inverse instead.
.Ar fix_spec
is a string containing any combination of the following characters:
.Pp
.Bl -tag -compact -width xx
.It Cm l
Fix the Nintendo logo
.Pq Ad 0x104 Ns \(en Ns Ad 0x133 .
.It Cm L
Trash the Nintendo logo.
.It Cm h
Fix the header checksum
.Pq Ad 0x14D .
.It Cm H
Trash the header checksum.
.It Cm g
Fix the global checksum
.Pq Ad 0x14E Ns \(en Ns Ad 0x14F .
.It Cm G
Trash the global checksum.
.El
.It Fl h , Fl \-help
Print help text for the program and exit.
.It Fl i Ar game_id , Fl \-game-id Ar game_id
Set the game ID string
.Pq Ad 0x13F Ns \(en Ns Ad 0x142
to a given string.
If it's longer than 4 characters, it will be truncated.
.It Fl j , Fl \-non-japanese
Set the non-Japanese region flag
.Pq Ad 0x14A
to 0x01.
.It Fl k Ar licensee_str , Fl \-new-licensee Ar licensee_str
Set the new licensee string
.Pq Ad 0x144 Ns \(en Ns Ad 0x145
to a given string.
If it's longer than 2 characters, it will be truncated.
.It Fl L Ar logo_file , Fl \-logo Ar logo_file
Specify a logo file to use instead of the official Nintendo logo.
The file must be 48 bytes of 1bpp tile data; the source image should be 48 pixels wide and 8 pixels tall.
.It Fl l Ar licensee_id , Fl \-old-licensee Ar licensee_id
Set the old licensee code
.Pq Ad 0x14B
to a given value from 0 to 0xFF.
This value is deprecated and should be set to 0x33 in all new software.
.It Fl m Ar mbc_type , Fl \-mbc-type Ar mbc_type
Set the MBC type
.Pq Ad 0x147
to a given value from 0 to 0xFF.
.Pp
This value may also be an MBC name.
The list of accepted names can be obtained by passing
.Ql Cm help
or
.Ql Cm list
as the argument.
Any amount of whitespace (space and tabs) is allowed around plus signs, and the order of "components" is free, as long as the MBC name is first.
There are special considerations to take for the TPP1 mapper; see the
.Sx TPP1
section below.
.It Fl n Ar rom_version , Fl \-rom-version Ar rom_version
Set the ROM version
.Pq Ad 0x14C
to a given value from 0 to 0xFF.
.It Fl O , Fl \-overwrite
Alias for
.Fl Wno-overwrite .
.It Fl o Ar out_file , Fl \-output Ar out_file
Write the modified ROM image to the given file, or '-' to write to standard output.
If not specified, the input files are modified in-place, or written to standard output if read from standard input.
.It Fl p Ar pad_value , Fl \-pad-value Ar pad_value
Pad the ROM image to a valid size with a given pad value from 0 to 255 (0xFF).
.Nm
will automatically pick a size from 32 KiB, 64 KiB, 128 KiB, ..., 8192 KiB.
The cartridge size byte
.Pq Ad 0x148
will be changed to reflect this new size.
The recommended padding value is 0xFF, to speed up writing the ROM to flash chips, and to avoid "nop slides" into VRAM.
.It Fl r Ar ram_size , Fl \-ram-size Ar ram_size
Set the RAM size
.Pq Ad 0x149
to a given value from 0 to 0xFF.
.It Fl s , Fl \-sgb-compatible
Set the SGB flag
.Pq Ad 0x146
to 0x03.
This flag will be ignored by the SGB unless the old licensee code
.Pq Fl l
is 0x33!
.It Fl t Ar title , Fl \-title Ar title
Set the title string
.Pq Ad 0x134 Ns \(en Ns Ad 0x143
to a given string.
If the title is longer than the maximum length, it will be truncated.
The max length is 11 characters if the game ID
.Pq Fl i
is specified, 15 characters if the CGB flag
.Fl ( c
or
.Fl C )
is specified but the game ID is not, and 16 characters otherwise.
.It Fl V , Fl \-version
Print the version of the program and exit.
.It Fl v , Fl \-validate
Equivalent to
.Fl f Cm lhg .
.It Fl W Ar warning , Fl \-warning Ar warning
Set warning flag
.Ar warning .
A warning message will be printed if
.Ar warning
is an unknown warning flag.
See the
.Sx DIAGNOSTICS
section for a list of warnings.
.It Fl w
Disable all warning output, even when turned into errors.
.El
.Sh DIAGNOSTICS
Warnings are diagnostic messages that indicate possibly erroneous behavior that does not necessarily compromise the header-fixing process.
The following options alter the way warnings are processed.
.Bl -tag -width Ds
.It Fl Werror
Make all warnings into errors.
This can be negated as
.Fl Wno-error
to prevent turning all warnings into errors.
.It Fl Werror=
Make the specified warning or meta warning into an error.
A warning's name is appended
.Pq example: Fl Werror=overwrite ,
and this warning is implicitly enabled and turned into an error.
This can be negated as
.Fl Wno-error=
to prevent turning a specified warning into an error, even if
.Fl Werror
is in effect.
.El
.Pp
The following warnings are
.Dq meta
warnings, that enable a collection of other warnings.
If a specific warning is toggled via a meta flag and a specific one, the more specific one takes priority.
The position on the command-line acts as a tie breaker, the last one taking effect.
.Bl -tag -width Ds
.It Fl Wall
This enables warnings that are likely to indicate an error or undesired behavior, and that can easily be fixed.
.It Fl Weverything
Enables literally every warning.
.El
.Pp
The following warnings are actual warning flags; with each description, the corresponding warning flag is included.
Note that each of these flag also has a negation (for example,
.Fl Wtruncation
enables the warning that
.Fl Wno-truncation
disables; and
.Fl Wall
enables every warning that
.Fl Wno-all
disables).
Only the non-default flag is listed here.
Ignoring the
.Dq no-
prefix, entries are listed alphabetically.
.Bl -tag -width Ds
.It Fl Wno-mbc
Warn when there are inconsistencies with or caveats about the specified MBC type.
.It Fl Wno-overwrite
Warn when overwriting different non-zero bytes in the header.
.It Fl Wno-sgb
Warn when the SGB flag
.Pq Fl s
conflicts with the old licensee code
.Pq Fl l .
.It Fl Wno-truncation
Warn when truncating values to fit the available space.
.El
.Sh EXAMPLES
Most values in the ROM header do not matter to the actual console, and most are seldom useful anyway.
The bare minimum requirements for a workable program are the header checksum, the Nintendo logo, and (if needed) the CGB/SGB flags.
It is a good idea to pad the image to a valid size as well
.Pq Do valid Dc meaning a power of 2, times 32 KiB .
.Pp
The following will make a plain, non-color Game Boy game without checking for
a valid size:
.Pp
.D1 $ rgbfix -v foo.gb
.Pp
The following will make a SGB-enabled, color-enabled game with a title of
.Dq foobar ,
and pad it to a valid size.
.Pq The Game Boy itself does not use the title, but some emulators or ROM managers do.
.Pp
.D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
.Pp
The following will duplicate the header of the game
.Dq Survival Kids ,
sans global checksum:
.Pp
.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
SurvivalKids.gbc
.Sh TPP1
TPP1 is a homebrew mapper designed as a functional superset of the common traditional MBCs, allowing larger ROM and RAM sizes combined with other hardware features.
Its specification, as well as more resources, can be found online at
.Lk https://github.com/aaaaaa123456789/tpp1 .
.Ss MBC name
The MBC name for TPP1 is more complex than standard mappers.
It must be followed with the revision number, of the form
.Ql major.minor ,
where both
.Ql major
and
.Ql minor
are decimal, 8-bit integers.
There may be any amount of spaces or underscores between
.Ql TPP1
and the revision number.
.Nm
only supports 1.x revisions, and will reject everything else.
.Pp
Like other mappers, the name may be followed with a list of optional,
.Ql + Ns
-separated features; however,
.Ql RAM
should not be specified, as the TPP1 mapper implicitly requests RAM if a non-zero RAM size is specified.
Therefore,
.Nm
will ignore the
.Ql RAM
feature on a TPP1 mapper.
.Ss Special considerations
TPP1 overwrites the byte at
.Ad 0x14A ,
usually indicating the region destination
.Pq see Fl j ,
with one of its three identification bytes.
Therefore,
.Nm
will warn about and ignore
.Fl j
if used in combination with TPP1.
.Sh BUGS
Please report bugs or mistakes in this documentation on
.Lk https://github.com/gbdev/rgbds/issues GitHub .
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbgfx 1 ,
.Xr gbz80 7 ,
.Xr rgbds 7
.Sh HISTORY
.Nm
was originally written by
.An Carsten S\(/orensen
as a standalone program called GBFix, which was then packaged in ASMotor, and was later repackaged in RGBDS by
.An Justin Lloyd .
It is now maintained by a number of contributors at
.Lk https://github.com/gbdev/rgbds .