MSBT

MSBT, short for Message Studio Binary Text is a file format used to store messages linked to labels. PylibMS offers several functions used for dealing with these files.

Reading

from lms.message.msbtio import read_msbt_path

msbt = read_msbt_path("path/to/msbt")

A BinaryIO stream object can be passed in or raw bytes when reading. Useful for msbts embedded into archive files.

from lms.message.msbtio import read_msbt

with open("path/to/msbt", "rb") as f:
    msbt = read_msbt(f) 

raw = b"" # Data here
msbt = read_msbt(raw)

Writing

from LMS.Message.MSBTStream import write_msbt_path

write_msbt_path("path/to/msbt", msbt)

If the raw data is needed, write_msbt can be utilized

from lms.message.msbtio import write_msbt

raw_data = write_msbt(msbt)

MSBTEntry

Accessing relevant data is done through the MSBTEntry class.

# By index
entry = msbt.entries[4]
entry.name 
# >>> Entry04

# By name
entry = msbt.get_entry("Entry04")

Messages

Text and control tag related data is accessed through a LMS_MessageText object. This class gives extra tag manipulation functionality.

Text

message = entry.message
message.text
# >>> "Hi"

Control Tags

Control tags are bb-code formatted form of tags that alters the properties of a message or inserts text. PylibMS offers additional tag viewing option and manipulation functions.

Tag Formats

Tags parsed from PylibMS may be encoded or decoded. The type of tag is determined by it's parameters.

• Encoded: [1:3 00-00-00-CD]
• Encoded: [Mii:Nickname 01-00-00-CD]
• Decoded: [System:Color r="0" g="0" b="0" a="255"]
• Decoded: [Reference:SpecialProduct buffer="0" type="Name" sp="Plural"]

The value preceding the colon is always the tag group, and value after is the index/name of the tag in that group. When a config is provided, they are replaced by their names. Tag groups are a container that group related tags together.

Tags modify messages in unique ways and are game-specifc. In some cases, closing tags (i.e [/Group:Tag] is a closing tag) may be used to indicate where the region the tag affects ends.

Tag Properties

Both types of tags are stored as LMS_EncodedTag and LMS_DecodedTag objects. Both share the following properties:

• group_id: The ID of the group.
• tag_index: The index of the tag in the group.
• parameters: The parameters for the tag. May be a list of hex strings or a LMS_FieldMap.
• is_closing: Determines if the tag is a closing tag

Decoded Specific attributes

• group_name: The name of the group for the game.
• tag_name: The name of the tag in the group.
• description: The description of the tag.

Decoded tags loaded from a TitleConfig.

The LMS_MessageText object can be iterated directly. It will split the message by any control tags, allowing you to loop given raw text and tags.

from lms.message.tags.lms_tag import LMS_EncodedTag, LMS_DecodedTag

entry = msbt.get_entry("Entry00")

for part in entry.message:
    match part:
       case LMS_DecodedTag():
          ... # Decoded info actions
       case LMS_EncodedTag():
         ... # Encoded info actions
       case _:
         ... # String info actions

Alternative option is importing the is_tag TypeGuard to catch both tag types.

from lms.message.tags.lms_tag import is_tag

for part in entry.message:
    if is_tag(part):
       ...

The list of control tags can be retrieved from the current message through the message.tags property.

Adding and modifying tags.

Several functions can be utilized to add and modify control tags in messages.

# Appending an encoded tag (Same as '[1:3 00-00-00-CD])
message.append_encoded_tag(1, 3, "00", "00", "00", "CD") 

# Appending an decoded tag, the resulting tag is returned
tag = message.append_decoded_tag("Reference", "SpecialProduct", buffer=0, type="Name", sp="Plural")

Tags may also be added from their string representation.

message.append_tag_string('[1:3 00-00-00-CD]')
message.append_tag_string('[/2:3]')
message.append_tag_string('[Reference:SpecialProduct buffer="0" type="Name" sp="Plural"]']
message.append_tag_string('[/Edward:ToLowerRange]')

You may also access and edit the parameters of the tags.

# Decoded Editing
tag = message.append_decoded_tag("Reference", "SpecialProduct", buffer=0, type="Name", sp="Plural")
field: LMS_Field = tag.parameters.get_field("buffer") 
tag.parameters.set_value("buffer", 1)

Attributes

Attributes are containers of fields mapped to each label in a MSBT file. These may be byte objects when encoded, and LMS_Fields when decoded, depending on if a TitleConfig is provided.

# Encoded attributes (by default)
msbt = read_msbt(f)
entry = msbt.get_entry("Entry00")
entry.attribute
# >>> b"\x01\x01\x00\x00"

# Decoded attributes
msbt = read_msbt(f, attribute_config["Main"])
entry = msbt.get_entry("Entry00")
entry.attribute

# >>> {"RegionJP": LMS_Field(value="Enabled"), "RegionEU": LMS_Field(value="Enabled"), "RegionEU": LMS_Field(value="Disabled"), "RegionKR": LMS_Field(value="Disabled"))

Style Indexes

The index of styles in a MSBP object is located in the MSBTEntry object through the style_index property, and the style object can be accessed through a MSBP object.

index = entry.style_index
style = msbp.styles[index]
# >>> LMS.Project.Definitions.Style.LMS_Style object at 0x00