Dynamic Context
Inject live game state into a Convai character's awareness so it can reference environments, player actions, and simulation events naturally in dialogue.
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 containmentThis 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.
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:
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
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
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 is the fastest way to see it working.
Last updated
Was this helpful?