# Dynamic Context ## Dynamic Context Dynamic Context is the mechanism by which you feed live runtime information — player status, environment conditions, simulation events — directly into a Convai character's awareness during a conversation. Without it, a character knows only what was written into its system prompt at configuration time. With Dynamic Context, it can acknowledge and respond to the world as it changes around it in real time. This section covers every aspect of Dynamic Context: how to set it up without writing a single line of code, how to drive it from scripts when your game logic demands it, and the precise rules that govern when and how updates reach the character. ## How It Works Dynamic Context is built on two concepts: **States** are persistent key-value facts that describe the current condition of something. A state has a name and a value — for example, `"Hazard Level"` is `"High"`, or `"Active Station"` is `"Control Room B"`. When a state changes, the old value is replaced. The character always knows the current value of each state. **Events** are chronological, one-time occurrences appended in order — for example, `"Trainee bypassed emergency lockout"` or `"Visitor asked about reactor containment"`. Events are never replaced or deduplicated; they accumulate as a timeline the character can reference. When the character receives context, it sees states first (in the order they were first introduced), followed by events in chronological order: ``` Active Station is Control Room B Hazard Level is High Trainee bypassed emergency lockout Visitor asked about reactor containment ``` This canonical format is assembled automatically by the SDK. You only supply the names, values, and event text. ## Two Entry Points Dynamic Context can be driven from the Inspector or from C# scripts. Both paths feed the same underlying tracker. ```mermaid flowchart TD A["ConvaiDynamicContextCommand\n(Inspector / UnityEvent)"] B["ConvaiCharacter.DynamicContext\n(Scripting API)"] T["DynamicContext Tracker\nHolds canonical state + events"] Q["Pending queue\n(flushed on conversation start)"] R["RTVI context-update message"] C["Convai character reasoning"] A -->|Execute| T B -->|SetState / AddEvent / ...| T T -->|Conversation not yet started| Q T -->|In conversation| R Q --> R R --> C ``` The **Inspector path** uses `ConvaiDynamicContextCommand`, a no-code component you add to any GameObject. You configure a command type and its parameters directly in the Inspector, then call `Execute()` from any `UnityEvent`, animation timeline, trigger collider, or button click. The **scripting path** accesses `ConvaiCharacter.DynamicContext`, which returns an `IConvaiDynamicContext` interface with seven methods covering every operation from setting a single state to sending raw typed updates. Both paths share the same tracker, the same pre-conversation queue, and the same transport. ## Example: Safety Training Context Mid-Simulation To make this concrete, here is what a safety training character's context might look like partway through a fire emergency drill: ``` Station is Fire Suppression Bay Hazard Level is Extreme Active Suppressant is CO2 Trainee activated water suppressor on electrical fire Trainee bypassed the manual lockout ``` The character can reference any of this naturally: *"I can see you're at the Fire Suppression Bay — with an extreme hazard rating, bypassing the manual lockout is a critical error. Let's walk through what should have happened first."* ## Key Concepts at a Glance

Concept	Description
State	A named, persistent key-value fact. Updated in-place when the value changes.
Event	A chronological, append-only occurrence. Never deduplicated.
Canonical context	The full assembled context string: states (insertion order) then events (chronological).
Reaction mode	Controls whether a context update immediately triggers an LLM response from the character.
Pre-conversation queue	Updates made before a conversation starts are queued and flushed automatically when the conversation begins.
Initial context	A fixed text block set on `ConvaiCharacter` and sent once at connection time, separate from runtime updates.

## What Goes Where

Entry Point	Where / How	Best For
`ConvaiDynamicContextCommand`	Add Component on any GameObject; fires via `Execute()` from any `UnityEvent`	Designers and technical artists; inspector-driven workflows, buttons, timelines, triggers
`ConvaiCharacter.DynamicContext`	Accessed in C# as `character.DynamicContext`	Programmers; game systems, inventory managers, event buses
Initial context (`ConvaiCharacter`)	Dynamic Info (Connection Request) header on the `ConvaiCharacter` Inspector	Fixed scenario facts sent once at session start, before the first conversational turn

## In This Section


Quick Start	Configure your first Dynamic Context update from the Inspector, wire it to a UnityEvent, and watch your character reference live game state in conversation.
Command Component Reference	Complete field-by-field reference for all six command types on `ConvaiDynamicContextCommand`.
Static Context at Connection Time	Set a fixed context block sent once when a conversation starts, before any runtime updates.
Usage Examples	Realistic examples across four simulation scenarios covering the full command surface.
Scripting API Reference	All seven `IConvaiDynamicContext` methods with exact signatures and parameter semantics.
Sync Behavior and Timing	When and how updates are sent; canonical rebuild; pre-conversation queueing; transport details.
Troubleshooting & Diagnostics	Diagnose silent updates, unexpected character responses, and pre-conversation timing problems.

## Conclusion Dynamic Context gives your Convai characters awareness of everything that matters in your simulation — from a trainee's current station to the mistakes they made moments ago. The [Quick Start](/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/dynamic-context/quick-start.md) is the fastest way to see it working. --- # Agent Instructions: 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/unity-plugin-beta-overview/features/dynamic-context.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.