> 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/embodiment/body-animation/troubleshooting.md). # Troubleshoot body animation Diagnose no motion, a T-pose, locomotion desync, a fighting Animator Controller, actions that never fire, and misaimed pointing gestures. Most body animation problems trace back to one of a small number of setup gaps, and `ConvaiBodyAnimationController`'s inspector reports most of them by name before you ever open the console. This page covers the symptoms that checklist does not fully explain, the `AnimTraceVerbosity` dial for deeper diagnosis, and a complete reference for every common failure. ### Diagnose with AnimTraceVerbosity `ConvaiBodyAnimationConfig`'s **Trace Verbosity** field controls how much a character writes to the console, through the `AnimTraceVerbosity` enum: `Off`, `State`, `Detail`, `Firehose`. It ships as `Off`, which still logs every warning and error — a character that walks and talks transitions constantly, so a console full of routine play-by-play is where a real warning goes unread. | Level | What it adds | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `Off` | No trace output. Warnings and errors still log. | | `State` | State-machine transitions, layer ownership changes, action lifecycle, and clip selections — raise the one character you are diagnosing to this level. | | `Detail` | Adds selector decisions (angles, distances, foot phase), variant rolls with weights, and speed-warp clamps. | | `Firehose` | Adds throttled per-tick dumps of layer weights and blend positions. Extremely chatty; use only for short debugging sessions. | Raise **Trace Verbosity** to `State` on the character you are diagnosing, reproduce the symptom, then put it back to `Off`. The SDK's own `ConvaiSettings` log level also has to allow the line through: `State` logs at `Info`, `Detail`/`Firehose` at `Debug`. The same entries also feed a ring buffer that backs the controller inspector's compact **Live** strip and the **Body Animation Editor** window's deeper Live mode — verbosity gates the ring buffer too, so at `Off` the Live surfaces still show dialogue state, movement state, and any warning, but the rolling transition log needs `State` or higher to populate. ### Symptom quick reference | Symptom | Likely cause | Fix | Verify | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Character never idles or reacts to speech | No `Animator`, a non-Humanoid avatar, or no `ConvaiBodyAnimationSet` assigned | Add a Humanoid `Animator`, or assign a set to the component or its profile | Controller inspector shows **Ready** instead of **Not Set Up** | | Character holds a T-pose | Same as above — the `PlayableGraph` never built, so the Animator falls back to its bind pose | Same fix as no motion | Character shows a looping idle in Play mode | | Character glides, slides its feet, or its legs desync from movement | Locomotion clips have no measured metadata, or a custom locomotion provider does not implement `IConvaiManagedLocomotion` | Run **Measure Clips** on the set, or implement the managed-locomotion capability | `LocomotionClipsMissingMetadata` in the Setup checklist reads `0` | | Legs or arms twitch or fight the intended pose | A Runtime Animator Controller is still assigned on the Animator | Clear the Animator's **Controller** field | The `rig.redundant-animator-controller` finding disappears from Setup | | An action or gesture never plays | Action name does not match any `ActionName`/alias in the set, or the call ran before the runtime was ready | Compare the requested name to the set's authored names (case-insensitive, space/dash/underscore-equivalent); call from `RuntimeReady` instead of `Awake`/`Start` | Console shows the matching name reach `_actionLayer.Play` instead of the "no matching action" warning | | Pointing arm aims at the wrong spot | Only one or a few directions are authored in the set's pointing table; `PointAt` snaps to the angularly closest one | Author more directional pointing clips covering the angles your scene needs | The played clip's authored yaw/pitch is close to the requested direction | ### No motion at all A character with no motion at all — no idle sway, no talk gestures, nothing — almost always fails one of three setup checks the controller's own inspector reports before you open the console: * **No Animator was found under the character root.** `ConvaiBodyAnimationController` needs a Humanoid `Animator` to build its `PlayableGraph`, so with none present the module stays inactive (`BodyAnimationTroubleshooter.cs:228-230`). * **The Animator's avatar is not a valid Humanoid rig.** Set the model's **Animation Type** to **Humanoid** in its import settings (`BodyAnimationTroubleshooter.cs:238-239`). * **No Animation Set is assigned**, directly or through a profile — the character has content it could play but nothing wired to it (`BodyAnimationTroubleshooter.cs:264-267`). Open the controller's inspector or **Convai > Body Animation Editor**'s Setup mode; all three report as an error-severity finding that names the exact missing piece rather than a generic failure. ### Character stuck in T-pose A T-pose is Unity's fallback when nothing is driving the Animator at all — it shares the same underlying cause as no motion at all, and reads more visibly wrong because the character has no authored idle to fall back to. Check the same three conditions: a Humanoid `Animator`, a valid Humanoid avatar, and an assigned `ConvaiBodyAnimationSet` with at least one looping idle entry. A set with no valid idle entry (`HasAnyIdle` false) leaves the character with nothing to blend to even once the graph itself builds successfully. ### Locomotion out of sync with the NavMeshAgent Two distinct symptoms share this heading, and they have different causes. **The character does not walk at all.** `ConvaiNavMeshLocomotion.MoveTo` logs the exact reason and returns `false`: ``` [ConvaiNavMeshLocomotion] '' cannot walk: it is not standing on a baked NavMesh. Bake a NavMesh for the floor (Window > AI > Navigation), and check the character starts on it. ``` (`ConvaiNavMeshLocomotion.cs:238-242`.) A destination with no walkable floor nearby logs a second, similar warning naming the destination (`ConvaiNavMeshLocomotion.cs:248-252`), and a destination on a disconnected piece of NavMesh logs a third naming the connectivity problem (`ConvaiNavMeshLocomotion.cs:260-264`). Bake a NavMesh covering both the character's start position and every destination you send it to. **The character walks, but feet slide or the gait looks wrong at speed.** This is a measurement problem, not a NavMesh problem: locomotion clips assigned to the set need their ground speed measured by the Clip Motion Analyzer before the animation can track the agent's real speed. The Setup checklist reports this directly: ``` {N} locomotion clip(s) have not been measured, so the character falls back to configured speeds instead of the clips' real ground speed — the usual cause of sliding feet. Directional starts and planted stops also stay off until their motion is measured. ``` (`BodyAnimationTroubleshooter.cs:359-363`.) Re-run **Measure Clips** — on the set's own inspector, or in the Body Animation Editor's Content mode — after any locomotion clip changes. ### An Animator Controller fighting the graph `ConvaiBodyAnimationController`'s `PlayableGraph` replaces the Animator's output while active, but it does not clear a Runtime Animator Controller left assigned on the Animator component. When one is present, the Setup checklist reports it: ``` An Animator Controller is assigned; the body animation PlayableGraph replaces its output while active. Remove it to avoid confusion, or leave it as an inert fallback. ``` (`BodyAnimationTroubleshooter.cs:247-249`.) In practice, a leftover controller most often surfaces as legs or arms twitching or briefly snapping toward a different pose than the graph intends. Clear the Animator's **Controller** field — the Setup checklist offers a one-click fix for this specific finding. ### Actions not firing A `PlayAction` call that never plays fails in one of two ways, and the console tells you which: * **The runtime was not ready yet.** A call made from `Awake()`/`Start()`, before the `PlayableGraph` finishes building, is queued in a single deferred slot and replayed automatically — but only until it expires: ``` PlayAction('') requested before the animation graph was ready — it will be replayed automatically once the graph builds, or expire after 2s. ``` (`ConvaiBodyAnimationController.cs:462-465`.) Subscribe to `RuntimeReady`, or check `IsRuntimeBuilt`, instead of relying on the deferred slot for anything that must not be dropped. * **The name did not match any authored entry.** Matching is case-insensitive and treats spaces, dashes, and underscores as equivalent, but an unmatched name still fails: ``` PlayAction('') — no matching action in set ''. ``` (`ConvaiBodyAnimationController.cs:472-473`.) Compare the exact name your code or a backend action sends against the `Action Name` and `Aliases` fields authored in the set. `PlayAction` never returns `null` in either case — check `handle.Failed` and read `handle.FailureReason` instead of expecting an exception. ### Pointing looks wrong `ConvaiBodyAnimationController.PointAt` fails outright (`handle.Failed`) only when the target is `null`, the runtime is not built, or the set authors no pointing clips at all — each reports its own `FailureReason` (`ConvaiBodyAnimationController.cs:594-667`). A pointing gesture that plays but aims at the wrong spot is not a failure — it is expected behavior from how directions are selected. Each `PointingEntry` authors a fixed character-local yaw and pitch, and `PointAt` always plays whichever authored entry is angularly closest to the requested direction; it does not blend or procedurally aim between entries (`PointingEntry.cs:8-12,84-106`). A set with only a few authored directions snaps to the nearest one, which can be visibly off for a target well outside any authored angle. Author more directional pointing clips covering the range of angles your scene actually needs. ### Next steps {% content-ref url="/pages/oLiANbc0KEankOmnGH0D" %} [Play actions and gestures](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/body-animation/play-actions-and-gestures.md) {% endcontent-ref %} {% content-ref url="/pages/MZZXmWiseGyylD51REZZ" %} [Body animation config reference](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/body-animation/config-reference.md) {% endcontent-ref %} {% content-ref url="/pages/ae8k7JCmNIvZyl8ctZ6K" %} [Release notes](/api-docs/plugins-and-integrations/convai-unity-sdk/overview/release-notes.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/embodiment/body-animation/troubleshooting.md?ask=&goal= ``` `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.