ref: abf8f8255abe5834bb5dde880fcc1b64aa045381
dir: /src/fix/rgbfix.1/
.Dd $Mdocdate$
.Dt RGBFIX 1
.Os RGBDS Manual
.Sh NAME
.Nm rgbfix
.Nd Game Boy checksum fixer
.Sh SYNOPSIS
.Nm rgbfix
.Op Fl Ccjsv
.Op Fl k Ar licensee_str
.Op Fl l Ar licensee_id
.Op Fl m Ar mbc_type
.Op Fl n Ar rom_version
.Op Fl p Ar pad_value
.Op Fl r Ar ram_size
.Op Fl t Ar title_str
.Ar file
.Sh DESCRIPTION
The
.Nm
program changes headers of Game Boy ROM images.
It also performs other filetype operations, such as truncation.
The arguments are as follows:
.Bl -tag -width Ds
.It Fl C
Set the Game Boy Color\(enonly flag:
.Ad 0x143
= 0xC0.
If both this and the
.Fl c
flag are set, this takes precedence.
.It Fl c
Set the Game Boy Color\(encompatible flag:
.Ad 0x143
= 0x80.
If both this and the
.Fl C
flag are set,
.Fl C
takes precedence.
.It Fl j
Set the non-Japanese region flag:
.Ad 0x14A
= 1.
.It Fl k Ar licensee_str
Set the new licensee string
.Pq Ad 0x144 No Ns \(en Ns Ad 0x145
to a given string, truncated to at most two characters.
.It Fl l Ar licensee_id
Set the old licensee code,
.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
Set the MBC type,
.Ad 0x147 ,
to a given value from 0 to 0xFF.
.It Fl n Ar rom_version
Set the ROM version,
.Ad 0x14C ,
to a given value from 0 to 0xFF.
.It Fl p Ar pad_value
Pad the image to a valid size with a given pad value from 0 to 0xFF.
.Nm
will automatically pick a size from 32KiB, 64KiB, 128KiB, ..., 8192KiB and
give a warning thereafter.
The cartridge size byte
.Pq Ad 0x148
will be changed to reflect this new size.
.It Fl r Ar ram_size
Set the RAM size,
.Ad 0x149 ,
to a given value from 0 to 0xFF.
.It Fl s
Set the SGB flag:
.Ad 0x146
= 3.
.It Fl t Ar title
Set the title string
.Pq Ad 0x134 No Ns \(en Ns Ad 0x143
to a given string, truncated to at most 16 characters.
It is recommended to use 15 characters instead, to avoid clashing with the CGB
flag
.Pq Fl c No or Fl C .
.It Fl v
Validate the header and fix checksums: the Nintendo character area
.Pq Ad 0x104 No Ns \(en Ns Ad 0x133 ,
the header checksum
.Pq Ad 0x14D ,
and the global checksum
.Pq Ad 0x14E No Ns \(en Ns Ad 0x14F .
.El
.Sh EXAMPLES
Most values in the ROM header are only cosmetic.
The bare minimum requirements for a workable image are checksums, 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 ("valid" meaning a
multiple of 32KiB).
.Pp
The following will make a plain, no-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
"foobar", and pad it to a multiple of 32KiB.
(The Game Boy itself does not use the title, but some emulators or ROM managers
might.)
.Pp
.D1 $ rgbfix \-vcs \-p 0 \-t foobar baz.gb
.Pp
The following will duplicate the header (sans global checksum) of the game
"Survival Kids":
.Pp
.D1 $ rgbfix \-cjsv \-k A4 \-m 0x1B \-p 0xFF \-r 3 \-t SURVIVALKIDAVKE SurvivalKids.gbc
.Sh SEE ALSO
.Xr rgbds 7 ,
.Xr rgbasm 1 ,
.Xr rgblib 1 ,
.Xr rgblink 1 ,
.Xr gbz80 7
.Sh HISTORY
.Nm
was originally released by Carsten S\(/orensen as a standalone program called
gbfix.
It was later integrated with the ASMotor package, which became RGBDS.