Guide: Integrating Actions

Use action nodes when a conversation should trigger gameplay or UI behavior without turning the dialogue system into a game logic monolith.

See it in action — the Control Room Actions demo

The included Demo_ControlRoomActions graph (open DialogueDemo.unity and choose "Control Room Actions" from the demo menu) demonstrates action nodes at work. It shows both fire-and-forget UnityEvent bindings and blocking coroutine handlers — study it before building your own to understand how the graph pauses and resumes around action nodes.

When to use action nodes

• play a sound effect or music cue
• start a countdown or timer
• open or close a UI panel
• unlock a door or trigger a physics event
• trigger a cutscene step or camera cut
• award items or update game state

DialogActionSO — defining an action

Each action is defined as a DialogActionSO asset. Create one via Right-click → Create → Dialogue Graph System → Definitions → Action. Fill in:

• Action ID — the stable string key your handler checks (e.g. PlayExplosion, UnlockDoor). Use this exact ID in graph action nodes and in CanHandle().
• Display Name — human-readable label shown in the Actions sidebar tab.
• Description — tooltip text shown in the editor.
• Wait For Completion — if true, the dialogue pauses until your coroutine finishes.
• Default Delay — optional seconds to wait after a fire-and-forget action before advancing.
• Default Payload JSON — default JSON string passed to your handler if no payload is set on the node.

The Actions sidebar tab in the graph editor shows all DialogActionSO assets in your project. Browse them and assign IDs to action nodes without leaving the editor.

Runtime wiring

1. Add DialogActionRunner to the scene.
2. Assign it to DialogManager.actionRunner.
3. Add your IActionHandler MonoBehaviours to the scene — the runner discovers them automatically.

Fire-and-forget (UnityEvent)

For simple one-shot triggers, bind a UnityEvent directly on the DialogActionSO asset. No code needed.

Blocking coroutine handler

Implement IActionHandler when the dialogue must wait for a result — a countdown, a fade, a door opening animation, or any async gameplay event.

using System.Collections;
using DialogSystem.Runtime.Interfaces;
using UnityEngine;

public class CountdownHandler : MonoBehaviour, IActionHandler
{
    public bool CanHandle(string actionId) => actionId == "Countdown";

    public IEnumerator Handle(string actionId, string payloadJson)
    {
        // Dialogue pauses here until this coroutine completes
        yield return new WaitForSeconds(3f);
    }
}

Other definition ScriptableObjects

Three more definition assets help you set up characters and AI context quickly — all under Create → Dialogue Graph System → Definitions:

DialogCharacterSO — character definitions

Create via Create → Dialogue Graph System → Definitions → Character. Assign in the Characters sidebar tab for bulk portrait, name, and audio assignment across all matching nodes. Key fields:

• Character ID — stable key used to match dialog nodes.
• Display Name — shown in the runtime UI speaker nameplate.
• Portrait — sprite shown in the portrait/avatar frame.
• Short Description, Personality Traits, Speech Style, Example Lines — fed to the AI extension when rewriting or generating dialog for this character, so the AI writes in their voice consistently.

DialogEnvironmentSO — location context

Create via Create → Dialog Graph System → Definitions → Environment. Set in the Context tab to give the AI a sense of place. Key fields: Display Name, Description, Atmosphere, Mood, Time of Day, Canon Rules, Default Tone.

DialogSceneContextSO — full scene context for AI

Create via Create → Dialog Graph System → Definitions → Scene Context. Combines environment, characters, and available actions into one asset. Assign it in the Context tab of the graph editor sidebar. The AI reads this when building prompts — filling it in produces significantly more coherent, canon-consistent results. Key fields: Environment, Participating Characters, Available Actions, Scene Goal, Tone, Extra Rules.