> 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/dynamic-context/dynamic-context-usage-examples.md).

# Dynamic context usage examples

The following examples progress from a single-state Inspector setup to multi-state scripting scenarios. Each example includes the scenario context, concrete setup, and the expected runtime outcome.

{% hint style="info" %}
All examples assume `ConvaiManager` is in the scene with a valid API key configured, and the target NPC has a `ConvaiCharacter` component with a Character ID assigned and is able to hold a conversation.
{% endhint %}

### Safety drill: station tracking

**Context:** A fire suppression certification drill. A trainer NPC guides operators through suppression stations. The character must always know the operator's current station to give station-specific instructions and hazard warnings.

#### Setup (Inspector)

1. Add `ConvaiDynamicContextCommand` to the trainer NPC's GameObject.
2. Set **Command Type** to **Set State**.
3. Set **State Name** to `Station`.
4. Set **State Value** to `Fire Suppression Bay`.
5. Set **Reaction Mode** to **React Immediately** — the character should acknowledge each station transition.
6. Add a trigger collider to the Fire Suppression Bay zone. Wire its `OnTriggerEnter` event to the command's `Execute()` method.

Repeat with a separate child-GameObject command for each additional station, each with the appropriate **State Value**. In each child command's **Target** section, disable **Auto Resolve Character** and assign the NPC's `ConvaiCharacter` explicitly — auto-resolve only searches the same GameObject.

#### Expected outcome

When the operator enters the Fire Suppression Bay, `Execute()` fires. The character receives the updated `Station` state and immediately responds:

> *"You've arrived at the Fire Suppression Bay. With the current extreme hazard rating, confirm your PPE is on before touching any equipment."*

The `Station` state persists in the tracker. If the operator asks "Where am I?" at any point, the character answers with the current station value.

### Onboarding walkthrough: batch state update

**Context:** A corporate onboarding simulation. An HR representative NPC adapts its guidance based on which items a new employee has collected and which checkpoints they have cleared. Two conditions are met simultaneously — they should be sent in one atomic update.

#### Setup (Scripting)

```csharp
using System.Collections.Generic;
using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

public class OnboardingProgressTracker : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _hrCharacter;

    public void OnAccessCardAndBriefingComplete()
    {
        // Batch update — one canonical rebuild, one network round-trip
        _hrCharacter.DynamicContext.SetStates(
            new Dictionary<string, string>
            {
                { "AccessCard", "Collected" },
                { "SecurityBriefing", "Completed" }
            },
            ConvaiContextReactionMode.ReactImmediately
        );
    }

    public void CheckIfReadyForFloorAccess()
    {
        // Read local tracker — no network call
        bool hasCard = _hrCharacter.DynamicContext.TryGetStateValue("AccessCard", out string cardState)
                       && cardState == "Collected";
        bool hasBriefing = _hrCharacter.DynamicContext.TryGetStateValue("SecurityBriefing", out string briefingState)
                           && briefingState == "Completed";

        if (hasCard && hasBriefing)
            Debug.Log("Employee is ready for floor access.");
    }
}
```

#### Expected outcome

`OnAccessCardAndBriefingComplete()` sends one atomic update. The HR character responds immediately:

> *"You've collected your access card and completed the security briefing — you're cleared for floor access. Head to Workstation 4B next."*

`TryGetStateValue` reads from the local tracker with no network round-trip. It returns the current value if the state was set, or `false` if it was never set or has been removed.

### Guided tour: multiple commands and timeline events

**Context:** A museum guided tour. A docent NPC tracks which exhibit is currently active and records visitor interactions as chronological events. The docent uses that history to give personalized recommendations.

#### Setup (Inspector — multiple child commands)

Because `ConvaiDynamicContextCommand` allows only one instance per GameObject, each command lives on a child GameObject of the NPC.

**Child GameObject 1 — "SetActiveExhibit"**

* Command Type: `Set State`
* State Name: `ActiveExhibit`
* State Value: `Ancient Rome Collection`
* Reaction Mode: `SyncOnly` — the exhibit name updates silently; tour narrative drives pacing
* Target → Auto Resolve Character: disabled; Character field: NPC's `ConvaiCharacter`

**Child GameObject 2 — "RecordVisitorQuestion"**

* Command Type: `Add Event`
* Event Text: `Visitor asked about the Colosseum reconstruction`
* Reaction Mode: `Auto`
* Target → Auto Resolve Character: disabled; Character field: NPC's `ConvaiCharacter`

**Child GameObject 3 — "RecordPhotoTaken"**

* Command Type: `Add Event`
* Event Text: `Visitor photographed the gladiator exhibit`
* Reaction Mode: `Auto`
* Target → Auto Resolve Character: disabled; Character field: NPC's `ConvaiCharacter`

Wire each child command's `Execute()` to timeline markers, interaction zones, or UI buttons. Wire the **On Executed** event on each child to drive UI feedback — highlight exhibit cards, update tour progress — without additional scripting.

#### Expected outcome

As the visitor progresses, the docent's canonical context accumulates:

```
ActiveExhibit is Ancient Rome Collection
Visitor asked about the Colosseum reconstruction
Visitor photographed the gladiator exhibit
```

The docent references both the current exhibit and the visitor's specific interactions:

> *"Since you photographed the gladiator exhibit, you might enjoy the additional display on Roman military equipment in the next room."*

### Emergency response: multi-state transition

**Context:** An industrial safety simulation. A supervisor NPC must respond to a simultaneous shift from routine inspection to emergency mode — three conditions change at once, and the character must acknowledge all of them immediately.

#### Setup (Scripting)

```csharp
using System.Collections.Generic;
using Convai.Runtime.Components;
using Convai.Runtime.DynamicContext;
using UnityEngine;

public class EmergencyResponseController : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _supervisorCharacter;

    public void TriggerChemicalLeak()
    {
        // All three states change simultaneously — one atomic update, one canonical rebuild
        _supervisorCharacter.DynamicContext.SetStates(
            new Dictionary<string, string>
            {
                { "OperationMode", "Emergency" },
                { "HazardType", "Chemical Leak — Bay 7" },
                { "EvacuationStatus", "In Progress" }
            },
            ConvaiContextReactionMode.ReactImmediately
        );

        // Log the triggering event after the state batch
        _supervisorCharacter.DynamicContext.AddEvent(
            "Chemical leak alarm triggered at Bay 7 — automated ventilation engaged",
            ConvaiContextReactionMode.SyncOnly
        );
    }
}
```

#### Expected outcome

The supervisor character receives three state updates and one event. The `ReactImmediately` mode on `SetStates` triggers an immediate response acknowledging all simultaneous changes:

> *"Chemical leak at Bay 7 — all personnel evacuate the east wing immediately. Bay 7 ventilation is engaged. Do not re-enter until the all-clear is given."*

Using `SetStates` for three simultaneous transitions produces one canonical rebuild rather than three sequential ones, ensuring the character receives a coherent picture rather than three partial updates.

### Next steps

{% content-ref url="/pages/Pwb170m39yjzkfAghzLG" %}
[Dynamic context scripting API](/api-docs/plugins-and-integrations/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/jLDVtNvrQQtepjrSEeAv" %}
[Sync behavior and timing](/api-docs/plugins-and-integrations/convai-unity-sdk/features/dynamic-context/sync-behavior-and-timing.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/dynamic-context/dynamic-context-usage-examples.md?ask=<question>
```

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.