Msbt: Difference between revisions

From ZeldaMods (Breath of the Wild)
Jump to navigation Jump to search
VisualWikitext
m (→‎Group 5: Proofreading is a skill I need to master)
m (→‎Group 5: Group name uniformity)
Line 429: Line 429:
// TODO
// TODO


==== Group 5 ====
==== Group 5 Tags ====
Group 5 is used a more general form of the Delay tag. Exact durations have not been tested.
Group 5 is used a more general form of the Delay tag. Exact durations have not been tested.
{| class="wikitable"
{| class="wikitable"

Revision as of 21:57, 1 January 2025

Message Studio Binary Text MSBT is a binary file format belonging to LibMessageStudio (LMS). These files store the game's text and can contain "tags" that define how said text is displayed/interacted with.

File Layout

MSBT files are composed of a file header followed by blocks (each with their own block header). All sections/blocks must be aligned to 0x10 (16) bytes. In BotW, the file layout is as follows:

  • Header
  • Labels Block
  • Attributes Block
  • Text Block

The list of possible blocks is as follows:

  • LBL1 (labels)
  • TXT2 (text)
  • ATR1 (attributes)
  • TSY1 (style info)
  • ATO1 (unknown)

File Header

Header Structure

Offset (h) Size Data Type Description
0x00 8 char[8] msbt file signature (magic) 4D 73 67 53 74 64 42 6E or "MsgStdBn"
0x08 2 u16 Byte-Order Mark
0x0a 2 Padding [check]
0x0c 1 u8 Encoding (0 = UTF8, 1 = UTF16, 2 = UTF32 - games generally only support one specific encoding) [check]
0x0d 1 u8 Version (3)
0x0e 2 u16 Block Count [check]
0x10 2 Padding [check]
0x12 4 u32 File Size
0x16 10 Padding [check]

Block Header

This header is shared across all block types. The block data follows directly after the header and is aligned to 0x10 (16) bytes. The block size does not include the size of the header.

Offset (h) Size Data Type Description
0x00 4 u32 Block Signature
0x04 4 u32 Block Size
0x08 8 Padding

Labels Block

The labels block contains the label names for file's text. Its signature is LBL1.

The section begins with a four-byte header specifying the number of label groups.

Offset (h) Size Data Type Description
0x00 4 u32 Label Group Count

Label Groups

Following the header is a table of label groups. Each entry in the table is eight bytes. The first four bytes specify the number of labels in the group and the second four specify the offset of the first label relative to the start of the section. The number of label groups in many games appears to be the smallest prime number larger than half the number of labels (with a max of 101 groups and a minimum of 2). In BotW, this may not always be the case.

Offset (h) Size Data Type Description
0x00 4 u32 Label Count
0x04 4 u32 Offset

Messages are sorted into label groups by hashing the label name. A recreation of the hash function is as follows:

def calc_hash(label):
    hash = 0
    for char in label:
        hash = hash * 0x492 + ord(char)
    return (hash & 0xFFFFFFFF) % num_label_groups

Labels

Following the label groups is the array of labels. Each label consists of a u8 string length followed by a null-terminated string. At the end of the label is a u32 index specifying the index of the message that corresponds to the label in the text block.

Offset (h) Size Data Type Description
0x00 1 u8 String Length
0x01 n char[n] Label String
0xnn 4 u32 Message Text Index

Attributes Block

The attributes block stores additional, optional attributes that can be associated with messages. Its signature is ATR1. The interpretation of attribute data is completely up to the game's discretion and attributes in BotW 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).

Each attribute corresponds to the message of the same index in the text block [check].

The block begins with an eight-byte header that specifies the number of attributes and the size of a single attribute.

Offset (h) Size Data Type Description
0x00 4 u32 Attribute Count
0x04 4 u32 Attribute Size

Following the brief header is an array of the attribute data. In many cases, this data is actually a string offset relative to the start of the section (as is the case in BotW).

Offset (h) Size Data Type Description
0x00 4 u32 Attribute String Offset

Attribute Strings

Should the attribute data be a string offset, then the data is followed by an array of null-terminated strings encoded using the encoding specified in the file header. In BotW, this is means UTF16-LE on Switch and UTF16-BE on Wii U.

Offset (h) Size Data Type Description
0x00 n char_type[] String

Text Block

The text block contains the text for messages. Its signature is TXT2.

The section begins with a small four-byte header specifying the number of messages in the section.

Offset (h) Size Data Type Description
0x00 4 u32 Message Count

Following the brief header is an array of u32 offsets to the text strings. Each offset is relative to the beginning of the section.

Offset (h) Size Data Type Description
0x00 4 u32 String Offset

Message Strings

The strings are stored as an array of strings encoded using the encoding specified in the header. In BotW, this is means UTF16-LE on Switch and UTF16-BE on Wii U. Each string is read from its specified offset until the next string offset. The last string uses the section size specified in the block header to determine its end position.

Offset (h) Size Data Type Description
0x00 n char_type[] String

Tags

Message strings can contain tags that alter how the message is displayed or processed. These tags are processed by nn::ui2d::TagProcessorBase which in Nintendo EPD games is extended byeui::TagProcessor which can then be further extended by the game to handle game-specific tags. The interpretation of tags is completely game-dependent.

Tags are embedded directly inside of the text and begin with a brief tag header.

Offset (h) Size Data Type Description
0x00 2 u16 Signature (00 0e or 00 0f)
0x02 2 u16 Tag Group
0x04 2 u16 Tag Type
0x06 2 u16 Extra Data Size (this value is ignored for 00 0f tags which have no data)
0x08 ? ? Extra data (size is dependent on Extra Data Size, type is dependent on Group and Type)

In Nintendo EPD games, tag group 0 tags are system tags, group 1 is eui tags, group 2 is app (game) specific tags, and group 201 is grammar tags. The other groups are currently unknown. In BotW, group 4 appears to be for animations and group 5 appears to be for delays.

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 tag header followed with tag group 1 and tag type 6. 0xa is the size of the extra data with the extra data being [00 02 00 03 00 04 00 05 02 03].

Tags

Not all tags functions are currently known.

System Tags

Group Type Notes
0 0 Ruby (extra data is a u16 display span followed by the ruby text)
0 1 Font (extra data is a u16 font type)
0 2 Font Size (extra data is a u16 font size)
0 3 Font Color (extra data is a u16 color type)
0 4 Page Break (no extra data)

The available colors in BotW are red, green, blue, gray, and orange in that order. 0xffff indicates a reset to the default white text color. These colors are generally either hardcoded in the game's executable or defined in a separate MSBP file if present. If defined in a MSBP file, the color type instead acts as an index into the colors in the MSBP file.

EUI Tags

Group Type Notes
1 0 Delay (extra data is a u32 frame count)
1 1 Text Speed?
1 2 No Text Scroll?
1 3 Auto Advance (extra data is a u32 frame count)
1 4 Two Choices (See #Choices)
1 5 Three Choices (See #Choices)
1 6 Four Choices (See #Choices)
1 7 Picture Font (Icon) (extra data is two u8s, the second being the type)
1 8
1 9
1 10
Choices
Offset (h) Size Data Type Description
0x00 2 Unsigned Short First choice
0x02 2 Unsigned Short Second choice
0x04 1 Byte Default option (option highlighted when the choices are first shown)
0x05 1 Byte Cancel option (option chosen when the B button is pressed)

Each choice type is a group of choices, whose text corresponds to the string conversion of the label indices in the current file. For example, if the label is 00 04 then the displayed choice will be the text corresponding to the "0004" key.

For ChoiceThree there is an additional choice at 0x04, and the default and cancel options are at 0x06 and 0x07, respectively.

For ChoiceFour there are additional choices at 0x04 and 0x06, and the default and cancel options are at 0x08 and 0x09, respectively.

App Tags

// TODO

Group 3 Tags

// TODO

Group 4 Tags

// TODO

Group 5 Tags

Group 5 is used a more general form of the Delay tag. Exact durations have not been tested.

Group Type Pause Duration
5 0 Short
5 1 Long
5 2 Longer

Grammar Tags

// TODO

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.


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=11888"