> 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-unreal-engine-plugin/features/character-actions/character-actions-examples.md).

# 角色动作示例

下面每个示例都是独立完整的：它列出了实现一个可工作的动作所需的 Details 面板配置和 Blueprint 处理器伪代码。如果你是第一次接触角色动作，请从示例 1 开始。示例将从默认导航逐步过渡到带有类型化参数的自定义动作。

### 示例 1：导航到已注册对象

**场景：** 一个训练模拟中的教官 NPC 会在学员要求它前往某处时导航到一件设备。

#### 配置

在 NPC Actor 的 **详情** 面板中，在 **Convai Chatbot > Environment**:

1. **启用动作** 已勾选。
2. `动作` 数组包含一个 `移动到` 条目，其具有一个 `destination` 类型为 **Actor 引用** 的参数。（这是默认值）。
3. `对象` 数组包含一个条目：
   * `名称`: `“SafetyValve”`
   * `Ref`：关卡中的阀门 Actor
   * `对象是`: `整个 Actor`
   * `AcceptanceRadius`: `100.0`

#### Blueprint 处理器 — 移动到

为每个结构和安全门添加一个 **自定义事件** 名为 `移动到` 添加到 NPC Actor Blueprint 中，并带有一个 `FConvaiResultAction` 输入：

```
// Blueprint 伪代码
Event Move To(ActionData: FConvaiResultAction)
    // 读取目标对象引用
    DestEntry = GetParamAsRef(ActionData, "destination")

    // 将条目解析为 AI Move To 输入
    ResolveGoalLocation(
        Entry = DestEntry,
        SourceActor = Self,
        // 输出：
        TargetActor, ObjectActor, ObjectComponent, Destination,
        OutAcceptanceRadius, bUsesDestination,
        bSuccess, bAlreadyThere, bReachable, PathEnd, PathPoints,
        GoalTravelDistance, MovementPointIndex
    )

    如果不是 bSuccess：
        AbortActionSequence(
            EventText = "目标 Actor 不再存在",
            ShouldRespond = Always
        )
        return

    如果 bAlreadyThere：
        HandleActionCompletion(IsSuccessful = true)
        return

    // 直接把两个引脚连接到同一个 AI Move To——无需分支。
    // 当 Destination 应该优先生效时，Target Actor 恰好为空。
    AIMoveTo(Target = TargetActor, Destination = Destination, AcceptanceRadius = OutAcceptanceRadius)

    // 通过 OnMoveCompleted 等待 AIMoveTo 完成
    // 然后调用：
    HandleActionCompletion(IsSuccessful = true)
```

{% hint style="info" %}
始终基于以下内容分支： `bOut Success` 和 `bOut 已经在那里` 在发出之前 `AI Move To`。在解析失败时， `目标` 持有的是过时快照，而 `目标 Actor` 为 `为空` ——发出 `AI Move To` 仍然会把 pawn 发送到过时位置。
{% endhint %}

该 `Convai 移动到` 异步节点封装了同样的解析，并在内部发出移动——参见 [动作蓝图参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md) ，这是手动连接 `解析目标位置` 和 `AI Move To` 的更简单替代方案。

***

### 示例 2：跟随角色

**场景：** 一个安保训练 NPC 会沿着巡逻路线跟随玩家，直到被告知停止。

#### 配置

1. `动作` 数组包含 `跟随` （名称： `“跟随”`，参数： `角色`，类型 **Actor 引用**）以及 `停止移动` （名称： `"Stop Moving"`，无参数）——二者都是默认值。
2. `角色` 数组包含：
   * `名称`: `“玩家”` 或与玩家的 `PlayerName` 上的字段 `Convai Player` 组件。
   * `Ref`：玩家 pawn Actor。

#### Blueprint 处理器 — 跟随

```
// Blueprint 伪代码
Event Follow(ActionData: FConvaiResultAction)
    TargetEntry = GetParamAsRef(ActionData, "character")

    如果 TargetEntry.Ref 为空：
        AbortActionSequence(
            EventText = "找不到要跟随的角色",
            ShouldRespond = Always
        )
        return

    // 启动一个重复定时器，或使用跟踪任务
    // 它会在每个 tick 持续向 TargetEntry.Ref 发送 AIMoveTo

    // 在循环启动后完成 Follow 动作。
    // 定时器/任务会一直运行，直到稍后触发 Stop Moving。
    HandleActionCompletion(IsSuccessful = true)
```

#### Blueprint 处理器 — 停止移动

事件名称必须与注册的动作名称完全匹配，包括空格。由于默认动作注册为 `"Stop Moving"` （带空格），Blueprint 自定义事件也必须命名 `停止移动` ——而不是 `StopMoving`.

```
// Blueprint 伪代码
Event Stop Moving(ActionData: FConvaiResultAction)
    // 取消重复移动定时器 / 任务
    StopFollowTask()

    // 停止 pawn 移动
    AIController 上的 StopMovement

    HandleActionCompletion(IsSuccessful = true)
```

{% hint style="warning" %}
`跟随` 会启动一个持续行为，但动作本身应该在跟随循环开始后完成。这样后续动作，包括 `停止移动`，都能正常分发。
{% endhint %}

***

### 示例 3：带字符串选项的参数化动作

**场景：** 一个医疗模拟 NPC 在接到指令时会从固定列表中执行所选治疗。

#### 配置

向 `动作` 数组中添加一个自定义动作：

* `名称`: `“实施治疗”`
* `描述`: `“向患者实施特定治疗”`
* 参数：
  * `名称`: `“treatment”`
  * `类型`: `String`
  * `Choices`: `["心肺复苏", "除颤", "静脉输液", "氧气面罩"]`

#### Blueprint 处理器

```
// Blueprint 伪代码
Event Administer Treatment(ActionData: FConvaiResultAction)
    TreatmentName = GetParamAsString(ActionData, "treatment")

    // 按治疗类型分支
    switch TreatmentName:
        case "CPR":            PlayCPRAnimation()
        case "Defibrillation": PlayDefibrillationAnimation()
        case "IV Fluids":      PlayIVFluidsAnimation()
        case "Oxygen Mask":    PlayOxygenMaskAnimation()
        default:
            AbortActionSequence(
                EventText = "未知治疗：" + TreatmentName,
                ShouldRespond = Always
            )
            return

    // 等待动画
    延迟 2.0 秒

    HandleActionCompletion(
        IsSuccessful = true,
        bAutoReport = true,
        AdditionalNote = TreatmentName + " 已执行"
    )
```

***

### 示例 4：带枚举的参数化动作

**场景：** 一个企业入职 NPC 会根据命令改变其姿势。

#### 配置

假设已有一个 `UENUM` 名为 `ENPCPosture` ，其值为 `Standing`, `Sitting`, `Crouching`.

添加一个自定义动作：

* `名称`: `“更改姿势”`
* 参数：
  * `名称`: `“posture”`
  * `类型`: `Enum`
  * `EnumType`: `ENPCPosture`

#### Blueprint 处理器

```
// Blueprint 伪代码
Event Change Posture(ActionData: FConvaiResultAction)
    PostureByte = GetParamAsByte(ActionData, "posture")
    Posture = ByteToEnum<ENPCPosture>(PostureByte)

    switch Posture:
        case Standing:  SetPostureAnimation(Standing)
        case Sitting:   SetPostureAnimation(Sitting)
        case Crouching: SetPostureAnimation(Crouching)

    HandleActionCompletion(IsSuccessful = true)
```

***

### 示例 5：使用动态字符串参数打印

**场景：** 一个训练 NPC 在被要求时会将 Convai 提供的文本打印到屏幕上。

#### 配置

向 `动作` 数组中添加一个自定义动作：

* `名称`: `“打印”`
* 参数：
  * `名称`: `“text”`
  * `类型`: `String`
  * `描述`：留空或使用简短提示

编译 Blueprint，然后用以下内容搭建处理器脚手架 **Create Convai Action Handler**.

#### Blueprint 处理器

```
// Blueprint 伪代码
Event Print(ActionData: FConvaiResultAction)
    Message = GetParamAsString(ActionData, "text")
    Print String(Message)
    HandleActionCompletion(IsSuccessful = true, ShouldRespond = Never)
```

**测试提示：** `“请把你的名字打印到屏幕上。”`

***

### 示例 6：带选项和回退的舞蹈

**场景：** 一个角色会通过单个动作播放若干舞蹈蒙太奇中的一种。

#### 配置

1. 创建一个 `Anim Montage` ，对应每种舞蹈风格。调整每个蒙太奇的淡入/淡出。
2. 添加动作 `舞蹈` ，并带有一个参数：
   * `名称`: `“type”`
   * `类型`: `String`
   * `Choices`: `["groove", "disco", "g-style"]`

#### Blueprint 处理器

```
// Blueprint 伪代码
Event Dance(ActionData: FConvaiResultAction)
    DanceType = GetParamAsString(ActionData, "type")

    Switch on String(DanceType):
        case "groove":  PlayMontage(GrooveMontage, onComplete, onInterrupted)
        case "disco":   PlayMontage(DiscoMontage, onComplete, onInterrupted)
        case "g-style": PlayMontage(GStyleMontage, onComplete, onInterrupted)
        default:
            HandleActionCompletion(
                IsSuccessful = false,
                bAutoReport = true,
                ShouldRespond = Always,
                AdditionalNote = "这种舞蹈风格不可用",
                Delay = 1.5
            )
            return

    // 将 onComplete 和 onInterrupted 连接到：
    HandleActionCompletion(IsSuccessful = true, ShouldRespond = Never)
```

**测试提示：** `“给我看看 groove 舞步。”` （播放蒙太奇）， `“做芭蕾舞。”` （回退分支——角色解释该风格不可用）。

***

### 示例 7：在语音开始后启动序列

**场景：** 一个安全演练 NPC 会在口头警告开始后朝出口标志做手势，然后走向该标志。

#### 配置

在以下两个动作中 `动作` 数组中添加一个自定义动作：

1. `播报` ——自定义动作，无参数， `bWaitForBotSpeech = true`, `DelayAfterBotSpeechSec = 0.5`.
2. `移动到` （默认）—— `bWaitForBotSpeech = false`.

当 Convai 生成响应 `“播报, Move To ExitSign”` 而动作队列为空时，插件：

1. 接收 `播报` 作为新序列中的第一个动作。
2. 因为 `播报` 具有 `bWaitForBotSpeech = true`，会等待角色开始说话、说话结束、无响应路径触发，或者动作等待超时结束。
3. 在等待条件解析完成后触发 `播报` 秒。 `0.5` 之后推进到
4. 经过 `移动到` 后 `播报` 处理器调用 `HandleActionCompletion(true)`.

#### Blueprint 处理器 — 播报

```
// Blueprint 伪代码
Event Announce(ActionData: FConvaiResultAction)
    // 播放通告动画 / 音频提示
    PlayAnnouncementAnim()

    HandleActionCompletion(
        IsSuccessful = true,
        bAutoReport = true,
        ShouldRespond = Never
    )
```

***

### 下一步

{% content-ref url="/pages/e29ff52f0d30b08b7f190e5b10f7b84aa21c7ff4" %}
[参数化动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/8c96d39684a8203fb0c40d8bcb7467ca8267e3c9" %}
[排查角色动作问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/troubleshoot-character-actions.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-unreal-engine-plugin/features/character-actions/character-actions-examples.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.