ZeldaMods (Breath of the Wild)

Help:Text modding: Difference between revisions

Help page Discussion

Help:Text modding (view source)

Revision as of 08:09, 2 August 2022

11,145 bytes added ,  2 years ago
Complete text modding page
VisualWikitext
(Add Text modding page)
 
(Complete text modding page)
Line 17: Line 17:
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 <code>entries</code> section.
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 <code>entries</code> 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) In the game, the <code>contents</code> section is played back top-to-bottom.
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.
 
In the game, the nodes within the <code>contents</code> section are played back top-to-bottom.


Here's an example of what a single key looks like in MSYT:<syntaxhighlight lang="yaml">
Here's an example of what a single key looks like in MSYT:<syntaxhighlight lang="yaml">
Line 42: Line 46:
</syntaxhighlight>
</syntaxhighlight>


=== Text nodes ===
===Text nodes===
A text node is a basic container for text. When putting spaces or line breaks at the beginning or end of a text node, it must be surrounded by double-quotes.
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 [https://lisa-wolfgang.github.io/Bubble-Wrap/ 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, <code>\n</code> (for line breaks) and <code>\"</code> (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.<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L98</ref>
 
===Control nodes===
 
==== Color<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L62</ref> ====
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:
          kind: set_colour
          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>
 
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">
      - control:
          kind: reset_colour
</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> ====
A font-type control node sets the font that the text is displayed in.<syntaxhighlight lang="yaml">
      - control:
          kind: font
          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>.
 
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> ====
An icon-type control node displays the specified icon inline with the text.<syntaxhighlight lang="yaml">
      - control:
          kind: icon
          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>).
 
==== Pausing<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L54</ref> ====
A pause-type control node "pauses" for a period of time before playing back the subsequent nodes.<syntaxhighlight lang="yaml">
      - control:
          kind: pause
          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>.
 
The duration of a pause can also be specified in frames by using the <code>frames</code> parameter:<syntaxhighlight lang="yaml">
      - control:
          kind: pause
          frames: 30
</syntaxhighlight>It has not been tested if this assumes a 30FPS frame rate.
 
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.
 
==== Size<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L85</ref> ====
A size-type control node sets the size that the text is displayed in:<syntaxhighlight lang="yaml">
      - control:
          kind: text_size
          percent: 100
</syntaxhighlight>The value of <code>percent</code> is a percentage value relative to the default text size.
 
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> ====
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">
      - control:
          kind: variable
          variable_kind: 19
          name: Gerudo_CarryIce_s
</syntaxhighlight>The purpose of <code>variable_kind</code> is not fully understood.
 
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.
 
=== Dialogue-only control nodes ===
 
==== Animations<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L24</ref> ====
An animation-type control node plays an animation on the currently speaking NPC.<syntaxhighlight lang="yaml">
      - control:
          kind: animation
          name: Think_00
</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> ====
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">
      - control:
          kind: auto_advance
          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.
 
==== Choices<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L32</ref> ====
A choice-type control node presents one or more selectable dialogue choices for Link.<syntaxhighlight lang="yaml">
      - control:
          kind: choice
          choice_labels:
            - 9
            - 10
            - 11
            - 12
          selected_index: 0
          cancel_index: 3
          unknown: 8
</syntaxhighlight>If you only want to present one dialogue choice (to make NPC monologues more interactive) use the <code>single_choice</code> control node:<ref>https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt#L69</ref><syntaxhighlight lang="yaml">
      - control:
          kind: single_choice
          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>)
 
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>.


=== Control nodes ===
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.
A control node tells the game to do something with the text or NPC, including playing sounds. Read https://github.com/polarbunny/msyt-tools/blob/master/docs/notes.txt for information on all the available control nodes.
 
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.
 
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 looks like this:<syntaxhighlight lang="yaml">
A sound-type control node plays a sound effect from the currently speaking NPC.<syntaxhighlight lang="yaml">
       - control:
       - control:
           kind: sound
           kind: sound
Line 55: Line 172:
             - 7
             - 7
             - 0
             - 0
</syntaxhighlight>The numbers in <code>unknown</code> are not fully understood. We do know that with the bottom number set to 0, certain values of the top number have the following behaviors (WIP):
</syntaxhighlight>The numbers under <code>unknown</code> 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:
{| class="wikitable"
{| class="wikitable"
|+
|+
!
!
!
!Facial Emotion
!
!Sound
!
|-
|-
|0
|0
|
|Normal
|
|No
|
|-
|-
|1
|1
|
|Pleasure
|
|No
|
|-
|-
|2
|2
|
|Anger
|
|No
|
|-
|-
|3
|3
|
|Sorrow
|
|No
|
|-
|-
|4
|4
|
|Shock
|
|No
|
|-
|-
|5
|5
|
|Thinking
|
|No
|
|-
|-
|6
|6
|
|Normal
|
|Yes
|
|-
|-
|7
|7
|
|Pleasure
|
|Yes
|
|-
|-
|8
|8
|
|Anger
|
|Yes
|
|-
|-
|9
|9
|
|Sorrow
|
|Yes
|
|-
|-
|10
|10
|
|Shock
|
|Yes
|
|-
|11
|Thinking
|Yes
|}
|}
There is also a <code>sound2</code> control node. It is unknown how this differs from the <code>sound</code> control node.
== 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 />
<references />
<references />
Retrieved from "https://zeldamods.org/wiki/Special:MobileDiff/11650"