> 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/overview/release-notes.md).

# Release notes

Release notes for the Convai Unity SDK — current version highlights, previous release notes, bug fixes, and migration guidance for each release.

Track changes to the Convai Unity SDK across releases, including new features, bug fixes, and configuration changes. The current release is <code class="expression">space.vars.unity\_sdk\_version</code>.

{% updates format="full" %}
{% update date="2026-09-04" tags="v4.6.0,Current" %}

## v4.6.0

**Breaking this release:** `SetExplicitConversationTarget` renames to `SetInitialCharacter`, three Gaze profile Conversation Attention fields are removed and replaced, `headStabilityDegrees` is removed, two Gaze profile defaults changed, and the microphone open timing in multi-character scenes changed. See **Breaking changes and migration** below.

**Multi-character conversations**

* Conversation targeting moved into the SDK: no component to add, no collider, no layer, and no field to fill. `ConvaiManager.ConversationTargeting` reads the player's view by default and scores every candidate by angle with distance as a tiebreak, so it works the same on a mouse, a gamepad, and a head-mounted display. `Mode` chooses `LookAt`, `Proximity`, or `Manual`; `ConvaiManager.TalkTo(character)` points the conversation explicitly for scripted moments
* A room now opens on the character the player is looking at, instead of always the first character in scene order. An assigned **Convai Manager > Initial Character** still wins outright, and the Console names the character it opened on and why
* A character that joins or leaves a connected room is added or removed live, with no reconnect — instantiating a character prefab, or enabling a character `GameObject`, is the whole integration. A room that connected with a single character carries no roster and cannot grow live; the Console names that case and what to do instead
* `ConvaiManager.Events` gains `OnConversationAvailabilityChanged`, `OnConversationTargetChanged` (with phases `Requested`, `Confirmed`, `Failed`), and `OnRoomRosterChanged`
* `Convai.ConfigureConversationTargeting` joins the MCP and Unity Assistant tool set, and `Convai.DiagnoseConversation` reports the roster, the addressed character, and the targeting verdict. Tool contract version `7`
* A **Multi-Character Sample** ships alongside the existing Basic and LipSync samples

**Conversation availability**

* `ConvaiManager.ConversationAvailability` answers whether the player can talk right now — `Offline`, `Connecting`, `Preparing`, `Ready`, `Answering`, `Unavailable` — for `ConvaiManager.AddressedCharacter`, with `ConversationAvailabilityChanged` reporting each move and `CanAcceptPlayerInput()` as the question a UI asks. The same answer is available per character on `ConvaiCharacter.ConversationAvailability`
* The shipped chat field, push-to-talk, and hands-free input all consult this now. The chat field disables until the character can hear, and `ConvaiPlayer.TrySendTextMessage` refuses with a reason a project can show instead of dropping the message silently
* **Behaviour change:** in multi-character scenes the microphone now opens when the room confirms its first character, rather than when the transport connects — typically a fraction of a second later. Single-character rooms are unaffected

**Gaze**

* **Attend To Speaker** on the Gaze component now follows the conversational floor — the player, another character, or both — while a character is not in its own turn, so listeners in a room with more than one participant react to whoever is speaking instead of sitting in `Idle`. Four new settings in the profile's **Conversation** group tune the model: **Typical Pause Before Turning**, **How Much Reactions Vary**, **How Long Attention Fades Over**, and **Shortest Gap Between Listeners Turning**
* Listener attention is now a per-participant value that rises on a speech onset and decays continuously, fixing listeners that turned to a new speaker late, together, or to the wrong person
* The head and chest now follow a moving target continuously instead of in bursts, removing the dead band that caused parked holds and whip-like corrections. A camera cut is now treated as an ordinary look rather than a startle. **Head Speed Limit** drops from 240°/s to 150°/s, and **Turn Speed (Rigs Without Turn Animation)** drops from 140°/s to 90°/s — both are safety ceilings; profiles already authored keep their saved values

**Speech and performance**

* On a character with Lip Sync, the speaking turn now ends on lip sync's own frame data rather than waiting on the silence detector or the service's confirmation, so a character stops performing when its voice stops rather than up to two seconds later. `ConvaiCharacter.IsSpeaking`, `OnSpeechStopped`, and `OnTurnCompleted` are unaffected. The Conversation Flow profile carries a `stopWhenTheVoiceStops` switch for the previous timing, but it ships on and is not exposed in the profile's Inspector or through a public setter, so the new timing is what every character gets
* A character's mouth now settles closed at the end of a sentence instead of hanging open or snapping shut: a new **Settle Duration** (0.35 s) on the Lip Sync component drives a spring-based close, and `LipSyncPlaybackEngine.SettleToRest()` triggers it from code
* A talking hand no longer freezes mid-gesture when a response ends — the gesture now decelerates to rest as its weight fades, starting **Talk Release Lead Seconds** (0.6 s) before the response actually ends
* Lip sync no longer stalls after the first response in a session; every later response now plays with a moving mouth instead of a still one
* `ConvaiCharacter.OnTranscriptReceived` fires. It previously read a message the service does not send, so it never fired in any room and everything downstream of it sat idle — gaze referential glances, and any `IConvaiCharacterBehavior` reacting to what a character said. It now reads the room transcript feed, and its `isFinal` argument comes from the message's own lifecycle instead of being hard-coded to `false`, so consumers gating on the final utterance work. Two consequences: text arrives per sentence rather than per synthesis chunk, and a line that streams before it settles is delivered twice — once interim, once final

**Editor and inspector work**

* Multi-character controls in the **Convai Manager** inspector were renamed for clarity: *Include in Next Room* is now **Characters Joining the Room**, *Within* is **Range (Metres)**, *Seen From* is **Player Camera**, *Scene Characters* is **Characters in Scene**, and *Roster room* / *Single character* are **Several characters** / **One character only**
* The **Convai Manager** inspector's Live section now names who is being addressed, whether the player can talk to them, and one row per character in the room with its status
* The Character inspector now flags a duplicated Character ID before Play mode, instead of only when the room refuses to connect
* The **Convai Player** and **Convai Room Manager** Validation sections were redesigned with a header that reflects the worst check found, instead of a permanently amber header
* Every Convai inspector section now shares one left-edge alignment and one section-padding system

**Unity 6000.5 compatibility**

* The package compiles on Unity 6000.5 again. Unity's scene identity move to a 64-bit `EntityId`, and the deprecation of `Object.GetInstanceID()`, are now routed through compatibility seams (`ConvaiSceneId`, `ConvaiObjectId`, `ConvaiObjectFind`), so ids are unchanged on `6000.0` through `6000.3` and agree with the old ones on `6000.4` and later

**Package dependencies**

* `com.unity.ai.inference` `2.2.1` is a new dependency, for client-side voice activity detection
* `com.unity.nuget.newtonsoft-json` `3.2.2`, `com.unity.ugui` `2.0.0`, and `com.unity.inputsystem` `1.19.0` are retained
* `com.unity.ai.navigation`, `com.unity.collections`, and `com.unity.modules.xr` are no longer declared dependencies

**Breaking changes and migration**

* **`ConvaiManager.SetExplicitConversationTarget` is renamed to `ConvaiManager.SetInitialCharacter`.** The old name is still callable and marked `[Obsolete]`. The rename exists because the old name read like the verb for changing who the player is talking to, but it chooses which character speaks first, and calling it on a connected room queues an ownership reconnect rather than moving the conversation. Replace `SetExplicitConversationTarget(character)` with `SetInitialCharacter(character)` for the same behavior; use `TalkTo(character)` to switch the conversation in a running room
* **The Gaze profile's Conversation Attention fields are removed:** **Shortest/Longest Delay Before Turning**, **Stays With The Conversation For**, and **Looks To Whoever Answers Next**, along with `ConvaiGazeProfile.SpeakerAttentionReactionDelayMin/Max`, `SpeakerAttentionLingerSeconds`, and `SpeakerAttentionHandOffGlanceChance`. Their replacements are **Typical Pause Before Turning**, **How Much Reactions Vary**, **How Long Attention Fades Over**, and **Shortest Gap Between Listeners Turning**. A profile carrying the removed fields loses them silently on its next save — re-apply a personality, or leave the defaults, to pick up the new attention model's tuning
* **The Gaze profile's Ignore Small Target Movement (`headStabilityDegrees`) is removed.** Its replacements on **Head & Body** are **How Quickly The Head Follows Movement** (`HeadFollowSeconds`, default 0.2 s) and **How Quickly The Chest Follows Movement** (`TorsoFollowSeconds`, default 0.35 s). A profile carrying the removed field ignores it from the moment it loads and drops it on its next save; lower **How Quickly The Head Follows Movement** if a fast target trails the head more than wanted
* **Two Gaze profile defaults changed:** **Neck Relaxes During A Turn** (`bodyTurnHeadRelief`) from `0.4` to `1`, and **Chest Speed Limit** (`maxTorsoAngularSpeed`) from `180°/s` to `90°/s`. Existing profiles keep their saved values — only new profiles pick up the new defaults. To pick up the new defaults on an existing profile, set both values by hand
* **Behaviour change:** in multi-character scenes the microphone now opens when the room confirms its first character, rather than when the transport connects
  {% endupdate %}

{% update date="2026-08-14" tags="v4.5.0" %}

## v4.5.0

**Character embodiment**

Five behavior modules now share one component family under **Add Component > Convai > Embodiment**, and each module reads the same dialogue state.

* **Convai Gaze** (`ConvaiGazeController`) replaces the previous Gaze implementation and the Attention module. It decides what the character looks at and performs the look in one component: eye-contact styles (`Natural`, `Speaking Focus`, `Conversation Lock`, `Always Lock`), `ConvaiGazeTarget` for scene objects with priority tier and aim offset, `PlayerAttentionSensor` for "is the player looking at me", a whole-body look-sharing ladder from eyes to head to chest to feet, and an XR eye-tracking extension point through `IPlayerGazeRaySource`
* **Convai Body Animation** (`ConvaiBodyAnimationController`) replaces Dialogue Animation. It builds its own layered `PlayableGraph` in code, so there is no Animator Controller asset to author. It covers idle and talk variants, co-speech gestures, target-aimed gestures, and NavMesh-synced walking with directional starts, planted stops, and turns in place. Animation clips and `ConvaiBodyAnimationSet_Female` ship with the module
* **Convai Body Language** (`ConvaiBodyLanguageController`) is new: breathing, weight shifts, sway, posture pulses, speech-timed head beats, listening lean-in, idle fidget, and startle or amused reactions. It layers on top of the Animator without owning a clip and needs no imported content
* **Emotion** gained semantic expression recipes that resolve onto ARKit, Reallusion CC3 and CC4, and MetaHuman rigs with no per-character authoring, plus resting mood, mood drift, a micro-expression idle layer, and shader-property output. `ConvaiEmotionController.SetMood(label, intensity, transitionSeconds)` and `ClearMood(transitionSeconds)` control mood at runtime, and `DominantEmotionChanged` and `MoodChanged` report resolved expression. Four personalities ship: Composed, Warm, Energetic, and Reserved
* **Conversation flow** supplies the dialogue state the other four modules read

**Character Actions**

* The **Actions Editor** window (**Convai > Actions Editor**) adds reusable Action Sets, Scene Knowledge, Character Settings, and a Live mode with batch progress, timeline, target registry, and per-action insights. The **Try It** box previews an action in Edit mode and dispatches it in Play mode
* Four built-in executors are new: Lead Player To Target, Scan Environment, Count Target Group, and Measure Distance
* `ConvaiActionExecutionResult.Answered("…")` lets an action supply a sentence the character can speak, separate from the diagnostic `Message`. **When It Finishes** authors this per action
* `ConvaiActionFailureReason` reports a typed failure cause on `ConvaiActionExecutionResult` and `ConvaiActionStepReport`. `ConvaiActionParameterValue.Presence` distinguishes an unfilled slot from a blank one. `ConvaiActionDispatcher` exposes `IsBusy`, `PendingBatchCount`, and `CurrentActionName`
* `ConvaiActionExecutorBase`, `ConvaiTargetedActionExecutor`, and `ConvaiCharacterActionExecutor<TPeer>` are the base classes for custom behaviors. `ConvaiPlayerBody` is now public, and `ConvaiActionExecutorBase.ResolvePlayer()` is `virtual`, so first-person rigs that move a child capsule resolve to the player's real position
* Wire parsing was corrected across a large set of dropped and garbled command cases, and a scene-placed `ConvaiActionTarget` is now synced to Convai mid-session

**Authentication**

* Authentication is now a project-level choice between API Key mode and Auth Token mode. Auth Token mode resolves a fresh short-lived credential from a configured endpoint or an `IConvaiAuthTokenProvider` before each room connection, works on Native and WebGL transports, sends the credential in the `API-AUTH-TOKEN` header, and strips the saved account API key from player builds while keeping it for Editor tooling
* `ConvaiManager.ConnectWithAuthTokenAsync` is a one-shot connect for projects whose login layer already holds a Convai auth token. It also supplies `end_user_id` and `end_user_metadata.name` without a registered provider or a configured endpoint

**Session lifecycle**

Idle-warning and idle-deadline events, `ResetIdleTimer` and `ExtendIdleTimeout`, and explicit pause, resume, and reconnect controls are available at runtime. Background behavior is set through the `ContinueAudibly`, `PauseTimeline`, and `MuteButCatchUp` policies, with an observable WebGL fallback from `PauseTimeline` to `MuteButCatchUp`.

**Editor tooling**

* **Convai > Troubleshooter** reports every Convai capability per character as set up, blocked, or set up but inert, with one-click fixes and a **Fix All** action. Extend it with `IConvaiSetupHealthProvider` and `ConvaiSetupHealthRegistry.Register`
* The **Convai** menu was reduced from 17 rows to 9 — see Breaking changes and migration below
* Every Convai inspector and window moved to a shared editor design system, and the Character Rig inspector was rewritten to lead with a Ready or Needs Attention verdict and banded detection confidence
* Opening a package-shipped settings asset is read-only and offers **Create A Project Copy**, which lands the copy under `Assets/Convai/`

**Requirements and dependencies**

The minimum Unity version is `6000.0.80f1`. The package adds three dependencies: `com.unity.ai.navigation`, `com.unity.collections`, and `com.unity.modules.xr`.

**LipSync, samples, and platforms**

* The Lip Sync Sample ships Sofia, a Reallusion CC4 character, in place of Camila
* Built-in viseme maps and lip sync profiles moved from `SamplesShared/Resources/` into the LipSync module and are constructed in code. Project registries under `Resources/LipSync/ProfileRegistries/` are still discovered and still win
* `ConvaiLipSyncSpeechEnergyAdapter` never sampled, so every feature reading speech energy read a flat signal. It now joins the character tick and samples each frame
* The package ships `ConvaiSampleFirstPersonController` and `ConvaiSampleFirstPersonInputs`, a renamed copy of Unity's Starter Assets first-person controller
* Meta Quest push-to-talk release now reads the A, B, X, and Y buttons through Unity's XR input API, and a controller read failure or disconnect fails closed so microphone capture cannot stay open
* The Quest Vision Frame Source has a designed inspector with live capture readout. Vision component foldout states reset once on upgrade

**Breaking changes and migration**

* **Unity 6000.0.80f1 is the minimum editor version.** There is no supported configuration below this floor. Upgrade the editor before upgrading the package
* **Three modules were retired, each with a successor.** Attention is replaced by Convai Gaze, Dialogue Animation by Convai Body Animation, and the facial clip system by the Emotion module's micro-expression layer. Their assemblies, profile assets, and preset slots were removed with them
* **Migrating from Attention or the previous Gaze components:** replace `ConvaiAttentionController`, `ConvaiGazeCoordinator`, `ConvaiHeadLookActuator`, and `ConvaiEyeGazeActuator` with a single `ConvaiGazeController` (**Add Component > Convai > Embodiment > Gaze**). Delete your `ConvaiAttentionProfile`, `ConvaiGazeCoordinationProfile`, `ConvaiGazeEyeProfile`, and `ConvaiGazeHeadProfile` assets — those types are gone and the assets will not deserialize. Tuning values do not carry over; re-tune on a `ConvaiGazeProfile`, or assign none and start from the defaults. Replace a custom `IFocusTargetProvider` or `IGazeIntentProvider` with `IGazeTargetProvider` registered through `RegisterTargetProvider`, `ConvaiAttentionDynamicContextBridge` with `GazeDynamicContextBridge`, and `ConvaiWorldObjectFocusProvider` with `ConvaiGazeTarget`. Replace `ConvaiWorldObjectFocusProvider` before you save the affected scenes, because Unity strips the removed component silently on the next save
* **Migrating from Dialogue Animation:** replace `ConvaiDialogueAnimationController` with `ConvaiBodyAnimationController`, move clips from a `DialogueAnimationLibrary` into a `ConvaiBodyAnimationSet`, and move timing and weight tuning into a `ConvaiBodyAnimationConfig`. Delete the `DialogueAnimatorContract` asset, its four Animator layers, the ping-pong states, and the `ConvaiDialogueSlot_*` placeholder clips; an Animator Controller left in place fights the graph for the same bones. Per-clip gender filtering (`CharacterGender`) and per-clip emotion affinity tags (`DialogueEmotionAffinity`) have no field-level migration — author one set per character type instead of filtering a mixed set at runtime. `AnimationRiggingGazeBridge` is gone, and Convai Gaze needs no rigging package
* **Migrating from facial clips:** delete `ConvaiFacialClipPlayer`, `ConvaiFacialClipRuntimePlayer`, and their profile assets, and let the Emotion module's micro-expression layer produce idle facial life — it is on by default and nothing needs porting. A deliberate authored facial performance has no supported replacement in this release; drive the mesh yourself with `SkinnedMeshRenderer.SetBlendShapeWeight` on a mesh no Convai module composes. Bake your clips into your own asset before upgrading, because `ConvaiFacialAnimationProfile` assets will not deserialize once the module is gone
* **The Convai editor menu was restructured.** **Convai > Welcome**, **Convai > Account**, **Convai > Long Term Memory**, **Convai > Updates**, **Convai > Contact Us**, and **Convai > AI Coding Setup** are gone; those sections live one click further in, inside the window that **Convai > Convai Editor** opens. The nine current rows group into three bands: the Convai Editor window and its settings — **Convai > Convai Editor**, **Convai > Settings**, **Convai > Documentation**; the per-feature authoring editors — **Convai > Actions Editor**, **Convai > Body Animation Editor**, **Convai > Emotion Editor**, **Convai > Gaze Editor**, **Convai > Embodiment Editor**; and diagnostics — **Convai > Troubleshooter**. The `ConvaiConfigurationWindowEditor` methods that opened a section directly are still public
* **`UnityEventActionExecutor` was renamed to `ConvaiUnityEventActionExecutor` and carries a new GUID.** Unity does not migrate the component: it is dropped from every scene and prefab that had one, along with the events wired into it, and no upgrade step recovers them. Record what each event called before you upgrade. Afterwards, add `ConvaiUnityEventActionExecutor` (**Add Component > Convai > Actions > Raise Unity Event**) on each affected object, re-wire its event by hand, and re-point any action bound to the old component. The serialized field is still `_onExecute`
* **Three experimental action executors were removed from the public catalog:** Guided Tour, Address The Group, and Perform Gesture At Target. `LookAtTargetActionExecutor` was also removed — add `ConvaiLookAtActionExecutor` (**Add Component > Convai > Actions > Look At Target**) instead and give the character Gaze, since the replacement works through `ConvaiGazeController`. Six sample action behaviors, `ConvaiActionTestSetup`, and `ConvaiActionDebugWindow` were removed; the Actions Editor covers their work
* **Point At Target's `Hold Seconds` means only the mid-gesture pause**, not the length of the whole gesture. Two settings now reach the pointing layer: **Gesture Speed** multiplies the rise and fall, and **Release** set to `Blend` drops the pose when the hold ends. Both default to the previous behavior, so no existing scene changes; a point of about a second is Gesture Speed `1.5` with Release `Blend`
* **Fourteen editor types are now `internal`,** among them `ConvaiVisionBaseEditor`, `ConvaiCharacterEditor`, and `TurnTakingOptionsDrawer`. Subclassing a Convai editor or property drawer is no longer supported and has no replacement extension point — delete the subclass, and add project-specific controls through a separate `MonoBehaviour` of your own. `[CustomEditor]` registration is unaffected, so every Convai inspector draws as before
* **The Emotion module's slot-list facial output path was removed:** `EmotionSlotBinding`, `BlendshapeEmotionBinding`, `AnimatorParameterEmotionBinding`, `RealisticEmotionSlots`, `NeutralAlternator`, and the `SemanticExpressionsEnabled` and `NeutralAlternationEnabled` switches on `ConvaiEmotionProfile`. The runtime discarded this data whenever semantic expressions were on, which was every shipped profile, so nothing needs porting. Shader-property output is unaffected
* **The shared Emotion taxonomy and profile assets changed identity.** `ConvaiSamplesShared_EmotionTaxonomy.asset` was rebuilt and `ConvaiSamplesShared_EmotionProfile.asset` was replaced by the four named personalities. Open each affected character and re-point the taxonomy and the personality; a character with no taxonomy still runs, but every emotion dropdown comes up empty
* **Embodiment types were renamed, with asset GUIDs preserved:** `EmbodimentProfileReceiver<T>` to `ConvaiCharacterModule<T>`, `CharacterEmbodimentPreset` to `ConvaiEmbodimentPreset`, `EmbodimentPresetLibrary` to `ConvaiEmbodimentPresetLibrary`, and `ConvaiCharacterEmbodimentBinding` to `ConvaiEmbodimentPresetBinding`. Only source references need updating. `EmbodimentContext` replaced its per-seam registration members with one `CharacterServiceRegistry` — implement `IEmbodimentTickable` and call `EmbodimentContext.RegisterTickable(this)` from `OnEnable` to join the character tick. `EmbodimentContext.TryResolve` no longer creates a context on a GameObject that is not a Convai character; call `TryResolveFor` for a diagnosable failure
* **`ActionResponsePayload` and the public `UnityObjectCompatibility` class were removed.** Action commands still arrive through `ConvaiCharacter.OnActionsReceived` and `ConvaiManager.Events.OnCharacterActionReceived`. Replace `UnityObjectCompatibility.FindObjectsByType<T>(mode)` with Unity's `Object.FindObjectsByType<T>`, and `UnityObjectCompatibility.GetId(value)` with `value.GetInstanceID()` up to Unity 6000.4 or `value.GetEntityId()` on 6000.2 and newer
* **The Camila sample character was removed.** A scene or prefab referencing her prefab, materials, or textures reports a missing reference. Sofia uses the same blendshape convention, so a Convai setup transfers. Copy any customized Camila assets out of the package before upgrading
  {% endupdate %}

{% update date="2026-07-30" tags="v4.4.1" %}

## v4.4.1

**Fixes**

* Added Unity 6.0 through 6.5+ compatibility paths for object IDs and object searches. Unity 6.4 and newer use 64-bit `EntityId` and no-sort search APIs, while Unity 6.0 through 6.3 retain legacy fallbacks
* Fixed Unity 6.0 project resolution by removing unavailable pseudo-module dependencies and pinning `com.unity.collections` to `2.6.8`, avoiding the known Collections `2.6.7` and AI Assistant `xxHash3`/`Unsafe` compiler regression
* Kept the LipSync sample background light isolated on Unity 6.0 and 6.4+ by aligning both URP rendering-layer serialization formats, preventing the light from overexposing the sample character
* Push-to-talk release now keeps the microphone and speech recognition open while waiting for the final transcription result. When the configurable `PushToTalkPolicy.ReleaseTailMs` window expires, the SDK signals the authoritative stop and allows one more bounded window before closing capture
* Fixed WebGL builds crashing from a stale `NativeLib` reference in `livekit-bridge.jslib`, and restored first-turn LipSync by correcting audio-timing registration order, warming the WebGL analyser, and recovering missed `PlaybackStarted` callbacks
  {% endupdate %}

{% update date="2026-07-21" tags="v4.4.0" %}

## v4.4.0

**Canonical transcript timeline**

`ConvaiManager.Transcripts` now exposes a room-scoped `TranscriptTimeline` built from immutable `TranscriptTurn` and `TranscriptChange` models, replacing the previous snapshot-based contract. `CurrentTimeline` returns `TranscriptTimeline` instead of a timeline snapshot, `Changed` supplies `TranscriptChangeBatch`, and `Subscribe`/`SubscribeCommitted` callbacks receive `TranscriptChange` values. This is a breaking change for any code that consumed the old snapshot types — see the [Transcript API](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/transcript-api.md) reference for the full migration path.

**Character Actions**

* `ConvaiActionConfigPatch` updates a character's actions, character targets, object targets, and current attention object during an active session, with omitted-versus-empty list semantics and generated update IDs
* `ConvaiActionDefinition.WaitForBotSpeech` (mirrored on `ConvaiActionCommand`) makes the first action of a fresh batch wait for character speech before executing, with an optional `DelayAfterBotSpeechSeconds` pause and a dispatcher-level speech gate timeout so a silent turn never stalls the batch

**AI Coding Assistant integration**

**Convai > AI Coding Setup** opens a new Editor section for configuring Unity MCP-based AI coding assistance, with support for Codex, Claude Code, Cursor, Gemini, and VS Code Copilot. A dedicated documentation section covers this integration in full.

**Dynamic Vision Context**

Rooms can opt into backend frame sampling through a new Dynamic Vision Context section on `ConvaiRoomManager` and `ConvaiRoomManagerProfile`.

**Convai SDK Settings**

The **Convai SDK** Project Settings page (**Edit > Project Settings > Convai SDK**) and the Editor window's new **Convai > Settings** section share one implementation, covering Setup Health, Credentials, Runtime Defaults, Diagnostics, Advanced, and About. Credentials adds API key obfuscation with automatic migration from plaintext, an Environment preset (Production, Beta, or Custom), and a Validate & Save action with a cached validation badge.

**LipSync**

Playback-alignment hardening anchors NeuroSync lipsync to the exact audio frame where speech starts, reducing drift on long or interrupted responses.

**Breaking changes**

* `ConvaiSettings.DefaultMicrophoneIndex` was replaced by `DefaultMicrophoneDeviceId` (string) — the integer index is not migrated; re-pick the microphone in Settings > Runtime Defaults
* `ConvaiSettings.ServerUrl` is now derived from the Environment preset — the serialized URL applies only when the environment is `Custom`
* The **Convai > Logger Settings** menu was removed — logging configuration lives in **Convai > Settings** (Diagnostics)
* `ConvaiRespondMode` unifies the respond-mode vocabulary (`ConvaiContextReactionMode` removed) — only relevant to scenes saved against unreleased beta builds
  {% endupdate %}

{% update date="2026-06-23" tags="v4.3.0" %}

## v4.3.0

* **VAD settings:** Configurable connect-time user voice activity detection (VAD) settings for room connections, with room and profile Inspector controls and server-default handling
* **Dynamic context v2:** Consolidated dynamic context flow with tracked state and events, batching, acknowledgement/result events, and the `ConvaiDynamicContextRelay` authoring surface
* **World-object context:** Synced world-object context sends tracked scene metadata and the current focus object through dynamic context
* **Narrative triggers:** Separate trigger modes for saved triggers, inline events, and scripted speech
* **Transcript UI:** World-space chat transcript prefab for spatial UI setups
* **Actions:** Action configuration validation and duplicate-binding preservation, with step diagnostics and action debug probing
* **Chat input:** Enter-to-focus behavior for chat input

**Migration notes**

* Dynamic context now uses the v2 tracked update flow — prefer `ConvaiCharacter.DynamicContext` or `ConvaiDynamicContextRelay` over the removed command-style dynamic context UI
* Narrative trigger requests now carry an explicit mode — use saved triggers, inline events, or scripted speech according to the desired backend behavior
* Custom VAD values are sent only during room connect — use the server-default option when the backend should own VAD defaults
  {% endupdate %}

{% update date="2026-05-08" tags="v4.2.0" %}

## v4.2.0

**Actions System**

Characters can execute in-scene commands through a structured runtime. New in this release:

* `ConvaiActionDispatcher` with queued dispatch — actions execute in sequence without race conditions
* `IConvaiActionExecutor` interface for custom executors
* Six built-in executors: move-to (Transform and NavMesh), pick-up, look-at, Animator trigger, and UnityEvent
* Inspector-driven configuration — no scripting required for standard action setups
* Runtime diagnostics for monitoring action queue state

**Meta Quest Passthrough Vision**

`QuestVisionFrameSource` enables the Vision module on Quest 3 and Quest 3S devices without an external camera. Characters see through the device's passthrough camera during mixed reality sessions.

**Runtime Turn-Taking Mode Switching**

Switch between hands-free and push-to-talk modes during live sessions using `ConvaiManager.SetConversationInputModeAsync()` or the runtime Settings Panel — no scene reload required.

**Dynamic Context Expansion**

* Tracker APIs let you monitor current context state from scripts
* Inspector tooling for authoring context commands without code
* `SampleDynamicContextUI` prefab demonstrates runtime injection patterns

**Scene Setup Tooling and Validation**

Menu-driven component creation (**GameObject > Convai > Setup Required Components**) and scene validation (**GameObject > Convai > Validate Scene Setup**) prevent misconfiguration before entering Play mode.

**Settings Panel Input Mode Control**

The runtime Settings Panel now exposes input mode switching — players or developers can change turn-taking mode during a session without scripting.
{% endupdate %}

{% update date="2026-04-09" tags="v4.1.0" %}

## v4.1.0

* **Dynamic Context:** `ConvaiDynamicContextCommand` component enables runtime injection of state and events into character knowledge
* **LipSync sample:** Removed camera dependency from the LipSync sample scene — works with any camera setup
* **Vision module:** Reliability improvements to frame source lifecycle and reconnection handling
* **iOS:** Fixed crash on first microphone access when `NSMicrophoneUsageDescription` was absent from build settings
* **Sample scenes:** Refined setup and scene structure across Basic and LipSync samples
* **Editor:** Startup time improvements for projects with large scene counts
  {% endupdate %}

{% update date="2026-03-12" tags="v4.0.0,Initial Release" %}

## v4.0.0

Initial public release of the Convai Unity SDK.

**Core components:** `ConvaiManager`, `ConvaiRoomManager`, `ConvaiCharacter`, `ConvaiPlayer`

**Conversation pipeline:** Speech-to-text, language understanding and generation, text-to-speech — fully streamed in real time

**Modules:** LipSync, Emotion, Vision, Narrative Design, Dynamic Context, Long-Term Memory, Scene Metadata, Dialogue Animation, Gaze and Attention

**Platform support:** Windows, macOS, Linux, Android, iOS, WebGL

**Editor tooling:** Scene setup, validation, Project Settings integration, and the Convai Welcome window
{% endupdate %}
{% endupdates %}

### Next steps

To start using the SDK, follow Getting Started.

{% content-ref url="/pages/1d9fa274483952ca377014dd2a4fb49c2f3e80a1" %}
[Getting started](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started.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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/overview/release-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.