Example Tutorial Blueprint

[[TOC]]

ℹ️ NOTE: The FINAL Example Project is here

1. Introduction

The purpose of this tutorial is to teach you how to use the dialogue system and how to integrate it into your own project.

The tutorial starts from the Third Person template project.

At the end the player character will be able to talk to our NPC, Mr. Cube and ask him to change his color. Mr. Cube will be happy to do that at the first few times, then he gets annoyed and won't change his color anymore.

2. Getting started

• Create new project using the Third Person Blueprint template project with the name DlgExample.
• Install plugin from marketplace / Get the plugin source from our repository (Click HERE)

3. Setting up an NPC and a Dialogue

a. Create a new NPC Blueprint

• Create a new Blueprint based on Actor with the name BP_MrCube.
• Open the Blueprint, add a Cube component.
• Go the the Class Settings to add the DlgDialogueParticipant interface to the implemented interfaces list.

b. Implement the GetParticipantName Functions

GetParticipantName

• Open the GetParticipantName Function
• Create a DialogueParticipantName Variable of Type equal to Name on the Blueprint and set the value to MrCube.

GetParticipantDisplayName

NOTE: Only Used in the UI

• Open the GetParticipantDisplayName Function
• Create a DialogueParticipantDisplayName Variable of Type equal to Text on the Blueprint and set the value to Mr. Cube.

c. Create & Open Dialogue

• Switch to the Content Browser
• Create a Dialogue asset with the name Dlg_MrCube
• Open the Dialogue
• Drag an edge from the border of the start node and place a Speech node.

d. Setup Participant Name and Text on first Node

• With the recently added node selected, set the Participant Name to MrCube
• Set the Text to I am Mr. Cube! What can I do for you?

e. Setup first Node enter condition and create second Node

• Create a new Speech node and place it on the right of our first Node.
  • Set the Participant Name to MrCube
  • Set the Text to Good to See you again!
• Save the Dialogue
• Select the first Node you added
  • Add an Enter Condition
  • Set the Condition Type to Was node already visited?
  • The node index has to match the white number on the top right corner of the selected node
  • Make sure that the Is Node Visited? checkbox is unchecked

This setup will make sure that MrCube will say his name only the first time the player talks to him.

Observe the fact that the node has an icon on its top left corner - that means that it has an Enter Condition.

f. Setup Player Node and first End Node

• Add a Speech Node child from Node 0
  • Set the Participant Name to Player
  • Set the Text to Could you change your color?
• Add a End Node child from Node 0
• Make and edge from Node 1 to the newly created Nodes: Node 2 and Node 3
• On the edges leading to Node 2 set the Text to Ask him to change his color
• On the edges leading to Node 3 set the Text to Leave

g. Add Selector Node and the two Speech Nodes

• Add a Selector Node child from Node 2
  • Set the Participant Name to MrCube
  • Set the Selector Type to First
• Add a Speech Node child from the Selector Node (`Node 4)
  • Set the Participant Name to MrCube
  • Set the Text to Sure. What color would you like to see?
• Add a Speech Node child from the Selector Node (`Node 4)
  • Set the Participant Name to MrCube
  • Set the Text to I can't keep changing my color all the time! Just leave me alone!

This selector node automatically select the first child with satisfied conditions.

h. Add ColorChangeRequestCount Variable to the NPC Blueprint

• Open the MrCube NPC Blueprint
• Add a new Variable named ColorChangeRequestCount
• Set the Type to Integer
• Compile & Save the Blueprint

i. Setup ColorChangeRequestCount Edge Condition

• Select the Edge from Node 4 to Node 5
  • Add a new Condition
  • Set the Condition Type to Check Class Int Variable
  • Set the Participant Name to MrCube
  • Set the Variable Name to ColorChangeRequestCount
  • Set the Operation to <= (Is Less Than or Equal To)
  • Set the Int Value to 3

This will check the ColorChangeRequestCount variable (you will have to type it the first time you use it).

If it is less than or equal to 3 then Mr. Cube will be happy to change his color.

This selector node automatically select the first child with satisfied conditions - so each time the player asks Mr. Cube to change its color it will either say the text of Node 5 or Node 6 depending on the variable value.

This ColorChangeRequestCount variable will be Modified by the Dialogue in the next step.

j. Setup ColorChangeRequestCount Node Enter Event

• Select the Speech Node 5
  • Add a new Enter Event
  • Set the Event Type to Modify Class Int Variable
  • Set the Participant Name to MrCube
  • Set the Variable Name to ColorChangeRequestCount
  • Set the Int Value to 1
  • Make sure that the Delta checkbox is checked

This will increase the ColorChangeRequestCount variable each time the dialogue enters this node.

k. Setup Final End Nodes

• Add an End Node child from the Speech Node 6
• Add three End Node children from Speech Node 5
  • Set the Edge Text in this order from left to right: Red, Green, Blue
  • Add an Enter Event to all three Nodes
    • The Participant Name should be MrCube
    • The Event Type should be Event
  • Set the Event Name in this order from left to right: ColorToRed, ColorToGreen, ColorToBlue

l. Make Cube NPC Blueprint change his Color

• Open the BP_MrCube Blueprint

SetCubeColor

• Create a new Function with the Name SetCubeColor
  • Add a new Parameter named Color of type Vector
  • Call SetVectorParameterValueOnMaterials on the Cube with the Color input
    • Set the Parameter Name to Color

• Create a New Material like in the picture below and set it on the Cube Component of the BP_MrCube Blueprint

OnDialogueEvent

• In the BP_MrCube Blueprint open the OnDialogueEvent Function
• Place the Switch on Relevant Dialogue Event node - it lists the event names associated with Mr. Cube and works as a normal switch node.

• Call SetCubeColor depending on Event Name

4. Setting up the Player

a. Implement the DlgDialogueParticipant Interface & Required Functions

• Open the Player Blueprint (for example BP_ThirdPersonCharacter)
• Go the the Class Settings to add the DlgDialogueParticipant interface to the implemented interfaces list.
• Add the DialogueContext Variable of Type equal to DlgContext

GetParticipantName

• Open the GetParticipantName Function
• Add the DialogueParticipantName Variable of type Name and set the value to Player

GetParticipantDisplayName

NOTE: Only Used in the UI

• Open the GetParticipantDisplayName Function
• Add the DialogueParticipantDisplayName Variable of type Text and set the value to Player (or whatever you want)

b. Create the StartDialogueWithNPC Custom Event

• Open the EventGraph of your Player Blueprint
• Add a Custom Event with the Name StartDialogueWithNPC
• Set the following inputs
  • Dialogue of type DlgDialogue
  • NPC of type Object
• Start the Dialogue by calling StartDialogue
• Use the return value of the StartDialogue to set the DialogueContext Variable of the Blueprint

c. Create the SelectDialogueOption Custom Event

• Open the EventGraph of your Player Blueprint
• Add a Custom Event with the Name SelectDialogueOption
• Set the following inputs
  • OptionIndex of type Integer
• Call ChooseOption (NOTE: we will handle the return value later when we have the UI setup)

5. Starting the Dialogue

a. Setup Collision on the NPC Blueprint

• Open the BP_MrCube Blueprint
• Add a Sphere Collision Component as a child of the Cube Component
  • Set the Sphere Radius to 300.0

b. Setup Overlap Event with Player on the NPC Blueprint

• Open the EventGraph on the BP_MrCube Blueprint
• Add a Variable with the Name Dialogue of Type DlgDialogue
  • Set the value to Dlg_MrCube
• Add a On Component Being Overlap on the Sphere Collision Component you added in step a.
• Cast the Other Actor to your Player Blueprint and call StartDialogueWithNPC (created here)

6. UI

The UI will be composed from two widgets

• UI_DialogueOption - Which is just a button with a text, this represents a dialogue option
• UI_Dialogue - Which is the main UI widget that contains Text, Participant Name and the multiple ``UI_DialogueOption` options

ℹ️ Example widgets UI_DialogueOption and UI_Dialogue you can copy/look at are in the Example Project

a. Create the UI_DialogueOption Button Widget

• Switch to the Content Browser
• Create a new Widget Blueprint with the name UI_DialogueOption
• Open the UI_DialogueOption Widget Blueperint
• Add a Button Widget with the name ButtonX
  • Set it as the root of the widget
• Add a TextBlock Widget as a child of the Button, with the name OptionText
• Make them both as Variables

b. Setup the UI_DialogueOption Button Widget

• Switch to the Graph of the UI_DialogueOption Widget Blueperint
• Add a new Variable of Type equal to Integer and Name equal to OptionIndex
• Compile & Save the Blueprint

Button Events

• Select the ButtonX Button and add the following three events: On Clicked, On Hovered, On Unhovered
• From the On Clicked call SelectDialogueOption (created here) on your Player Blueprint
• From the On Hovered events set the color of your OptionText

Update

• Add a Custom Event with the Name Update

• Add as input a Parameter with the Name equal to Context and Type equal to DlgContext
• Update the OptionText only if the OptionIndex is Valid and set the widget visibility in each case

c. Create the UI_Dialogue Widget

• Switch to the Content Browser
• Create a new Widget Blueprint with the name UI_Dialogue
• Open the UI_Dialogue Widget Blueperint
• Set a Canvas Panel Widget as the root
• Add the following TextBlock Widgets: SpeakerName and Text
• Add a VerticalBox Widget with the Name equal to Options
  • Add four UI_DialogueOption Widgets inside this vertical box
  • Set the Option Index for each of them
• All these Widgets should be Variables
• All the Variables are anchored to the bottom left

d. Setup the UI_Dialogue Widget

• Switch to the Graph of the UI_Dialogue Widget Blueperint

Close & Event Construct

• On Event Construct hide this Widget
• Add a Custom Event with the Name Close
  • Which hides this Widget
  • And sets the Input Mode and Hides the Mouse

Update

• Add a Custom Event with the Name Update
• Set the SpeakerName, Text and Avatar (Optional)
• Iterate over all the UI_DialogueOption Widgets and call Update (created here) on them

Open

• Add a Custom Event with the Name Open
• Set this Widget to Visible
• Set the Input Mode and Show the Mouse
• Call the Update event on this Widget you created previously

e. Create the UI_Dialogue Widget on Begin Play

• Open the Player Blueprint (for example BP_ThirdPersonCharacter)
• Create a UI_Dialogue Variable of Type equal to UI_Dialogue (This is the Dialogue Widget you created above)
• Open the EventGraph and on Event BeginPlay Create the new widget and add it to viewport

f. Setup UI in StartDialogueWithNPC of the Player Blueprint

• Go to the StartDialogueWithNPC Event you Created
• There at the end Open the UI_Dialogue

g. Setup UI in SelectDialogueOption of the Player Blueprint

• Go to the SelectDialogueOption Event you Created
• There at the end Update the UI_Dialogue
• And reset the DialogueContext and Close the UI_Dialogue if ChooseOption returns false

7. Start

• Place the BP_MrCube Blueprint in the level
• If you start the game and go near him the dialogue should start
• You can ask him to change his color four times before he gets annoyed
• Leaving him and returning again triggers the dialogue again

8. Other

a. Register Console Commands & Clear History

• Open your GameMode Blueprint (for example BP_ThirdPersonGameMode)
• On Event Begin Play call Register Dialogue Console Commands and `Clear Dialogue History
• On Event End Play call Unregister Dialogue Console Commands