 |
|
This section explains how to make things happen in the Dialogue System.
Note: If you are making a 2D project, see Enable Physics2D Support.
The Dialogue System Trigger component has three main parts:
You can set the Trigger dropdown to these values:
| Trigger | Description |
|---|---|
| On Use | The player’s Selector or Proximity Selector sent an OnUse message to the GameObject, or the Dialogue System Trigger’s OnUse() method was called manually in a UnityEvent or script. |
| On Start | The component started (e.g., at scene start). See note below. |
| On Save Data Applied | The save system has applied save data to the scene or an equivalent number of frames have passed. |
| On Enable | The component was enabled. |
| On Disable | The component was disabled. |
| On Destroy | The component was destroyed. |
| On Trigger Enter | The component received an OnTriggerEnter message. To use this trigger, the component’s GameObject should have a trigger collider. You may want to set Conditions → Accepted Tags to restrict this trigger to GameObjects with specific tags such as Player. |
| On Trigger Exit | The component received an OnTriggerExit message. |
| On Collision Enter | The component received an OnCollisionEnter message. |
| On Collision Exit | The component received an OnCollisionExit message. |
| On Bark Start | The GameObject started playing a bark (one-off line of dialogue). |
| On Bark End | The GameObject finished playing a bark. |
| On Conversation Start | The GameObject just started as a primary participant in a conversation. |
| On Conversation End | The GameObject just ended a conversation. |
| On Sequence Start | The GameObject just started as a primary participant in a cutscene sequence. This event is not called for in-conversation sequences unless you’ve ticked the Dialogue Manager’s Subtitle Settings → Inform Sequence Start And End checkbox. |
| On Sequence End | The GameObject just ended a sequence. |
Note: When Trigger is set to On Start, if you're using the save system the trigger may start before the save system has applied save data. Use OnSaveDataApplied instead, or set DialogueManager.onStartTriggerWaitForSaveDataApplied = true in code.
Conditions allow you to specify states that must be true for the Dialogue System Trigger to fire, including:
| Condition Type | Description |
|---|---|
| Lua Conditions | Lua expressions such as checking the value of a variable. |
| Quest Conditions | Required quest states. |
| Accepted Tags | For OnCollision and OnTrigger events, the other GameObject must have one of these tags. If Accepted Tags is empty, all GameObjects are allowed. |
| Accepted GameObjects | For OnCollision and OnTrigger events, the other GameObject must be in this list. If Accepted GameObjects is empty, all GameObjects are allowed. |
To add actions to perfom, click the Add Action button. You can add these actions:
| Action | Description |
|---|---|
| Set Quest State | Sets quest and/or quest entry states. (See Quests.) |
| Run Lua Code | Runs Lua expressions. Lua Variable["Actor"] and Variable["ActorIndex"] are set to the interactor's info. (See Logic & Lua.) |
| Play Sequence | Plays a cutscene sequence. Sequence speaker is set to the interactor's info. (See Cutscene Sequences) |
| Show Alert | Shows an alert message through the dialogue UI. |
| Send Messages | Uses Unity’s SendMessage() method to send messages to targets. |
| Bark | Plays a bark (one-off line of dialogue) on a GameObject. |
| Start Conversation | Starts a conversation. |
| Set GameObjects Active/Inactive | Works on entire GameObjects. |
| Set Components Enabled/Disabled | Works on specific components of a GameObject. |
| Set Animator States | Sets animator states on GameObjects. Useful to idle characters when conversations start. |
| OnExecute() UnityEvent | Allows you to specify other actions using a UnityEvent. |
Note: Actor GameObjects used in runtime conversations don't have to be the same as the actors assigned to the conversation in your dialogue database! See below for an explanation.
Conversation Actor & Conversant
When you create a conversation in the Dialogue Editor, you'll assign an actor and a conversant from the dialogue database's list of actors. Typically, the actor is the player and the conversant is the primary NPC involved in the conversation. To view or change the conversation's actor and conversant, click on empty canvas space to inspect the conversation's properties.
Dialogue Entry Node Actor & Conversant
As you add dialogue entry nodes, the editor will automatically assign an actor and conversant to the node. The node's actor is the character who is speaking. The node's conversant is the character being spoken to. To change a node's actor or conversant, click on the node to inspect its properties.
Dialogue System Trigger Actor & Conversant
When you set up a Dialogue System Trigger, you can assign GameObjects to the Start Conversation > Conversation Actor and Conversation Conversant fields. These GameObjects can represent different actors than those assigned to the conversation in your dialogue database.
The conversation will use these GameObjects even if they don't match the actors assigned to the conversation. This allows you to reuse conversations for different characters – for example, reusing the same shopkeeper conversation for all shopkeepers in your game world. (Tip: In your dialogue database, you can create a generic actor named "Shopkeeper" with a generic conversation such as: "Hello, I'm [var=Conversant]. Welcome to my shop!" etc. Then reuse the same shopkeeper conversation for each village's shopkeeper and simply assign the specific village shopkeeper to the Conversation Conversant field.)
Conversation Actor
If you don't assign the Conversation Actor field, the Dialogue System Trigger will try to choose an appropriate GameObject:
Conversation Conversant
If you don't assign the Conversation Conversant field, the Dialogue System Trigger will generally try to choose an appropriate GameObject:
Other Participants
If a dialogue entry node is assigned to an actor that is not the conversation's primary actor or conversant, it will look for a GameObject that has a Dialogue Actor component whose actor dropdown matches the node's actor. Failing that, it will look for a GameObject whose name matches the node's actor.
Logging & Debugging
See Video: Logging & Debugging Tips for instructionson settings the Dialogue Manager's Other Settings > Debug Level to Info to see which GameObjects conversations use as the primary actor and conversant.
Use Bark On Idle to play barks on a GameObject at a random frequency between Min Seconds and Max Seconds. See the Barks section for more information about barks.
Use Range Trigger to activate GameObjects and enable components OnTriggerEnter when specified Conditions are met. When OnTriggerExit occurs, the GameObjects are deactivated and components disabled. This component is useful to enable components such as Bark On Idle only when the player enters a trigger collider that represents proximity to the barker. You can also configure UnityEvents to run on enter and exit.
The Trigger Event, Collision Event, and Timed Event components are general-purpose components that run UnityEvents on trigger collisions, regular physics collisions, and elapsed durations, respectively.
The Dialogue System Events component runs UnityEvents when Dialogue System activity occurs. Each foldout has a section of events that the component can handle when its GameObject receives the corresponding message, such as OnConversationStart. Note that many events, such as OnConversationStart, are only called on the two primary participants and the Dialogue Manager. If you want to run an event regardless of who the participants are, put the Dialogue System Events component on the Dialogue Manager.
You can also handle events in your own scripts by adding special methods described Scripting.
The Dialogue System provides an optional interaction system that can interact with GameObjects (e.g., NPCs) that have Usable components. You can add one of two components to the player:
The Selector component detects Usables by raycasting from a specified position, such as the mouse position or center of screen. When the player presses the use button, it sends an OnUse Message to the Usable. Note: In 2D mode, the camera must be orthographic.
The Proximity Selector component detects Usables when entering trigger colliders. When the player presses the use button, it sends an OnUse Message to the Usable.
When you add a Selector or Proximity Selector, the Dialogue System will ask if you want to add a Selector Use Standard UI Elements component. This component enables the Selector or Proximity Selector to use the Unity UI that's assigned to the Dialogue Manager's Instantiate Prefabs component or, if none is assigned, whatever Standard UI Selector Elements GameObject it finds in the scene. If you want to restyle the Standard UI Selector Elements, locate the prefab (e.g., the one assigned to the Instantiate Prefabs component), duplicate it, assign the duplicate to the Instantiate Prefabs component in place of the original, and customize the duplicate. Or, if you prefer, remove the prefab from the Instantiate Prefabs list and add an instance of a Standard UI Selector Elements prefab directly to the scene.
When the player targets a Usable and presses the Use Key or Use Button, the Selector will send an OnUse(Transform player) message to the usable GameObject. The Dialogue System's triggers, such as Dialogue System Trigger, respond to this message. Your own scripts can also respond to this message by adding an OnUse method such as:
Usables also have UnityEvents that run when selected, deselected, and used. You can configure these events in the inspector.
In a typical configuration, NPCs will have 1-2 components:
The player will typically have 2 components:
Typically in the Dialogue Manager's hierarchy there will be:
The Standard UI Selector Elements can have an Animator component. When the Selector or Proximity Selector deselects a Usable (e.g., player walks away), its Selector Use Standard UI Elements component tells the Standard UI Selector Elements to play the Animator's Hide Animation Trigger. Depending on your visual goals, you may want to adjust what the Animator does, or just remove it and let the Standard UI Selector Elements component immediately activate or deactivate the UI instead of using an animation.
If you're using Standard Usable UI, Selector Use Standard UI Elements will tell the Standard Usable UI's Animator to play its Show & Hide Animation Triggers instead. In this case, you may need to adjust what the Standard Usable UI's Animator does, or just remove it and let the Standard Usable UI component immediately activate or deactivate the UI instead of using an animation.
Interactive conversations usually have a back-and-forth flow, where the actor says a line, then the conversant says a line, and so on. Barks, on the other hand, are one-off lines of dialogue that don't involve a player response menu or any back-and-forth. They're typically spoken by an NPC for atmosphere (e.g., "Nice weather today") or to give the player an idea of the NPC's internal state (e.g., "Reloading. Cover me!"). The content of barks can come from text strings or conversations.
To create a bark conversation, add all bark entries as children of the START node. In other words, the conversation tree will only be one level deep. When an actor barks, the Dialogue System will evaluate all children of the START node to generate a list of currently-valid entries. It will then choose an entry from this list and bark it. By setting Conditions on the bark conversation's dialogue entries, barks can be aware of the current game state. For example, an NPC could bark different things based on its health level.
You can specify priority levels on your bark entries to prevent lower-priority entries from interrupting higher ones. To do this, add a custom Number field named "Priority" to your dialogue entry. Higher values have higher priority. If you don't want to have to add this custom field on each entry, you can add it to the template on the Dialogue Editor Templates Tab. If the dialogue entry doesn't have a custom field named "Priority", it uses a default of 0. When a bark is triggered, if the NPC is already barking, the Dialogue System will only interrupt it to play the new bark if the new bark's Priority is greater than or equal to the current bark's Priority.
Barks don't use the dialogue UI. Instead, barks are played through a bark UI on the barker, which usually appears as text over the NPC's head and/or as audio played through the NPC's audio source. The Dialogue UIs section covers bark UIs.
If you want only one barker in a group to show bark text at time, configure them as Bark Group Members by adding a Bark Group Member component to each. When one member of the group barks, the others will hide any active barks to reduce onscreen clutter.
If you tick a Bark Group Member's Queue Barks checkbox, then when another member is currently barking, it will queue its bark to play after the other member instead of playing immediately and hiding the other member's bark.
The Dialogue System supports 2D physics as well as 3D physics. In Unity, the 2D physics package (Physics2D) can be enabled or disabled, so the Dialogue System's code doesn't assume that Physics2D is available in your project. To tell the Dialogue System that Physics2D is available, open the Welcome Window (Tools → Pixel Crushers → Dialogue System → Welcome Window) and tick Enable 2D Physics or select menu item Tools → Pixel Crushers → Common → Misc → Enable Physics2D Support.... Note: If you're using Unity 2017 or older, this menu item will not be visible.
If you want to enable Physics2D support manually instead, select menu item Edit → Settings → Player, add the scripting symbol USE_PHYSICS2D as shown below:
If you're having trouble getting the Selector component to detect your 2D Usables, please see Why isn't 2D detection working?.
<< Welcome to the Dialogue System for Unity! | Dialogue UIs >>