shithub: rgbds

ref: 8c765883fb21e117ee32a6602a4fe3c2f9657feb
dir: /docs/rgbfix.1.html/

View raw version
<!DOCTYPE html>
<html>
<!-- This is an automatically generated file.  Do not edit.
   This file is part of RGBDS.
  
   Copyright (c) 2010-2017, Anthony J. Bentley and RGBDS contributors.
  
   SPDX-License-Identifier: MIT
   -->
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta charset="utf-8"/>
  <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
  <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
  <title>RGBFIX(1)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">RGBFIX(1)</td>
    <td class="head-vol">General Commands Manual</td>
    <td class="head-rtitle">RGBFIX(1)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<code class="Nm">rgbfix</code> &#x2014;
<span class="Nd">Game Boy header utility and checksum fixer</span>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<table class="Nm">
  <tr>
    <td><code class="Nm">rgbfix</code></td>
    <td>[<code class="Fl"><a href="#j">-j</a><a href="#s">s</a><a href="#V">V</a><a href="#v">v</a></code>] [<code class="Fl"><a href="#C">-C</a></code> |
      <code class="Fl"><a href="#c">-c</a></code>] [<code class="Fl"><a href="#f">-f</a></code>
      <var class="Ar">fix_spec</var>] [<code class="Fl"><a href="#i">-i</a></code>
      <var class="Ar">game_id</var>] [<code class="Fl"><a href="#k">-k</a></code>
      <var class="Ar">licensee_str</var>] [<code class="Fl"><a href="#l">-l</a></code>
      <var class="Ar">licensee_id</var>] [<code class="Fl"><a href="#m">-m</a></code>
      <var class="Ar">mbc_type</var>] [<code class="Fl"><a href="#n">-n</a></code>
      <var class="Ar">rom_version</var>] [<code class="Fl"><a href="#p">-p</a></code>
      <var class="Ar">pad_value</var>] [<code class="Fl"><a href="#r">-r</a></code>
      <var class="Ar">ram_size</var>] [<code class="Fl"><a href="#t">-t</a></code>
      <var class="Ar">title_str</var>] <var class="Ar">file</var></td>
  </tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
The <code class="Nm">rgbfix</code> program changes headers of Game Boy ROM
  images. It also performs other correctness operations, such as padding.
<p class="Pp">Note that options can be abbreviated as long as the abbreviation
    is unambiguous: <code class="Fl">--verb</code> is
    <code class="Fl">--verbose</code>, but
    <code class="Fl">--ver</code> is invalid because it
    could also be <code class="Fl">--version</code>. The
    arguments are as follows:</p>
<dl class="Bl-tag">
  <dt><a class="permalink" href="#C"><code class="Fl" id="C">-C</code></a>,
    <code class="Fl">--color-only</code></dt>
  <dd>Set the Game Boy Color&#x2013;only flag: <span class="Ad">0x143</span> =
      0xC0. If both this and the <code class="Fl">-c</code> flag are set, this
      takes precedence.</dd>
  <dt><a class="permalink" href="#c"><code class="Fl" id="c">-c</code></a>,
    <code class="Fl">--color-compatible</code></dt>
  <dd>Set the Game Boy Color&#x2013;compatible flag:
      <span class="Ad">0x143</span> = 0x80. If both this and the
      <code class="Fl">-C</code> flag are set, <code class="Fl">-C</code> takes
      precedence.</dd>
  <dt><a class="permalink" href="#f"><code class="Fl" id="f">-f</code></a>
    <var class="Ar">fix_spec</var>,
    <code class="Fl">--fix-spec</code>
    <var class="Ar">fix_spec</var></dt>
  <dd>Fix certain header values that the Game Boy checks for correctness.
      Alternatively, intentionally trash these values by writing their binary
      inverse instead. <var class="Ar">fix_spec</var> is a string containing any
      combination of the following characters:
    <p class="Pp"></p>
    <dl class="Bl-tag Bl-compact">
      <dt><a class="permalink" href="#l"><code class="Cm" id="l">l</code></a></dt>
      <dd>Fix the Nintendo logo
          (<span class="Ad">0x104</span>&#x2013;<span class="Ad">0x133</span>).</dd>
      <dt><a class="permalink" href="#L"><code class="Cm" id="L">L</code></a></dt>
      <dd>Trash the Nintendo logo.</dd>
      <dt><a class="permalink" href="#h"><code class="Cm" id="h">h</code></a></dt>
      <dd>Fix the header checksum (<span class="Ad">0x14D</span>).</dd>
      <dt><a class="permalink" href="#H"><code class="Cm" id="H">H</code></a></dt>
      <dd>Trash the header checksum.</dd>
      <dt><a class="permalink" href="#g"><code class="Cm" id="g">g</code></a></dt>
      <dd>Fix the global checksum
          (<span class="Ad">0x14E</span>&#x2013;<span class="Ad">0x14F</span>).</dd>
      <dt><a class="permalink" href="#G"><code class="Cm" id="G">G</code></a></dt>
      <dd>Trash the global checksum.</dd>
    </dl>
  </dd>
  <dt><a class="permalink" href="#i"><code class="Fl" id="i">-i</code></a>
    <var class="Ar">game_id</var>,
    <code class="Fl">--game-id</code>
    <var class="Ar">game_id</var></dt>
  <dd>Set the game ID string
      (<span class="Ad">0x13F</span>&#x2013;<span class="Ad">0x142</span>) 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.</dd>
  <dt><a class="permalink" href="#j"><code class="Fl" id="j">-j</code></a>,
    <code class="Fl">--non-japanese</code></dt>
  <dd>Set the non-Japanese region flag: <span class="Ad">0x14A</span> = 1.</dd>
  <dt><a class="permalink" href="#k"><code class="Fl" id="k">-k</code></a>
    <var class="Ar">licensee_str</var>,
    <code class="Fl">--new-licensee</code>
    <var class="Ar">licensee_str</var></dt>
  <dd>Set the new licensee string
      (<span class="Ad">0x144</span>&#x2013;<span class="Ad">0x145</span>) to a
      given string, truncated to at most two characters.</dd>
  <dt><a class="permalink" href="#l_2"><code class="Fl" id="l_2">-l</code></a>
    <var class="Ar">licensee_id</var>,
    <code class="Fl">--old-licensee</code>
    <var class="Ar">licensee_id</var></dt>
  <dd>Set the old licensee code, <span class="Ad">0x14B</span>, to a given value
      from 0 to 0xFF. This value is deprecated and should be set to 0x33 in all
      new software.</dd>
  <dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a>
    <var class="Ar">mbc_type</var>,
    <code class="Fl">--mbc-type</code>
    <var class="Ar">mbc_type</var></dt>
  <dd>Set the MBC type, <span class="Ad">0x147</span>, to a given value from 0
      to 0xFF.</dd>
  <dt><a class="permalink" href="#n"><code class="Fl" id="n">-n</code></a>
    <var class="Ar">rom_version</var>,
    <code class="Fl">--rom-version</code>
    <var class="Ar">rom_version</var></dt>
  <dd>Set the ROM version, <span class="Ad">0x14C</span>, to a given value from
      0 to 0xFF.</dd>
  <dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
    <var class="Ar">pad_value</var>,
    <code class="Fl">--pad-value</code>
    <var class="Ar">pad_value</var></dt>
  <dd>Pad the image to a valid size with a given pad value from 0 to 0xFF.
      <code class="Nm">rgbfix</code> will automatically pick a size from 32 KiB,
      64 KiB, 128 KiB, ..., 8192 KiB. The cartridge size byte
      (<span class="Ad">0x148</span>) will be changed to reflect this new
    size.</dd>
  <dt><a class="permalink" href="#r"><code class="Fl" id="r">-r</code></a>
    <var class="Ar">ram_size</var>,
    <code class="Fl">--ram-size</code>
    <var class="Ar">ram_size</var></dt>
  <dd>Set the RAM size, <span class="Ad">0x149</span>, to a given value from 0
      to 0xFF.</dd>
  <dt><a class="permalink" href="#s"><code class="Fl" id="s">-s</code></a>,
    <code class="Fl">--sgb-compatible</code></dt>
  <dd>Set the SGB flag: <span class="Ad">0x146</span> = 3. This flag will be
      ignored by the SGB unless the old licensee code is 0x33!</dd>
  <dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a>
    <var class="Ar">title</var>,
    <code class="Fl">--title</code>
    <var class="Ar">title</var></dt>
  <dd>Set the title string
      (<span class="Ad">0x134</span>&#x2013;<span class="Ad">0x143</span>) 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
      (<code class="Fl">-c</code> or <code class="Fl">-C</code>). If both this
      and the game ID are set, the game ID will overwrite the overlapping
      portion of the title.</dd>
  <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
    <code class="Fl">--version</code></dt>
  <dd>Print the version of the program and exit.</dd>
  <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a>,
    <code class="Fl">--validate</code></dt>
  <dd>Equivalent to <code class="Fl">-f</code> <code class="Cm">lhg</code>.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
Most values in the ROM header are only cosmetic. 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 (&#x201C;valid&#x201D; meaning a power of 2, times 32 KiB).
<p class="Pp">The following will make a plain, non-color Game Boy game without
    checking for a valid size:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent">$ rgbfix -v foo.gb</div>
<p class="Pp">The following will make a SGB-enabled, color-enabled game with a
    title of &#x201C;foobar&#x201D;, and pad it to a valid size. (The Game Boy
    itself does not use the title, but some emulators or ROM managers do.)</p>
<p class="Pp"></p>
<div class="Bd Bd-indent">$ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb</div>
<p class="Pp">The following will duplicate the header (sans global checksum) of
    the game &#x201C;Survival Kids&#x201D;:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent">$ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t
  SURVIVALKIDAVKE SurvivalKids.gbc</div>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
Please report bugs on
  <a class="Lk" href="https://github.com/rednex/rgbds/issues">GitHub</a>.
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.1.html">rgblink(1)</a>,
  <a class="Xr" href="rgbds.7.html">rgbds(7)</a>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<code class="Nm">rgbfix</code> was originally released by Carsten
  S&#x00F8;rensen 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
  <a class="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">December 5, 2019</td>
    <td class="foot-os">General</td>
  </tr>
</table>
</body>
</html>