shithub: rgbds

ref: 29d2fc6ebc4611728f750b28089a67b80483334a
dir: /src/fix/rgbfix.1/

View raw version
.\"
.\" This file is part of RGBDS.
.\"
.\" Copyright (c) 2010-2017, Anthony J. Bentley and RGBDS contributors.
.\"
.\" SPDX-License-Identifier: MIT
.\"
.Dd March 11, 2018
.Dt RGBFIX 1
.Os RGBDS Manual
.Sh NAME
.Nm rgbfix
.Nd Game Boy checksum fixer
.Sh SYNOPSIS
.Nm rgbfix
.Op Fl CcjsVv
.Op Fl f Ar fix_spec
.Op Fl i Ar game_id
.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 f 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 i Ar game_id
Set the game ID string
.Pq Ad 0x13F Ns \(en Ns Ad 0x142
to a given string of exactly 4 characters.
If both this and the title are set, the game ID will overwrite the
overlapping portion of the title.
.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 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 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
.Po Fl c
or
.Fl C
.Pc .
If both this and the game ID are set, the game ID will overwrite the
overlapping portion of the title.
.It Fl V
Print the version of the program and exit.
.It Fl v
Equivalent to
.Fl f Cm lhg .
.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
.Pq Do valid Dc 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
.Dq foobar ,
and pad it to a multiple of 32KiB.
.Po
The Game Boy itself does not use the title, but some emulators or ROM managers
might.
.Pc
.Pp
.D1 $ rgbfix -vcs -l 0x33 -p 0 -t foobar baz.gb
.Pp
The following will duplicate the header
.Pq sans global checksum
of the game
.Dq Survival Kids :
.Pp
.D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
SurvivalKids.gbc
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,
.Xr rgbds 7
.Sh HISTORY
.Nm
was originally released by Carsten S\(/orensen as a standalone program called
gbfix, and was later packaged in RGBDS by Justin Lloyd. It is now maintained by
a number of contributors at
.Lk https://github.com/rednex/rgbds .