Documentation

The **Harmony Dialogue System** simplifies the integration of interactive dialogues into Unity projects. With support for both 2D and 3D environments, this package enables developers to effortlessly create engaging dialogue between characters and players. It supports both Ink files (Using the Inky Unity System) and allows developers to make use of TXT files and other Text asset formats by either using the default system or easily developing their own parsing code. 

   The Harmony Dialogue System is compatible with Ink dialogue files and the Inky Unity integration system. However, these are **separate components** that require additional installation.

      View the full  documentation at [<https://kindhearted-fiber-243.notion.site/Harmony-Dialogue-System-b8bf355dd132413b806293c4fe8d5925?pvs=4>](<https://kindhearted-fiber-243.notion.site/Harmony-Dialogue-System-b8bf355dd132413b806293c4fe8d5925>).

Quick Setup

1. Setup Prefabs:

   • Locate the provided Prefab named "Dialogue" in the package’s Harmony Dialogue System/Prefabs folder.
   • Add the "Dialogue" Prefab to your Canvas within the Unity scene.

2. Select Trigger Type:

   • Based on your project's environment (2D or 3D), choose between "DialogueTrigger2D" and "DialogueTrigger3D" prefabs in the Harmony Dialogue System/Prefabs folder.
   • Both trigger types come equipped with a Box Collider (2D or 3D), which can be customized as per your requirements.
   • The Dialogue Trigger scripts includes a SettingsType option that allows users to choose between two options for configuring trigger settings:
     • Use a Dialogue Object Settings: Select this option to reference an external Dialogue Settings object. This allows you to reuse predefined settings across multiple dialogue triggers.
     • Use Script Settings: Select this option to use the settings defined directly within the Dialogue Trigger script itself.
   • To get started, choose one of the options in the SettingsType dropdown:
     • If using a Settings Object: Create or assign an existing Dialogue Settings object.
     • If using Script Values: Adjust the settings directly within the Dialogue Trigger script to customize the behavior for this specific trigger.
   • Finally set the Player Tag to the tag of the Player object in your scene or the object interacting with the Dialogue. It is defaulted as Player

3. Customize Dialogue Events:

   • Utilize Unity Events provided within the Dialogue Trigger script for additional customization. These are called DialogueEnterEvent and DialogueExitEvent.
   • Subscribe functions to these events to trigger actions when the player enters the Dialogue Trigger. They are used to show the Alert Sprite on top of the Player in the example 2D and 3D scene.

4. Using other options to Initiate Dialogue:

   • Optionally, if the user wants the dialogue to start once the game begins, feel free to put the Dialogue Start Trigger into the game scene.
   • In situations you don’t want to use any of the Triggers but want to initiate dialogue or want further customizations of Dialogue settings. Check the Customization and Settings section on the full documentation at https://kindhearted-fiber-243.notion.site/Harmony-Dialogue-System-b8bf355dd132413b806293c4fe8d5925?pvs=4.

5. Setup Ink System (Optional):

   • In order to make use of the Ink system with this system. Go to Tools>Harmony Dialogue>Ink Settings and ensure that Ink Installed is checked Yes (If not, install Inky Unity from the Asset Store) and then click Enable Ink Integration.

6. Attach Dialogue Data:

   • Assign a TXT file or an Ink JSON file containing the dialogue content to the script component on the chosen Dialogue Trigger.

7. Initiate Dialogue:

   • With the setup complete, you're ready to initiate dialogues within your Unity project.

   It is key to note that each Dialogue Trigger and corresponding TXT or Ink File is for each Dialogue Moment. So a scene can have several Dialogue Triggers with as many TXT or Ink Files. Each Trigger is treated as a separate game Object on its own controlled by the Dialogue Manager.

   This setup guide provides a streamlined approach to integrating the Harmony Dialogue System into your Unity projects. For advanced customization and usage scenarios, refer to the subsequent sections for in-depth explanations and examples on the full documentation at https://kindhearted-fiber-243.notion.site/Harmony-Dialogue-System-b8bf355dd132413b806293c4fe8d5925?pvs=4.

Customization and Settings

 In order to customize the UI, Go to the Dialogue Prefab. It contains two things. Dialogue Panel (which is what is in charge of the UI aspect of the Dialogue and is what should be customized to suit whatever UI you wish to use for your project). Certain Key UI elements such as DialoguePanel, DialogueText, SpeakerName and Portrait are UI elements called by the Script by the Dialogue Manager Game Object.

Dialogue Manager:

    The Dialogue Manager is a major part of the Harmony Dialogue system managing the states of dialogue. In situations that a user may not want to use a Collider Trigger to trigger dialogue. The dialogue offers a function called EnterDialogueMode that takes in the Text Asset file as well as the file type the text asset file is in (Ink or TXT for custom files). An example of the EnterDialogueMode is:

public void StartDialogue(TextAsset text)
{
  DialogueManager.instance.dialogueSystemOnEvent += StartMoving;
  DialogueManager.instance.dialogueSystemOffEvent += StopMoving;
	DialogueManager.instance.EnterDialogueMode(text, FileTypeUsed.Ink);
  DialogueManager.instance.ClearOffEvent();
}

   Another example can be found in the Dialogue2DTrigger and 3DTrigger which make use of this function to start a dialogue.

      Dialogue Manager also contains two Unity Actions called dialogueSystemOnEvent and dialogueSystemOffEvent that are called when the Dialogue starts and ends respectively. You can access these via code. An example of them being used is shown below:

public void StartDialogue(TextAsset text)
{
  DialogueManager.instance.dialogueSystemOnEvent += StartMoving;
  DialogueManager.instance.dialogueSystemOffEvent += StopMoving;
	DialogueManager.instance.EnterDialogueMode(text, FileTypeUsed.Ink);
  DialogueManager.instance.ClearOffEvent();
}

• Dialogue Manager:

    The **Dialogue Manager** Game Object within the Dialogue Prefab encapsulates essential scripts for managing dialogues.
  

  • Dialogue UI: Customize the appearance and layout of the entire dialogue UI.
  • Dialogue Text: Define the text displayed by the dialogue system.
  • Dialogue Choice Prefab: Modify the appearance and behavior of dialogue choice buttons to suit your project's aesthetics and requirements.
    • Dialogue Choices are instantiated within a vertical layout group based on the number of available options, providing flexibility in presentation.
  • Choices Container: This is the vertical layout group that contains all the choices.
  • TXTReader: A scriptable object asset for custom parsing of TXT files. It is defaulted to the default txt reader created by me.
  • Seconds to Wait: Set the duration to wait before automatically closing the Dialogue UI when the dialogue ends.
  • Dialogue Passing Type: Define how dialogue transitions to the next sequence:
    • Time-based transition after a specified duration. (Automatic)
    • User-initiated transition via button press or key press. (Manual)
    • Using Both (Both)
  • Dialogue Manager also contains two Unity Actions called dialogueSystemOnEvent and dialogueSystemOffEvent that are called when the Dialogue starts and ends respectively.

Character Manager:

• Character Manager:

     The **Character Manager** script facilitates the management of characters involved in dialogues.
  

  • Character Name: Define the UI element displaying the character's name.
  • Character Portrait: Specify the UI element displaying the character's portrait.
  • Default Portrait: Set a default portrait used for characters lacking specific portraits.
  • Character Changed: A Unity Event<Character> triggered whenever the speaking character changes to a new character. If one wants to get subscribe to an event every time a new dialogue line come up, the EachDialogueLine Action can be made use of.
  • Character List: Maintain a list of characters, providing flexibility in dialogue interactions and storytelling. Characters will be explained further in the next section

Input Customization:

• Input Dialogue Manager:

     The **Input Manager** script enables customization of input buttons for interacting with the dialogue system.
  

  • Easily modify input settings without directly altering other scripts.
  • Seamlessly switch between the old and new Unity Input Systems by adjusting the return statements within specific functions.
  • Configure interaction buttons or keys to suit user preferences or project requirements.
  • It does this by using functions that return bools used by the Dialogue system to interact with the Dialogue Trigger. You can change the structure of these return statements to either return a Key Down press from the Old or new Input System;

Characters

   Characters play a crucial role in enhancing the flexibility and depth of interactions within the **Harmony Dialogue System**. Each character represents an individual speaker within a dialogue sequence, allowing for nuanced storytelling and dynamic interactions.

Character Management:

• Automatic Character Creation:
  • Characters are automatically generated by the system if not explicitly defined, simplifying setup for basic dialogue systems.
  • For more advanced customization and control, developers have the option to create and manage characters manually through the Character Manager.

Character Parameters:

1. Name:
   • Unique identifier for each character within the system.
   • Names must be distinct to differentiate between characters. This means that multiple characters cannot share the same name.
2. Display Name:
   • Name to be displayed in the Character UI. This name does not have to be unique and multiple characters can share the same display name.
   • If left null, the name displayed will be defaulted to the Name variable.
3. Portrait:
   • Image representing the character displayed during dialogue interactions.
4. Character GameObject:
5. Character Speaking Event (characterSpeaking):

Customization Options:

• InvokeCharacter Function:
• Collaboration with Dialogue Scripts:
• LookForCharacterTag Function:

Advanced Features:

• Dynamic Character Interactions:
• Tag Integration:

Tags

  Tags are dynamic markers embedded within dialogue text files or Ink files, providing additional context and functionality to dialogue interactions within the **Harmony Dialogue System**. By leveraging tags, developers can customize character behavior, appearance, and interactions on a per-line basis, enriching the storytelling experience.

Tag Format:

• Tags are written in the format: #key:value.