> 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` ，不属于公共接口的一部分。

### `ConvaiBodyLanguageController`

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

菜单路径： **Convai > 具身化 > 身体语言**

约束： `DisallowMultipleComponent`

#### 属性

| 属性    | 类型                    | 描述                                                                                             |
| ----- | --------------------- | ---------------------------------------------------------------------------------------------- |
| `当前`  | `BodyLanguageReading` | 最新发布的肢体语言读数。只读遥测——绝不要构造读数来驱动身体。                                                                |
| `表现力` | `float` （get/set）     | 运行时表达力覆盖， `0`–`1`。设置后会优先于配置文件，直到下一次配置文件热切换。getter 返回有效值：若已设置则返回覆盖值，否则返回最近一次 tick 时配置文件自身解析出的值。 |

#### 方法

| 方法                       | 签名                                                                  | 描述                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `点头`                     | `HeadGestureHandle Nod(HeadGestureKind kind, float intensity = 1f)` | 请求一个脚本化的一次性头部动作。返回的 handle 的 `完成` 会在程序结束时完成。被拒绝或不可用的请求会返回一个已完成的 handle，并且 `IsActive == false` ——绝不 `null`，也绝不抛出异常。 |
| `PulseGesture`           | `GestureCueHandle PulseGesture(GestureCue cue)`                     | 请求一个脚本化的语义手势提示，其优先级高于自动手势。返回的 handle 的 `完成` 会在分发结果已知时立即完成。绝不 `null`，也绝不抛出异常。                                       |
| `TriggerReaction`        | `void TriggerReaction(ReactionKind kind, float intensity = 1f)`     | 一次性、只管触发的身体反应。没有 handle。可安全地在不能 tick 的控制器上调用——静默无操作。                                                               |
| `ClearScriptedOverrides` | `void ClearScriptedOverrides()`                                     | 完成所有未结的 `点头`/`PulseGesture` handle，并将头部动作通道交还给自动 director。幂等。                                                      |
| `CaptureSnapshot`        | `void CaptureSnapshot(BodyLanguageSnapshot snapshot)`               | 用调用方拥有、可复用的 `BodyLanguageSnapshot` 填充完整的实时诊断状态。                                                                    |
| `CaptureSnapshot`        | `BodyLanguageSnapshot CaptureSnapshot()`                            | 对上面方法的分配型便捷重载。                                                                                                     |

参见 [触发手势和反应](/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` 契约发布，并在控制器上暴露为 `当前`。不依赖引擎（没有 `UnityEngine` 引用）。

#### 属性

| 属性                      | 类型                         | 描述                                                               |
| ----------------------- | -------------------------- | ---------------------------------------------------------------- |
| `DialogueState`         | `DialogueState`            | 策略引擎当前正在作用的对话状态。                                                 |
| `PostureOpenness`       | `float`                    | 姿态开放度， `-1` （封闭/戒备）到 `1` （开放），经弹簧平滑后的当前值。                        |
| `PostureLean`           | `float`                    | 矢状面前倾/后仰， `-1` （后倾）到 `1` （前倾），经弹簧平滑后的当前值。                        |
| `ShoulderTension`       | `float`                    | 肩部/躯干紧张度， `-1`–`1`，经弹簧平滑后的当前值。                                   |
| `BreathPhase`           | `float`                    | 呼吸振荡器相位，归一化到 `[0, 1)`. `0` 为周期起点。                                |
| `抑制`                    | `GesticulationSuppression` | 会话手势执行器报告的当前手势通道抑制。                                              |
| `HasActiveHeadGesture`  | `bool`                     | 当前是否有一个脚本化头部动作程序（`点头`/`摇头`/`倾斜`）正在播放。                            |
| `ActiveHeadGestureKind` | `HeadGestureKind`          | 当前正在播放的头部动作程序的种类。只有在 `HasActiveHeadGesture` 为 `true`.            |
| `LastGestureCueKind`    | `GestureCueKind`           | 最后一次尝试的语义手势提示种类，无论是否被接受或拒绝。                                      |
| `WeightShift`           | `float`                    | 姿态 director 当前的髋部侧向重心转移值， `-1` （左）到 `1` （右）。 `0` 当重心转移被禁用或尚未排程时。 |
| `表现力`                   | `float`                    | 本 tick 的有效表达力， `0`–`1`.                                          |
| `ActiveReaction`        | `ReactionKind`             | 当前正在播放的一次性身体反应， `ReactionKind.None` 在空闲时。                        |

#### 静态成员

| 成员                         | 描述                                           |
| -------------------------- | -------------------------------------------- |
| `BodyLanguageReading.None` | 脱离/静止的读数——没有活动手势，姿态中性， `DialogueState.Idle`. |

### `HeadGestureHandle`

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

单个脚本化 `点头` 请求的活动 handle。所有操作都是幂等的，并且绝不抛出异常。

#### 属性

| 属性         | 类型                   | 描述                                                                      |
| ---------- | -------------------- | ----------------------------------------------------------------------- |
| `类型`       | `HeadGestureKind`    | 请求的手势种类。                                                                |
| `IsActive` | `bool`               | 该请求是否仍然存活——尚未完成、被取代或被清除。                                                |
| `拒绝原因`     | `HeadGestureRefusal` | 为何该请求被拒绝，适用于从未存活过的 handle。始终 `无` 适用于已接受的请求，包括其结束之后。                     |
| `完成`       | `Task`               | 在头部动作程序结束时完成——自然结束、被取代，或被 `ClearScriptedOverrides`清除。对于被拒绝的请求，在构造时就已完成。 |

#### 方法

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

### `HeadGestureRefusal`

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

为什么一个脚本化头部动作请求没有成为一个活跃程序。

| 值      | Integer | 描述                                                  |
| ------ | ------- | --------------------------------------------------- |
| `无`    | `0`     | 请求已被接受；该句柄表示一个正在运行的程序。                              |
| `Busy` | `1`     | 角色已经在执行一个头部手势，并且后面还排了另一个。该情况是暂时性的——同样的请求在稍后片刻通常会成功。 |
| `不可用`  | `2`     | 角色当前完全无法执行头部手势：没有可用的骨架、没有身体语言配置文件，或者该组件被禁用或未在播放。    |

### `GestureCueHandle`

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

单个脚本化 `PulseGesture` 请求的活动 handle。所有操作都是幂等的，并且绝不抛出异常。

#### 属性

| 属性         | 类型               | 描述                                                   |
| ---------- | ---------------- | ---------------------------------------------------- |
| `类型`       | `GestureCueKind` | 请求的提示种类。                                             |
| `IsActive` | `bool`           | 该请求是否仍在等待其分发结果。始终 `false` 对于被拒绝或被替换的提示会立即如此。         |
| `完成`       | `Task`           | 一旦提示的分发结果已知就完成（用于表演则接受，或被拒绝/被替换）。不会跟踪最终生成的片段在视觉上的结束。 |

#### 方法

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

### `GestureCue`

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

执行语义手势的单个请求——来自脚本调用、后端动作，或内部反应性的肯定/否定节拍。零分配值类型。

#### 属性

| 属性   | 类型               | 描述                               |
| ---- | ---------------- | -------------------------------- |
| `类型` | `GestureCueKind` | 所请求手势的语义类别。                      |
| `强度` | `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` — 枚举

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

| 值        | Integer | 已发货内容 | 描述                                                                            |
| -------- | ------- | ----- | ----------------------------------------------------------------------------- |
| `无`      | `0`     | —     | 未请求手势。始终被拒绝。                                                                  |
| `肯定`     | `1`     | 是     | 一个肯定节拍（例如“是”、同意）。                                                             |
| `否定`     | `2`     | 是     | 一个否定节拍（例如“不是”、不同意）。                                                           |
| `问候`     | `3`     | 是     | 一个问候或告别节拍（例如“嗨”、“拜拜”）。                                                        |
| `不确定`    | `4`     | 是     | 一个不确定/思考节拍（例如“嗯”、沉思）。                                                         |
| `强调`     | `5`     | 内敛    | 一个强调性的伴语手势节拍。已发货内容尚未标记这种类型——保留给未来的伴语手势 director。                              |
| `节拍`     | `6`     | 内敛    | 一个通用的节奏性伴语手势节拍。已发货内容尚未标记这种类型。                                                 |
| `手掌朝向玩家` | `7`     | 内敛    | 一个朝向玩家张开的手掌手势，旨在角色台词中出现第二人称词时触发。已发货内容尚未标记这种类型——在内容为其编写之前，指涉手势 director 完全不工作。 |
| `手放胸前`   | `8`     | 内敛    | 一个手按胸口的手势，旨在第一人称词出现时触发。已发货内容尚未标记这种类型。                                         |
| `指示物体`   | `9`     | 内敛    | 一个指示/指向手势，旨在注册的场景对象被命名时触发。已发货内容尚未标记这种类型。                                      |
| `列举`     | `10`    | 内敛    | 一个枚举节拍，旨在序数词或数字词出现时触发。已发货内容尚未标记这种类型。                                          |

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

### `ReactionKind`

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

身体语言可请求的一次性身体反应种类。

| 值       | Integer | 描述                            |
| ------- | ------- | ----------------------------- |
| `无`     | `0`     | 无活动反应。                        |
| `惊讶一颤`  | `1`     | 一次快速受惊：脊柱短暂伸直，肩膀一跳。驱动程序化反应包络。 |
| `愉悦弹动`  | `2`     | 一次轻微、愉快的胸部轻弹。驱动程序化反应包络。       |
| `倒吸一口气` | `3`     | 一次快速、锐利的吸气。路由到呼吸系统自身的吸气事件。    |
| `叹气`    | `4`     | 一次漫长、深而慢的呼吸。路由到呼吸系统自身的叹息事件。   |

### `HeadGestureKind`

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

身体语言可请求的脚本化一次性头部动作种类。

| 值    | Integer | 描述                           |
| ---- | ------- | ---------------------------- |
| `点头` | `0`     | 俯仰双点头（下-上-下-停稳）——肯定性的确认。     |
| `摇头` | `1`     | 偏航双交替——否定/拒绝式摇头。             |
| `倾斜` | `2`     | 翻滚式舒缓进入-保持-舒缓退出——好奇/思考式头部倾斜。 |

### `ExpressivenessPreset`

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

身体语言的单一表达力旋钮：一个作者设定或运行时的单一参数，可一致地调节整个非语言系统看起来有多大、多频繁以及多丰富。

| 值        | Integer | 描述                                           |
| -------- | ------- | -------------------------------------------- |
| `含蓄`     | `0`     | 最小、克制的动作：小幅度、更慢的节奏，带有可选/由丰富度门控的行为，大多或完全缺失。   |
| `自然`     | `1`     | 已发货的默认值：在正常 2 米对话相机距离下可清晰看到的非语言行为，但不会显得像在表演。 |
| `富有表现力`  | `2`     | 比 `自然`.                                      |
| `戏剧化`    | `3`     | 最大幅度、频率和丰富度——一个夸张而具有戏剧感的表演者。                 |
| `Custom` | `4`     | 更大、更频繁、更多样的动作。 `自定义表现力` 配置文件自身的`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`                                 | `GesticulationSuppression`     | 会话手势执行器报告的当前抑制。                       |
| `LastGestureCueKind` / `LastGestureCueAccepted`            | `GestureCueKind` / `bool`      | 最后一次尝试的语义提示，以及它是否被接受。                 |
| `ReactionFlinch` / `ReactionBounce`                        | `float`                        | 当前受惊与弹跳反应包络值。                         |
| `表现力` / `AmplitudeGain` / `FrequencyGain` / `RichnessGain` | `float`                        | 已解析的表达力及其三个派生增益。                      |
| `RecentTrace`                                              | `List<BodyLanguageTraceEntry>` | 最近的跟踪日志条目，最旧的在前。                      |

完整字段列表与 `ConvaiBodyLanguageController` 检查器的 **运行时状态** 部分绘制的内容一致——见 [排查身体语言问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/troubleshooting.md).

### 下一步

{% content-ref url="/pages/b0a834d0e9425d60d0788646a7b3343330f88cf0" %}
[触发手势与反应](/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" %}
[肢体语言配置文件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/profile-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/36545202fce61c9549c36fc04283ca75f22dd128" %}
[肢体语言故障排查](/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 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/body-language/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.