prevnext   » SZS: Wiimms SZS Toolset » Guides » BMG: Syntax and usage of BMG text files

BMG: Syntax and usage of BMG text files

Contents

1.   Introduction

The tool wbmgt appeared in April 2011. From the beginning it supports a text representation of BMG message files. The advantage of a text file is that it can be created and modified by humans and machines (scripts) without knowledge of the internal file structure. Also many thing can be made easier by using escape sequences instead of binary codes.

Wiimms SZS Tools accept binary and text BMG files as input and can convert each format to each other. Moreover BMG files of both formats can be used to patch other BMG files of both formats (see option --patch-bmg).

This pages describes the syntax of BMG text files and how to convert them to and from binary BMG files used by Nintendo. It also gives usage examples.

2.   Syntax

A valid BMG text file starts with the magic '#BMG' (4 characters). A byte-order-mark (BOM) is accepted before the magic.

A BMG text file is line oriented with support of continuation lines:

All other lines must follow one of the following line formats:

Line Format
Format Description
MID ~ ATTRIB32 MID is the Message ID (see below). Define a 32-bit attribute for the message MID without any string. Use a following text assignment to define a text.
MID / Define a message ID without any string (NULL pointer). This is different to a message with an empty string. The impact is unknown, but Mario Kart Wii use NULL pointers and emtpy strings.
MID '[' ATTRIB ']' / Define a message ID without any string (NULL pointer). ATTRIB is a attribute vector with any number of byte values. The ATTRIB must be enclosed by brackets ([..]). For more details, see below.

This line format is available since v1.40a.

MID = TEXT Define a text string for MID. An already existing string is replaced, but the attribute of an existing string is not changed. For new messages, the attribute is set to 0x01000000 ([1]).

Continuation lines are possible.

MID '[' ATTRIB ']' = TEXT Define a text string for MID. An already existing string is replaced. ATTRIB is a attribute vector with any number of byte values. The ATTRIB must be enclosed by brackets ([..]). For more details, see below.

Continuation lines are possible. This line format is available since v1.40a.

    + TEXT This is a text continuation line for a previous text assignment.

Multiple continuation can be used. Spaces and tabs before the '+' are ignored. Maximal 1 space behind the '+' is ignored. A line feed is not included on continuation and must be explicitly defined as part of TEXT.

Spacing
Before the assignment character ('~', '/', '=' or '+') any number of spaces and tabs can be used. Between '='/'+' and TEXT only the first space is skipped. Additional spaces are part of the text.

On output, always 1 space behind '='/'+' is printed.

MID
Each message is identified by a Message ID (MID). The MID is either a hexadecimal number (without 0x prefix) or a name of:
Tct
The literal 'T' is used for a track name definition. 'c' is a cup number between 1–8 and 't' a track index between 1–4. Both messages related to the track with respect of re-ordered tracks are defined. If CT-CODE is active, then a third CT-CODE relevant message is also defined.
Uct
The literal 'U' is used for a battle arena name definition (an 'A' would conflict with hex numbers). 'c' is a cup number between 1–2 and 't' a track index between 1–5. Both messages related to the track with respect of re-ordered tracks are defined.
Mnn
The literal 'M' is used for a chat message. 'nn' is a decimal number between 01 and 96.
TEXT
The text to assign. The text may contain escape sequences to enter special characters and Nintendo escapes.
ATTRIB32
The attribute of the message as 32-bit hex numbers.
ATTRIB
The attribute of the message with any number of 4 byte values in hexadecimal notation. This line format is available since v1.40a and the default since v1.44. On text output, the new in-line format can be disabled by option --no-bmg-inline.

2.1   Attributes

For each message, a string and an attribute is defined. wbmgt supports attributes of different length. Mario Kart Wii uses always a attribute size of 4 bytes (32-bit word) and Animal Crossing Wii 16 bytes.

If the attribute size is exact 4 bytes, then it can be printed as single value (ATTRIB32). Otherwise the vector format '[...]' (ATTRIB) is used. A attribute vector is always surrounded by brackets. The vector itself is a comma separated list of byte (8-bit) values in hexadecimal notation. NULL values can be omitted.
Example: [1,,A0] == [1,,A0,] == [1,0,A0,0]

If using a slash ('/') instead of a comma, the next value will be word (32-bit) aligned. The ommited bytes are assumed to be NULL.
Example for an 8 byte attribute: [,B/33] == [,B,,,33] == [0,0B,0,0,33,0,0,0]

Mario Kart Wii uses 4 different attributes to select a font. Other attributes will lead into a game freeze.

Attributes used by Mario Kart Wii
ATTRIB32 ATTRIB
(full)
ATTRIB
(short)
Description
0x00000000 [0,0,0,0] [0] Value used for count down and for final race strings like "FINISH!".
0x01000000 [1,0,0,0] [1] Standard font for nearly all messages.
0x04000000 [4,0,0,0] [4] Use special red font (only digits) used for battle and team points.
0x05000000 [5,0,0,0] [5] Use special blue font (only digits) used for battle and team points.

2.2   Escapes for TEXT

The text is scanned char by char assuming UTF-8. Invalid UTF-8 characters are interpreted as ISO LATIN-15 character as fallback. The backslash ('\' ) is a special character that starts an escape sequence. The meaning depends on the following characters:

Escape Sequences
Syntax Description
\\ The backslash itself.
\a ASCII 7 = 0x07 = BEL (bell)
\b ASCII 8 = 0x08 = BS (back space)
\f ASCII 12 = 0x0c = FF (form feed)
\n ASCII 10 = 0x0a = LF (line feed)
\r ASCII 13 = 0x0d = CR (carriage return)
\t ASCII 9 = 0x09 = HT (horizontal tabulator)
\v ASCII 11 = 0x0b = VT (vertical tabulator)
\nnn Insert a character (16-bit) defined by the octal number 'nnn' with 1–3 digits. Only characters with code 0–511 (–0x1ff) are possible.
\x{nnnn} Insert a character (16-bit) defined by the hexadecimal number 'nnnn' with any number of hexadecimal digits. Only the lowest 16 bits of the number are used.
\x{a,b,...} Since v1.44, \x{} supports also a comma separated lists of parameters. Each parameter is interpreted as hexadecimal number and defines exact one 16-bit character.
\z{xyy,a} This is a short cut for Nintendos escape sequences up to 12 bytes:
  • 'x' is one of '6', '8', 'a' or 'c' and defines the byte length of the whole sequence.
  • 'y' is any byte code to identify the main functionality.
  • 'a' is a hexadecimal number of any length. Only the lowest 16-bit (on x=6), 32-bit (on x=8), 48-bit (on x=a) or 64-bit (on x=c) of the number are used.
The data is stored as \x{1a}\x{xyy} followed by the integer zzzz (1–4 values of 16-bit; most significant first).
\z{xyy,a,b,c,...} Since v1.44, the tools support also Nintendos escape sequences from 14 to 254 bytes:
  • 'x' is one of 'e' (or '0e') to 'fe' and defines the byte length of the whole sequence.
  • 'y' is any byte code to identify the main functionality.
  • 'a' is a hexadecimal number of any length. Only the lowest 16-bit, 32-bit, 48-bit or 64-bit of the number are used.
  • 'b,c,...' are 64-bit hexadecimal numbers and each represents four 16-bit characters.
The data is stored as \x{1a}\x{xyy} followed by the integers a, b, ... (5 or more characters of each 16-bit; most significant first).
\u{zzzzzzzz} Insert the 32-bit unicode character U+zzzzzzzz. It's a short cut for \z{801,zzzzzzzz}.
\u{a,b,...} Since v1.44, \u{} supports also a comma separated lists of parameters. Each parameter is interpreted as 32-bit unicode character U+x and inserted as \z{801,x}.
\c{zzzz} Insert the 16-bit color zzzz. It's a short cut for: \z{800,1zzzz}.

If zzzz is not a number, but a known color name, then the related color number is used.

2.3   Colors

Mario Kart Wii supports colored texts. To change a color, a Nintendo Escape Sequence is used.

The tools accept escape sequences of format \c{num_or_name} to change the current color. The following table lists the color names and the related color codes. The examples are made by capturing a video. So the example colors are inaccurare and depending of the used TV system, but give a good overview.

Colors used by Mario Kart Wii
Names Number Info Examples
OFF
NONE
GRAY
GREY
0x00 No special color defined. Often grey is used. Only this color is blinking on track selection. 123 Abc 123 Abc 123 Abc
TRANSP
CLEAR
0x08 Characters are invisible and only space is reserved.
WHITE 0x02 123 Abc 123 Abc 123 Abc
RED1
RED
0x40 123 Abc 123 Abc 123 Abc
RED2 0x20 123 Abc 123 Abc 123 Abc
RED3 0x32 123 Abc 123 Abc 123 Abc
RED4 0x01 123 Abc 123 Abc 123 Abc
YELLOW 0x30 123 Abc 123 Abc 123 Abc
GREEN 0x33 123 Abc 123 Abc 123 Abc
BLUE1
BLUE
0x21 123 Abc 123 Abc 123 Abc
BLUE2 0x31 123 Abc 123 Abc 123 Abc
YOR0 0x10 Begin of yellow-orange-red (YOR) series. 123 Abc 123 Abc 123 Abc
YOR1 0x11 123 Abc 123 Abc 123 Abc
YOR2 0x12 123 Abc 123 Abc 123 Abc
YOR3 0x13 123 Abc 123 Abc 123 Abc
YOR4 0x14 123 Abc 123 Abc 123 Abc
YOR5 0x15 123 Abc 123 Abc 123 Abc
YOR6 0x16 123 Abc 123 Abc 123 Abc
YOR7 0x17 End of yellow-orange-red series. 123 Abc 123 Abc 123 Abc

2.4   Examples

#BMG  <<<  The first 4 characters '#BMG' are the magic for a BMG text file.
#     <<<  Don't remove them!

# Set the Message ID (MID) a234 to "Hello"
 a234 = Hello

# Standard C escape sequences are allowed:
 a234 = Hello\nWiimm

# Continuation lines and colors are also possible
 a234 = Hello\n
      + \c{blue}Wiimm\c{off}

# Attributes are specified with ~
 a234 ~ 0x01000000

# For track names use the MID alternative 'Tct'
# Both related messages will be defined.
 T11 = name of first track

# Points for battles; use blue special font (in-line mode for attribute)
 76d [5] = \z{a02,1000000000}

3.   Decode and Encode

For all SZS tools, DECODE means: Convert data to an external file format. And ENCODE means: Convert data to an internal file format.

A BMG file is decoded into a human and machine readable text file. And encoding means: Create a new BMG binary file from scratch. The source may be a binary or text BMG file.

Commands to decode (examples without options):

wbmgt decode FILE.bmg
wbmgt cat FILE.bmg
wbmgt mix FILE.bmg
wszst bmg FILE.szs
wctct bmg CT-FILE

Command to encode (examples without options):

wbmgt encode FILE.txt

4.   Options

The following options change the output format of text files. The text scanner accepts all formats:

Options
Option Param Description
-H --no-header Suppress the syntax information section in BMG text files.
-B --brief If set, the information header in decoded text files is suppressed (for historical reasons same as --no-header). If set at least twice, all comments are suppressed and the output is packed without empty lines. If set 3 times, the #BMG file indentification is also suppressed.
--inf-size size Defines the 'INF0' size of new BMG files between 4 and 1000. The first 4 bytes of a INF0 record is a pointer to the string and the remaining bytes the string attributes. However, maximal 20 attribute bytes are supported and additional bytes are assumed to be NULL. All BMG files of MKW have a size of 8.
--force-attrib attrib Forces, that all attributes are set to this vector.
--def-attrib attrib Define the default attributes for BMG files. If not set, the default attributes are estimated. On text output, strings with default attributes are printed without attribute vector. The usual default attribute for MKW is [1].
--no-attrib Suppress the output of any BMG attributes at text BMG files.
--x-escapes Use \x{} escapes instead of \z{} escapes.
--old-escapes To be compatible with v1.43 and earlier, print 1A escape sequences with total size of >12 bytes as single words using \x{}. Also don't use \x{} and \u{} with parameter lists.
-1 --single-line If set, don't print continuation lines for BMG text output. If set twice, print only single text lines and suppress attributes like option --no-attrib does it.
-l --long Print long numeric message IDs instead of alternative message names like Txx, Uxx or Mxx.
-X --export Enable the export modus and create small and machine readable text files for easy post processing. The option works similar like -HBl11 for BMG text files.
--msg list If this option is set, the BMG messages are filtered by this list. Only enabled messages are exported to the ouput BMG file (binary or text).

The parameter is a list of message ids (short MID, 'Txx' or 'Uxx' or Mxx' or hex number) or message ranges (MID:MID) or one of the keywords NONE, PARAM, CUPS, TRACKS, ARENAS, CHAT, CTCODE, CTTRACKS or ALL. If an element is preceeded by a minus sign, it is removed from the filter list (disabled).

--no-bmg-colors If set, suppress the output of '\c{color}' escape sequences for colors definitions in BMG text output to be compatible with old versions of the tools.
--bmg-colors Force output of '\c{color}' escape sequences with names, even for foreign (not MKWii) BMG files.
--no-bmg-inline Print BMG values as separate line before the message definition to be compatible with versions until v1.39. The output for the standard value 0x01000000 is always suppressed. This was the default until v1.43. Since v1.44, --bmg-inline is the default.
--bmg-inline [DEPRECATED] Print BMG values between message name and the equal sign using the format '[...]'. The output for the standard value (usually 0x01000000) is always suppressed. Since v1.44, the inline mode is the default. It can be disabled by option --no-bmg-inline to be compatible with versions until v1.39.
--compatible vers The option expects a version number (format '#.##' or 'v#.##') or a revision number (format 'r#') as parameter. If set, the tools try to create BMG and KMP text files, that are compatible to the entered version of the tools. This may override other legacy options.