> 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/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/character-embodiment.md).

# 角色具身化

了解角色的具身模块如何共享一个组合根、以确定性方式逐帧运行，以及如何避免重复写入同一骨骼。

Convai 角色上的每个具身模块——注视、身体动画、肢体语言、对话流程和情绪——都会接入该角色同一个组合根。这个根负责管理角色的更新顺序，以及访问 Animator 和面部的唯一途径。理解这一点，就能明白为什么各模块可以协同工作，而不是争用同一根骨骼或混合形状。

***

### 组合根

`EmbodimentContext` (`SDK/Runtime/Embodiment/EmbodimentContext.cs`) 是组合根：每个角色对应一个实例。Convai 会在该角色上的任一具身模块首次解析自身时自动添加它——你无需手动添加；它还带有 `[AddComponentMenu("")]` ，因此不会显示在“添加组件”菜单中。

上下文会公开所有模块都能读取的共享基础设施：

| 成员              | 类型                    | 提供给模块的内容                       |
| --------------- | --------------------- | ------------------------------ |
| `CharacterRoot` | `Transform`           | 角色的根级变换。                       |
| `EventHub`      | `IEventHub`           | 模块用于监听领域事件的事件总线。               |
| `Logger`        | `ILogger`             | 结构化诊断日志记录。                     |
| `RigBinding`    | `IStandardRigBinding` | 以语义方式访问角色骨架——按角色而非名称访问骨骼和混合形状。 |
| `Character`     | `ConvaiCharacter`     | 层级结构中存在所属角色时，提供该角色。            |

它还会触发三个模块可订阅的事件： `RigBindingChanged` （语义骨架已重新构建或替换）、 `EmbodimentConfigurationChanged` （模块配置在运行时发生变化，例如切换预设），以及 `DependenciesPopulated` （例如 `EventHub` 等仅在运行时使用的基础设施已就绪）。

每个模块控制器—— `ConvaiGazeController`, `ConvaiBodyAnimationController`, `ConvaiBodyLanguageController`, `ConvaiConversationFlowController`和 `ConvaiEmotionController` ——都继承自 `ConvaiCharacterModule<TProfile>` (`SDK/Runtime/Embodiment/ConvaiCharacterModule.cs`)，并在 `OnEnable` 中解析同一个共享上下文，并将自身注册为该上下文的配置文件接收器。如果模块无法解析上下文（例如它不在 Convai 角色上），就会停用自身并记录原因，而不会在缺少驱动的情况下继续运行。

***

### 自动提供的基础设施

模块首次需要时，上下文还会延迟创建另外四个基础设施组件： `StandardRigBinding` （确定 Humanoid、ARKit、CC3/CC4 等常见骨架中的骨骼和混合形状分别承担什么语义角色）、 `AnimatorConductor`, `EmbodimentTickScheduler`和 `FacialBlendshapeCompositorHost`。这四个都是普通组件，你可以在层级视图中选中并检查它们——SDK 有意不将它们隐藏，因为看不见的组件就无法调试。 `AnimatorConductor`, `EmbodimentTickScheduler`和 `FacialBlendshapeCompositorHost` 带有 `[AddComponentMenu("")]`；应将这三个组件都视为 Convai 提供的行为，而不是由你添加的组件或直接调用的 API。

***

### 确定性更新顺序

每个需要逐帧执行工作的模块都会实现 `IEmbodimentTickable` 并通过以下接口向上下文注册 `RegisterTickable`/`UnregisterTickable` 而不是依赖 Unity 自身的 `Update`/`LateUpdate` 顺序。在 `OnEnable` 中注册，并在 `OnDisable` 中注销，这是受支持的模式；对同一实例重复注册不会产生任何操作。

调度器每个 tick 都会按以下顺序执行所有可 tick 对象的三个阶段：

| 阶段           | 执行内容                                                             |
| ------------ | ---------------------------------------------------------------- |
| `Cognition`  | 对话流程、注视和情绪控制器采样信号并更新其读数。                                         |
| `Expression` | 注视、身体和面部执行器将这些读数转换为骨骼、混合形状和 Animator 参数的写入操作。                    |
| `Finalize`   | 在 Cognition 和 Expression 阶段都完成后，面部合成器和 Animator 控制器会最终确定各自的写入操作。 |

在同一阶段内，可 tick 对象的 `TickOrder` 决定执行先后——数值越小越早执行；数值相同时则按注册顺序执行。因此，tick 顺序不受层级顺序或哪个模块先启用的影响：重新设置 GameObject 的父级，或以不同顺序添加模块，都不会悄然改变哪个模块先写入共享骨骼。

***

### Animator 和面部的单一写入者访问机制

两个模块在同一帧写入同一个 Animator 参数或同一个混合形状，这类错误只会表现为可见故障，而不会触发编译错误。Convai 通过为 Animator 和角色的面部混合形状分别指定唯一写入者来避免这种情况：

* `AnimatorConductor` 是 Animator 参数唯一且权威的写入者。模块通过控制器提交带名称的参数写入，而不是直接调用 `Animator.SetFloat` ；控制器会记录每个参数由哪个模块注册，并拒绝其他模块对同一参数的冲突注册。
* `FacialBlendshapeCompositorHost` 是面部混合形状的唯一写入者。它会将各模块的贡献——情绪、口型同步以及任何自定义层——合成为一组混合形状值，并根据 `ConvaiFacialCompositionProfile` 中的区域规则，决定各个贡献者对嘴部、眉毛、眼睛、脸颊和下颌区域的影响程度。

两者都是自动提供的基础设施组件，而不是需要直接配置的组件。如果你需要影响它们的写入内容，请通过负责相应行为的模块进行操作——表情通过 Emotion，嘴型通过 LipSync——不要自行写入同一网格上的混合形状。

{% hint style="info" %}
跨模块约定（例如注视如何告知身体动画进行转向）属于包内部的 `internal` 内容，并非公开的扩展点；公开扩展点仅包括组件及其配置文件。
{% endhint %}

***

### 五个具身模块

| 模块   | 组件                                 | “添加组件”菜单路径                            | `ModuleIds` 常量                                            |
| ---- | ---------------------------------- | ------------------------------------- | --------------------------------------------------------- |
| 凝视   | `ConvaiGazeController`             | `Convai/Embodiment/Gaze`              | `ModuleIds.Gaze` (`convai.gaze`)                          |
| 身体动画 | `ConvaiBodyAnimationController`    | `Convai/Embodiment/Body Animation`    | `ModuleIds.BodyAnimation` (`convai.body-animation`)       |
| 身体语言 | `ConvaiBodyLanguageController`     | `Convai/Embodiment/Body Language`     | `ModuleIds.BodyLanguage` (`convai.body-language`)         |
| 对话流程 | `ConvaiConversationFlowController` | `Convai/Embodiment/Conversation Flow` | `ModuleIds.ConversationFlow` (`convai.conversation-flow`) |
| 情绪   | `ConvaiEmotionController`          | `Convai/Embodiment/Emotion`           | `ModuleIds.Emotion` (`convai.emotion`)                    |

每个 `ModuleIds` (`SDK/Domain/Embodiment/Modules/ModuleIds.cs`) 常量是 `ConvaiEmbodimentPreset` 插槽用于将设置资源传递给相应模块的路由键。五个模块均为可选项，可独立添加——角色可以仅运行 Gaze、仅运行 Emotion，或任意组合；即使缺少其他模块，每个模块也都能正常降级运行。

***

### 后续步骤

{% content-ref url="/pages/9aa58b1250604b0f44e22f31b27c7ffe4a02efeb" %}
[对话状态](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/dialogue-state.md)
{% endcontent-ref %}

{% content-ref url="/pages/8eaf58d7e1fc1a2176b0c4b26425f595bc8e8851" %}
[资产所有权与写时复制](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/asset-ownership.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/character-embodiment.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
