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

# 肢体语言脚本参考

Convai 肢体语言模块的完整 API 参考，涵盖控制器、读取结构体、句柄以及所有公共枚举类型。

Convai Body Language 模块中公共类型的完整 API 参考。类型位于 `Convai.Modules.BodyLanguage.Components`, `Convai.Domain.Embodiment.Readings`, `Convai.Domain.Embodiment.Interfaces`或 `Convai.Domain.Embodiment.Semantics`中，具体位置已按类型注明。跨模块契约（`IBodyLanguageSource` 以及内部 director）均为 `internal` ，不属于公共 API。

### `ConvaiBodyLanguageController`

`MonoBehaviour` — `Convai.Modules.BodyLanguage.Components`

菜单路径： **Convai > Embodiment > Body Language**

限制： `DisallowMultipleComponent`

#### 返回的结果

| 属性               | 类型                    | 说明                                                                                                 |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
| `Current`        | `BodyLanguageReading` | 最新发布的肢体语言读数。只读遥测数据——切勿构造读数来驱动肢体动作。                                                                 |
| `Expressiveness` | `float` （获取/设置）       | 运行时表现力覆盖值， `0`–`1`。设置后，该值优先于配置文件，直到下次热切换配置文件。Getter 返回有效值：如果设置了覆盖值，则返回该值；否则返回最近一次 tick 时配置文件解析出的值。 |

#### 方法

| 方法                       | 签名                                                                  | 说明                                                                                                                   |
| ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Nod`                    | `HeadGestureHandle Nod(HeadGestureKind kind, float intensity = 1f)` | 请求执行一次脚本化头部动作。返回一个句柄，其 `Completion` 会在动作执行结束时完成。若请求被拒绝或不可用，则返回一个已完成的句柄，其 `IsActive == false` ——绝不会返回 `null`，也不会抛出异常。 |
| `PulseGesture`           | `GestureCueHandle PulseGesture(GestureCue cue)`                     | 请求执行一次脚本化语义手势提示，其优先级高于自动手势。返回一个句柄，其 `Completion` 会在确定分发结果后立即完成。绝不会返回 `null`，也不会抛出异常。                                 |
| `TriggerReaction`        | `void TriggerReaction(ReactionKind kind, float intensity = 1f)`     | 触发一次即发即弃的单次身体反应。无句柄。可安全地对无法 tick 的控制器调用——调用会静默地无操作。                                                                  |
| `ClearScriptedOverrides` | `void ClearScriptedOverrides()`                                     | 完成所有尚未完成的 `Nod`/`PulseGesture` 句柄，并将头部手势通道交还给自动导演。此操作具有幂等性。                                                          |
| `CaptureSnapshot`        | `void CaptureSnapshot(BodyLanguageSnapshot snapshot)`               | 将完整的实时诊断状态填入调用方拥有且可重复使用的 `BodyLanguageSnapshot` 。                                                                    |
| `CaptureSnapshot`        | `BodyLanguageSnapshot CaptureSnapshot()`                            | 上述方法的便捷重载，会分配新对象。                                                                                                    |

请参阅 [触发手势和反应](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/gestures-and-reactions.md) ，了解用法以及 `HeadGestureRefusal` 的处理模式。

### `BodyLanguageReading`

`Convai.Domain.Embodiment.Readings` — 只读结构体

角色当前非语言状态的不可变快照，通过内部 `IBodyLanguageSource` 契约发布，并在控制器上通过 `Current`公开。与引擎无关（不包含 `UnityEngine` 引用）。

#### 返回的结果

| 属性                      | 类型                   | 说明                                                        |
| ----------------------- | -------------------- | --------------------------------------------------------- |
| `DialogueState`         | `DialogueState`      | 策略引擎当前正在处理的对话状态。                                          |
| `PostureOpenness`       | `float`              | 姿势开放度， `-1` （闭合/戒备）至 `1` （开放），弹簧稳定后的当前值。                  |
| `PostureLean`           | `float`              | 矢状面倾斜度， `-1` （后仰）至 `1` （前倾），弹簧稳定后的当前值。                    |
| `ShoulderTension`       | `float`              | 肩部/躯干张力， `-1`–`1`，弹簧稳定后的当前值。                              |
| `BreathPhase`           | `float`              | 呼吸振荡器的相位，归一化至 `[0, 1)`. `0` 表示周期起点。                       |
| `Suppression`           | `GestureSuppression` | 对话手势执行器报告的当前手势通道抑制状态。                                     |
| `HasActiveHeadGesture`  | `bool`               | 当前是否正在播放脚本化头部手势程序（`Nod`/`Shake`/`Tilt`）。                  |
| `ActiveHeadGestureKind` | `HeadGestureKind`    | 当前正在播放的头部手势程序类型。仅当 `HasActiveHeadGesture` 为 `true`.       |
| `LastGestureCueKind`    | `GestureCueKind`     | 上一次尝试的语义手势提示类型，无论请求被接受还是拒绝。                               |
| `WeightShift`           | `float`              | 姿态控制器当前的骨盆横向重心偏移值， `-1` （左）至 `1` （右）。 `0` 在重心偏移已禁用或尚未安排时。 |
| `Expressiveness`        | `float`              | 此刻的有效表现力， `0`–`1`.                                        |
| `ActiveReaction`        | `ReactionKind`       | 当前正在播放的一次性身体反应， `ReactionKind.None` 表示空闲。                 |

#### 静态成员

| 成员                         | 说明                                              |
| -------------------------- | ----------------------------------------------- |
| `BodyLanguageReading.None` | 未参与／静止状态的读数——没有活动手势，姿势中立， `DialogueState.Idle`. |

### `HeadGestureHandle`

`Convai.Modules.BodyLanguage.Components` — 密封类

用于单个脚本化 `Nod` 请求的实时句柄。所有操作均为幂等操作，且不会抛出异常。

#### 返回的结果

| 属性           | 类型                   | 说明                                                                        |
| ------------ | -------------------- | ------------------------------------------------------------------------- |
| `Kind`       | `HeadGestureKind`    | 请求的手势类型。                                                                  |
| `IsActive`   | `bool`               | 请求是否仍然有效——尚未完成、被取代或清除。                                                    |
| `Refusal`    | `HeadGestureRefusal` | 请求被拒绝的原因；此时句柄从未处于有效状态。已接受的请求始终为 `None` 即使请求已结束也如此。                        |
| `Completion` | `Task`               | 头部手势程序结束时完成——自然结束、被取代，或被 `ClearScriptedOverrides`清除。对于被拒绝的请求，该任务在构造时即已完成。 |

#### 方法

| 方法        | 签名               | 说明                  |
| --------- | ---------------- | ------------------- |
| `Release` | `void Release()` | 放弃对此请求的关注。可安全地多次调用。 |

### `HeadGestureRefusal`

`Convai.Modules.BodyLanguage.Components` — 枚举

脚本化头部手势请求未能成为有效程序的原因。

| 值             | 整数  | 说明                                                       |
| ------------- | --- | -------------------------------------------------------- |
| `None`        | `0` | 请求已接受；此句柄表示一个正在运行的程序。                                    |
| `Busy`        | `1` | 角色正在执行头部动作，且后面还排队等待执行一个动作。此状态是暂时的——通常稍后片刻再次发送相同请求即可成功。   |
| `Unavailable` | `2` | 角色目前完全无法执行头部动作：没有可用的骨架、没有 Body Language 配置，或该组件已禁用或未在运行。 |

### `GestureCueHandle`

`Convai.Modules.BodyLanguage.Components` — 密封类

用于单个脚本化 `PulseGesture` 请求的实时句柄。所有操作均具备幂等性，且绝不会抛出异常。

#### 返回的结果

| 属性           | 类型               | 说明                                                    |
| ------------ | ---------------- | ----------------------------------------------------- |
| `Kind`       | `GestureCueKind` | 请求的提示类型。                                              |
| `IsActive`   | `bool`           | 请求是否仍在等待派发结果。对于被拒绝或替换的提示，始终 `false` 立即返回。             |
| `Completion` | `Task`           | 提示的派发结果一经确定（已接受执行，或被拒绝/替换），操作即完成。不会跟踪最终动画片段直至其视觉播放结束。 |

#### 方法

| 方法        | 签名               | 说明                  |
| --------- | ---------------- | ------------------- |
| `Release` | `void Release()` | 放弃对此请求的关注。可安全地多次调用。 |

### `GestureCue`

`Convai.Domain.Embodiment.Interfaces` — 只读结构体

用于执行一个语义动作的单次请求——可来自脚本调用、后端操作，或内部的肯定/否定响应节拍。零分配值类型。

#### 返回的结果

| 属性          | 类型               | 说明                                  |
| ----------- | ---------------- | ----------------------------------- |
| `Kind`      | `GestureCueKind` | 请求动作的语义类别。                          |
| `Intensity` | `float`          | 请求的相对强度/强调程度，通常为 `0`–`1+`。默认值为 `1`. |

#### 构造函数

```csharp
new GestureCue(GestureCueKind.Affirmative)               // kind, intensity defaults to 1
new GestureCue(GestureCueKind.Uncertain, intensity: 0.6f) // kind + intensity
```

#### 静态成员

| 成员                | 说明                                 |
| ----------------- | ---------------------------------- |
| `GestureCue.None` | 无操作提示： `GestureCueKind.None` 强度为零。 |

### `GestureCueKind`

`Convai.Domain.Embodiment.Interfaces` — 枚举

脚本或后端驱动的动作请求可携带的语义类别。

| 值                | 整数   | 随附内容 | 说明                                                                             |
| ---------------- | ---- | ---- | ------------------------------------------------------------------------------ |
| `None`           | `0`  | —    | 未请求动作。始终会被拒绝。                                                                  |
| `Affirmative`    | `1`  | 是    | 表示肯定的节拍（例如“是”、表示赞同）。                                                           |
| `Negative`       | `2`  | 是    | 表示否定的节拍（例如“不”、表示反对）。                                                           |
| `Greeting`       | `3`  | 是    | 问候或告别节拍（例如“你好”“再见”）。                                                           |
| `Uncertain`      | `4`  | 是    | 表示不确定或思考的节拍（例如“嗯”、沉思）。                                                         |
| `Emphatic`       | `5`  | 预留   | 用于强调性伴语动作的节拍。目前随附内容尚未标记此类型——该类型预留给未来的伴语手势控制器。                                  |
| `Beat`           | `6`  | 预留   | 通用的节奏性伴语节拍。目前随附内容尚未标记此类型。                                                      |
| `PalmToPlayer`   | `7`  | 预留   | 掌心朝向玩家的手势，预期在角色台词中出现第二人称词语时触发。目前随附内容尚未标记此类型——在创作包含该手势的内容之前，指示性手势控制器将完全不执行任何操作。 |
| `HandToChest`    | `8`  | 预留   | 一种手放胸前的手势，旨在由第一人称代词触发。目前发布的内容中尚未标记此类手势。                                        |
| `IndicateObject` | `9`  | 预留   | 一种指示/指向手势，旨在在提及已注册的场景对象时触发。目前发布的内容中尚未标记此类手势。                                   |
| `Enumerate`      | `10` | 预留   | 一种列举节拍，旨在由序数词或数字词触发。目前发布的内容中尚未标记此类手势。                                          |

由保留值构建的提示始终会解析为“无映射”，并回退到头部节拍/姿势脉冲（以及在手臂链完整时，回退到程序化手臂/手部）原语——参见 [触发手势与反应](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/gestures-and-reactions.md).

### `ReactionKind`

`Convai.Domain.Embodiment.Semantics` — 枚举

身体语言可请求的即发即弃身体反应类型。

| 值                 | 整数  | 说明                              |
| ----------------- | --- | ------------------------------- |
| `None`            | `0` | 当前没有反应。                         |
| `SurpriseFlinch`  | `1` | 快速受惊反应：脊柱短暂挺直，肩膀猛地一抖。驱动程序化反应包络。 |
| `AmusementBounce` | `2` | 轻微愉悦的胸部弹动。驱动程序化反应包络。            |
| `CatchBreath`     | `3` | 快速而急促地吸一口气。转交给呼吸系统自身的屏息事件。      |
| `Sigh`            | `4` | 缓慢、深长地呼吸一次。转交给呼吸系统自身的叹气事件。      |

### `HeadGestureKind`

`Convai.Domain.Embodiment.Interfaces` — 枚举

身体语言可请求的脚本化单次头部手势类型。

| 值       | 整数  | 说明                          |
| ------- | --- | --------------------------- |
| `Nod`   | `0` | 俯仰方向连续点头两次（下-上-下-停稳）——表示肯定。 |
| `Shake` | `1` | 偏航方向连续摆动两次——表示否定/拒绝的摇头。     |
| `Tilt`  | `2` | 滚转方向缓入-保持-缓出——表示好奇/思索的歪头。   |

### `ExpressivenessPreset`

`Convai.Domain.Embodiment.Semantics` — 枚举

身体语言的单一表现力刻度：一个由创作者或运行时设置的参数，用于协调缩放整个非语言系统的动作幅度、频率和多样性。

| 值            | 整数  | 说明                                                       |
| ------------ | --- | -------------------------------------------------------- |
| `Subtle`     | `0` | 极简、含蓄的动作：幅度较小、节奏较慢；可选行为或受丰富度控制的行为大多或完全不启用。               |
| `Natural`    | `1` | 发布时的默认设置：在正常的 2 米对话摄像机距离下，非语言行为清晰可见，但不会显得刻意表演。           |
| `Expressive` | `2` | 动作幅度、频率和多样性均高于 `Natural`.                                |
| `Theatrical` | `3` | 动作幅度、频率和丰富度均达到最大——呈现大幅度、戏剧化的表演风格。                        |
| `Custom`     | `4` | 使用配置文件自身的 `Custom Expressiveness` 标量（`0`–`1`），而非固定的锚点预设。 |

### `BodyLanguageSnapshot`

`Convai.Modules.BodyLanguage.Core.Diagnostics` — 密封类

用于 HUD 和测试的身体语言运行时状态可变、可复用的捕获对象。只需分配一次，然后通过 `ConvaiBodyLanguageController.CaptureSnapshot(BodyLanguageSnapshot)`.

#### 选定属性

| 属性                                                                    | 类型                             | 说明                                         |
| --------------------------------------------------------------------- | ------------------------------ | ------------------------------------------ |
| `DialogueState`                                                       | `DialogueState`                | 策略引擎在此帧处理的对话状态。                            |
| `IsInert`                                                             | `bool`                         | 模块是否处于惰性状态——骨架不可用、记录一条错误，且每个 tick 不执行任何工作。 |
| `HasSpine` / `HasChest` / `HasUpperChest` / `HasShoulders`            | `bool`                         | 骨架解析出的躯干骨骼。                                |
| `ProfileName`                                                         | `string`                       | 捕获时生效的配置文件名称。                              |
| `MasterWeight`                                                        | `float`                        | 此 tick 的姿势/呼吸主权重。 `0` 表示完全不写入任何骨骼。         |
| `BreathPhase` / `BreathRateCpm` / `BreathDepth`                       | `float`                        | 实时呼吸振荡器状态。                                 |
| `HeadGestureIsPlaying` / `HeadGestureProgress`                        | `bool` / `float`               | 脚本化头部手势是否正在播放，以及其归一化进度。                    |
| `GesticulationSuppression`                                            | `GestureSuppression`           | 对话手势执行器报告的当前抑制值。                           |
| `LastGestureCueKind` / `LastGestureCueAccepted`                       | `GestureCueKind` / `bool`      | 最近尝试的语义提示，以及该提示是否被接受。                      |
| `ReactionFlinch` / `ReactionBounce`                                   | `float`                        | 当前闪避和弹跳反应包络值。                              |
| `Expressiveness` / `AmplitudeGain` / `FrequencyGain` / `RichnessGain` | `float`                        | 解析出的表现力及其三个派生增益。                           |
| `RecentTrace`                                                         | `List<BodyLanguageTraceEntry>` | 最近的跟踪日志条目，按时间从早到晚排列。                       |

完整字段列表与 `ConvaiBodyLanguageController` 检查器中的 **运行时状态** 部分所显示的内容一致，详见 [排查肢体语言问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/troubleshooting.md).

### 后续步骤

{% content-ref url="/pages/b0a834d0e9425d60d0788646a7b3343330f88cf0" %}
[触发手势与反应](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/gestures-and-reactions.md)
{% endcontent-ref %}

{% content-ref url="/pages/aa2dfbd502cd5beea5e136b8b51781cf4aa0c88c" %}
[肢体语言配置文件参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/profile-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/36545202fce61c9549c36fc04283ca75f22dd128" %}
[肢体语言故障排查](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/troubleshooting.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/body-language/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.
