> 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 脚本可以直接使用的公共 embodiment 类型参考： `EmbodimentContext`，则 `ConvaiCharacterModule<TProfile>` 自定义模块的基类， `StandardRigBinding`, `ConvaiTravelIntent`, `ModuleIds`，以及共享的 `CharacterDemeanor`, `StandardBone`, `StandardBlendshape`，以及 `RigConvention` 枚举。跨模块契约（例如 `IGazeSource` 和 `IEmotionStateSource` ）属于内部实现，不在此表面 API 范围内——请改为阅读各模块自己的控制器参考文档。

### `EmbodimentContext`

`EmbodimentContext` (`密封类：MonoBehaviour`）是角色作用域的组合根，embodiment 模块会解析它以访问共享基础设施。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`           | 角色根 Transform。                   |
| `EventHub`      | `IEventHub`           | 用于监听领域事件的事件总线。                   |
| `日志记录器`         | `ILogger`             | 用于结构化诊断的日志记录器。若尚未注入，可能为 `null` 。 |
| `RigBinding`    | `IStandardRigBinding` | 角色的 rig 绑定抽象（语义骨骼与 blendshape）。  |
| `Character`     | `ConvaiCharacter`     | 拥有该角色的对象（如果此层级中存在）。              |

#### 事件

| 事件                               | 签名                                  | 在以下情况时触发                                      |
| -------------------------------- | ----------------------------------- | --------------------------------------------- |
| `RigBindingChanged`              | `event Action<IStandardRigBinding>` | 语义 rig 绑定在运行时被重建或替换。缓存了骨骼或网格引用的模块应重新解析它们。     |
| `EmbodimentConfigurationChanged` | `event Action`                      | embodiment 模块配置在运行时已更新——例如应用了一个预设。            |
| `DependenciesPopulated`          | `event Action`                      | 诸如 `EventHub`、tick 调度器以及动画器基础设施等仅运行时依赖项会变为可用。 |

#### Tickable

| 成员                   | 签名                                                      | 描述                                                                                                                                                                              |
| -------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RegisterTickable`   | `bool RegisterTickable(IEmbodimentTickable tickable)`   | 驱动 `tickable` 从此角色的 embodiment 调度器执行，而不是使用 Unity 的按组件 `Update`，因此它的写入会按已声明的顺序相对于 Convai 自身的写入生效。请从 `OnEnable`调用。重复注册同一实例不会产生任何效果。返回 `false` ，表示当前还没有可加入的调度器——在 Play 模式之外这是正常情况。 |
| `UnregisterTickable` | `void UnregisterTickable(IEmbodimentTickable tickable)` | 停止驱动 `tickable`。请从 `OnDisable`调用。即使该 tickable 从未注册过，或者调度器已经消失，调用也安全。                                                                                                            |

### `ConvaiCharacterModule<TProfile>`

`ConvaiCharacterModule<TProfile>` (`抽象类：MonoBehaviour`, `[ExecuteAlways]`）是每个 embodiment 模块都要继承的基类—— `ConvaiGazeController`, `ConvaiBodyAnimationController`, `ConvaiBodyLanguageController`, `ConvaiConversationFlowController`，以及 `ConvaiEmotionController` 所有模块都扩展自它。 `TProfile` 是 `ScriptableObject` 该模块拥有的 profile 类型。编写你自己的此类型子类，就可以构建一个自定义 embodiment 模块，使其参与与随附模块相同的上下文解析、profile 接收器注册和 tick 生命周期。

#### 受保护成员

| 成员                      | 类型                        | 描述                                                                                 |
| ----------------------- | ------------------------- | ---------------------------------------------------------------------------------- |
| `上下文`                   | `EmbodimentContext`       | 为该角色解析得到的上下文。设置一次， `OnEnable` 成功后。                                                 |
| `EffectiveProfile`      | `TProfile`                | 已创作的 profile 资源（如果分配了的话），否则为来自 `DefaultProfileFactory`. `null` 之前 `Awake` 的运行时默认值。 |
| `ProfileModuleId`       | `abstract string`         | 此子类向 profile 接收器系统报告的模块 ID。当模块是五个随附模块之一时，请使用一个 `ModuleIds` 常量；否则使用你自己稳定的字符串。       |
| `DefaultProfileFactory` | `abstract Func<TProfile>` | 在未分配资源时创建运行时默认 profile 的工厂。                                                        |

#### 方法

| 方法                        | 签名                                                     | 描述                                                                                          |
| ------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `OnProfileApplied`        | `virtual void OnProfileApplied(TProfile newProfile)`   | 在 profile 槽位更新后调用，例如由预设触发。重写它以重置状态，或重新解析依赖 profile 的绑定。                                     |
| `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` 并在基类实现中处理上下文解析与 profile 接收器注册——重写任一方法时都要调用基类方法。

### `StandardRigBinding`

`StandardRigBinding` (`密封类：MonoBehaviour, IStandardRigBinding`, `[AddComponentMenu("Convai/Embodiment/Character Rig")]`）会检查角色层级，并据此解析语义骨骼和 blendshape 查找。有关检测与置信度如何工作，请参见 [角色骨骼设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md) 。

#### 属性

| 属性                    | 类型                                   | 描述                                                         |
| --------------------- | ------------------------------------ | ---------------------------------------------------------- |
| `Root`                | `Transform`                          | 如果角色有 Animator，则为其 Transform；否则为此组件自身的 Transform。          |
| `FacialMeshes`        | `IReadOnlyList<SkinnedMeshRenderer>` | 用于 blendshape 解析的网格。                                       |
| `DetectedConvention`  | `RigConvention`                      | 为该 rig 检测到的 blendshape 命名约定，或者在设置了手动覆盖时使用手动覆盖。             |
| `CustomConventionMap` | `CustomRigConventionMap`             | 自定义的语义到 blendshape 映射，用于当 `DetectedConvention` 为 `Custom`. |
| `DetectionConfidence` | `float`                              | 上一次检测过程的置信度，范围为 `0` 到 `1`. `1` 当手动设置了约定覆盖时。                |

#### 方法

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

### `ConvaiTravelIntent`

`ConvaiTravelIntent` (`密封类：MonoBehaviour, IEmbodimentTickable, ITravelIntentSource`, `[AddComponentMenu("Convai/Embodiment/Travel Intent")]`）用于报告角色正要去哪里，因此像 Gaze 这样的模块可以在角色行走时观察道路，而不是一直盯着目的地。

你通常不需要手动添加此组件——一旦角色开始移动，它就会自动提供，并在角色消失时一并消失。只有在想更改运动检测阈值或关闭自动检测时，才手动添加它。

Travel 从三个来源解析，优先级从高到低：通过 `ReportTravel` 或 `ReportTravelTo`的显式报告、来自 `ConvaiNavMeshLocomotion` 的推送（如果角色有的话），或 Convai 直接在角色 Transform 上观察到的移动。请在你自己的移动代码中调用 `ReportTravel` （或 `ReportTravelTo`）——例如一个 `NavMeshAgent`驱动的移动器、一个 `CharacterController`、根运动或 tween——这样即使角色的移动不是由 `ConvaiNavMeshLocomotion` 驱动，它在移动时也仍会正确转头并调整步态。如果不重复报告，报告会在 `TravelReportTimeoutSeconds` 后过期，因此停止报告的调用方不会让角色永远处于旅行状态。

#### 属性

| 属性                           | 类型             | 描述                                                                               |
| ---------------------------- | -------------- | -------------------------------------------------------------------------------- |
| `IsTraveling`                | `bool`         | 角色现在是否正在前往某处。                                                                    |
| `HasSubject`                 | `bool`         | 是否有任何内容声明了当前旅程的主题。没有主题时，角色会看着路，但心里没有目的地。                                         |
| `来源`                         | `TravelSource` | 当前 travel 读数的来源： `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` 的 travel，并在一次调用中将其设为 travel 主题。                       |
| `ClearTravel`    | `void ClearTravel()`                                                                | 立即结束已报告的旅程，而不必等待其过期。                                                              |
| `SetSubject`     | `void SetSubject(Transform subject)`                                                | 声明这段旅程是关于 `subject` ——例如，被跟随的人。这就是它为何会定期朝它瞥一眼。                                    |
| `SetSubject`     | `void SetSubject(Vector3 worldPosition)`                                            | 声明这段旅程是关于一个固定地点的。                                                                 |
| `ClearSubject`   | `void ClearSubject()`                                                               | 忘记这段旅程是关于什么的。角色仍会继续看路。                                                            |

### `ModuleIds`

`ModuleIds` (`静态类`）保存了 embodiment 模块在向 `EmbodimentContext`注册 profile 时使用的规范路由键，以及一个 `ConvaiEmbodimentPreset` slot 用来定位模块的键。

| 常量             | 值                          | 路由到                                |
| -------------- | -------------------------- | ---------------------------------- |
| `身体动画`         | `convai.body-animation`    | `ConvaiBodyAnimationController`    |
| `BodyLanguage` | `convai.body-language`     | `ConvaiBodyLanguageController`     |
| `对话流程`         | `convai.conversation-flow` | `ConvaiConversationFlowController` |
| `情绪`           | `convai.emotion`           | `ConvaiEmotionController`          |
| `注视`           | `convai.gaze`              | `ConvaiGazeController`             |

### `CharacterDemeanor`

`CharacterDemeanor` 是 Emotion、Body Animation 和 Body Language 编辑器共用的一套创作词汇，这样在每个模块的资源上选择相同的 demeanor 就能描述同一个连贯的角色。demeanor 只用于创作：应用它时只会把普通值写入正在编辑的资源，而运行时没有任何东西会读取这个枚举。每个模块都会按自己的语义来解释同一个词。

| 值      | 编号  | 描述                       |
| ------ | --- | ------------------------ |
| `沉稳`   | `0` | 平静而均衡——接待员、职员、向导。        |
| `温暖`   | `1` | 亲和且易读。当角色被刻意赋予个性时，这是默认值。 |
| `充满活力` | `2` | 反应大、速度快——主持人、导游、主播。      |
| `内敛`   | `3` | 几乎不表现任何情绪——警卫、司仪。        |

### `StandardBone`

`StandardBone` 识别角色 rig 骨骼的 embodiment 模块可以通过 `StandardRigBinding.TryGetBone`解析这些骨骼，而不依赖底层 rig 的命名约定。

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

### `StandardBlendshape`

`StandardBlendshape` 识别角色面部 blendshape 的 embodiment 模块可以通过 `StandardRigBinding.TryGetBlendshape`解析这些 blendshape。值遵循 ARKit 52-blendshape 命名约定；其他约定（Reallusion CC3、MetaHuman、Custom）都会映射到这些相同的语义名称上。并非每个 rig 都提供每个 blendshape——模块必须能够优雅地处理 `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`                                                                                                                                                                                                                                                                                                                                                |
| Cheek / Nose | `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` 识别 blendshape 和骨骼命名约定 `StandardRigBinding` ，适用于角色面部 rig 检测到的约定，或作为覆盖手动指定的约定。

| 值                       | 编号   | 描述                                                                     |
| ----------------------- | ---- | ---------------------------------------------------------------------- |
| `未知`                    | `0`  | 检测尚未运行，或者该 rig 未匹配任何已知约定。                                              |
| `ARKit`                 | `1`  | Apple ARKit 52-blendshape 约定。大多数 VRoid 和 MetaHuman 导出的 rig 都使用它。       |
| `ReallusionCC3`         | `2`  | Reallusion Character Creator 3 的基础面部 rig。                              |
| `MetaHuman`             | `3`  | Epic MetaHuman 原生面部 rig。                                               |
| `ReallusionCC4Extended` | `4`  | Reallusion Character Creator 4 Extended 面部配置文件——严格来说是 `ReallusionCC3`. |
| `Custom`                | `99` | 的超集。 `CustomRigConventionMap` 该 rig 不匹配任何内置约定；由一个                      |

### 相关参考

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

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

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