Narrative Design

Structured narrative graphs for Convai AI characters — how sections, triggers, and template keys converge at runtime to create state-aware experiences that adapt to every player action.

What Is Narrative Design?

Narrative Design gives your Convai AI character a structured story to follow. You author a graph of sections (story beats) and triggers (the edges between them) in the Convai dashboard. At runtime, the SDK listens for the server's section-change signals and fires the Unity Events you configure — no polling, no manual state machines.

The character's behaviour, knowledge, and conversational goals automatically adapt to the active section, so the same character can play a neutral receptionist in the opening section and a strict examiner in an assessment section, all within a single session.

How It Works at Runtime

When the player activates a trigger, the SDK sends a named signal to the Convai backend. The backend advances the story graph and responds with a behavior-tree-response message that carries the new section ID and any associated behaviour-tree data. The SDK translates this message into a NarrativeSectionChanged domain event and delivers it to ConvaiNarrativeDesignManager, which fires the per-section Unity Events you wired in the Inspector.

The Three Building Blocks

Component
Where it lives
What it does

ConvaiNarrativeDesignManager

On the character GameObject

Listens for section changes, fires per-section OnSectionStart / OnSectionEnd Unity Events, manages template keys

ConvaiNarrativeDesignTrigger

On any world GameObject

Sends a named trigger to the character when activated (collision, proximity, timer, or manual)

IConvaiNarrativeDesign

Accessed via convaiCharacter.NarrativeDesign

Character-scoped C# API for code-driven trigger invocation, template key control, and async data fetching

You can use any combination of the three. Most projects need all of them; simple linear narratives may only need the Manager and one or two Triggers.

Key Concepts

Term
Definition

Section

A named story beat defined in the Convai dashboard. The character's objectives and behaviour adapt to the active section.

Trigger

A named edge in the story graph. Sending a trigger advances the graph from one section to the next.

Template Key

A runtime key-value pair (e.g., PlayerName = "Alex") that fills placeholders in the dashboard's narrative objectives.

Orphaned Section

A section that was deleted from the dashboard after it was synced locally. Its Unity Events are preserved but will never fire until the section is restored and re-synced.

Behavior Tree Response

The server message that carries the new SectionId plus optional BehaviorTreeCode and BehaviorTreeConstants used by advanced integrations.

Prerequisites

Before using Narrative Design in your project, ensure:

  • The Convai Unity SDK is imported and a ConvaiCharacter component exists in your scene.

  • You have authored a narrative graph in the Convai dashboard with at least one section and one trigger.

  • Your character's ID is set on the ConvaiCharacter component — the SDK cannot fetch or react to sections without it.

What Goes Where

Understanding which component belongs on which GameObject avoids the most common setup mistakes.

Component
Where to place it
Typical count per scene

ConvaiNarrativeDesignManager

On the character's GameObject, alongside ConvaiCharacter

One per character

ConvaiNarrativeDesignTrigger

On any world GameObject — a doorway, an exhibit, a UI event target

One per graph transition point

IConvaiNarrativeDesign

Not placed — accessed via convaiCharacter.NarrativeDesign in code

N/A

In This Section

Quick Start

Get a character responding to section changes in minutes with no code required.

Setting Up the Narrative Design Manager

Add, sync, and configure the Manager component — the listening post for section transitions.

Setting Up Narrative Design Triggers

Place world triggers with collision, proximity, timer, or manual activation.

Template Keys: Dynamic Narrative Variables

Inject runtime values into the character's narrative objectives from the Inspector or code.

Scripting Narrative Design

Full C# API reference for IConvaiNarrativeDesign, NarrativeDesignFetcher, and programmatic control.

Usage Examples

Four worked examples at increasing complexity — from a simple welcome sequence to an adaptive multi-section scenario.

Troubleshooting & Diagnostics

Diagnose every TriggerStatus state, common misconfigurations, and fetch failures.

Conclusion

Narrative Design gives your Convai characters a structured, reactive story without any custom state machine code. The three components — Manager, Trigger, and the IConvaiNarrativeDesign interface — cover everything from a single-button kiosk to a fully adaptive multi-step scenario. Start with the Quick Start to get a working setup in minutes, then explore the deeper configuration guides as your needs grow.

Last updated

Was this helpful?