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.MSBTStream import read_msbt

# Create the MSBT object
with open("Drama.msbt", "rb+") as f:
    msbt = read_msbt(f)

Writing

from LMS.Message.MSBTStream import write_msbt

with open("Out.msbt", "wb") as f:
    write_msbt(f, 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

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 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.

Decoded tags are game specific, and are loaded from a TitleConfig. This excludes the System group of tags, which are included in every game that utilizes LMS.

Tag Properties

Both types of tags are stored as LMS_EncodedTag and LMS_DecodedTag objects. Both classes are children of the LMS_TagBase class, so they each share the following properties:

group_index

The index of the group for the game

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 Field map.

group_name

The name of the group for the game. This is optional.

tag_name

The name of the tag in the group. This is optional.

Accessing tags

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

entry = msbt.get_entry("Entry00")
entry.message.tags
# >>> [<LMS.Message.Tag.LMS_Tag.LMS_EncodedTag object at 0x00>, <LMS.Message.Tag.LMS_Tag.LMS_DecodedTag object at 0x1

The LMS_MessageText object is also to be iterated directly. It will split the message by any control tags, allowing you to loop given raw text and tags. With isinstance, you can access the tags mid iteration.

from LMS.Message.Tag.LMS_Tag import LMS_TagBase

entry = msbt.get_entry("Entry00")
for part in entry.message:
    # Catching all tags
    if isinstance(part, LMS_TagBase):
        ...

for part in entry.message:
    # Catching encoded and decoded tags
    if isinstance(part, LMS_DecodedTag):
        ...
    elif isinstane(part, LMS_EncodedTag):
        ...

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 (same as'[Reference:SpecialProduct buffer="0" type="Name" sp="Plural"]', only valid if a Config was used when reading)
message.append_encoded_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('[Reference:SpecialProduct buffer="0" type="Name" sp="Plural"]']

## Attributes
Attributes are containers of [fields](https://github.com/AbdyyEee/PylibMS/wiki/LMS_Field) 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](https://github.com/AbdyyEee/PylibMS/wiki/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