mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 10:12:06 +00:00
346 lines
10 KiB
Groff
346 lines
10 KiB
Groff
.\" 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 hjsVvw
|
|
.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
|
|
.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 file
|
|
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 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-obsolete
|
|
Warn when obsolete features are encountered, which have been deprecated and may later be removed.
|
|
.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 .
|