Core concepts

Find explanations for how the Convai Unity SDK works at runtime — connections, sessions, embodiment, dialogue state, and event-driven responses.

The Core Concepts section explains the systems that run beneath every Convai character in your scene — the runtime layers that manage connections, the session state machine that governs each character's lifecycle, the per-character embodiment layer that drives modules like Gaze and Emotion, the turn-taking system that controls who speaks and when, and the event components that let your scene react to what happens at runtime.

Start with Runtime architecture if you are new to the SDK internals. Read the other pages when you need to configure a specific system or understand why the SDK behaves a certain way.

Runtime architecture Runtime layers, interface inventory, and what you can replace.

Session lifecycle State machine, per-character sessions, persistence, and reconnection.

Character embodiment The per-character composition root, deterministic tick, and single-writer rules for Animator and facial blendshapes.

Dialogue state The eight-value dialogue state model every embodiment module reads.

Asset ownership and copy-on-write Why editing a package-shipped profile creates a project copy instead of editing in place.

Turn-taking modes Hands-free vs. push-to-talk — every field and policy explained.

Voice activity detection Server default vs. custom detection thresholds resolved at connect time.

Event system Relay components, payload types, and subscription patterns.