> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design/setting-up-the-narrative-design-manager.md). # Configure the narrative design manager `ConvaiNarrativeDesignManager` is the permanent listening post on your character. It subscribes to section-change signals from Convai and forwards them to the Unity Events you configure in the Inspector. One Manager per character is the standard setup; it lives on the character GameObject for the lifetime of the scene. ### Add the component {% stepper %} {% step %} #### Select the character GameObject Choose the GameObject that has your `ConvaiCharacter` component. The Manager auto-detects the character if both components are on the same GameObject. {% endstep %} {% step %} #### Add the component In the Inspector, click **Add Component** and navigate to **Convai > Narrative Design Manager**. The **Character** field is populated automatically if a `ConvaiCharacter` is on the same GameObject. If not, drag your character into the field manually.
ConvaiNarrativeDesignManager added to the character GameObject with Character field auto-populated

ConvaiNarrativeDesignManager on the character's GameObject.

{% endstep %} {% step %} #### Sync with the backend Click the **Sync with Backend** button in the Inspector. The Manager calls `FetchAndSyncFromBackend()`, which fetches your character's sections from the Convai dashboard and populates the **Narrative Sections** list. You only need to do this when your section list changes on the dashboard. The section IDs and Unity Event wiring persist between sessions in your scene file.
Narrative Sections list populated after Sync with Backend

Narrative Sections list after a successful sync.

{% endstep %} {% endstepper %} ```mermaid flowchart TD A[Click Sync with Backend] --> B[FetchSectionsAsync] B --> C{Success?} C -- Yes --> D[SyncSectionConfigs] D --> E[Update _sectionConfigs list] E --> F[OnSectionsSynced.Invoke] C -- No --> G[_lastFetchError set] G --> H[Error displayed in Inspector] ``` ### Sync status The **Sync Status** header in the Inspector shows the current state of the last fetch operation. All fields are read-only. | Field | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Is Fetching** | `true` while a fetch operation is in progress. The Sync button is disabled during this time. | | **Last Sync Time** | Timestamp of the last successful sync (format: `yyyy-MM-dd HH:mm:ss`). | | **Last Synced Character ID** | The character ID used in the last successful sync. Useful for verifying the correct character is configured. | | **Last Fetch Error** | The error message from the most recent failed fetch, if any. Empty when the last fetch succeeded. | {% hint style="warning" %} If **Last Fetch Error** is not empty, the most common causes are a missing or invalid API key — see [Configure the API key](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-api-key.md) or a blank character ID on the `ConvaiCharacter` component. {% endhint %} The sync result is also reported via the `OnSectionsSynced` event (see Global events below). The `SectionSyncResult` it carries tells you exactly what changed: | Field | Description | | --------------------- | -------------------------------------------------------------------- | | `SectionsAdded` | Sections new to the local list (not previously synced). | | `SectionsUpdated` | Sections whose name changed on the dashboard. | | `SectionsOrphaned` | Sections removed from the dashboard since the last sync. | | `SectionsReactivated` | Sections that were orphaned but have been restored on the dashboard. | ### Narrative sections After syncing, each dashboard section appears as an entry in the **Narrative Sections** list. Every entry is a `UnitySectionEventConfig` with the following fields: | Field | Type | Description | | -------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Section ID** | `string` (read-only) | Unique identifier matching the section on the dashboard. Never edit this manually. | | **Section Name** | `string` (read-only) | Display name from the dashboard. Updated automatically on the next sync if the name changes. | | **Is Orphaned** | `bool` (read-only) | `true` if this section no longer exists on the dashboard. Orphaned sections show a warning badge and their events will not fire. | | **On Section Start** | `UnityEvent` | Invoked when the character transitions **into** this section. | | **On Section End** | `UnityEvent` | Invoked when the character transitions **out of** this section. | #### Wire section events Click the **+** button on **On Section Start** or **On Section End** to add a listener. You can call any public method on any GameObject in the scene — Animator parameters, AudioSource playback, UI panel activation, and so on. **Example:** To unlock a door when the character enters an "Access Granted" section, drag the door's `DoorController` component into the listener field and select `DoorController.Unlock`.
On Section Start Unity Event wired to a DoorController Unlock method

On Section Start wired to a DoorController component.

#### Orphaned sections A section becomes orphaned when it is deleted from the dashboard but still exists in your local list. Orphaned entries are preserved so you do not lose your Unity Event wiring. Their `OnSectionStart` and `OnSectionEnd` events will never fire at runtime. If you restore the section on the dashboard, click **Sync with Backend** again to reactivate it.
Inspector showing an orphaned section entry with a warning badge

An orphaned section entry in the Narrative Sections list.

{% hint style="danger" %} **Clear All Sections** permanently removes all `UnitySectionEventConfig` entries, including all `OnSectionStart` / `OnSectionEnd` wiring. This action cannot be undone. Use it only when switching to a different character and no longer need the existing wiring. The equivalent runtime call is `ClearAllSectionConfigs()`. {% endhint %} ### Global events The **Events** foldout exposes three global Unity Events that fire regardless of which specific section is active. | Event | Signature | When it fires | | ----------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `OnAnySectionChanged` | `UnityEvent` | Every time the active section changes. Receives the new section ID as a string. | | `OnSectionDataReceived` | `UnityEvent` | Every section transition. Carries the full `NarrativeSectionData` payload including `BehaviorTreeCode` and `BehaviorTreeConstants`. | | `OnSectionsSynced` | `UnityEvent` | After each successful call to `FetchAndSyncFromBackend()` or `FetchAndSyncFromBackendAsync()`. | `OnAnySectionChanged` is useful for UI that needs to reflect the current story state without knowing section IDs in advance — for example, a progress indicator that increments each time the section changes. `OnSectionDataReceived` provides the raw behavior-tree payload. Most projects do not need this directly; it is intended for advanced integrations that interpret `BehaviorTreeCode` or `BehaviorTreeConstants`. ### Inspector reference #### Character Reference header | Field | Default | Description | | ------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- | | **Character** | Auto-detected | The `ConvaiCharacter` (or any `IConvaiCharacterAgent`) to listen to. Auto-found on the same GameObject if left blank. | #### Narrative Sections header | Field | Default | Description | | -------------------------- | -------- | ------------------------------------------------------------------------------ | | **Section Configs** | Empty | List of `UnitySectionEventConfig` entries. Populated by **Sync with Backend**. | | **Active Section Count** | Computed | Number of non-orphaned entries (read-only, shown in Inspector header). | | **Orphaned Section Count** | Computed | Number of orphaned entries (read-only, shown in Inspector header). | #### Template Keys header | Field | Default | Description | | ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Template Keys** | Empty | List of `UnityTemplateKeyConfig` entries (Key / Value pairs). See [Configure narrative template keys](/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design/template-keys-dynamic-narrative-variables.md) for full documentation. | #### Sync Status header | Field | Default | Description | | ---------------------------- | ------- | ------------------------------------------------ | | **Is Fetching** | `false` | Read-only. `true` during an active fetch. | | **Last Sync Time** | Empty | Read-only. Timestamp of last successful sync. | | **Last Synced Character ID** | Empty | Read-only. Character ID used in last sync. | | **Last Fetch Error** | Empty | Read-only. Last error message; empty on success. |
ConvaiNarrativeDesignManager Inspector showing all header sections

Full Inspector view of ConvaiNarrativeDesignManager.

### Next steps {% content-ref url="/pages/TN48vuadtxlKi07jDDXf" %} [Configure narrative design triggers](/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design/setting-up-narrative-design-triggers.md) {% endcontent-ref %} {% content-ref url="/pages/GGAj3nmRIj3JmjXWgn9u" %} [Configure narrative template keys](/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design/template-keys-dynamic-narrative-variables.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design/setting-up-the-narrative-design-manager.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.