Narrative design usage examples

Four worked Narrative Design examples from a single-trigger welcome sequence to an adaptive multi-section scenario with dynamic feedback.

The following examples show how to compose ConvaiNarrativeDesignManager, ConvaiNarrativeDesignTrigger, and IConvaiNarrativeDesign into complete, working setups. They are ordered from simple to advanced and cover different domains to illustrate the breadth of what Narrative Design supports. Each example is self-contained — start from whichever matches your current complexity level.

Example 1: scripted welcome sequence

Complexity: Beginner | Activation mode: Manual | Features used: Manager, Trigger (Manual), one template key

Scenario: A visitor arrives at a reception desk. A "Start" button in the UI kicks off the experience by sending a single trigger that moves the character from an idle state into an active welcome section.

Setup

1

Prepare the scene

Add ConvaiNarrativeDesignManager to the character GameObject and sync sections from the dashboard. You need at least two sections: an idle section (where the character waits) and a welcome section (where the character begins the experience).

2

Set the visitor's name before the session

Before starting the session, send a template key so the character can reference the visitor by name:

public class ReceptionController : MonoBehaviour
{
    [SerializeField] private ConvaiNarrativeDesignManager _narrativeManager;
    [SerializeField] private string _visitorName;

    private void Start()
    {
        _narrativeManager.UpdateAndSendTemplateKey("VisitorName", _visitorName);
    }
}
3

Add a Manual trigger

Add ConvaiNarrativeDesignTrigger to any GameObject (it won't be in the world — it's driven by UI). Set Activation Mode to Manual and fetch/select the welcome trigger from the dashboard.

4

Wire the UI button

In the Button component's On Click () event, assign the ConvaiNarrativeDesignTrigger and select ConvaiNarrativeDesignTrigger.InvokeTrigger.

5

Wire the section event

In the Manager's Narrative Sections list, find the welcome section entry and add an OnSectionStart listener. Point it to whatever should change in the scene when the welcome begins — for example, enabling a name badge UI or starting an ambient animation.

What happens at runtime: Player clicks Start → InvokeTrigger() sends the trigger to the backend → the graph moves to the welcome section → OnSectionStart fires on the welcome section entry → the character begins the welcome.

Example 2: branching conversation

Complexity: Intermediate | Activation mode: Manual (code-driven) | Features used: Manager, IConvaiNarrativeDesign, InvokeSpeech, multiple template keys

Scenario: An orientation assistant can guide users through three independent topic areas (facilities, systems access, policies). Topic selection is driven by UI buttons, and the user can navigate freely between topics. Open-ended follow-up questions are supported after each topic.

Setup

Sync all topic sections in the Manager. No ConvaiNarrativeDesignTrigger component is needed — triggers are sent directly via IConvaiNarrativeDesign.

public class OrientationController : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;
    [SerializeField] private ConvaiNarrativeDesignManager _narrativeManager;
    [SerializeField] private TextMeshProUGUI _activeTopicLabel;

    private void OnEnable()
    {
        _character.NarrativeDesign.OnSectionChanged += OnSectionChanged;
    }

    private void OnDisable()
    {
        _character.NarrativeDesign.OnSectionChanged -= OnSectionChanged;
    }

    // Called by UI buttons
    public void SelectTopic(string triggerName)
    {
        _character.NarrativeDesign.InvokeTrigger(triggerName);
    }

    // Called by a free-text input field's submit event — plain text context injection
    // The character responds naturally in its own words
    public void AskFollowUp(string userQuestion)
    {
        _character.NarrativeDesign.InvokeSpeech(userQuestion);
    }

    // Called when a scripted announcement is needed — character says this verbatim
    public void AnnounceToUser(string announcement)
    {
        _character.NarrativeDesign.InvokeSpeech($"<speak>{announcement}</speak>");
    }

    private void OnSectionChanged(string previous, string next)
    {
        // Update breadcrumb UI — look up the human-readable name from the Manager
        if (_narrativeManager.FindSectionConfig(next) is { } cfg)
            _activeTopicLabel.text = cfg.SectionName;
    }
}

Assign trigger names to buttons in the Inspector: "TopicFacilities", "TopicSystemsAccess", "TopicPolicies".

Set TriggerOnce = false on all triggers so the user can revisit any topic. Send template keys (UserName, Department) from a form before the session opens using UpdateTemplateKeys.

InvokeSpeech has two modes: plain text makes the character respond naturally in its own words (useful for free-text follow-up questions); wrapping the message in <speak> tags makes the character say that text verbatim (useful for scripted announcements or exact prompts). Neither mode advances the graph. See Control character speech for the full reference.

Example 3: proximity-triggered exhibit tour

Complexity: Intermediate | Activation mode: Proximity | Features used: Manager, Trigger (Proximity), zone events, batch template keys

Scenario: A product showroom has five display stations. As the visitor walks toward each station, a host character begins narrating that product. Each station is independent and can be visited in any order.

Setup

Create one ConvaiNarrativeDesignTrigger per station. For each:

  • Activation Mode: Proximity

  • Proximity Radius: adjust per station size (visible as green sphere gizmo in Scene view)

  • Trigger Once: true

  • Reset On Scene Load: true (so the tour resets on each visit)

Wire station-specific context via template keys. Populate them from a ScriptableObject at Start():

Use OnPlayerEnterZone to highlight the product model (for example, enable an outline shader). Use OnPlayerExitZone to remove the highlight.

Example 4: adaptive scenario with dynamic feedback

Complexity: Advanced | Activation mode: Code-driven | Features used: Manager, IConvaiNarrativeDesign, OnSectionDataReceived, BehaviorTreeConstants, dynamic template keys, retake flow

Scenario: A technical skills evaluator runs a multi-step scenario. After each step, the learner's performance is scored. The character's level of guidance and the scenario's challenge level adapt dynamically based on the running score. The scenario can be retaken, resetting all state.

Session lifecycle

Implementation

BehaviorTreeConstants is a JSON string you author in the Convai dashboard per section. It carries any data you want to inject into Unity from the graph — time limits, scoring thresholds, hint flags, or other scenario parameters. The SDK delivers it in every NarrativeSectionData payload.

BehaviorTreeCode and BehaviorTreeConstants are read-only from the SDK side. They carry data authored in the Convai dashboard and are not modifiable at runtime from Unity.

Next steps

Narrative design scripting referenceTroubleshoot narrative design

Last updated

Was this helpful?