1RGBFIX(1)                 BSD General Commands Manual                RGBFIX(1)
2

NAME

4     rgbfix — Game Boy header utility and checksum fixer
5

SYNOPSIS

7     rgbfix [-jsVv] [-C | -c] [-f fix_spec] [-i game_id] [-k licensee_str]
8            [-l licensee_id] [-m mbc_type] [-n rom_version] [-p pad_value]
9            [-r ram_size] [-t title_str] [file ...]
10

DESCRIPTION

12     The rgbfix program changes headers of Game Boy ROM images, typically gen‐
13     erated by rgblink(1), though it will work with any Game Boy ROM.  It also
14     performs other correctness operations, such as padding.  rgbfix only
15     changes the fields for which it has values specified.  Developers are ad‐
16     vised to fill those fields with 0x00 bytes in their source code before
17     running rgbfix, and to have already populated whichever fields they don't
18     specify using rgbfix.
19
20     Note that options can be abbreviated as long as the abbreviation is unam‐
21     biguous: --color-o is --color-only, but --color is invalid because it
22     could also be --color-compatible.  Options later in the command line
23     override those set earlier.  Accepted options are as follows:
24
25     -C, --color-only
26             Set the Game Boy Color–only flag (0x143) to 0xC0.  This overrides
27             -c if it was set prior.
28
29     -c, --color-compatible
30             Set the Game Boy Color–compatible flag: (0x143) to 0x80.  This
31             overrides -c if it was set prior.
32
33     -f fix_spec, --fix-spec fix_spec
34             Fix certain header values that the Game Boy checks for correct‐
35             ness.  Alternatively, intentionally trash these values by writing
36             their binary inverse instead.  fix_spec is a string containing
37             any combination of the following characters:
38
39             l   Fix the Nintendo logo (0x1040x133).
40             L   Trash the Nintendo logo.
41             h   Fix the header checksum (0x14D).
42             H   Trash the header checksum.
43             g   Fix the global checksum (0x14E0x14F).
44             G   Trash the global checksum.
45
46     -i game_id, --game-id game_id
47             Set the game ID string (0x13F0x142) to a given string.  If it's
48             longer than 4 chars, it will be truncated, and a warning emitted.
49
50     -j, --non-japanese
51             Set the non-Japanese region flag (0x14A) to 0x01.
52
53     -k licensee_str, --new-licensee licensee_str
54             Set the new licensee string (0x1440x145) to a given string.  If
55             it's longer than 2 chars, it will be truncated, and a warning
56             emitted.
57
58     -l licensee_id, --old-licensee licensee_id
59             Set the old licensee code (0x14B) to a given value from 0 to
60             0xFF.  This value is deprecated and should be set to 0x33 in all
61             new software.
62
63     -m mbc_type, --mbc-type mbc_type
64             Set the MBC type (0x147) to a given value from 0 to 0xFF.
65
66             This value may also be an MBC name.  The list of accepted names
67             can be obtained by passing "help" as the argument.  Any amount of
68             whitespace (space and tabs) is allowed around plus signs, and the
69             order of "components" is free, as long as the MBC name is first.
70             There are special considerations to take for the TPP1 mapper; see
71             the TPP1 section below.
72
73     -n rom_version, --rom-version rom_version
74             Set the ROM version (0x14C) to a given value from 0 to 0xFF.
75
76     -p pad_value, --pad-value pad_value
77             Pad the ROM image to a valid size with a given pad value from 0
78             to 255 (0xFF).  rgbfix will automatically pick a size from 32
79             KiB, 64 KiB, 128 KiB, ..., 8192 KiB.  The cartridge size byte
80             (0x148) will be changed to reflect this new size.  The recom‐
81             mended padding value is 0xFF, to speed up writing the ROM to
82             flash chips, and to avoid "nop slides" into VRAM.
83
84     -r ram_size, --ram-size ram_size
85             Set the RAM size (0x149) to a given value from 0 to 0xFF.
86
87     -s, --sgb-compatible
88             Set the SGB flag (0x146) to 0x03.  This flag will be ignored by
89             the SGB unless the old licensee code is 0x33!  If this is given
90             as well as -l, but is not set to 0x33, a warning will be printed.
91
92     -t title, --title title
93             Set the title string (0x1340x143) to a given string.  If the ti‐
94             tle is longer than the max length, it will be truncated, and a
95             warning emitted.  The max length is 11 characters if the game ID
96             (-i) is specified, 15 characters if the CGB flag (-c or -C) is
97             specified but the game ID is not, and 16 characters otherwise.
98
99     -V, --version
100             Print the version of the program and exit.
101
102     -v, --validate
103             Equivalent to -f lhg.
104

EXAMPLES

106     Most values in the ROM header do not matter to the actual console, and
107     most are seldom useful anyway.  The bare minimum requirements for a work‐
108     able program are the header checksum, the Nintendo logo, and (if needed)
109     the CGB/SGB flags.  It is a good idea to pad the image to a valid size as
110     well (“valid” meaning a power of 2, times 32 KiB).
111
112     The following will make a plain, non-color Game Boy game without checking
113     for a valid size:
114
115           $ rgbfix -v foo.gb
116
117     The following will make a SGB-enabled, color-enabled game with a title of
118     “foobar”, and pad it to a valid size.  (The Game Boy itself does not use
119     the title, but some emulators or ROM managers do.)
120
121           $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
122
123     The following will duplicate the header of the game “Survival Kids”, sans
124     global checksum:
125
126           $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t
127           SURVIVALKIDAVKE SurvivalKids.gbc
128

TPP1

130     TPP1 is a homebrew mapper designed as a functional superset of the common
131     traditional MBCs, allowing larger ROM and RAM sizes combined with other
132     hardware features.  Its specification, as well as more resources, can be
133     found online at https://github.com/TwitchPlaysPokemon/tpp1
134
135   MBC name
136     The MBC name for TPP1 is more complex than standard mappers.  It must be
137     followed with the revision number, of the form ‘major.minor’, where both
138     ‘major’ and ‘minor’ are decimal, 8-bit integers.  There may be any amount
139     of spaces or underscores between ‘TPP1’ and the revision number.  rgbfix
140     only supports 1.x revisions, and will reject everything else.
141
142     Like other mappers, the name may be followed with a list of optional,
143     ‘+’-separated features; however, ‘RAM’ should not be specified, as the
144     TPP1 mapper implicitly requests RAM if a non-zero RAM size is specified.
145     Therefore, rgbfix will ignore the ‘RAM’ feature on a TPP1 mapper with a
146     warning.
147
148   Special considerations
149     TPP1 overwrites the byte at 0x14A, usually indicating the region destina‐
150     tion (see -j), with one of its three identification bytes.  Therefore,
151     rgbfix will warn about and ignore -j if used in combination with TPP1.
152

BUGS

154     Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
155

SEE ALSO

157     rgbasm(1), rgblink(1), rgbds(7)
158

HISTORY

160     rgbfix was originally released by Carsten Sørensen as a standalone pro‐
161     gram called gbfix, and was later packaged in RGBDS by Justin Lloyd.  It
162     is now maintained by a number of contributors at
163     https://github.com/gbdev/rgbds
164
165BSD                             March 28, 2021                             BSD
Impressum