1RGBFIX(1) BSD General Commands Manual RGBFIX(1)
2
4 rgbfix — Game Boy header utility and checksum fixer
5
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
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 -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 -r ram_size, --ram-size ram_size
85 Set the RAM size (0x149) to a given value from 0 to 0xFF.
86 -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 -t title, --title title
93 Set the title string (0x134–0x143) 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 -V, --version
100 Print the version of the program and exit.
101 -v, --validate
103 Equivalent to -f lhg.
104
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 The following will make a plain, non-color Game Boy game without checking
113 for a valid size:
114 $ rgbfix -v foo.gb
116 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 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
122 The following will duplicate the header of the game “Survival Kids”, sans
124 global checksum:
125 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t
127 SURVIVALKIDAVKE SurvivalKids.gbc
128
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 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 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 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
154 Please report bugs on GitHub: https://github.com/gbdev/rgbds/issues
155
157 rgbasm(1), rgblink(1), rgbds(7)
158
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
164BSD March 28, 2021 BSD