> 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/gestures-and-reactions.md).

# 触发手势与反应

在 Convai 角色上触发脚本化的点头、语义手势提示和一次性反应，并处理被拒绝或忙碌的请求。

在具有以下组件的 Convai 角色上触发脚本化头部动作、语义动作提示或一次性身体反应： `ConvaiBodyLanguageController`，并处理角色当前无法执行该动作的情况。

### 前提条件

* 已添加并正在运行的 Humanoid 角色，包含 `ConvaiBodyLanguageController` (**Convai > 具身化 > 身体语言**）。请参阅 [身体语言快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/quick-start.md).
* 对角色上控制器的引用，通过以下方式获取： `GetComponent<ConvaiBodyLanguageController>()`.

### 触发脚本化头部动作

调用 `Nod(HeadGestureKind kind, float intensity = 1f)` 以请求一次性的 `Nod`, `Shake`或 `Tilt`动作。该方法会返回一个 `HeadGestureHandle` ，其 `Completion` 任务会在程序结束时完成——动作自然结束、被另一个动作取代，或被 `ClearScriptedOverrides()`.

```csharp
using Convai.Domain.Embodiment.Interfaces;
using Convai.Modules.BodyLanguage.Components;
using UnityEngine;

public class HeadGestureExample : MonoBehaviour
{
    private ConvaiBodyLanguageController _bodyLanguage;

    private void Awake()
    {
        _bodyLanguage = GetComponent<ConvaiBodyLanguageController>();
    }

    public async void NodOnce()
    {
        HeadGestureHandle handle = _bodyLanguage.Nod(HeadGestureKind.Nod, intensity: 1f);
        await handle.Completion;
    }
}
```

脚本化的 `Nod`/`Shake` 动作会以自身经过阻尼处理的双点头方式完成确认，其持续时间刻意设置得比自动的协同语音节拍更长、幅度更平缓。脚本化请求与自动协同语音节拍和聆听时的倾斜保持共用同一个活动/待处理槽位，因此，如果角色正在执行动作时发出请求，该请求可能会被拒绝。

### 处理被拒绝的头部动作请求

`Nod` 绝不会返回 `null` ，也绝不会抛出异常。如果请求被拒绝或不可用，则会返回一个已完成的句柄，其中 `IsActive` 设为 `false` ，而 `Refusal` 设为某个 `HeadGestureRefusal` 值。忽略该值的调用方 `Refusal` 当手势无法播放时，会静默地什么也不做，因此在假定手势已执行之前，请先检查：

| `HeadGestureRefusal` | 含义                                                            | 操作方法                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `None` (`0`)         | 请求已被接受；此句柄表示一个正在运行的程序。                                        | 等待 `Completion` 即可。                                                                                                                                            |
| `Busy` (`1`)         | 角色正在执行头部手势，且队列中还排着一个手势。这是暂时状态——稍后片刻重试同一请求通常就会成功。              | 稍等片刻后重试，或者跳过这一行的手势。                                                                                                                                            |
| `Unavailable` (`2`)  | 角色当前完全无法执行头部手势：没有可用的骨骼绑定、没有 Body Language 配置文件，或者该组件已禁用或未在运行。 | 不要重试。请修复设置问题——参见 [排查 Body Language 问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/troubleshooting.md). |

```csharp
HeadGestureHandle handle = _bodyLanguage.Nod(HeadGestureKind.Shake, intensity: 0.8f);

if (!handle.IsActive)
{
    switch (handle.Refusal)
    {
        case HeadGestureRefusal.Busy:
            // 暂时状态 — 稍后重试是安全的。
            break;
        case HeadGestureRefusal.Unavailable:
            // 骨骼绑定或配置文件不支持该手势。不要重试。
            break;
    }
}
```

{% hint style="info" %}
随附的动作执行器 `ConvaiHeadResponseActionExecutor` （菜单路径 **Convai > Actions > Nod Or Shake Head**）已实现此重试逻辑：遇到 `Busy` 拒绝时，最多等待 1.5 秒，然后才会将动作步骤判定为失败。使用它即可让点头或摇头响应 Convai 的动作，无需自行编写这套逻辑。参见 [角色动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions.md).
{% endhint %}

### 触发语义手势提示

`PulseGesture(GestureCue cue)` 会请求一个优先级高于自动手势的语义手势。它会返回一个 `GestureCueHandle` 其 `Completion` 会在提示的分发结果确定后立即完成——即被接受并开始播放，或被拒绝并替换。它不会跟踪生成的动画片段，直到其视觉播放结束。

```csharp
using Convai.Domain.Embodiment.Interfaces;

GestureCueHandle cue = _bodyLanguage.PulseGesture(new GestureCue(GestureCueKind.Affirmative));
await cue.Completion;
```

目前只有四种 `GestureCueKind` 值映射到随附的动画内容： `Affirmative`, `Negative`, `Greeting`和 `Uncertain`。其余值—— `Emphatic`, `Beat`, `PalmToPlayer`, `HandToChest`, `IndicateObject`和 `Enumerate` ——这些是为未来的伴随言语手势和指示性手势内容预留的数据模型槽位。已发布的动画集没有任何动画片段带有这些标签，因此由预留值构建的提示始终会解析为“无映射”：请求会回退到相同的点头和姿势脉冲基础动作 `PulseGesture` 会对任何被拒绝的提示使用这些动作；如果 Humanoid 手臂链完整，还会执行简短的程序化手臂/手部手势。 `GestureCueKind.None` 始终会被拒绝。

### 触发反应

`TriggerReaction(ReactionKind kind, float intensity = 1f)` 会触发一次性身体反应。该调用是即发即弃的——不会返回句柄，因为每个反应包络的持续时间都不到两秒。

```csharp
_bodyLanguage.TriggerReaction(ReactionKind.AmusementBounce, intensity: 0.8f);
```

| `ReactionKind`          | 动作             | 触发条件                         |
| ----------------------- | -------------- | ---------------------------- |
| `None` (`0`)            | 无反应。           | 无操作。                         |
| `SurpriseFlinch` (`1`)  | 脊柱短暂挺直，肩膀猛地一抖。 | 自主触发的惊讶反应峰值，或由脚本触发。          |
| `AmusementBounce` (`2`) | 愉悦时胸部轻微弹动。     | 自主触发的喜悦反应峰值，或由脚本触发。          |
| `CatchBreath` (`3`)     | 转发至呼吸系统的屏息事件。  | 仅由脚本触发，通过 `TriggerReaction`. |
| `Sigh` (`4`)            | 转发至呼吸系统的叹气事件。  | 仅由脚本触发，通过 `TriggerReaction`. |

以下反应中同一时间只会播放一个： `SurpriseFlinch`/`AmusementBounce` 触发新反应会替换当前正在播放的反应。每种类别都遵循其自身的配置文件开关（`React To Sudden Emotion`, `Catch Breath When Interrupted`, `Sigh When Settling`）；已禁用的类别会被静默忽略。

`TriggerReaction` 可安全地在无法更新的控制器上调用——例如已禁用、未播放或因缺少绑定骨架而处于惰性状态的控制器；调用会静默地变成无操作，与 `Nod` 和 `PulseGesture`的降级行为一致。

### 清除脚本覆盖

`ClearScriptedOverrides()` 会完成所有尚未完成的 `Nod`/`PulseGesture` 句柄，以解除等待中的调用方阻塞，并将头部手势通道交还给自动控制器（伴随言语节拍、聆听时的倾斜保持）。

```csharp
_bodyLanguage.ClearScriptedOverrides();
```

已启动的自主程序会继续运行——仅取消控制器自身跟踪的脚本请求。 `ClearScriptedOverrides` 具有幂等性，即使当前没有任何活动项，调用它也是安全的。

### 验证设置

进入播放模式并调用 `Nod`, `PulseGesture`或 `TriggerReaction` ，可通过脚本或 Action Debug Window 调用。角色会在当前动作之上叠加播放所请求的动作——呼吸、重心转移和视线变化等动作仍会在底层持续进行。 `ConvaiBodyLanguageController` 检查器中的 **运行时状态** 部分会在场景运行期间显示当前激活的头部手势、最近一次尝试的手势提示，以及当前激活的反应。

### 后续步骤

{% 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/0ca05e2081622e66aa066b861879b41f4427d1c9" %}
[肢体语言脚本参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-language/scripting-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/gestures-and-reactions.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.
