UTTERER USER MANUAL

Table of Contents
Utterer Languages
1. Adding Languages
i. Choose Languages
ii. Add To List
2. Setting a Language
i. Method 1
ii. Method 2
3. Using with UDS
i.UDS Options
4. Using with Text/TextMeshPro
i. Text Options
5. Using with Audiosources
6. Using with Images


Utterer Dialogue System
1. Getting Started
2. Utterance Controls
3. Utterer Object Control
4. Settings
5. Styles
6. Tips


Utterer Dynamics
1. Built-In Dynamics
2. Adding Dynamics in Editor
i. Developer Input
ii. Player Input
3. Removing Dynamics

UTTERER LANGUAGES

Utterer Languages is a localization tool for Text/TextMeshPro, AudioSource, and Image components as well as the Utterer Dialogue System.

WARNING : Deleting the LanguageCodes.txt file in Utterer/Languages/Resources will result in the loss of all available languages in the Choose Languages Menu.

Adding Languages to the Languages In Use List
PLEASE NOTE : It is recommended to add all of the languages you will be using to the Languages In Use list before you start localizing your components.

1. Add an UttererLanguages script to an empty object in the hierarchy.
The script can be found here: Assets/Utterer/Languages/UttererLanguages.cs

2. Select languages from the 'Choose Languages' button.
Click the languages you want to add to the Languages In Use list. To remove a language from the list, select it again in the Choose Languages menu.

Can't Find What You're Looking For in Choose Languages?
1. In the Project window, right click LanguageCodes and select 'Show In Explorer'
The file can be found here: Assets/Utterer/Languages/Resources/LanguageCodes.txt

2. Open the document from the explorer.
3. At the bottom of the list, add the new language in this format :
English Name (iso code) "Local endonym, Roman endonym"
Example: Icelandic (is) "íslenska"

Format explanation :
English Name is used for display and reference purposes during development.
ISO codes are necessary for setting the currency and decimal formats for each language.
Local script endonym is the native name of the language in its native script and only applies to languages written in non-Roman scripts (Arabic, Mandarin, Hebrew, etc).
Roman script endonym is the native name of languages written in Roman script, or the backup native name of a language in a non-Roman script (in case the font doesn't contain the script's characters).

IMPORTANT :
If this language is written Right-To-Left, you must add an asterisk (*) after the iso code so the system knows to reformat when this language is selected.
Example: Fula (ff)* "Fulfulde"

4. When you're finished, save the file. The new language is now in the Choose Languages menu.

Setting A Language
To Set Language in Editor:
1. In the Languages In Use list, check the box of the language you want to set as the current language in use
You can change the current language selection in any UttererLanguages script that is added to an object.
While the application is playing, if no language is selected then the first language in the list will become the current language in use.

To Set Language During Play :
METHOD 1 :
1. Add a Language Chooser prefab to the hierarchy as a child of a Canvas.
Found here: Assets/Utterer/Prefabs/LanguageChooser
This dropdown list allows the user to pick a language at runtime and saves the chosen language as the main language for all other instances of UttererLanguages.

METHOD 2 :
1. Add UttererLanguages to any game object in the hierarchy with a Dropdown component.
UttererLanguages will fill out the Dropdown's Options with its Languages List and work as a Language Chooser at runtime.
While the Languages In Use list displays the English names of each language, Language Choosers will display the native name of each language in its native script if available, else the name will display in Roman script.

Using with UDS
1. Add UttererLanguages.cs to a UDS object in the hierarchy.
In each Utterance, a speaker Text Area and an utterance Text Area is added for each language. UDS will use the current language in use and show the text from that language's text areas.

UDS Options
1. Use File Name to create a new .csv file or find an already existing .csv file in Assets/Utterer/Languages/SavedFiles.
Name only, .csv is included automatically.
2. Save this object's UDS data to a .csv file.
Saves/overwrites all Utterances into the file with the name you entered in File Name.
3. Import UDS data from a .csv file.
Imports Utterances from the file with the name you entered in File Name.
Based on the number of Languages in the Languages List and the number of Utterances in the current UDS, Utterer Languages with UDS reads and writes .csv in the following format:
Utterance 1
Language 1
Speaker, Utterance.
Language 2
Speaker, Utterance.

EXAMPLE:
Utterance 1
English
John, Hello.
Spanish
John, Hola.


Using with Text/TextMeshPro
1. Add UttererLanguages.cs to an object with a Text/TMPro Component.
For every language you added to the Languages In Use list, a Text Area will appear in UttererLanguages for this object. Each Text Area will be named after its respective language.

Text Options
Use Main File Name to create a new .csv file or find an already existing .csv file in Assets/Utterer/Languages/SavedFiles.
1. Enter the name of an already existing file, or enter a unique name to create a new file.
Name only, .csv is included automatically.
When creating a new Text file, it is recommended to give it a distinguishable name such as 'TextObjectName-SceneName'.

Use Subsection to create a new subsection of a file, or find an already existing subsection of a file.
1. Enter the name of an already existing subsection of the file referenced in Main File Name, or enter a unique name to create a new subsection of the file referenced in Main File Name.
This will be used to store/find this Text/TMPro component's data in Main File Name.
When creating a new subsection it is recommended to give the subsection a distinguishable name, such as the name of the text object you are saving so you can easily remember or decipher which Subsection to reference for each Text/TMPro component.

Save Text/TMPro to File
Saves all of the data from Texts to the file you entered in Main File Name. If you entered a subsection, the data will be saved under the name of that subsection.

Import Text/TMPro from File
Imports from the Main File Name and Subsection you have entered. If no Subsection, reads all data from the file with the Main File Name you entered.
Based on the number of Languages in the Languages In Use list, Utterer Languages with Text/TMPro reads and writes .csv in the following format:
Subsection name
Language 1
Text.
Language 2
Text.

EXAMPLE:
Example-DemoScene
English
Hello.
Spanish
Hola.

Using with AudioSources
1. Add UttererLanguages.cs to an object with an AudioSource Component.
For every language you added to the Languages In Use list, an AudioClip field will appear in UttererLanguages under a Sounds foldout. Each field will be named after its respective language.
Whichever language is currently in use will decide which AudioClip is played out of the Sounds list.


Using with Images
Add UttererLanguages.cs to an object with an Image Component.
For every language you added to the Languages In Use list, a Sprite field will appear in UttererLanguages under an Images foldout. Each field will be named after its respective language.
Whichever language is currently in use will determine which Sprite is displayed on the Image component.


UTTERER DIALOGUE SYSTEM (UDS)
The Utterer Dialogue System is built to format itself based on your input so you can easily create and control single person/multiple person dialogue/subtitles/captions.

Getting Started
1. Drag the 'UDS' prefab into the hierarchy.
Found here : Assets/Utterer/Prefabs/UDS
UDS must be a child of a Canvas. UDS works best when the Canvas Scaler's UI Scale Mode is set to scale with screen size, though it will still work with other modes.
2. Increase the size of Utterances.
The Utterances array contains your subtitles/dialogue as individual utterances.

Utterance Controls
1. Add an icon to the Icon field.
Sprite/Texture 2D

2. Input the title/name of the speaker into the Speaker field.
This field is hidden if the system is set to Subtitles or if the No Speaker setting is enabled.

3. Input the dialogue for this utterance into the large text field.
This field is the only one that is always enabled and never hidden.
4. Add a sound to play during this utterance.
You can also loop this sound for the duration of the utterance. The sound field can be left empty.
5. Input into each utterance's Duration field the amount of time you would like it to display itself.
This field and the Break Between field are hidden if the system is set to be interactive.
6. Input the amount of time you want to wait to display the next utterance into the Break Between field.
Utterer will display nothing during this break.

Settings
Pause Scene
Grab the original timeScale, set the timeScale of the scene to 0 until UDS is finished, then set timeScale back to its original value.

Delay Start
The length of time to delay UDS from starting the dialogue/subtitle sequence. Can be null.


System Fade The entire system fades in and out at the beginning and end of the dialogue/subtitle sequence.

Content Fade
Icon, speaker, and dialogue fade in for each utterance if they are enabled.

Using TMPro
Switch the speaker and dialogue Text components to TextMeshPro Text components. Uchecking this switches them back to Legacy Text.

Interactive Inputs
Set the system to allow any key to progress the dialogue, or choose which keys you want to use instead.

Type Writer Effect
Adds one letter at a time like a typewriter. Has a Rate field for you to control the speed.

Styles
No Icons, No Button, No Back, No Outline, No Speaker, No Scrollbar
Hides the icon placeholder, next button, background, outline, speaker, and scrollbar, respectively. If Subtitles is enabled, the icons, next button, speaker, and scrollbar are automatically hidden.
Back, Next, Outline, Scrollbar Colors & Images
If the next button, background, outline, or scrollbar are displayed, you can choose the color and texture (sprite/image) of each in their respective fields.

Speaker Style
Contains settings for the speaker font. This foldout and its contents will be hidden if Subtitles or No Speaker is enabled.
Dialogue Style
Contains settings for the dialogue font. Will be renamed to Subtitle Style if Subtitles is enabled.

Tips
⦁ You can have multiple Utterer Dialogue Systems in a scene but only one can be enabled at a time when the application is playing.
⦁ Use the UDS automatic scaling and anchoring system to set up a basic layout, then in Settings check Custom Layout for ultimate customization.
⦁ Next button has a Text child that when enabled creates a color field for it in the Style foldout.
⦁ The background, outline, and next button objects are set to use 9-slice sprites but you can technically use any sprites as long as you apply the proper settings.

Utterer Dynamics
With Utterer Dynamics, you can make string calls to the system using the format to change strings in any applicable Text/TMPro component at runtime.
Only one instance of Utterer Dynamics is needed in order to control all calls in the scene. UttererDynamics.cs can be added to any object.

Built-In Dynamics
Utterer Dynamics contains several built in calls that are formatted at runtime based on the current culture settings.

DateTimes
Use any of the following calls in any Text/TMPro/UDS/UL text area:
CALLS IDS
System.DateTime.Now.ToLongDateString()
System.DateTime.Now.ToShortDateString()
System.DateTime.Now.ToLongTimeString()
System.DateTime.Now.ToShortTimeString()
System.DateTime.Now.DayOfWeek
System.DateTime.Now.Month
System.DateTime.Now.Year

Currency
Use c (case sensitive) followed by the amount inside the Dynamics indicators
Example if culture is (en) : Adding to any Text/TMPro component's text will be overwritten at runtime as $4,321.56.


Decimals, doubles, floats, etc.
Place the number inside the Dynamics indicators <1234.5678>
Example if culture is (en) : Adding <2552.5225> to any Text/TMPro component's text will be overwritten at runtime as 2552.523.


The Dynamics List
With the Dynamics List you can call your own specific calls and replace them with their ID string. These call and ID strings are saved into Utterer/Dynamics/Resources/ in a file called DynamicsList.json.
To use a call from the Dynamics List, input it into any Text/TMPro/UDS/UL text area.
Example: Hello .

Adding Dynamics to Dynamics List
Add an UttererDynamics script to any gameObject in the scene.


DEVELOPER INPUT
1. Click the 'Add to List' button of the Dynamics List and enter a call key and an ID.
Calls must begin with "<" and end with ">"
EXAMPLE Call: ID: Madsir

Utterer Dynamics can also be used to make specific strings remain a certain color no matter the color of the Text's font.
1. Enter a call key and then in its ID field, type the word 'color' (not case sensitive).
EXAMPLE :
Call:
ID: color
A new color field will appear beneath the ID field. Choose the color you wish and any instance of the call string will display in that color.

PLAYER INPUT
1. Add an Input Field to the hierarchy.
(Works with both Text and TextMeshPro InputFields)
2. Add a new element to Input Field component's On End Edit() and then add the object containing this scene's Utterer Dynamics instance to the new element's object field.
3. Set to On Runtime Only, then call the DynamicsInput(Object) function from UttererDynamics and drag the Input Field object into the method's Object field.
4. Use the InputField's placeholder text to save the inputted text to a call in the Dynamics List, OR use the placeholder text to create a new call to save to the Dynamics List.


EXAMPLE :
If the InputField's placeholder text is "Player Name" Utterer will check the Dynamics list to see if that call exists, and if not, save the call as
So any previously created strings containing will be replaced with the call's ID.
The ID for the call is saved as the string inputted by the player during runtime.

Removing Dynamics
1. Click the Dynamic you want to remove in the Dynamics List.
2. Click the 'Remove from List' button of the Dynamics List.
Utterer will automatically save the Dynamics after you're finished editing the Dynamics List.


Questions, concerns, or suggestions?
contactmadsir@gmail.com
Utterer © 2023 Madsir Studio