> 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/embodiment/scripting-reference.md).

# 具身化脚本参考

Convai 具身化脚本接口参考，包括角色上下文、模块基类、骨架绑定和共享枚举。

Unity 脚本可直接使用的公开具身类型参考： `EmbodimentContext`、 `ConvaiCharacterModule<TProfile>` （自定义模块的基类）、 `StandardRigBinding`, `ConvaiTravelIntent`, `ModuleIds`，以及共享的 `CharacterDemeanor`, `StandardBone`, `StandardBlendshape`和 `RigConvention` 枚举。诸如 `IGazeSource` 和 `IEmotionStateSource` 之类的跨模块契约属于内部内容，不在此公开接口范围内——请参阅各模块自己的控制器参考。

### `EmbodimentContext`

`EmbodimentContext` (`sealed class : MonoBehaviour`）是角色级组合根，具身模块通过它访问共享基础设施。Convai 会自动将其添加到角色上——它带有隐藏的 `[AddComponentMenu("")]` ，无需手动添加。

#### 静态解析

| 成员              | 签名                                                                          | 说明                                                                                                 |
| --------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `TryResolve`    | `static bool TryResolve(Component origin, out EmbodimentContext context)`   | 在 `origin`所属角色根对象上查找或创建上下文。如果 `false` ，则静默返回 `origin` 不属于 `ConvaiCharacter`的子级时。适用于缺少上下文属于正常情况的场景。 |
| `TryResolveFor` | `static bool TryResolveFor(Component owner, out EmbodimentContext context)` | 解析方式相同，但如果无法解析出上下文，则会记录一条设置错误，并指出 `owner` 。适用于没有角色便无法运行的组件。                                        |

#### 返回的结果

| 属性              | 类型                    | 说明                               |
| --------------- | --------------------- | -------------------------------- |
| `CharacterRoot` | `Transform`           | 角色根变换。                           |
| `EventHub`      | `IEventHub`           | 用于监听领域事件的事件总线。                   |
| `Logger`        | `ILogger`             | 用于结构化诊断的日志记录器。可能为 `null` 如果尚未注入。 |
| `RigBinding`    | `IStandardRigBinding` | 角色的绑定抽象（语义骨骼和混合形状）。              |
| `Character`     | `ConvaiCharacter`     | 如果此层级中存在所属角色，则为该角色。              |

#### 事件

| 事件                               | 签名                                  | 在以下情况下触发：                                    |
| -------------------------------- | ----------------------------------- | -------------------------------------------- |
| `RigBindingChanged`              | `event Action<IStandardRigBinding>` | 语义绑定在运行时被重建或替换。缓存骨骼或网格引用的模块应重新解析这些引用。        |
| `EmbodimentConfigurationChanged` | `event Action`                      | 具身模块配置已在运行时更新，例如应用了一个预设。                     |
| `DependenciesPopulated`          | `event Action`                      | 运行时专用依赖项，例如 `EventHub`、tick 调度器和动画器基础设施现已可用。 |

#### Tickable 对象

| 成员                   | 签名                                                      | 说明                                                                                                                                                               |
| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RegisterTickable`   | `bool RegisterTickable(IEmbodimentTickable tickable)`   | 使 `tickable` 由此角色的具身调度器驱动，而不是使用 Unity 的逐组件 `Update`，从而确保其写入相对于 Convai 自身的写入按声明顺序执行。请从 `OnEnable`中调用。重复注册同一实例不会产生任何效果。如果尚无可加入的调度器，则返回 `false` ——在 Play 模式之外通常会如此。 |
| `UnregisterTickable` | `void UnregisterTickable(IEmbodimentTickable tickable)` | 停止驱动 `tickable`。请从 `OnDisable`中调用。如果该 tickable 从未注册，或调度器已不存在，调用此方法也是安全的。                                                                                         |

### `ConvaiCharacterModule<TProfile>`

`ConvaiCharacterModule<TProfile>` (`abstract class : MonoBehaviour`, `[ExecuteAlways]`）是所有具身模块的基类，以下类均继承自它： `ConvaiGazeController`, `ConvaiBodyAnimationController`, `ConvaiBodyLanguageController`, `ConvaiConversationFlowController`以及 `ConvaiEmotionController` 均继承自该类。 `TProfile` 是 `ScriptableObject` 该模块拥有的配置文件类型。编写此类型的子类，以构建自定义具身模块，使其参与与内置模块相同的上下文解析、配置文件接收器注册和帧更新生命周期。

#### 受保护成员

| 成员                      | 类型                        | 说明                                                                        |
| ----------------------- | ------------------------- | ------------------------------------------------------------------------- |
| `Context`               | `EmbodimentContext`       | 此角色解析后的上下文。仅在 `OnEnable` 成功后设置一次。                                         |
| `EffectiveProfile`      | `TProfile`                | 如果指定了配置文件资源，则为该资源；否则为来自 `DefaultProfileFactory`. `null` ；在 `Awake` 运行之前为  |
| `ProfileModuleId`       | `abstract string`         | 此子类向配置文件接收器系统报告的模块 ID。如果模块属于五个内置模块之一，请使用 `ModuleIds` 中的常量；否则请使用自定义的稳定字符串。 |
| `DefaultProfileFactory` | `abstract Func<TProfile>` | 未指定资源时，用于创建运行时默认配置文件的工厂。                                                  |

#### 方法

| 方法                        | 签名                                                     | 说明                                                                         |
| ------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- |
| `OnProfileApplied`        | `virtual void OnProfileApplied(TProfile newProfile)`   | 配置文件槽更新后调用，例如由预设更新时。重写此方法可重置状态，或重新解析依赖于配置文件的绑定。                            |
| `ProvideService`          | `void ProvideService<TContract>(TContract service)`    | 将此组件注册为角色的 `TContract` 服务提供者，并跟踪该注册，以便在 `OnDisable`.                       |
| `ContributeService`       | `void ContributeService<TContract>(TContract service)` | 将此组件添加为扇出契约的贡献者（每个角色可有多个观察者），并以与 `ProvideService`.                         |
| `ReleaseProvidedServices` | `void ReleaseProvidedServices()`                       | 撤销此组件发布的所有契约。在基类的 `OnDisable`中调用。重写 `OnDisable` 的子类 `base.OnDisable()`必须调用 |

`Awake`, `OnEnable`, `OnDisable`和 `OnDestroy` 均为 `virtual` 并在基类实现中处理上下文解析和配置文件接收器注册——重写其中任一方法时，请调用基类方法。

### `StandardRigBinding`

`StandardRigBinding` (`sealed class : MonoBehaviour, IStandardRigBinding`, `[AddComponentMenu("Convai/Embodiment/Character Rig")]`) 会检查角色的层级结构，并据此解析语义骨骼和混合形状查找。有关检测和置信度的工作方式，请参阅 [角色骨架设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md) 。

#### 返回的结果

| 属性                    | 类型                                   | 说明                                               |
| --------------------- | ------------------------------------ | ------------------------------------------------ |
| `Root`                | `Transform`                          | 如果角色有动画器，则为动画器的变换；否则为此组件自身的变换。                   |
| `FacialMeshes`        | `IReadOnlyList<SkinnedMeshRenderer>` | 用于解析混合形状的网格。                                     |
| `DetectedConvention`  | `RigConvention`                      | 为此骨架检测到的混合形状命名约定；如果设置了手动覆盖，则使用该覆盖值。              |
| `CustomConventionMap` | `CustomRigConventionMap`             | 自定义语义到混合形状的映射；当 `DetectedConvention` 为 `Custom`. |
| `DetectionConfidence` | `float`                              | 上次检测的置信度，范围为 `0` 至 `1`. `1` 手动设置约定覆盖时的置信度。       |

#### 方法

| 方法                 | 签名                                                                                                          | 说明                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `Rebuild`          | `void Rebuild()`                                                                                            | 重新扫描层级结构并重建骨骼和混合形状解析表。当服装发生变化、网格被替换或在运行时应用约定覆盖时调用。 |
| `TryGetBone`       | `bool TryGetBone(StandardBone semantic, out Transform bone)`                                                | 解析语义骨骼。找不到骨骼时，在此组件的生命周期内仅记录一次警告。                   |
| `TryGetBlendshape` | `bool TryGetBlendshape(StandardBlendshape semantic, out SkinnedMeshRenderer mesh, out int blendshapeIndex)` | 解析语义混合形状。找不到时，在此组件的生命周期内仅记录一次警告。                   |

### `ConvaiTravelIntent`

`ConvaiTravelIntent` (`sealed class : MonoBehaviour, IEmbodimentTickable, ITravelIntentSource`, `[AddComponentMenu("Convai/Embodiment/Travel Intent")]`) 会报告角色的行进方向，使 Gaze 等模块能够在角色行走时观察前方道路，而不是一直盯着目的地。

通常无需手动添加此组件——角色开始移动时会自动创建，并随角色一同移除。只有在需要更改移动检测阈值或关闭自动检测时，才手动添加。

行进方向按优先级从高到低由以下三个来源确定：通过 `ReportTravel` 或 `ReportTravelTo`显式报告，通过 `ConvaiNavMeshLocomotion` （如果角色有此组件）推送的信息，或 Convai 直接观察到的角色变换移动。请从你自己的移动代码中调用 `ReportTravel` （或 `ReportTravelTo`）——一个 `NavMeshAgent`驱动的移动器、 `CharacterController`、根运动或补间动画——因此，即使角色的移动并非由 `ConvaiNavMeshLocomotion` 驱动，它在移动时仍能正确转头并调整步态。如果未重复报告，报告会在 `TravelReportTimeoutSeconds` 后过期，因此调用方停止报告后，角色不会永远处于旅行状态。

#### 返回的结果

| 属性                           | 类型             | 说明                                                                           |
| ---------------------------- | -------------- | ---------------------------------------------------------------------------- |
| `IsTraveling`                | `bool`         | 角色此刻是否正前往某处。                                                                 |
| `HasSubject`                 | `bool`         | 是否已有人声明当前旅程的目的。若没有目标对象，角色就会望着前方的道路，却没有明确目的地。                                 |
| `Source`                     | `TravelSource` | 当前旅行状态读数的来源： `NotTraveling`, `Reported`, `Locomotion`，或 `Observed`，按优先级顺序排列。 |
| `TravelReportTimeoutSeconds` | `float`        | 未重复报告时，已报告的旅程持续有效的时长。                                                        |

#### 方法

| 方法               | 签名                                                                                  | 说明                                                                            |
| ---------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `ReportTravel`   | `void ReportTravel(Vector3 worldDirection, float speed01)`                          | 报告角色正沿 `worldDirection` 方向，以 `speed01` (`0`的速度（`1` 为全力移动时的速度）。在移动持续期间，每帧调用一次。 |
| `ReportTravel`   | `void ReportTravel(Vector3 worldDirection, float speed01, float remainingDistance)` | 与上面相同，同时报告到目的地的剩余距离。                                                          |
| `ReportTravelTo` | `void ReportTravelTo(Vector3 destination, float speed01)`                           | 便捷方法，适用于常见情况：报告角色正朝 `destination` 移动，并在一次调用中将其设为旅行目标。                         |
| `ClearTravel`    | `void ClearTravel()`                                                                | 立即结束已报告的旅程，无需等待其过期。                                                           |
| `SetSubject`     | `void SetSubject(Transform subject)`                                                | 声明此旅程的目标是 `subject` ——例如正在跟随的人。角色会因此定期朝其瞥视。                                   |
| `SetSubject`     | `void SetSubject(Vector3 worldPosition)`                                            | 声明此旅程的目标是一个固定地点。                                                              |
| `ClearSubject`   | `void ClearSubject()`                                                               | 忘记此旅程的目标。角色会继续注视前方的道路。                                                        |

### `ModuleIds`

`ModuleIds` (`static class`）包含 embodiment 模块在向 `EmbodimentContext`注册配置文件时使用的规范路由键，以及 `ConvaiEmbodimentPreset` 插槽用于指定目标模块的键。

| 常量                 | 值                          | 路由至                                |
| ------------------ | -------------------------- | ---------------------------------- |
| `BodyAnimation`    | `convai.body-animation`    | `ConvaiBodyAnimationController`    |
| `BodyLanguage`     | `convai.body-language`     | `ConvaiBodyLanguageController`     |
| `ConversationFlow` | `convai.conversation-flow` | `ConvaiConversationFlowController` |
| `Emotion`          | `convai.emotion`           | `ConvaiEmotionController`          |
| `Gaze`             | `convai.gaze`              | `ConvaiGazeController`             |

### `CharacterDemeanor`

`CharacterDemeanor` 是情绪、身体动画和身体语言编辑器共用的创作词汇，因此，在每个模块的资源中选择相同的气质，就能描述同一个风格一致的角色。气质仅用于创作：应用气质时，只会将普通值写入正在编辑的资源，运行时没有任何代码会读取此枚举。每个模块都会用自己的方式诠释同一个词。

| 值           | 数值  | 说明                         |
| ----------- | --- | -------------------------- |
| `Composed`  | `0` | 沉稳平和——接待员、店员、向导。           |
| `Warm`      | `1` | 平易近人，易于理解。为角色刻意设定个性时的默认选项。 |
| `Energetic` | `2` | 反应幅度大、速度快——主持人、导游、主播。      |
| `Reserved`  | `3` | 几乎不显露情绪——保安、司仪。            |

### `StandardBone`

`StandardBone` 用于标识角色骨架中，embodiment 模块可通过 `StandardRigBinding.TryGetBone`解析的骨骼，不受底层骨架命名约定影响。

| 值            | 数值  | 值               | 数值   |
| ------------ | --- | --------------- | ---- |
| `Hips`       | `0` | `LeftShoulder`  | `8`  |
| `Spine`      | `1` | `RightShoulder` | `9`  |
| `Chest`      | `2` | `LeftUpperArm`  | `10` |
| `UpperChest` | `3` | `RightUpperArm` | `11` |
| `Neck`       | `4` | `LeftUpperLeg`  | `12` |
| `Head`       | `5` | `LeftLowerLeg`  | `13` |
| `LeftEye`    | `6` | `LeftFoot`      | `14` |
| `RightEye`   | `7` | `RightUpperLeg` | `15` |
|              |     | `RightLowerLeg` | `16` |
|              |     | `RightFoot`     | `17` |

### `StandardBlendshape`

`StandardBlendshape` 标识表情混合形状，具身模块可通过它们进行解析 `StandardRigBinding.TryGetBlendshape`。值遵循 ARKit 52 种混合形状的命名约定；其他约定（Reallusion CC3、MetaHuman、Custom）会映射到这些相同的语义名称。并非每个骨骼绑定都提供所有混合形状——模块必须处理 `TryGetBlendshape` 返回 `false` 并能妥善地不执行任何操作。

| 区域      | 数值                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 眼睛      | `EyeBlinkLeft`, `EyeBlinkRight`, `EyeLookDownLeft`, `EyeLookDownRight`, `EyeLookInLeft`, `EyeLookInRight`, `EyeLookOutLeft`, `EyeLookOutRight`, `EyeLookUpLeft`, `EyeLookUpRight`, `EyeSquintLeft`, `EyeSquintRight`, `EyeWideLeft`, `EyeWideRight`, `EyeUpperLidDownLeft`, `EyeUpperLidDownRight`, `EyeUpperLidUpLeft`, `EyeUpperLidUpRight`, `EyeLowerLidUpLeft`, `EyeLowerLidUpRight`                                             |
| 眉毛      | `BrowDownLeft`, `BrowDownRight`, `BrowInnerUp`, `BrowOuterUpLeft`, `BrowOuterUpRight`                                                                                                                                                                                                                                                                                                                                                |
| 脸颊 / 鼻子 | `CheekPuff`, `CheekSquintLeft`, `CheekSquintRight`, `NoseSneerLeft`, `NoseSneerRight`                                                                                                                                                                                                                                                                                                                                                |
| 下颌      | `JawForward`, `JawLeft`, `JawRight`, `JawOpen`                                                                                                                                                                                                                                                                                                                                                                                       |
| 嘴部      | `MouthClose`, `MouthFunnel`, `MouthPucker`, `MouthLeft`, `MouthRight`, `MouthSmileLeft`, `MouthSmileRight`, `MouthFrownLeft`, `MouthFrownRight`, `MouthDimpleLeft`, `MouthDimpleRight`, `MouthStretchLeft`, `MouthStretchRight`, `MouthRollLower`, `MouthRollUpper`, `MouthShrugLower`, `MouthShrugUpper`, `MouthPressLeft`, `MouthPressRight`, `MouthLowerDownLeft`, `MouthLowerDownRight`, `MouthUpperUpLeft`, `MouthUpperUpRight` |
| 舌头      | `TongueOut`                                                                                                                                                                                                                                                                                                                                                                                                                          |

### `RigConvention`

`RigConvention` 用于标识混合变形和骨骼的命名约定 `StandardRigBinding` 为角色面部绑定检测到的约定，或手动指定为覆盖项的约定。

| 值                       | 数值   | 说明                                                             |
| ----------------------- | ---- | -------------------------------------------------------------- |
| `Unknown`               | `0`  | 尚未运行检测，或绑定与任何已知约定都不匹配。                                         |
| `ARKit`                 | `1`  | Apple ARKit 的 52 个混合变形约定。大多数 VRoid 和 MetaHuman 导出绑定都采用此约定。     |
| `ReallusionCC3`         | `2`  | Reallusion Character Creator 3 基础面部绑定。                         |
| `MetaHuman`             | `3`  | Epic MetaHuman 原生面部绑定。                                         |
| `ReallusionCC4Extended` | `4`  | Reallusion Character Creator 4 扩展面部配置文件——严格包含 `ReallusionCC3`. |
| `Custom`                | `99` | 绑定与内置约定不匹配； `CustomRigConventionMap` 提供映射。                     |

### 相关参考

{% content-ref url="/pages/528b8780a5fa83913d2d3f95cdbf6b1a0c52b073" %}
[具身化如何运作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/how-embodiment-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/dddb9a87015e6befbe3c15caf6aa6b2df224fa33" %}
[角色骨架设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/491cfe5f38fba67eb46308256f5d4fa1ba67cda0" %}
[角色具身化](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/character-embodiment.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/embodiment/scripting-reference.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.
