Luigi's Mansion:Docs/BFN (File Format)

==Summary==
BFN files can be fully edited. It can be extracted and (custom) imported.
In Luigi Mansion, BFN files are used as the GameCubes font data.
===Tutorial===
Sometimes, you may find BFN files in unexpected places, such as the executable DOL. This tutorial will help you edit BFN files without converting it.
You will need the following tools:
* Crystal Tile 2
* An image editing software
Step 1:
==Format Information==
BFN is a format that defines font data for many GameCube games. It contains the image, character mapping, and width data for each glyph in the font. A single character in the font is rendered by looking up the input character in the font's mapping to convert it to a code, which is then assigned a glyph. Each glyph is given a width, texture, and other information necessary for rendering.
The format closely resembles the IFF format and are made up of any number of blocks. These are each identified by a unique FOURCC identifier, followed by a size. This allows unknown blocks to be safely skipped. The block types specified by BFN are INF1, MAP1, GLY1, and WID1. Any number of these blocks may be specified, each affecting only a specific range of characters or codes. A BFN file may have more than one INF1 block—in that case, only the last one is used.
=== Header ===
The FONT block contains information about the containing BFN file, not necessarily the font itself. Being the header, it must be the first, outermost block at the beginning of the file.
Start	Length	Description
0x00 	4 	FOURCC identifier for the block ('FONT').
0x04 	4 	FOURCC identifier for the version ('bfn1').
0x08 	4 	Total size of the file, in bytes.
0x0C 	4 	Total number of blocks in the file, including the INF1 block. The header is not included in this count.
0x10 	16 	Padding bytes.
=== INF1 ===
This block contains global information about the font as a whole. It specifies the base properties, such as ascent, descent, leading, and width. The height is assumed to be (ascent + descent).
Start	Length	Description
0x00 	4 	FOURCC identifier for the block ('INF1').
0x04 	4 	Total size of the block, in bytes, including padding.
0x08 	2 	Font encoding type (see below). This value is needed to properly read and decode any text rendered by this font.
0x0A 	2 	Ascent of the font, in screen units. This is how far above the baseline the top edge of the glyphs will reach.
0x0C 	2 	Descent of the font, in screen units. This is how far below the baseline the bottom edge of the glyphs will reach.
0x0E 	2 	Width of a character in the font, in screen units. This will be used as the base width of the font for scaling calculations at run time. It is also used as the width for all characters if the font is rendered in monospace.
0x10 	2 	Leading (also known as line-height) of the font, in screen units.
0x12 	2 	Replacement code (not character). The game will substitute unmapped characters with this code. It is assumed this code will have a valid glyph assigned to it.
0x14 	4 	Unknown (always zero, never referenced).
0x18 	8 	Padding bytes.
==== Encodings ====
There are three encoding types specified in BFN files, ranging from zero to two:
Type	Description
0 	Single-byte (8‑bit) encoding, allowing characters in the 0-255 range. This tends to be 1:1 with CP‑1252.
1 	Two-byte (16‑bit) encoding, allowing all characters in the 0-65535 range.
2 	Multi‑byte (8‑bit or 16‑bit) S‑JIS encoding, allowing characters in the 0x00‑0x7F and 0x8000‑0xFFFF ranges.
=== GLY1 ===
This block contains one or more texture atlases (or sheets), divided up into several rows and columns. Each cell is assigned a glyph (via its code). Each cell is a fixed size specified by the block's header.
Start	Length	Description
0x00 	4 	FOURCC identifier for the block ('GLY1').
0x04 	4 	Total size of the block, in bytes, including padding.
0x08 	2 	First code (not character) in the range of codes that this GLY1 block textures (inclusive).
0x0A 	2 	Last code (not character) in the range of codes that this GLY1 block textures (inclusive).
0x0C 	2 	Width of each cell, in texels. All cells in each of the texture sheets share this width.
0x0E 	2 	Height of each cell, in texels. All cells in each of the texture sheets share this height.
0x10 	4 	Total size, in bytes, of a single texture sheet, including padding.
0x14 	2 	Texture format for each texture sheet. Uses the same values as GX. Paletted/indexed formats are not valid.
0x16 	2 	The number of rows in each texture sheet. Rows begin from the left edge of the sheet.
0x18 	2 	The number of columns in each texture sheet. Columns begin from the top edge of the sheet.
0x1A 	2 	Width of each texture sheet, in texels. It is not mandatory to be a multiple of the cell width.
0x1C 	2 	Height of each texture sheet, in texels. It is not mandatory to be a multiple of the cell height.
0x1E 	2 	Padding bytes.
==== Data ====
Each texture sheet is laid out in its raw image data according to the format and dimensions specified in the header. The first sheet is directly after the header, and each following sheet is sheet size bytes after the previous.
A code will be assigned a glyph linearly across the range specified in the block header. To calculate the total number of sheets, use a formula similar to the following:
sheet count = (last code - first code) ÷ (row count × column count) + 1
=== MAP1 ===
This block contains a code mapping for a specified range of characters. The characters in this range will be mapped to codes using one of the various mapping methods, specified in the header. This code will be used to index the character in the GLY1 and WID1 blocks.
Start	Length	Description
0x00 	4 	FOURCC identifier for the block ('MAP1').
0x04 	4 	Total size of the block, in bytes, including padding.
0x08 	2 	Specifies which of the various mapping methods to use for this range of characters (see below).
0x0A 	2 	First character (not code) in the range of characters mapped by this block (inclusive).
0x0C 	2 	Last character (not code) in the range of characters mapped by the block (inclusive).
0x0E 	2 	Specifies how many mapping entries there are directly following this field. The size and meaning of each entry depends on the mapping type (see below).
==== Mapping ====
Characters can be mapped in one of several different ways. The method used is specified in the header. There are four possible values, ranging from zero to three:
Type	Description
0 	The characters are mapped to codes linearly as their index into the character range specified in the header. For example, a range of 32-255 would map the character 65 (ASCII for capital 'A') as the code 33. The entry count field is ignored and should be 0.
1 	Maps the basic set of S-JIS kanji characters linearly, starting at a base code. The entry count field should be either zero or one. If there is one entry, it overrides the base code value for the conversion (otherwise, a constant of 796 is used). Should be used only for the character range 0x889F - 0x9872 (亜 - 腕). See below for the specific formula.
2 	The characters are table mapped. An array of entry count 16‑bit codes follows the header. The input character's index into the character range is used as the index into this array, where the value in this array at that index is used as the character's code.
3 	The characters are map mapped. Two interlaced arrays of entry count 16‑bit codes follow the header. The first array is searched until a value matching the input character is found. Once found, that index is used to get the value out of the second array, which is then used as the final mapped code.
For mapping type 1, the formula is designed to map each of the 32, 94‑kanji blocks from 0x889F - 0x9872 to a linear range of codes, starting at a base code value (defaulting to 796). The formula is the following:
 lead byte = ((character >> 8) & 255)
 trail byte = ((character >> 0) & 255)
 index = (trail byte - 64)
 if index >= 64 --index
 mapped code = base code + index + ((lead byte - 136) × 188 - 94)
If the character fails to be mapped by any of the above methods, the invalid code field from the INF1 block is used as a substitute.
=== WID1 ===
This block contains the horizontal-spacing information of a specific range of codes. It assigns glyphs kerning and widths used for spacing and rendering the glyph.
Start	Length	Description
0x00 	4 	FOURCC identifier for the block ('WID1').
0x04 	4 	Total size of the block, in bytes, including padding.
0x08 	2 	First code (not character) of the range of codes spaced by this block (inclusive).
0x0A 	2 	Last code (not character) of the range of codes spaced by this block (inclusive).
==== Data ====
Directly following the last code field in the header is the width array. The number of elements is assumed to be last code - first code. Each element is 16 bits, split into two 8-bit fields.
Start	Length	Description
0x00 	1 	Specifies the kerning of the glyph, in screen units. This is how far to the left of the cursor the glyph will render. This value is ignored after spaces, newlines, and certain control codes.
0x01 	1 	Specifies the width of the glyph, in screen units. This is how far to the right the cursor should advance after printing this glyph's character.
Category:File Format