Starting Dialogue

Once you've written a script and have tested in the editor as much as you want, the next thing you'll want to do is actually run it in your game.

A runtime instance of the script is called a Dialogue.

A Simple Dialogue Runner

To make things convenient, SUDS Pro comes with a class called Suds Pro Runner. This acts as an "anchor" for a dialogue in the world, and organises everything for you - you then subclass it to decide when to trigger the start of the dialogue.

In the Example Project, our Suds Pro Runner subclass triggers the start of the dialogue based on combination of a collider overlap, and a player prompt. We'll do something a little simpler for this tutorial.

Creating a Suds Pro Runner subclass

1. Somewhere in your Content Browser, click "Add > Blueprint Class"
2. When prompted to Pick Parent Class, select the "All Classes" search box
3. Search for "sudsprorunner" and pick "Suds Pro Runner"
4. Give the new Blueprint a name of your choice, maybe "BP_TestDialogueRunner" or similar.

NOTE: Previously this class was known as BP_SudsProDialogueRunner, but from 1.5.1 this has been replaced with this new class. It's a new class because a property type had to change, and we couldn't change the type without breaking people's code. To upgrade from BP_SudsProDialogueRunner, re-parent any Blueprint subclasses to Suds Pro Runner, or replace level instances using the right-click > Replace Selected Actors With option. Properties are convertible so should retain their values.

Adding a Box Collider

Let's make the runner start our dialogue when the player overlaps with it. For that, we'll need a box collider on the Blueprint you just created.

1. Double-click to open the BP_TestDialogueRunner you just created
2. In Components in the top-left, click Add, and type "box" in the search
3. Pick "Box Collision" and accept the default name

You should now have a box collider in your Blueprint, like this:

To make it easier to find it in the world, let's make the box bigger than default. Select the "Box" component, then find "Shape" > "Box Extents" in Details and make it bigger, say 200 units in all dimensions:

Triggering the Dialogue

Now we need to make the dialogue start when the player overlaps with this box.

1. Right-click the "Box" entry in the components list
2. Select "Add Event" and then "OnComponentBeginOverlap"

This will open the Event Graph for your Blueprint. We need to add a little bit of code to this overlap event; re-create the nodes shown below:

What we're doing here is that when a component overlaps this box, we check if it's a Character, and if so, whether it's player controlled. If so, we trigger the "Start Dialogue" event, which is defined in the Suds Pro Runner parent class.

Important: Right now, we don't have any UI to display our dialogue, so nothing will actually seem to happen when you trigger this runner! Temporarily, add the following debug message nodes after the Start Dialogue so you can see something happen; you can remove this once your UI is set up.

Putting it in the world

To actually see this in action, you'll need to put an instance of your Blueprint in the world.

Drag your BP_TestDialogueRunner from the Content Browser into the viewport and place it where you like in the world. It's invisible, so put it somewhere you can easily find when playing.

Once it's in the world, you need to tell it what dialogue script to run. With the actor you just created selected, find the "Dialogue" section in Details, and set the "Script" property by picking "MyFirstScript" from the drop-down:

Testing

If you now play in the editor and run your character over that (invisible) spot, you should see the debug print happen in the top left:

Note: Because we're not showing a proper UI, or stopping the character from moving, you can trigger the runner multiple times if you run past it and back over it again. This will display an error message like: "Attempted to start dialogue twice! Ignoring". Don't worry about that for now; once we have a UI the player will be stopped from moving until the dialogue ends so this won't be able to happen.

If you want, you can now proceed to the next part of the tutorial, defining the UI. But if you want a little more detail about exactly what's going on here, carry on.

Async Loading Dialogue scripts

Just calling StartDialogue is fine, but you will see a message in the log about it having to load the script synchronously. You can remove this warning by pre-loading the script asynchronously by calling LoadScriptAsync a little bit before you need it.

For example, in the Example Project, we call LoadScriptAsync when the player triggers the colliders which show the talk prompt, so that by the time they trigger the dialogue the script is probably loaded (they're very fast to load).

What's happening under the hood?

Suds Pro Runner makes everything much simpler and generally it's a good idea to use it, but in case you want to know what's going on under the hood, here's a few more details.

One level down from the runner, SUDS Pro gives you a few convenience methods on top of base SUDS to start dialogue; this is the first thing that the runner's Start Dialogue function calls:

In C++, this is available as USudsProLibrary::StartDialogueWithParticipants.

There are variations of this function which take only a single participant, or none, but this is the most commonly useful one.

This function does a number of things:

1. Creates a dialogue instance from the script
2. Restores the saved state, if any (lets characters remember previous conversations)
3. Creates the UI needed to display it (via an extendable UI link class - defaulted in this case)
4. Starts the dialogue

SUDS Pro differs from base SUDS here in that it organises the creation of the UI automatically; although of course you can customise what that UI is.

An explanation of the input parameters to this function:

1. Owner: this is the object which will own the runtime dialogue instance. See Dialogue Owners
2. Script: this is the script asset to create the dialogue from, e.g. MyFirstScript
3. Participants: participants are objects which have some interest in the dialogue, for example providing variables or receiving events. Actors for characters in the dialogue will usually be participants, but any object can be one.
4. Start Label: If blank, the dialogue starts from the beginning of the script, but if you provide a label here, you can start from any label defined in the script.
5. Saved State: You can extract the saved state from a dialogue at any time, which includes the line the dialogue is on, and the variable state. Passing it back in here will restore the state rather than starting the dialogue fresh; useful for persistent dialogue.
6. Ui Class: Optional class which provides the link between this dialogue and the UI. If blank the global settings are used. See UI for more details.

Dialogue Owners

The StartDialogue functions ask for an owner of the dialogue; this is important to determine the lifecycle of the dialogue. You can leave the owner as null, but it means the dialogue is owned by the temporary package, which you probably don't want. When using Suds Pro Runner, it acts as the owner because it exists in the world as a representation of that dialogue.

You could also make the NPC the owner of a dialogue, although the advantage of keeping them as a separate object is that it's easier to represent different dialogues with the same NPC in different places (or even levels).

Dialogue owners are also usually in charge of saving dialogue state. Suds Pro Runner does indeed keep a record of the state so that if you initiate the dialogue twice, any state changes from last time will be remembered.

Next Steps

The next thing we need to do is talk about the dialogue user interface, because without this, we really can't do anything with the dialogue instance except start it! We need the ability to advance through the dialogue, and to make choices. That's the focus of the next section on UI