Fontimus Prime 0.1 (c) Ali Campbell 2016
Release Notes, 18th March 2016
https://chexum.co.uk/
---------------------

Fontimus Prime (FP) is a Swiss Army knife for manipulating the fonts used in 
the Metroid Prime series of games by Nintendo and Retro Studios.

CONTAINED IN THIS RELEASE
-------------------------
There are two versions of FP. If you are using Windows and you just want to be 
able to run the software, you need the win32 binary distribution available from:

  https://chexum.co.uk/fp/fontimus-prime-0.1-win32.zip

If you are running Linux, or you are a Windows user who wishes to build their 
own versions of FP, you will need to get the source package and build it 
yourself:

  https://chexum.co.uk/fp/fontimus-prime-0.1-src.zip

This software will probably also compile unmodified or with only superficial 
tweaks on Mac OS X, but I do not currently own any modern Apple hardware to 
test this on. If you would like to contribute Mac builds of FP, be my guest. 
For more information on building from source, see the NOTES ON THE SOURCE CODE 
section.

PREREQUISITES
-------------
Before using this software, you will need the following:

- One or more ISO disc image files of one or more Metroid Prime games. You can 
rip an image from a retail Wii or GameCube disc using a softmodded Wii running 
CleanRip:
  
  http://wiibrew.org/wiki/CleanRip
  http://code.google.com/p/cleanrip/downloads/list
  
  Please do not pirate ISOs!
    
- A tool for unbuilding and rebuilding Wii and GameCube ISO files. For 
GameCube, your options include GameCube ISO Tool (for Windows), GCRebuilder 
(for Windows), or mkiso, my own PHP script which should run on any platform 
with a working version of PHP 5 or (probably) 7:
  
  https://chexum.co.uk/entry.php?eid=44
  
For Wii ISO unbuilding and rebuilding, your best option is probably WIT (a.k.a. 
Wiimms ISO Tools); this also has some GameCube functionality, but last time I 
checked it did not have the ability to rebuild GameCube images (which is why I 
wrote mkiso). WIT is cross-platform:
    
  http://wit.wiimm.de/
  
- A utility for unpacking and repacking Retro Studios' .PAK files. The best 
option right now is probably Parax's PakTool (which is for Windows only); you 
can find it in the first post here:

  https://m2k2.taigaforum.com/post/metroid_prime_hacking_research.html
  
If you are using another x86 OS, you may be able to run PakTool using WINE.
  
If all else fails, you could try retropak (my own .PAK utility). This software 
was never properly released as it suffers from a design flaw which means it is 
unable to repack correctly a small minority of .PAK files. It also does not 
work with Metroid Prime 3. It is, however, open source and has been 
successfully built on several OSes, and it was used on Linux for most of 
Fontimus Prime's development. I am making it available here in case you are 
allergic to Windows binaries, but I will not be providing any help with it:
  
  https://chexum.co.uk/retropak/retropak-0.1-macosx.zip
  https://chexum.co.uk/retropak/retropak-0.1-source.zip
  https://chexum.co.uk/retropak/retropak-0.1-win32.zip
  
(If you are going to use retropak, you should to tell it to use short filenames 
mode (-s) so that its filenames match those used by PakTool; this will make the 
examples below make sense. One day I hope to fix this software. Meanwhile, feel 
free to send me patches.)
  
- You will of course also need something upon which to play the modified game. 
This is likely to be either a beefy PC running Dolphin, or a softmodded or 
drivechipped Wii.
  
WHICH PAK FILES DO I EXTRACT?
-----------------------------
Many (most?) of the PAK files in the Prime games contain .FONT files; many of 
these are duplicates and some of these files are more significant than others. 
Feel free to experiment with the assets in different .PAKs -- but to see quick 
results, I recommend you begin by unpacking and investigating these PAKs for 
the different games:

- Metroid Prime 1 original North American release (commonly known as 0-00):
  GGuiSys.pak
  
- Metroid Prime 1 European release (a.k.a. PAL):
  MiscData.pak
  
- Metroid Prime 2:
  GGuiSys.pak, FrontEnd.pak

- Metroid Prime 3:
  GuiNAND.pak
  
See also INTERESTING FONT FILES below for the scoop on which .FONT files within 
these PAKs are worth changing.
  
A NOTE ON .FONT FILES
---------------------
The .FONT files in the Metroid Prime games contain the metadata required to 
perform text layout; however, they do not actually contain any glyph graphics 
themselves. Instead, a .FONT file contains a texture ID field, which references 
a texture (.TXTR) file in the game; this .TXTR file contains the glyph bitmaps. 
A .FONT file therefore needs a corresponding .TXTR file along with it in order 
to be meaningful to the game engine. You can get the texture ID for a given 
.FONT file using Fontimus Prime's query (-q) mode (see below).

QUICK START
-----------
If you just want to get on with the serious business of altering a font in a 
game so you can try to impress kids on Twitch, feel free to skip ahead to the 
RENDER MODE and INTERESTING FONT FILES sections below.
  
USING FONTIMUS PRIME
--------------------
Fontimus Prime is a command-line tool with four modes of operation:

- Query mode, which loads a .FONT file and prints information about it;
- Edit mode, which loads a .FONT file, optionally performs transformations on 
it, and then saves it;
- Blank-font mode, which works like edit mode, but starts with a new, blank 
.FONT rather than by loading one;
- Render mode, which:
   - loads a .FONT file;
   - optionally performs transformations on it;
   - loads a TrueType or OpenType vector font file;
   - renders this vector font to a texture using FreeType;
   - populates the .FONT metadata accordingly;
   - saves the font and the texture to .FONT and .TXTR files.
   
More information on the various modes follows.

QUERY MODE (-q, -Q)
-------------------
You can use FP in query mode (-q) simply to print some information about a 
.FONT file. For example, to find out more about one of the fonts used in the 
0-00 version of Metroid Prime:

fp -q GGuiSys/b7bbd0b4.FONT

(These examples were written on Linux; for Windows, you may need to change the 
path separator from '/' to '\').

If you want a printout of all the glyphs in the file as well, try verbose query 
mode (-Q):

fp -Q GGuiSys/b7bbd0b4.FONT

EDIT MODE (-e)
--------------
Edit mode allows you to load a .FONT file, optionally perform transformations 
on it, and then save it back to a file. By default, FP saves .FONT files to the 
file fontimus.FONT in your current directory, but you can override this with -f.

To make a clone of one of the fonts from the PAL version of Metroid Prime and 
save it to clone.FONT:

fp -e -f clone.FONT MiscData/b7bbd0b4.FONT

By default FP will compact the original file's kerning table by removing 
redundant zero-adjust values, so clone.FONT may be smaller than b7bbd0b4.FONT. 
However, you can force a 1:1 copy by telling FP not to mess with the kerning 
using --no-compact-kerning:

fp -e --no-compact-kerning -f clone.FONT MiscData/b7bbd0b4.FONT

clone.FONT should now be an identical copy of b7bbd0b4.FONT.

You can use edit mode to perform various transformations on existing .FONT 
files. Here we will make a number of transformations over several runs of the 
program. We will stick with the PAL version of Metroid Prime for now.

Change font's internal name string:

fp -e -n "My Nice Font" MiscData/b7bbd0b4.FONT

Reduce line spacing to 8 pixels. We add -w to allow FP to overwrite 
fontimus.FONT; it is now loading and saving using the same file:

fp -w -e --line-spacing 8 fontimus.FONT

Add or subtract a number of pixels to or from the inter-letter spacing; here, 
we reduce the gap between letters by 3 pixels. Since changing the inter-letter 
spacing invalidates the existing kerning information in the FONT, we also tell 
FP to discard the old kerning table:

fp -w -e --letter-gap-adjust -3 --omit-kerning fontimus.FONT

Increase or decrease the width of spaces; here, we increase the spaces between 
words by 20 pixels:

fp -w -e --space-adjust 20 fontimus.FONT

We can now copy the hacked fontimus.FONT back to MiscData/b7bbd0b4.FONT, repack 
a new MiscData.pak, and finally rebuild a new PAL ISO file to be tested.

Note that the above transformations will all work fine in edit mode, but this 
is not universally true. Some tweaks such as changing the text size (-s) will 
have no effect on the game when performed in edit mode. Other operations such 
as changing the texture ID, texture format or version number will produce 
garbled text, or cause crashes because the .TXTR no longer matches the .FONT. 
These operations only make sense if the resulting edited .FONT file is 
subsequently loaded in render mode, where a new .TXTR is generated along with 
the output .FONT.

BLANK-FONT MODE (-b)
--------------------
Blank-font mode is like edit mode, but it starts out with an empty .FONT rather 
than by loading one; some fields are filled with default values, but the font 
contains no glyphs. This mode's appeal is its ability to craft new fonts out of 
thin air without actually needing any of the existing games' assets.

For example, you can create and save a "blank" version 2 font with the simple 
command:

fp -b

which will result in an empty 70-byte fontimus.FONT. Glyphs can be added to the 
font using glyph add mode (-g add) and all the normal transformations are 
possible. See GLYPH EDITING below for a full example of creating a font from 
scratch.

RENDER MODE
-----------
This mode provides full font replacement capability. Render mode will generate 
new, usable .FONT/.TXTR file pairs derived from an input TrueType or OpenType 
vector font. These files can then be loaded into whichever game they were made 
for, and the game may be played with new fonts.

To replace a font in Metroid Prime 2 with one generated from a TrueType vector 
font:

fp FrontEnd/93e909c1.FONT arial.ttf

Fontimus Prime will produce the usual fontimus.FONT, along with a texture file 
which is named 2973876d-fontimus.TXTR after the texture ID contained within the 
input FONT.

Overwrite the original FrontEnd/93e909c1.FONT with fontimus.FONT. 
FrontEnd/2973876d.TXTR should be replaced with 2973876d-fontimus.TXTR. If you 
knew the texture ID beforehand, you could have used overwrite mode to have FP 
replace the files in-place, to save you copying them manually:

fp -w -t FrontEnd/2973876d.TXTR -f FrontEnd/93e909c1.FONT 
FrontEnd/93e909c1.FONT arial.ttf

Then, FrontEnd should be repacked to a new FrontEnd.pak, and finally a new ISO 
should be rebuilt.

INTERESTING FONT FILES
----------------------
Here are some of the significant .FONT files in the Prime games along with a 
quick summary of the things they are used for. These are the ones you should 
try replacing first.

Metroid Prime (0-00)
--------------------
[GGuiSys/b7bbd0b4.FONT + GGuiSys/4344027b.TXTR] (no outline)
  - main menu heading
  - "black screen" text (e.g. "Unidentified distress beacon ...")
  - inventory screen heading
  - "Morph Ball acquired!"
  - hint system

[GGuiSys/c29c51f1.FONT + GGuiSys/f5d3ec15.TXTR] (outlined)
  - main menu text
  - map key

[GGuiSys/9bb52e75.FONT + GGuiSys/9eb494af.TXTR] (no outline)
  - contains digits only
  - used for player energy, Orpheon escape timer

Metroid Prime (PAL)
-------------------
See Metroid Prime (0-00) above, but note that the UI fonts are first loaded 
from MiscData.pak instead of GGuiSys.pak in this release, so you will need to 
edit and repack MiscData rather than GGuiSys.

Metroid Prime 2
---------------
[FrontEnd/93e909c1.FONT + FrontEnd/2973876d.TXTR] (outlined)
  - "Press START" (PAL only?)
  - main menu text ("Single Player", "Multiplayer" etc.)
  - main menu heading

[GGuiSys/0d940479.FONT + GGuiSys/744bcbb3.TXTR] (no outline)
  - missile counter
  - in-game UI text (when start pressed)
  - "Missile Launcher acquired"
  - main menu save slot text

[GGuiSys/23b0a3fa.FONT + GGuiSys/7aae75ea.TXTR] (no outline)
  - digits only
  - energy display (not missile counter though)
  - probably the escape countdown timer

Metroid Prime 3
---------------
[GuiNAND/073a875db4d51ce9.FONT + GuiNAND/e84503b86ef882c8.TXTR] (no outline)
  - main menu user interface font

GuiNAND/823a7f490543154c.FONT + GuiNAND/fb0343548e93c326.TXTR (no outline)
  - digits only
  - used for energy display, countdown timers

OUTLINES AND TEXTURE FORMATS
----------------------------
Each .FONT has a texture format field, which defines the way the game should 
interpret the graphics in the .TXTR file. Some of these texture formats specify 
an outlined font, with a one-pixel outline around the glyph; some offer smaller 
TXTR filesizes than others. If you are starting from an existing .FONT file, FP 
will just copy the texture field from the source, so you shouldn't have to 
worry about it.

More information is available here:

http://www.metroid2002.com/retromodding/wiki/FONT_%28File_Format%29

Texture formats 0, 2 and 4 are non-outlined; 1, 3 and 8 are outlined. If you 
wish to force the texture format used in the output .FONT file (only really 
useful when making new .FONT files from scratch using -b), you can do this 
using the -x option.

FONT SIZES
----------
By default, FP will attempt to interpret the text size field in the source 
.FONT, and (by multiplying by a suitable ratio and then setting FreeType's 
pixel size) produce an output .FONT of a similar size. However, this is far 
from an exact science and often the produced .TXTR will contain glyphs that are 
too small or (more commonly) too large.

You can manually set the size of the generated font with FP's -s option, which 
allows you to specify a decimal number. To find out which text size was written 
into an existing .FONT file, use query mode (-q).

Note that certain other transformations to change size and geometry (e.g. -y) 
can be performed on a .FONT in edit mode, without having to build a new texture 
in render mode; see EDIT MODE, above.

KERNING
-------
Kerning adjustment is not supported in this release.

It should be possible to ask FreeType to provide automatically the necessary 
kerning information for all combinations of glyphs in a .FONT. Code to do this 
exists in the get_kerning_from_freetype() function in text.c, but I could not 
get it to produce any kerning value other than zero. Maybe the vector fonts I 
was using did not contain any kerning information, or maybe my code is flawed. 
Feel free to take a look at it and try to get it working; the call to 
get_kerning_from_freetype() from fmus_main() in fmus.c is commented out, so you 
will need to put that back in.

In edit mode, Fontimus Prime will copy the original kerning information from 
the source FONT to the destination .FONT (unless --omit-kerning is specified), 
compacting it en route (unless --no-compact-kerning is specified). For 
blank-font and render modes, an empty kerning table is used.

There is currently no way to add or delete kerning values or edit them 
manually. This would be a useful feature and it may appear in a later release.

GLYPH EDITING
-------------
Each .FONT file contains a list of Unicode characters it supports, as well as 
some metadata about each one.

If you are modifying the text in the games (e.g. via their .STRG files) and are 
using a character that is not contained within the existing .FONT file you are 
using as your source, you can add it with -g add:

fp -g add 0x3a8 myfont.FONT arial.ttf

This will create fontimus.FONT and a texture as is usual for render mode, but 
adds a Greek capital psi to the supported list of glyphs, which you can then 
use in .STRG files which employ the font in question.

Note that many TrueType and OpenType fonts do not contain anything like a full 
set of Unicode glyphs, so if you need unusual characters in your .FONT you will 
need to make sure your vector font that contains those characters. (Look for 
the "Warning: X characters did not have glyphs in this TTF/OTF file" complaint 
from FP to get an idea of how many glyphs were missing from your vector font.)

All the glyph modes (-g add, -g edit and -g delete) expect a hexadecimal 16-bit 
Unicode value to follow as the next argument. This may be prefixed with 0x as 
was done here, but even if 0x is omitted, the value must still be in 
hexadecimal. There are plenty of resources online for finding the Unicode hex 
values for any character you might need. 

You can also delete glyphs with -g delete. Here we delete the lower case letter 
'e' from 0-00's GGuiSys/b7bbd0b4.FONT. We can do this in edit mode, since 
deleting glyphs does not require the generation of a new texture:

fp -e -g delete 0x65 GGuiSys/b7bbd0b4.FONT

We can also use glyph add mode with blank-font mode (-b) to build new fonts 
from scratch, without needing an input .FONT file. Here, we start with a blank 
font and add the numbers 0-9 to it, along with a colon and a decimal point:

fp -b -g add 0x2e -g add 0x30 -g add 0x31 -g add 0x32 -g add 0x33 -g add 0x34 
-g add 0x35 -g add 0x36 -g add 0x37 -g add 0x38 -g add 0x39 -g add 0x3a

(If this looks unwieldy, remember that you can also use repeated runs of FP to 
add these glyphs to the file one-by-one, in edit mode).

Assuming we're building this for Metroid Prime 3, we will need to tell it to 
use a version 5 font file using -o (see FONT VERSIONS, below). Then we can 
supply a texture ID of fb0343548e93c326 (Prime 3 uses longer, 64-bit texture 
IDs), and a texture format of 2, and render it:

fp -w fontimus.FONT -o 5 -i fb0343548e93c326 -x 2 arial.ttf

We have now made a worthy replacement for the "digits-only" font used for the 
energy counter in Prime 3, without using any existing assets from the game.

There is also glyph edit mode (-g edit), which can be used to edit a single 
glyph's fields individually. For example, we can use edit mode plus glyph edit 
mode to produce a hacked version of a Metroid Prime 2 font with the lowercase 
letter 'e' reversed. This is done by swapping the glyph's left and right 
texture coordinates (txl and txr, which we discovered previously using -Q):

fp -e -g edit 0x65 txl 0.7019 -g edit 0x65 txr 0.5673 FrontEnd/93e909c1.FONT 

The full list of glyph fields that may be modified using -g edit are as follows:

txl: texture left coordinate (decimal, 0.0 -> 1.0)
txt: texture top coordinate (decimal, 0.0 -> 1.0)
txr: texture right coordinate (decimal, 0.0 -> 1.0)
txb: texture bottom coordinate (decimal, 0.0 -> 1.0)
lsb: left side bearing (integer, -128 -> 127)
lwidth: layout width (integer, 0 -> 255)
rsb: right side bearing (integer, -128 -> 127)
dwidth: display width (integer, 0 -> 255; normally the same value as lwidth)
height: display height (integer, 0 -> 255)
vertoff: vertical offset (integer, 0 -> 255)

FONT VERSIONS
-------------
There are three possible .FONT versions: 2, 4 and 5. Version 2 is used by the 
original North American release of Metroid Prime (a.k.a. 0-00). Version 4 is 
used in the PAL version of Prime and all versions of Prime 2. Version 5 is used 
in Metroid Prime 3.

In blank-font mode (-b), FP will create version 2 .FONT/.TXTR pairs by default. 
These should also be compatible with PAL Prime and all versions of Prime 2, 
although forcing version 4 for these games will result in more compact .TXTR 
files. However, Metroid Prime 3 understands version 5 files only, due to the 
64-bit texture ID.

NOTES ON THE SOURCE CODE
------------------------
Source code is available in the -src release (fontimus-prime-0.1-src.zip). It 
is provided under a zlib licence; see LICENCE.TXT.

In order to build it, you will need to link against the FreeType library. On 
Linux Debian derivatives, this will require installing the libfreetype6-dev 
package before building.

For Linux and other Unixalikes, I have included a Makefile which should be 
enough for you to build the software just using 'make'.

I have not bothered to provide any Visual Studio project for Windows 
developers. I have however provided a .lib file, a .dll file and a suitable 
include\ directory from the FreeType project, which should be enough for you to 
link FP against FreeType. The basic steps for getting a working VS project go 
something like:

1. Start with an empty project;
2. Drag and drop FP's .c files into the project's "Source Files" folder;
3. Drag and drop FP's .h files into the project's "Header Files" folder;
4. Drag and drop the provided freetype .dll and .lib into the project;
5. Right-click on the project name, select Properties, open the "Configuration 
Properties" branch on the left, select C/C++, and then under "Additional 
Include Directories", add the path to the bundled FreeType include folder.
6. Switch from Debug to Release, and then repeat step 5.
7. Save the project.

Please note that the FreeType include files are provided here under the terms 
of their own licence; see FTL.TXT in the freetype directory.

ACKNOWLEDGEMENTS
----------------
Portions of this software are copyright (c) 2016 The FreeType
Project (www.freetype.org).  All rights reserved.

Metroid Prime is a registered trademark of Nintendo.


