Unraed Docs

Documentation for Unraed plugins and projects

Click here to return to table of contents.

Dialogue Tree: Dialogue Controller

Extends: AActor

Actor that serves as a controller linking the various aspects of dialogue behavior: user input, dialogue widgets (or other display schemes), and the dialogue itself. Think of this as the primary interface between the player and dialogue.

Some important considerations:

Contents

  1. Blueprint Callable Methods
  2. Blueprint Implementable Methods
  3. Data Attributes
  4. Configurable Settings

1. Blueprint Callable Methods

The following methods can be called but not overridden via blueprint.

Select Option (BlueprintCallable, Virtual)

/**
* Notifies the dialogue that the user is attempting to select
* the option at the given index.  
* 
* @param InOptionIndex - int32, index of the selection. 
*/
virtual void SelectOption(int32 InOptionIndex) const;


Get Speakers (BlueprintCallable, Virtual, Pure)

/**
* Retrieves the map of names to speaker components for the 
* current dialogue. Empty if the current dialogue is invalid.
* BlueprintCallable. 
* 
* @return TMap<FName, UDialogueSpeakerComponent*>, the map of speakers for
* the current dialogue.
*/
virtual TMap<FName, UDialogueSpeakerComponent*> GetSpeakers() const;


Start Dialogue with Names (BlueprintCallable)

/**
* Starts the provided dialogue with the provided speaker 
* components. Matches speakers to dialogue roles using
* the provided name-speaker pairings. 
* 
* @param InDialogue - UDialogue*, the dialogue to start. 
* @param InSpeakers - TMap<FName, UDialogueSpeakerComponent*>,
* Speaker Components mapped to their names in dialogue.
* @param bResume - bool - If true, the dialogue will resume from the marked
* resume node (if any). If false, the dialogue will start over.
*/
void StartDialogueWithNames(UDialogue* InDialogue, 
   TMap<FName, UDialogueSpeakerComponent*> InSpeakers, bool bResume);


Start Dialogue (BlueprintCallable)

/**
* Starts the provided dialogue with the provided speaker
* components.Matches the speakers to dialogue roles using their dialogue 
* names. Duplicate or unfilled names not allowed.  
* 
* @param InDialogue - UDialogue*, the dialogue to start.
* @param InSpeakers - TArray<UDialogueSpeakerComponent*>, Speaker 
* Components to use.
* @param bResume - bool - If true, the dialogue will resume from the marked
* resume node (if any). If false, the dialogue will start over.
*/
void StartDialogue(UDialogue* InDialogue, TArray<UDialogueSpeakerComponent*> InSpeakers,
   bool bResume);


Start Dialogue With Names At (BlueprintCallable)

/**
* Starts the provided dialogue with the provided speaker
* components at the given dialogue node ID. Matches speakers to dialogue
* roles using the provided name-speaker pairings.
*
* @param InDialogue - UDialogue*, the dialogue to start.
* @param InSpeakers - TMap<FName, UDialogueSpeakerComponent*>,
* Speaker Components mapped to their names in dialogue.
*/
void StartDialogueWithNamesAt(UDialogue* InDialogue, FName NodeID,
	TMap<FName, UDialogueSpeakerComponent*> InSpeakers);


Start Dialogue At (BlueprintCallable)

/**
* Starts the provided dialogue with the provided speaker
* components at the given dialogue node ID. Matches the speakers to
* dialogue roles using their dialogue names. Duplicate or unfilled names
* not allowed.
*
* @param InDialogue - UDialogue*, the dialogue to start.
* @param InSpeakers - TArray<UDialogueSpeakerComponent*>, Speaker
* Components to use.
*/
void StartDialogueAt(UDialogue* InDialogue, FName NodeID,
   TArray<UDialogueSpeakerComponent*> InSpeakers);


End Dialogue (BlueprintCallable)

/**
* Ends the current dialogue. BlueprintCallable. 
*/
void EndDialogue();


Skip (BlueprintCallable)

/**
* Tells the dialogue we want to skip the current speech, if 
* possible. BlueprintCallable. 
*/
void Skip() const;

Note: A common issue encountered here occurs when game input is set to not be allowed in the project settings. This blocks all input, which prevents Skip() getting called. You can bypass this restriction in one of two ways. Either allow game input while in dialogue, or implement an override of OnKeyDown() or OnMouseDown() in a custom Dialogue Widget.

Clear Node Visits (BlueprintCallable)

/**
* Tells the currentdialogue to clear all previous visits from its nodes, 
* so that the nodes register as unvisited. 
*/
void ClearNodeVisits();


Set Speaker (BlueprintCallable)

/**
* Adds the designated speaker to the target dialogue, using the provided
* name as a key. If no such name is present, or if the target dialogue 
* has not been set, does nothing. 
* 
* @param InName - FName, the target name. 
* @param InSpeaker - UDialogueSpeakerComponent*, the speaker component to 
* set.
*/
void SetSpeaker(FName InName, UDialogueSpeakerComponent* InSpeaker);


Get Dialogue Records (BlueprintCallable, Pure)

/**
* Exports a dialogue records struct containing the node visits for 
* all dialogues in the game. Useful for saving.
* 
* @return FDialogueMemory - record of all node visits in the game. 
*/
FDialogueRecords GetDialogueRecords() const;


Clear Dialogue Records (BlueprintCallable)

/**
* Clears node visitation info for all dialogues in the game. 
*/
void ClearDialogueRecords();


Import Dialogue Records (BlueprintCallable)

/**
* Imports a dialogue records struct, adding any recorded visits to the 
* appropriate dialogue's record. 
* 
* @param InRecords - const FDialogueRecords&, the records to load. 
*/
void ImportDialogueRecords(const FDialogueRecords& InRecords);


2. Blueprint Implementable Methods

The following methods are intended to be implemented by the user in blueprint when creating a custom dialogue controller.

Open Display (BlueprintImplementable)

/**
* Opens the user-defined dialogue display.
*/
void OpenDisplay();


Close Display ((BlueprintImplementable))

/**
* Closes the user-defined dialogue display. 
*/
void CloseDisplay();


Display Speech (BlueprintImplementable)

/**
* Displays the specified speech in dialogue. 
* 
* @param InSpeechDetails - FSpeechDetails, struct defining 
* speech details 
* @param InSpeaker - UDialogueSpeakerComponent*, speaker
* component associated with the target speech. 
*/
void DisplaySpeech(FSpeechDetails InSpeechDetails, UDialogueSpeakerComponent* InSpeaker);


Display Options (BlueprintImplementable)

/**
* Displays a set of options for the user to select from 
* in dialogue. 
* 
* @param InOptions - const TArray<FSpeechDetails>&, the speech
* details to display as options. 
*/
void DisplayOptions(const TArray<FSpeechDetails>& InOptions);


Can Open Display (BlueprintImplementable, Pure)

/**
* Checks if we can open the user-defined dialogue display. 
*/
bool CanOpenDisplay() const;


Handle Missing Speaker (BlueprintImplementable)

/**
* User-defined behavior for when a listed speaker component is
* not provided at dialogue start. 
* 
* @param MissingName - const FName&, the name of the missing
* speaker component. 
*/
void HandleMissingSpeaker(const FName& MissingName);


3. Data Attributes

The following are the data attributes associated with the class.

Current Dialogue (BlueprintReadOnly)

Controller Delegates (BlueprintAssignable)

The following are delegates that can be used to assign additional functionality to various phases in dialogue. These are included to provide another avenue for customizing/integrating dialogue into the world of your project. The delegates consist of:

4. Configurable Settings

There are several settings that can be used to configure the behavior of the default BP_BasicDialogueController. These settings, as well as the controller type to use, can be set from ProjectSettings»DialogueTree. For full details, please see the plugin settings documentation. Settings include: