Help:Text modding: Difference between revisions

From ZeldaMods (Breath of the Wild)
Jump to navigation Jump to search
(Complete text modding page)
(→‎Icons: Remove zr as it's not recognized by any libraries)
 
(15 intermediate revisions by 4 users not shown)
Line 8: Line 8:


==Accessing the files==
==Accessing the files==
All text in the game is located inside the <code>content/Pack/Bootup_xxXX.pack</code> files in what are called [[message archives]]. The <code>xxXX</code> is the locale of the message contents. If you want your mod to support multiple locales, you'll need to make your text changes in every locale file you want to support.
All text in the game is located inside the <code>content/Pack/Bootup_XXxx.pack</code> files in what are called [[message archives]]. The <code>XXxx</code> is the locale of the message contents, for example <code>EUen</code> for European English or <code>USes</code> for American Spanish. If you want your mod to support multiple locales, you'll need to make your text changes in every locale file you want to support.


Copy the message pack(s) you want to edit into your mod folder, then either open them with Wild Bits or unbuild your mod folder with Hyrule Builder. (If you use the latter, the new location of the message pack(s) will be <code>content/Message</code>.)
Copy the message pack(s) you want to edit into your mod folder, then either open them with Wild Bits or unbuild your mod folder with Hyrule Builder. (If you use the latter, the new location of the message pack(s) will be <code>content/Message</code>.)
Line 19: Line 19:
Message files use a key-value system, which marks different strings of text with a unique identifier. When creating new keys, the identifiers can be whatever you want, but ideally, you should make them easy to remember and be consistent. (e.g. Talk01, Talk02)
Message files use a key-value system, which marks different strings of text with a unique identifier. When creating new keys, the identifiers can be whatever you want, but ideally, you should make them easy to remember and be consistent. (e.g. Talk01, Talk02)


The <code>attributes</code> section, while not fully understood, seems to label the actor that is speaking the <code>contents</code> section.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L120</ref> It is unknown if this has any effect in-game.
The <code>attributes</code> section, while not fully understood, seems to label the actor that is speaking the <code>contents</code> section. It is unknown if this has any effect in-game.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L120</ref>  


In the game, the nodes within the <code>contents</code> section are played back top-to-bottom.
In the game, the nodes within the <code>contents</code> section are played back top-to-bottom.
Line 56: Line 56:


When putting spaces or line breaks at the beginning or end of a text node, the entire value of the node must be surrounded by unescaped double-quotes.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L98</ref>
When putting spaces or line breaks at the beginning or end of a text node, the entire value of the node must be surrounded by unescaped double-quotes.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L98</ref>
The font used in the game supports a number of special characters, including <code>♪</code>. For special characters not listed here, such as controller buttons, read about [[#Icons|the icon system]].


===Control nodes===
===Control nodes===


==== Color<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L62</ref> ====
====Color====
A color-type control node sets the color that the text is displayed in. (Note the British-English spelling of the value of <code>kind</code> -- "colour".)<syntaxhighlight lang="yaml">
A color-type control node sets the color that the text is displayed in. (Note the British-English spelling of the value of <code>kind</code> -- "colour".)<syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: set_colour
           kind: set_colour
           colour: blue
           colour: blue
</syntaxhighlight>The value of <code>colour</code> is the name of the color to set: <code>blue</code>, <code>red</code>, <code>grey</code>, <code>light_green1</code>, <code>light_green4</code>, <code>light_grey</code>, <code>orange</code>
</syntaxhighlight>The value of <code>colour</code> is the name of the color to set: <code>blue</code>, <code>red</code>, <code>grey</code>, <code>light_green1</code>, <code>light_green4</code>, <code>light_grey</code>, or <code>orange</code>.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L62</ref>


The color setting will remain in effect until it is changed again or when the end of the <code>contents</code> section is reached. To set the color back to white, use the <code>reset_colour</code> control node:<syntaxhighlight lang="yaml">
The color setting will remain in effect until it is changed again or when the end of the <code>contents</code> section is reached. To set the color back to white, use the <code>reset_colour</code> control node:<syntaxhighlight lang="yaml">
Line 71: Line 73:
</syntaxhighlight>From a game design standpoint, <code>blue</code> is used for the most important bits of information in a piece of dialogue. <code>red</code> is used when this pertains to the progression of a quest or when an irreversible action is about to occur, such as a purchase or exchange. <code>grey</code> is used when the NPC talking is supposed to sound quiet, often used in combination with a text size of <code>80</code>. In the unmodded game, the other colors are only used in the menus.
</syntaxhighlight>From a game design standpoint, <code>blue</code> is used for the most important bits of information in a piece of dialogue. <code>red</code> is used when this pertains to the progression of a quest or when an irreversible action is about to occur, such as a purchase or exchange. <code>grey</code> is used when the NPC talking is supposed to sound quiet, often used in combination with a text size of <code>80</code>. In the unmodded game, the other colors are only used in the menus.


==== Font<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L43</ref> ====
====Font====
A font-type control node sets the font that the text is displayed in.<syntaxhighlight lang="yaml">
A font-type control node sets the font that the text is displayed in.<syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: font
           kind: font
           font_kind: hylian
           font_kind: hylian
</syntaxhighlight>The value of <code>font_kind</code> is the name of the font to set: <code>normal</code> or <code>hylian</code>.
</syntaxhighlight>The value of <code>font_kind</code> is the name of the font to set: <code>normal</code> or <code>hylian</code>.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L43</ref>


The font setting will remain in effect until it is changed again or when the end of the <code>contents</code> section is reached.
The font setting will remain in effect until it is changed again or when the end of the <code>contents</code> section is reached.


==== Icons<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L47</ref> ====
====Icons====
An icon-type control node displays the specified icon inline with the text.<syntaxhighlight lang="yaml">
An icon-type control node displays the specified icon inline with the text.<syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: icon
           kind: icon
           icon: y
           icon: y
</syntaxhighlight>The value of <code>icon</code> is the name of the icon to show. Options include arrows (<code>right_arrow</code>, <code>left_arrow</code>, <code>up_arrow</code>) and controller-related images (<code>gamepad</code>, <code>a</code>, <code>b</code>, <code>x</code>, <code>y</code>, <code>l</code>, <code>r</code>, <code>zl</code>, <code>zr</code>, <code>l_stick_press</code>, <code>l_stick_forward</code>, <code>l_stick_back</code>, <code>r_stick_press</code>, <code>d_pad_down</code>, <code>d_pad_left</code>, <code>d_pad_up</code>, <code>d_pad_right</code>, <code>plus</code>, <code>minus</code>).
</syntaxhighlight>The value of <code>icon</code> is the name of the icon to show. The following is an exhaustive list of valid vanilla options:<ref>https://github.com/ascclemens/msyt/blob/master/src/botw/mod.rs#L453</ref>
* <code>right_arrow</code>
* <code>left_arrow</code>
* <code>up_arrow</code>
* <code>gamepad</code>
* <code>a: 10</code>
* <code>a: 11</code>
* <code>b</code>
* <code>x: 12</code>
* <code>x: 37</code>
* <code>x: 38</code>
* <code>y</code>
* <code>l</code>
* <code>r</code>
* <code>zl: 14</code>
* <code>zl: 15</code>
* <code>l_stick_press</code>
* <code>l_stick_forward</code>
* <code>l_stick_back</code>
* <code>r_stick_press</code>
* <code>d_pad_down</code>
* <code>d_pad_left</code>
* <code>d_pad_up</code>
* <code>d_pad_right</code>
* <code>plus</code>
* <code>minus</code>
* <code>l_stick_left</code>
* <code>l_stick_right</code>
* <code>r_stick_vertical</code>
* <code>r_stick_horizontal</code>


==== Pausing<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L54</ref> ====
Note that some any icon that has a number has multiple images, and the number determines which image is used. Also, some "icons" are actually available as [[#Text_nodes|standard characters]].
 
====Pausing====
A pause-type control node "pauses" for a period of time before playing back the subsequent nodes.<syntaxhighlight lang="yaml">
A pause-type control node "pauses" for a period of time before playing back the subsequent nodes.<syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: pause
           kind: pause
           length: long
           length: long
</syntaxhighlight>The value of <code>length</code> is how long to pause for: <code>short</code>, <code>long</code>, or <code>longer</code>.
</syntaxhighlight>The value of <code>length</code> is how long to pause for: <code>short</code>, <code>long</code>, or <code>longer</code>.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L54</ref>


The duration of a pause can also be specified in frames by using the <code>frames</code> parameter:<syntaxhighlight lang="yaml">
The duration of a pause can also be specified in frames by using the <code>frames</code> parameter:<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L58</ref><syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: pause
           kind: pause
           frames: 30
           frames: 30
</syntaxhighlight>It has not been tested if this assumes a 30FPS frame rate.
</syntaxhighlight>This assumes a 30FPS frame rate. However, frame rate mods should correctly convert your actual frame rate to 30, so a <code>frames</code> value of 30 should always correspond to 1 second, unless your game is lagging.


A common use of pauses is to break up sentences auditorily, like one would when speaking in real life. <code>short</code> is typically used after regular sentences while <code>long</code> and <code>longer</code> are used after exclamations, questions, and ponderings. The specific duration depends on the desired emphasis for the preceding sentence.
A common use of pauses is to break up sentences auditorily, like one would when speaking in real life. <code>short</code> is typically used after regular sentences while <code>long</code> and <code>longer</code> are used after exclamations, questions, and ponderings. The specific duration you should use depends on how much you want to emphasize the preceding sentence.


==== Size<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L85</ref> ====
====Size====
A size-type control node sets the size that the text is displayed in:<syntaxhighlight lang="yaml">
A size-type control node sets the size that the text is displayed in:<syntaxhighlight lang="yaml">
       - control:
       - control:
Line 111: Line 144:
In the unmodded game, <code>80</code> is used for any small text, and <code>125</code> is used for any large text. Other values have not been tested for efficacy.
In the unmodded game, <code>80</code> is used for any small text, and <code>125</code> is used for any large text. Other values have not been tested for efficacy.


==== Variables<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L89</ref> ====
====Variables====
A variable-type control node inserts the value of the specified game variable into the text. Examples include displaying the score of a minigame, showing the cost of the selected item, etc.<syntaxhighlight lang="yaml">
A variable-type control node inserts the value of the specified game variable into the text.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L89</ref> Examples include displaying the score of a minigame, showing the cost of the selected item, etc.<syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: variable
           kind: variable
           variable_kind: 19
           variable_kind: 19
           name: Gerudo_CarryIce_s
           name: Gerudo_CarryIce_s
</syntaxhighlight>The purpose of <code>variable_kind</code> is not fully understood.
</syntaxhighlight>The value of <code>variable_kind</code> is the type of Game Flag that is referenced (this includes strings, int and float values). Refer to existing in-game implementations of variables to determine how to use them in your dialogue.


The value of <code>name</code> is the name of the variable to insert.
The value of <code>name</code> is the name of the variable to insert.


Refer to existing in-game implementations of variables to determine how to use them in your dialogue. Usage of variables requires the associated event to be configured to set them.
Usage of variables requires the associated event flow to be configured to set them. Refer to existing in-game event flows that deal with variables.


=== Dialogue-only control nodes ===
===Dialogue-only control nodes===


==== Animations<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L24</ref> ====
====Animations====
An animation-type control node plays an animation on the currently speaking NPC.<syntaxhighlight lang="yaml">
An animation-type control node plays an animation on the currently speaking NPC.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L24</ref><syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: animation
           kind: animation
Line 132: Line 165:
</syntaxhighlight>The value of <code>name</code> refers to the name of an animation defined in the speaking NPC's <code>.bfres</code> file in <code>content/Model</code>. You can use [[Help:Tools/Switch Toolbox|Switch Toolbox]] to browse the available animations.
</syntaxhighlight>The value of <code>name</code> refers to the name of an animation defined in the speaking NPC's <code>.bfres</code> file in <code>content/Model</code>. You can use [[Help:Tools/Switch Toolbox|Switch Toolbox]] to browse the available animations.


==== Auto-advance<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L28</ref> ====
====Auto-advance====
An auto-advance-type control node "automatically advances" to the next dialogue bubble (without player input) after a given period of time.<syntaxhighlight lang="yaml">
An auto-advance-type control node "automatically advances" to the next dialogue bubble (without player input) after a given period of time.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L28</ref><syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: auto_advance
           kind: auto_advance
           frames: 101
           frames: 101
</syntaxhighlight>The value of <code>frames</code> is the number of frames to wait before auto-advancing. It has not been tested if this assumes a 30FPS frame rate.
</syntaxhighlight>The value of <code>frames</code> is the number of frames to wait before auto-advancing. This assumes a 30FPS frame rate. However, frame rate mods should correctly convert your actual frame rate to 30, so a <code>frames</code> value of 30 should always correspond to 1 second, unless your game is lagging.


==== Choices<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L32</ref> ====
====Choices====
A choice-type control node presents one or more selectable dialogue choices for Link.<syntaxhighlight lang="yaml">
A choice-type control node presents one or more selectable dialogue choices for Link.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L32</ref><syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: choice
           kind: choice
Line 155: Line 188:
           kind: single_choice
           kind: single_choice
           label: 9
           label: 9
</syntaxhighlight>The text for dialogue choices is not defined directly. It must be defined in keys whose identifiers are four-digit numbers surrounded by double-quotes. (e.g. <code>"0009"</code>, which corresponds with the <code>9</code> under <code>choice_labels</code>)
</syntaxhighlight>The text for dialogue choices is not defined directly. It must be defined in keys whose identifiers are four-digit numbers surrounded by double-quotes. (e.g. <code>"0009"</code>, which corresponds with the <code>9</code> under <code>choice_labels</code>) Nintendo's internal MSBT library converts the u16 labels to %04d-formatted strings for accessing the choice text.


The value of <code>selected_index</code> is the choice that is selected by default when the choice selector appears, based off of a zero-indexed list (where 0 is first, 1 is second, 2 is third, and 3 is fourth) of the <code>choice_labels</code>. It does '''not''' refer to choices with the same number system as labels. For example, trying to put <code>9</code> as the value of <code>selected_index</code> in the example above would not work because the list is only four items long; in that case, you would want to put <code>0</code>. From a game design standpoint, this should usually refer to the first choice, <code>0</code>.
Because the MSBT library used by Wild Bits and Hyrule Builder is out of date, the existence of <code>selected_index</code> is, as far as is currently known, an error. Always make sure <code>selected_index</code> is 0. It does not correspond to any valid part of the Choice control's binary layout, so any other value will produce unintended results. The parameter is believed to have been a misunderstanding made by the original reverse engineer, in that all Choice controls come at the end of a dialogue line, and therefore end with <code>0x0000</code>, a "null character" which tells the game that the string has ended. It could also be a Nintendo internal library inconsistency between BotW and other games.


The value of <code>cancel_index</code> is the choice that is selected when the player presses the B button. It refers to the same zero-indexed list as <code>selected_index</code>. From a game design standpoint, this should usually refer to the last choice.
The value of <code>cancel_index</code> is the choice that is selected when the player presses the B button. It refers to the <code>choice_labels</code> as a zero-indexed list, i.e. the first label is 0, second is 1, third is 2, and fourth is 3. From a game design standpoint, this should usually refer to the last choice.


As implied by its name, the purpose of <code>unknown</code> is not understood. It's probably safe to put <code>8</code> as the value, although other values do exist in unmodded message files.
The <code>unknown</code> code field's purpose is the total byte size of the parameters. There is one parameter per choice plus the <code>cancel_index</code>, and each of those is 2 bytes long, so it should always be 6 for a two-choice, 8 for a three-choice, and 10 for a four-choice control.


To implement branching-path dialogue with this control node, the associated event flow must have the switch-type event <code>EventSystemActor::GeneralChoiceX</code>, where <code>X</code> is the number of choices available.
To implement branching-path dialogue with this control node, the associated event flow must have the switch-type event <code>EventSystemActor::GeneralChoiceX</code>, where <code>X</code> is the number of choices available.


==== Sounds ====
====Sounds====
A sound-type control node plays a sound effect from the currently speaking NPC.<syntaxhighlight lang="yaml">
A sound-type control node plays a sound effect from the currently speaking NPC.<syntaxhighlight lang="yaml">
       - control:
       - control:
Line 176: Line 209:
|+
|+
!
!
!Facial Emotion
!Emotion
!Sound
!Sound
|-
|-
Line 227: Line 260:
|Yes
|Yes
|}
|}
There is also a <code>sound2</code> control node. It is unknown how this differs from the <code>sound</code> control node.
There is also a <code>sound2</code> control node. It is unknown how this differs from the <code>sound</code> control node, aside from it only having 1 parameter and being terminated with a <code>0xCD</code> byte (which is represented in MSYT by a <code>205</code> entry.)


== Saving the files ==
==Saving the files==
If you're using Wild Bits, make sure that you save every file you edit. However, this only "saves" to a temporary unsaved version of the message pack. When you're done, '''remember to save the entire pack''' in the SARC tab. Remember to update the mod in your mod-management software.
If you're using Wild Bits, make sure that you save every file you edit. However, this only "saves" to a temporary unsaved version of the message pack. When you're done, '''remember to save the entire pack''' in the SARC tab. Remember to update the mod in your mod-management software.


If you're using Hyrule Builder, simply ensure that your files are saved from the text editor. You'll need to create a new build of your mod folder every time you want to test changes to your mod. Remember to update the mod in your mod-management software.
If you're using Hyrule Builder, simply ensure that your files are saved from the text editor. You'll need to create a new build of your mod folder every time you want to test changes to your mod. Remember to update the mod in your mod-management software.


If you encounter issues, make sure that the indentation in your message files matches the examples in this guide. The YAML format is strict with this because the indentations have special structural meaning.<references />
If you encounter issues, make sure that the indentation in your message files matches the examples in this guide. The YAML format is strict with this because the indentations have special structural meaning.
 
==References==
<references />
<references />
[[Category:Guides]]

Latest revision as of 19:27, 25 February 2023

Breath of the Wild uses a very flexible system for implementing the large majority of text features in the game, including but not limited to dialogue, signboards, quest logs, item descriptions, and menus. This guide will explain how to utilize this system.

Prerequisites

There are two recommended toolsets for modding text:

Accessing the files

All text in the game is located inside the content/Pack/Bootup_XXxx.pack files in what are called message archives. The XXxx is the locale of the message contents, for example EUen for European English or USes for American Spanish. If you want your mod to support multiple locales, you'll need to make your text changes in every locale file you want to support.

Copy the message pack(s) you want to edit into your mod folder, then either open them with Wild Bits or unbuild your mod folder with Hyrule Builder. (If you use the latter, the new location of the message pack(s) will be content/Message.)

Read about message archives for more information on what the subfolders are for.

Editing the files

If you're modding text for an NPC, signboard, item, etc. that already exists, simply find and open the corresponding file. If you're creating a brand-new NPC, signboard, or quest, you'll need to create a new file inside of the corresponding folder. The easiest way to do this is by copying an existing message file in the same folder and deleting the entirety of the entries section.

Message files use a key-value system, which marks different strings of text with a unique identifier. When creating new keys, the identifiers can be whatever you want, but ideally, you should make them easy to remember and be consistent. (e.g. Talk01, Talk02)

The attributes section, while not fully understood, seems to label the actor that is speaking the contents section. It is unknown if this has any effect in-game.[1]

In the game, the nodes within the contents section are played back top-to-bottom.

Here's an example of what a single key looks like in MSYT:

  talk65:
    attributes: Npc_AncientDoctor
    contents:
      - control:
          kind: sound
          unknown:
            - 7
            - 0
      - text: "This is the "
      - control:
          kind: set_colour
          colour: blue
      - text: Hateno Ancient Tech Lab
      - control:
          kind: reset_colour
      - text: "!"
      - control:
          kind: pause
          length: long
      - text: "\nClick, snap!"

Text nodes

A text node is a basic container for text.

Breath of the Wild does not have built-in text wrapping, so line breaks must be specified in the message file itself. You can use Bubble Wrap to help visualize and automatically format your text. To fit aesthetically with the game, all dialogue should be wrapped after a certain width, which the tool also does for you. However, text is often wrapped earlier than this to achieve better visual balance, i.e. to prevent there being only one or two words on a single line, or to break up the text in a way that makes sense, i.e. to emphasize an object, location, action, or task.

The game allows three lines of text per bubble for dialogue and signboards. If there are more than three lines, only the first three lines will be shown initially; the game will then prompt the player to advance the dialogue, which will repeat the process with the remaining lines. To display only one or two lines in a bubble but still have text in following bubbles, use multiple consecutive line breaks until the number of lines exceeds three.

In YAML, line breaks and double-quotes have a special structural meaning, so they cannot be used directly in your text. Instead, \n (for line breaks) and \" (for double-quotes) must be used. This is called "escaping" the characters.

When putting spaces or line breaks at the beginning or end of a text node, the entire value of the node must be surrounded by unescaped double-quotes.[2]

The font used in the game supports a number of special characters, including . For special characters not listed here, such as controller buttons, read about the icon system.

Control nodes

Color

A color-type control node sets the color that the text is displayed in. (Note the British-English spelling of the value of kind -- "colour".)

      - control:
          kind: set_colour
          colour: blue

The value of colour is the name of the color to set: blue, red, grey, light_green1, light_green4, light_grey, or orange.[3] The color setting will remain in effect until it is changed again or when the end of the contents section is reached. To set the color back to white, use the reset_colour control node:

      - control:
          kind: reset_colour

From a game design standpoint, blue is used for the most important bits of information in a piece of dialogue. red is used when this pertains to the progression of a quest or when an irreversible action is about to occur, such as a purchase or exchange. grey is used when the NPC talking is supposed to sound quiet, often used in combination with a text size of 80. In the unmodded game, the other colors are only used in the menus.

Font

A font-type control node sets the font that the text is displayed in.

      - control:
          kind: font
          font_kind: hylian

The value of font_kind is the name of the font to set: normal or hylian.[4]

The font setting will remain in effect until it is changed again or when the end of the contents section is reached.

Icons

An icon-type control node displays the specified icon inline with the text.

      - control:
          kind: icon
          icon: y

The value of icon is the name of the icon to show. The following is an exhaustive list of valid vanilla options:[5]

  • right_arrow
  • left_arrow
  • up_arrow
  • gamepad
  • a: 10
  • a: 11
  • b
  • x: 12
  • x: 37
  • x: 38
  • y
  • l
  • r
  • zl: 14
  • zl: 15
  • l_stick_press
  • l_stick_forward
  • l_stick_back
  • r_stick_press
  • d_pad_down
  • d_pad_left
  • d_pad_up
  • d_pad_right
  • plus
  • minus
  • l_stick_left
  • l_stick_right
  • r_stick_vertical
  • r_stick_horizontal

Note that some any icon that has a number has multiple images, and the number determines which image is used. Also, some "icons" are actually available as standard characters.

Pausing

A pause-type control node "pauses" for a period of time before playing back the subsequent nodes.

      - control:
          kind: pause
          length: long

The value of length is how long to pause for: short, long, or longer.[6] The duration of a pause can also be specified in frames by using the frames parameter:[7]

      - control:
          kind: pause
          frames: 30

This assumes a 30FPS frame rate. However, frame rate mods should correctly convert your actual frame rate to 30, so a frames value of 30 should always correspond to 1 second, unless your game is lagging.

A common use of pauses is to break up sentences auditorily, like one would when speaking in real life. short is typically used after regular sentences while long and longer are used after exclamations, questions, and ponderings. The specific duration you should use depends on how much you want to emphasize the preceding sentence.

Size

A size-type control node sets the size that the text is displayed in:

      - control:
          kind: text_size
          percent: 100

The value of percent is a percentage value relative to the default text size.

In the unmodded game, 80 is used for any small text, and 125 is used for any large text. Other values have not been tested for efficacy.

Variables

A variable-type control node inserts the value of the specified game variable into the text.[8] Examples include displaying the score of a minigame, showing the cost of the selected item, etc.

      - control:
          kind: variable
          variable_kind: 19
          name: Gerudo_CarryIce_s

The value of variable_kind is the type of Game Flag that is referenced (this includes strings, int and float values). Refer to existing in-game implementations of variables to determine how to use them in your dialogue.

The value of name is the name of the variable to insert.

Usage of variables requires the associated event flow to be configured to set them. Refer to existing in-game event flows that deal with variables.

Dialogue-only control nodes

Animations

An animation-type control node plays an animation on the currently speaking NPC.[9]

      - control:
          kind: animation
          name: Think_00

The value of name refers to the name of an animation defined in the speaking NPC's .bfres file in content/Model. You can use Switch Toolbox to browse the available animations.

Auto-advance

An auto-advance-type control node "automatically advances" to the next dialogue bubble (without player input) after a given period of time.[10]

      - control:
          kind: auto_advance
          frames: 101

The value of frames is the number of frames to wait before auto-advancing. This assumes a 30FPS frame rate. However, frame rate mods should correctly convert your actual frame rate to 30, so a frames value of 30 should always correspond to 1 second, unless your game is lagging.

Choices

A choice-type control node presents one or more selectable dialogue choices for Link.[11]

      - control:
          kind: choice
          choice_labels:
            - 9
            - 10
            - 11
            - 12
          selected_index: 0
          cancel_index: 3
          unknown: 8

If you only want to present one dialogue choice (to make NPC monologues more interactive) use the single_choice control node:[12]

      - control:
          kind: single_choice
          label: 9

The text for dialogue choices is not defined directly. It must be defined in keys whose identifiers are four-digit numbers surrounded by double-quotes. (e.g. "0009", which corresponds with the 9 under choice_labels) Nintendo's internal MSBT library converts the u16 labels to %04d-formatted strings for accessing the choice text.

Because the MSBT library used by Wild Bits and Hyrule Builder is out of date, the existence of selected_index is, as far as is currently known, an error. Always make sure selected_index is 0. It does not correspond to any valid part of the Choice control's binary layout, so any other value will produce unintended results. The parameter is believed to have been a misunderstanding made by the original reverse engineer, in that all Choice controls come at the end of a dialogue line, and therefore end with 0x0000, a "null character" which tells the game that the string has ended. It could also be a Nintendo internal library inconsistency between BotW and other games.

The value of cancel_index is the choice that is selected when the player presses the B button. It refers to the choice_labels as a zero-indexed list, i.e. the first label is 0, second is 1, third is 2, and fourth is 3. From a game design standpoint, this should usually refer to the last choice.

The unknown code field's purpose is the total byte size of the parameters. There is one parameter per choice plus the cancel_index, and each of those is 2 bytes long, so it should always be 6 for a two-choice, 8 for a three-choice, and 10 for a four-choice control.

To implement branching-path dialogue with this control node, the associated event flow must have the switch-type event EventSystemActor::GeneralChoiceX, where X is the number of choices available.

Sounds

A sound-type control node plays a sound effect from the currently speaking NPC.

      - control:
          kind: sound
          unknown:
            - 7
            - 0

The numbers under unknown are not fully understood. However, it is known that with the bottom number set to 0, certain values of the top number have the following behaviors:

Emotion Sound
0 Normal No
1 Pleasure No
2 Anger No
3 Sorrow No
4 Shock No
5 Thinking No
6 Normal Yes
7 Pleasure Yes
8 Anger Yes
9 Sorrow Yes
10 Shock Yes
11 Thinking Yes

There is also a sound2 control node. It is unknown how this differs from the sound control node, aside from it only having 1 parameter and being terminated with a 0xCD byte (which is represented in MSYT by a 205 entry.)

Saving the files

If you're using Wild Bits, make sure that you save every file you edit. However, this only "saves" to a temporary unsaved version of the message pack. When you're done, remember to save the entire pack in the SARC tab. Remember to update the mod in your mod-management software.

If you're using Hyrule Builder, simply ensure that your files are saved from the text editor. You'll need to create a new build of your mod folder every time you want to test changes to your mod. Remember to update the mod in your mod-management software.

If you encounter issues, make sure that the indentation in your message files matches the examples in this guide. The YAML format is strict with this because the indentations have special structural meaning.

References