> For the complete documentation index, see [llms.txt](https://archleaders.gitbook.io/ncf-library/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://archleaders.gitbook.io/ncf-library/other-libraries/msbtlib.md).

# MsbtLib

MSBT Library by GingerAvalanche on GitHub.

## About [MsbtLib](https://github.com/GingerAvalanche/MsbtLib)

[MSBT (Message Standard Binary Table)](https://zeldamods.org/wiki/Msbt) is Nintendo's text container format.\
\
This library parses the binary format into editable C# classes that can be serialized to a pseudo HTML markup or back to binary.

## Usage

Usage examples for reading, writing, and editing MSBT files using [MsbtLib](https://github.com/GingerAvalanche/MsbtLib).

### Reading

#### Reading from a [FileStream](https://learn.microsoft.com/en-us/dotnet/api/system.io.filestream?view=net-7.0)

```csharp
using MsbtLib;

using FileStream fileStream = File.OpenRead("C:/ExtractedMsbt/Msg_USen.product/ActorType/ArmorHead.msbt");
MSBT msbt = new(fileStream);
```

#### Reading from a [byte\[\]](https://learn.microsoft.com/en-us/dotnet/api/system.byte?view=net-7.0) (example from a [SarcFile](https://github.com/ArchLeaders/NCF-Library/blob/master/SarcLibrary/SarcFile.cs))

```csharp
using MsbtLib;
using Nintendo.Sarc;
using Nintendo.Yaz0;

SarcFile bootup = new(File.ReadAllBytes("D:/Botw/Update/content/Pack/Bootup_USen.pack"));
SarcFile langPack = new(Yaz0.Decompress(bootup.Files["Msg_USen.product.ssarc"]));
MSBT msbt = new(langPack.Files["ActorType/ArmorHead.msbt"]);
```

#### Reading from a pseudo HTML [string](https://learn.microsoft.com/en-us/dotnet/api/system.string?view=net-7.0)

{% hint style="warning" %}
Documentation in progress.
{% endhint %}

### Editing

```csharp
using MsbtLib;

.. .. ..

// Deserialize the texts into a generic Dictionary
Dictionary<string, MsbtEntry> texts = msbt.GetTexts();

// Setting an attribute
texts["Armor_001_Head_Name"].Attribute = "NewHylianHoodAttribute";

// Setting localized text
texts["Armor_001_Head_Name"].Value = "New Hylian Hood Name";

// Adding a new entry
texts["Armor_001_Head_Name_New"] = new("", "New Head Armor Name");

// Set the modified texts
msbt.SetTexts(texts);
```

### Writing

#### Writing to pseudo HTML

```csharp
using MsbtLib;

.. .. ..

// Using texts from 'ActorType/ArmorHead.msbt'
Console.WriteLine(texts["Armor_063_Head_Desc"].Value);
```

```
Zora headgear made from dragon scales.
Increases swimming speed and allows you to
<color=Blue>spin</color> to attack underwater. A Great Fairy has
increased its defense by three levels.
```

{% hint style="info" %}
**Valid HTML Tags:**

* Animation - \<animation=\[<mark style="color:blue;">name</mark>] />
* Auto-Advance - \<auto\_advance=\[<mark style="color:blue;">num\_frames</mark>] />
* :information\_source: One Choice - \<choice1=\[<mark style="color:blue;">key</mark>] />
* :information\_source: Two Choice - \<choice2 0=\[<mark style="color:blue;">key</mark>] 1=\[<mark style="color:blue;">key</mark>] cancel=\[<mark style="color:blue;">index</mark>] />
* :information\_source: Three Choice - \<choice3 0=\[<mark style="color:blue;">key</mark>] 1=\[<mark style="color:blue;">key</mark>] 2=\[<mark style="color:blue;">key</mark>] cancel=\[<mark style="color:blue;">index</mark>] >
* :information\_source: Four Choice - \<choice4 0=\[<mark style="color:blue;">key</mark>] 1=\[<mark style="color:blue;">key</mark>] 2=\[<mark style="color:blue;">key</mark>] 3=\[<mark style="color:blue;">key</mark>] cancel=\[<mark style="color:blue;">index</mark>] >
* Font - \<font=\[<mark style="color:blue;">face</mark>] /> *(Only <mark style="color:blue;">Normal</mark> and <mark style="color:blue;">Hylian</mark>)*
* Icon - \<icon=\[<mark style="color:blue;">character</mark>] /> *(Some characters require numbers, e.g. <mark style="color:blue;">A(10)</mark>)*
* Pause for a number of frames - \<pauseframes=\[<mark style="color:blue;">num\_frames</mark>] />
* Pause for a duration - \<pauselength=\[<mark style="color:blue;">duration</mark>] /> *(Only <mark style="color:blue;">Short</mark>, <mark style="color:blue;">Long</mark>, or <mark style="color:blue;">Longer</mark>)*
* Set Text Color - \<color=\[<mark style="color:blue;">color</mark>]> *(Only <mark style="color:blue;">Red</mark>, <mark style="color:blue;">LightGreen1</mark>, <mark style="color:blue;">Blue</mark>, <mark style="color:blue;">Grey</mark>, <mark style="color:blue;">LightGreen4</mark>, <mark style="color:blue;">Orange</mark>, or <mark style="color:blue;">LightGrey</mark>)*
* Reset Text Color to Default - \</color>
* :warning: Sound - \<sound field\_1=\[<mark style="color:blue;">uint8</mark>] field\_2=\[<mark style="color:blue;">uint8</mark>] />
* :warning: Another Sound Type - \<sound2=\[<mark style="color:blue;">uint8</mark>] />
* Text Size - \<textsize percent=\[<mark style="color:blue;">num</mark>] /> *(Use \<textsize percent=<mark style="color:blue;">100</mark> /> to reset)*
* :spades: Variable - \<variable kind=\[<mark style="color:blue;">uint16</mark>] <mark style="color:blue;">name</mark>=\[<mark style="color:blue;">name</mark>] /> *(<mark style="color:blue;">name</mark> must correspond to a variable name in the executable)*
  {% endhint %}

{% hint style="warning" %}
**Extra Info**

:information\_source: These <mark style="color:blue;">key</mark>s are keys for other localized strings. Usually, those keys are read from the same MSBT, but in the case of shops, they are read from the shop NPC's MSBT. The keys are read as <mark style="color:red;">%04d</mark>-formatted strings, e.g. <mark style="color:orange;">'4'</mark> is read as <mark style="color:orange;">'0004'</mark>. The <mark style="color:blue;">index</mark>es are for which choice represents a cancellation.

:warning: It is currently unknown how the game uses these <mark style="color:blue;">uint8</mark>s

:spades: It is currently unknown how the game uses these <mark style="color:blue;">uint16</mark>s
{% endhint %}

#### Writing to a file

```csharp
using MsbtLib;

.. .. ..

msbt.Write("C:/ExtractedMsbt/Msg_USen.product/ActorType/ArmorHead_edited.msbt");
```

#### Writing to a [byte\[\]](https://learn.microsoft.com/en-us/dotnet/api/system.byte?view=net-7.0) (continued example from '[Reading from a byte\[\]](#reading-from-a-byte-e.g.-from-a-sarcfile)')

```csharp
using MsbtLib;
using Nintendo.Sarc;
using Nintendo.Yaz0;

.. .. ..

langPack.Files["ActorType/ArmorHead.msbt"] = msbt.Write();
bootup.Files["Msg_USen.product.ssarc"] = Yaz0.Compress(langPack.ToBinary());
File.WriteAllBytes(bootup.ToBinary());
```

## Download

The C# implementation of MSBT can be downloaded from GitHub - [Direct Download](https://github.com/GingerAvalanche/MsbtLib.git)

{% embed url="<https://github.com/GingerAvalanche/MsbtLib>" %}

{% hint style="success" %}
**Credits**\
[@Kyle Clemens](https://gitlab.com/jkcclemens) - Original Rust Implementation\
[@GingerAvalanche](https://github.com/GingerAvalanche) - C# Implementation and Usage Instructions
{% endhint %}