1RGBFIX(1) BSD General Commands Manual RGBFIX(1)
2
4 rgbfix — Game Boy header utility and checksum fixer
5
7 rgbfix [-jOsVv] [-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
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 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 -C, --color-only
26 Set the Game Boy Color–only flag (0x143) to 0xC0. This overrides
27 -c if it was set prior.
28 -c, --color-compatible
30 Set the Game Boy Color–compatible flag: (0x143) to 0x80. This
31 overrides -c if it was set prior.
32 -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 l Fix the Nintendo logo (0x104–0x133).
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 (0x14E–0x14F).
44 G Trash the global checksum.
45 -i game_id, --game-id game_id
47 Set the game ID string (0x13F–0x142) to a given string. If it's
48 longer than 4 chars, it will be truncated, and a warning emitted.
49 -j, --non-japanese
51 Set the non-Japanese region flag (0x14A) to 0x01.
52 -k licensee_str, --new-licensee licensee_str
54 Set the new licensee string (0x144–0x145) to a given string. If
55 it's longer than 2 chars, it will be truncated, and a warning
56 emitted.
57 -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 -m mbc_type, --mbc-type mbc_type
64 Set the MBC type (0x147) to a given value from 0 to 0xFF.
65 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 -n rom_version, --rom-version rom_version
74 Set the ROM version (0x14C) to a given value from 0 to 0xFF.
75 -O, --overwrite
77 Allow overwriting different non-zero bytes in the header without
78 a warning being emitted.
79 -p pad_value, --pad-value pad_value
81 Pad the ROM image to a valid size with a given pad value from 0
82 to 255 (0xFF). rgbfix will automatically pick a size from 32
83 KiB, 64 KiB, 128 KiB, ..., 8192 KiB. The cartridge size byte
84 (0x148) will be changed to reflect this new size. The recom‐
85 mended padding value is 0xFF, to speed up writing the ROM to
86 flash chips, and to avoid "nop slides" into VRAM.
87 -r ram_size, --ram-size ram_size
89 Set the RAM size (0x149) to a given value from 0 to 0xFF.
90 -s, --sgb-compatible
92 Set the SGB flag (0x146) to 0x03. This flag will be ignored by
93 the SGB unless the old licensee code is 0x33! If this is given
94 as well as -l, but is not set to 0x33, a warning will be printed.
95 -t title, --title title
97 Set the title string (0x134–0x143) to a given string. If the ti‐
98 tle is longer than the max length, it will be truncated, and a
99 warning emitted. The max length is 11 characters if the game ID
100 (-i) is specified, 15 characters if the CGB flag (-c or -C) is
101 specified but the game ID is not, and 16 characters otherwise.
102 -V, --version
104 Print the version of the program and exit.
105 -v, --validate
107 Equivalent to -f lhg.
108
110 Most values in the ROM header do not matter to the actual console, and
111 most are seldom useful anyway. The bare minimum requirements for a work‐
112 able program are the header checksum, the Nintendo logo, and (if needed)
113 the CGB/SGB flags. It is a good idea to pad the image to a valid size as
114 well (“valid” meaning a power of 2, times 32 KiB).
115 The following will make a plain, non-color Game Boy game without checking
117 for a valid size:
118 $ rgbfix -v foo.gb
120 The following will make a SGB-enabled, color-enabled game with a title of
122 “foobar”, and pad it to a valid size. (The Game Boy itself does not use
123 the title, but some emulators or ROM managers do.)
124 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
126 The following will duplicate the header of the game “Survival Kids”, sans
128 global checksum:
129 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t
131 SURVIVALKIDAVKE SurvivalKids.gbc
132
134 TPP1 is a homebrew mapper designed as a functional superset of the common
135 traditional MBCs, allowing larger ROM and RAM sizes combined with other
136 hardware features. Its specification, as well as more resources, can be
137 found online at https://github.com/aaaaaa123456789/tpp1
138 MBC name
140 The MBC name for TPP1 is more complex than standard mappers. It must be
141 followed with the revision number, of the form ‘major.minor’, where both
142 ‘major’ and ‘minor’ are decimal, 8-bit integers. There may be any amount
143 of spaces or underscores between ‘TPP1’ and the revision number. rgbfix
144 only supports 1.x revisions, and will reject everything else.
145 Like other mappers, the name may be followed with a list of optional,
147 ‘+’-separated features; however, ‘RAM’ should not be specified, as the
148 TPP1 mapper implicitly requests RAM if a non-zero RAM size is specified.
149 Therefore, rgbfix will ignore the ‘RAM’ feature on a TPP1 mapper with a
150 warning.
151 Special considerations
153 TPP1 overwrites the byte at 0x14A, usually indicating the region destina‐
154 tion (see -j), with one of its three identification bytes. Therefore,
155 rgbfix will warn about and ignore -j if used in combination with TPP1.
156
158 Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
159
161 rgbasm(1), rgblink(1), rgbds(7)
162
164 rgbfix was originally released by Carsten Sørensen as a standalone pro‐
165 gram called gbfix, and was later packaged in RGBDS by Justin Lloyd. It
166 is now maintained by a number of contributors at
167 https://github.com/gbdev/rgbds
168BSD March 28, 2021 BSD