msbt

From ZeldaMods (Breath of the Wild)
Jump to navigation Jump to search

MeSsage StuDio BiNary Text MSBT files are Message Studio Binary files. These files define how text is displayed and interacted with by the player.


msbt File Layout

msbt files are made up of four sections that are aligned to 16-bytes.

  • Header
  • Labels
  • Attributes
  • Texts

msbt Header

Header Structure

Offset (h) Size Data Type Description
0x00 8 String msbt file signature (magic) 4D 73 67 53 74 64 42 6E or "MsgStdBn"
0x08 2 Unsigned Short Byte-Order Mark
0x0a 2 Padding? [check]
0x0c 2 Unsigned Short Version? 1.3? [check]
0x0e 2 Unsigned Short Section Count? [check]
0x10 2 Padding? [check]
0x12 4 Unsigned Int File Size
0x16 10 Padding? [check]

Labels Section

The labels section has a header followed by an offset table and finally a string table with meta data regarding the later text section.

Labels Section Header

The section header includes a signature, table size and padding making the header 16 bytes. Table size is relative to the end of the section header.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int Signature (magic) 4C 42 4C 31 or "LBL1"
0x04 4 Unsigned Int Table size
0x08 8 Padding

Labels Section Offset Table

Offsets in the offset table are relative to the end of the Labels Section Header (byte `0x10`). The offset table length is defined in the first four bytes of the table.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int Offset count

Each entry in the offset table is 8 bytes. 4 bytes indicating the number of null-terminated strings at the offset and an offset relative to the beginning of the offset table.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int String count
0x04 4 Unsigned Int String offset

Labels Section String Table

The labels can be determined by iterating through the offset table and reading the number of null-terminated strings from the address. The first byte at the offset indicates the size of the label. One label can contain zero or more null-terminated strings but will not exceed the indicated total length.

After each null-terminated string, there are 4 bytes indicating which index in the texts table this label corresponds to. See the text table section for more information.

Offset (h) Size Data Type Description
0x00 1 Unsigned Byte String length
0x01 n char[n] String count number of null-terminated strings[1]
0xnn 4 Unsigned Int String Table Index

Attributes Section

Attributes are not fully understood at this time. The attribute seem to indicate which actor should be attributed with the dialog (A good example is in 100enemy.msbt where NPC_GodVoice is referenced).

The attributes seem to correspond to an entry in the text table with the same table index, since the attribute and text tables are usually the same size [check].

Attributes Section Header

The section header includes a signature, table size and padding making the header 16 bytes. Table size is relative to the end of the section header.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int Signature (magic) 41 54 52 31 or "ATR1"
0x04 4 Unsigned Int Table size
0x08 8 Padding

Attributes Section Offset Table

Offsets in the offset table are relative to the end of the Attributes Section Header (byte 0x10). The first 4 bytes of the table are the number of offsets and the second 4 bytes indicate the size of each offset (or table entry) in bytes.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int Offset count
0x04 4 Unsigned Int Attribute data size

Each entry in the offset table is a 4-byte relative offset from the beginning of the table.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int Attribute offset

Attributes Section String Table

The attributes can be determined by iterating through the offset table and a null-terminated string from the address. Strings in this table are UTF-16 (Wii U files are UTF-16-BE encoded) encoded and take up 2 bytes for each character. Strings are terminated with a UTF-16 null character 00 00 or \u0000.

Offset (h) Size Data Type Description
0x00 n char[2] Unicode character

Texts Section

The text section contains a table of strings.

Texts Section Header

The section header includes a signature, table size and padding making the header 16 bytes. Table size is relative to the end of the section header.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int Signature (magic) 54 58 54 32 or "TXT2"
0x04 4 Unsigned Int Table size
0x08 8 Padding

Texts Section Offset Table

Offsets in the offset table are relative to the end of the Texts Section Header (byte `0x10`). The offset table length is defined in the first four bytes of the table.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int Offset count

Each entry in the offset table is a 4-byte relative offset from the beginning of the table.

Offset (h) Size Data Type Description
0x00 4 Unsigned Int String offset

Texts Section String Table

The attributes can be determined by iterating through the offset table. Strings in this table are UTF-16 (Wii U files are UTF-16-BE encoded) encoded and take up 2 bytes for each character.

String length is determined by reading until the next offset in the table and not exceeding the end of the file. Strings cannot be read as null-terminated strings since many strings will have multiple null characters in them.

Offset (h) Size Data Type Description
0x00 n char[2] Unicode character

Text Commands

Some string include interpolation operators or commands within the strings. These commands tell the game to behave in a certain way while displaying the string. Commands include choices, selling items, buying items and interacting with objects.

Commands are indicated in the strings with 00 0e or \u000e.

Offset (h) Size Data Type Description
0x00 2 Unsigned Short Indicator 00 0e
0x02 2 Unsigned Short Command type

For example, in 100enemy.msbt the following data appears: 

   | 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F |                   
---|-------------------------------------------------|------------------|
00 | 00 57 00 68 00 69 00 63 00 68 00 20 00 70 00 61 | .W.h.i.c.h. .p.a |
10 | 00 72 00 74 00 20 00 6F 00 66 00 20 00 74 00 68 | .r.t. .o.f. .t.h |
20 | 00 65 00 20 00 54 00 72 00 69 00 61 00 6C 00 20 | .e. .T.r.i.a.l.  |
30 | 00 77 00 6F 00 75 00 6C 00 64 00 20 00 79 00 6F | .w.o.u.l.d. .y.o |
40 | 00 75 00 0A 00 6C 00 69 00 6B 00 65 00 20 00 74 | .u...l.i.k.e. .t |
50 | 00 6F 00 20 00 63 00 68 00 61 00 6C 00 6C 00 65 | .o. .c.h.a.l.l.e |
60 | 00 6E 00 67 00 65 00 3F 00 0E 00 01 00 06 00 0A | .n.g.e.?........ |
70 | 00 02 00 03 00 04 00 05 02 03 00 00             | ............     |

At byte 0x68 is the command indicator followed by the type of 1. Command types of 1 seem to be variable length. The type (in this instance) is followed by the number of additional Unsigned Shorts 6 and 6 shorts or choices in text. Each choice is a reference to another .msbt file or action.

[00 0A] [00 02] [00 03] [00 04] [00 05] [02 03]

There is also the [00 00] at the end which is a reference when a criteria is met. In this example the criteria is an unpowered Master Sword.

Commands

The commands are not fully understood at this time, but below is a list of the known command identifiers and variable counts.

Type Additional Shorts Notes
0 3 Modify text. Followed by modifiers. (Text Modifiers)
1 n Stop Text. Followed by stop type.
2 2
3 3
4 3 End with XX CD for choice
5 2 Seem to always end with a line-feed character 00 0A

Text Modifiers

The Modify text or 0 command can have up to 3 shorts after it. The shorts follow in this order Font Color Modifier Color.

Note: These 6 colors appear to be the only choices availible. [2]

Below are the known Hex codes for the shorts.

Type Hex Notes
Font [00 03] English font which allows color changing.
Font [00 01] Hylian Font. Does not allow color changes.
Color Modifier [00 02] Allows changes in color
Color [00 00] Red
Color [00 01] Green
Color [00 02] Blue
Color [00 03] Gray
Color [00 05] Orange
Color [FF FF] White

Text Stop Types

The Stop text or 1 command has varying stops depending on the type. There are two known stop types at this time: Choice and Delay

  • Choice is a stop of the text until the player makes a choice which then moves the the text option choosen. A choice is shown above in 100enemy.msbt.
  • Delay is a stop of the text for X number of frames. This is then followed by the frame counter and number of frames.
Type Code Note
Choice [00 XX] X is the number of choices availible. This can reference an event, text in its document, or text in other documents.
Delay [00 00] Immedietly Followed by the frame counter
Frame Counter [00 04] Followed by 4 nibbles [00 00 00 XX] where XX is the number of frames in hex. EX: 1 sec = 30 frames = [1E]
Example

A great example of Text stop and modifiers in use is in Demo700_0.msbt the following data appears: 

   | 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F |                   
---|-------------------------------------------------|------------------|
80 | 54 58 54 32 00 00 00 E4 00 00 00 00 00 00 00 00 | TXT2...d........ |
90 | 00 00 00 01 00 00 00 08 00 54 00 68 00 61 00 74 | .........T.h.a.t |
A0 | 00 20 00 69 00 73 00 20 00 61 00 20 00 0E 00 00 | ...i.s...a...... |
B0 | 00 03 00 02 00 00 00 53 00 68 00 65 00 69 00 6B | .......S.h.e.i.k |
C0 | 00 61 00 68 00 20 00 53 00 6C 00 61 00 74 00 65 | .a.h...S.l.a.t.e |
D0 | 00 0E 00 00 00 03 00 02 FF FF 00 2E 00 20 00 0E | ................ |
E0 | 00 01 00 00 00 04 00 00 00 4B 00 54 00 61 00 6B | .........K.T.a.k |
F0 | 00 65 00 20 00 69 00 74 00 2E 00 20 00 0E 00 01 | .e...i.t........ |
  • Text Modifier: At byte 0xAD command starts exicuting text color. The English Font is referenced at 0xB1 which leads into the Color Modifier. Then the color red is chosen. To end the red text and go back to white, the same command is ran after the words at 0xD2 but with white as the color.
  • Text Stop: At byte 0xDF command starts and a text stop command is run. Following the time stop, the delay command is chosen 0xE3. The delay command tells us that there is a 4B delay 0xE9 before the next line. Convert this to decimal is 75, devide 75 by 30 fps (botw default fps) and you get a 2.5 second delay.

Compiling the Sections

The sections are held together by the indexes in the labels table. The indexes correspond to the attributes table and the texts table. The data can be compiled using the index.

By default the indexes in the labels table are not in order, but the text table is (and possibly the attributes table). Below is the labels table in 100enemy.msbt.

String Count Offset Label Index
1 188 talk20 3
0 188
0 188
0 188
0 188
0 188
0 188
0 188
0 188
0 188
0 188
1 199 0002 8
1 208 0003 9
1 217 0004 10
1 226 0005 11
1 235 talk13 4
0 235
1 246 talk14 5
1 257 talk15 6
1 268 talk16 7
1 279 talk17 0
1 290 talk18 1
1 301 talk19 2

And the texts table.

Index Text
0 Which part of the Trial would you like to challenge?
1 Which part of the Trial would you like to challenge?
2 Which part of the Trial would you like to challenge?
3 You cannot participate in the Trial when the Master Sword is out of energy.
4 That sword you have reunited with... the Master Sword...it has yet to realize its true splendor. The trial that will awaken its true power... If you wish to rise to the challenge, place the Master Sword in its pedestal.
5 The Master Sword you wield is now more powerful than before. If you desire still more power and wish to retry the blade's test... once again place the Master Sword in its pedestal
6 Now your body, mind, and soul are ready to wield the Master Sword at its full potential. But do not let your guard down. Just as before, if you use your sword to excess, it will run out of energy and become unusable until it recovers. It would be reckless to rely only on your blade when facing Ganon. Prepare for the worst, and consider freeing the Divine Beasts before confronting your fate. Her smile... The princess's sweet smile... How I would love to see it once more..
7 Now your body, mind, and soul are ready to wield the Master Sword at its full potential. But do not let your guard down. Just as before, if you use your sword to excess, it will run out of energy and become unusable until it recovers. That blade is more than a tool. It is your partner across time, your ally from 100 years past... Wield it with care. Her smile... The princess's sweet smile...How I would love to see it once more...
8 Beginning Trials
9 Middle Trials
10 Final Trials
11 Cancel

Using the indexes to match the labels to the attributes and texts tables, the following table can be compiled.

The empty labels are not fully understood.

Label Index Attribute Text
talk17 0 NPC_GodVoice Which part of the Trial would you like to challenge?
talk18 1 NPC_GodVoice Which part of the Trial would you like to challenge?
talk19 2 NPC_GodVoice Which part of the Trial would you like to challenge?
talk20 3 NPC_GodVoice You cannot participate in the Trial when the Master Sword is out of energy.
talk13 4 TwnObj_Village_Korok_DekuTree_A_01 That sword you have reunited with... the Master Sword...it has yet to realize its true splendor. The trial that will awaken its true power... If you wish to rise to the challenge, place the Master Sword in its pedestal.
talk14 5 TwnObj_Village_Korok_DekuTree_A_01 The Master Sword you wield is now more powerful than before. If you desire still more power and wish to retry the blade's test... once again place the Master Sword in its pedestal
talk15 6 TwnObj_Village_Korok_DekuTree_A_01 Now your body, mind, and soul are ready to wield the Master Sword at its full potential. But do not let your guard down. Just as before, if you use your sword to excess, it will run out of energy and become unusable until it recovers. It would be reckless to rely only on your blade when facing Ganon. Prepare for the worst, and consider freeing the Divine Beasts before confronting your fate. Her smile... The princess's sweet smile... How I would love to see it once more...
talk16 7 TwnObj_Village_Korok_DekuTree_A_01 Now your body, mind, and soul are ready to wield the Master Sword at its full potential. But do not let your guard down. Just as before, if you use your sword to excess, it will run out of energy and become unusable until it recovers. That blade is more than a tool. It is your partner across time, your ally from 100 years past... Wield it with care. Her smile... The princess's sweet smile...How I would love to see it once more...
0002 8 Beginning Trials
0003 9 Middle Trials
0004 10 Final Trials
0005 11 Cancel

The attribute table is still not fully understood. In this example, there are 8 attribute entries in the table, but they correctly map to the 8 blocks of dialog.

  1. ↑ A label can contain zero or more null-terminated strings
  2. ↑ https://github.com/Argo-SC/BOTW-re-notes/blob/master/MSBT/Colour_Test.txt

Tools

Tool Cross-platform Setup Known issues
Wild Bits Yes
  1. Ensure you have a 64 bit version of Python 3.7+ before continuing. Windows users must also install the latest x64 Visual C++ redistributable. You will not be able to install or launch Wild Bits otherwise. See Help:Setting_up_tools.
  2. (Optional) For best results on Windows, install cefpython3. [CLI help]
  3. Install the wildbits package. [CLI help]

On some system configurations, launching with wildbits doesn't work and you must use python -m wildbits instead.

msyt Yes

Download the release for your OS and architecture from the MSYT GitLab under "Download artifacts." Extract it where you please and run it from the command line or terminal.

None

Retrieved from "https://zeldamods.org/w_botw/index.php?title=Msbt&oldid=2547"