> 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).

# 角色动作示例

端到端动作方案：导航到已注册对象、跟随角色，以及在 Convai Unreal Engine 插件中使用参数化动作。

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

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

**场景：** 当受训者请求它过去时，一名训练模拟导师 NPC 会导航到一件设备。

#### 配置

在 NPC Actor 的 **Details** 面板，在 **Convai Chatbot > Environment**:

1. **启用动作** 已勾选。
2. `动作` 数组包含一个 `移动到` 带有一个 `destination` 类型参数的 **Actor 引用** （这是默认值）。
3. `对象` 数组包含一项：
   * `名称`: `"SafetyValve"`
   * `引用`：关卡中的阀门 Actor
   * `对象为`: `整个 Actor`
   * `接受半径`: `100.0`

#### Blueprint 处理器 — Move To

添加一个 **自定义事件** 命名为 `移动到` 到 NPC Actor Blueprint，并带有一个 `FConvaiResultAction` 输入：

```
// 蓝图伪代码
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 为 false：
        AbortActionSequence(
            EventText = "目标对象不再存在",
            ShouldRespond = Always
        )
        返回

    如果 bAlreadyThere：
        HandleActionCompletion(IsSuccessful = true)
        返回

    // 将两个引脚直接接到同一个 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`之前。在解析失败时， `Destination` 保存的是过时的快照，并且 `目标 Actor` 是 `null` —— 仍然发出 `AI Move To` 会把 pawn 送到一个过时的位置。
{% endhint %}

该 `Convai Move To` 异步节点会封装同样的解析并在内部发起移动——参见 [Actions Blueprint 参考](/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. `动作` 数组包含 `跟随` （名称： `"Follow"`，参数： `character`，类型 **Actor 引用**）和 `停止移动` （名称： `“Stop Moving”`，无参数）——两者都是默认值。
2. `角色` 数组包含：
   * `名称`: `"Player"` 或与玩家的 `PlayerName` 字段，在 `Convai Player` 组件。
   * `引用`：玩家 pawn Actor。

#### Blueprint 处理器 — Follow

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

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

    // 启动重复计时器或使用跟踪任务
    // 持续每帧向 TargetEntry.Ref 发出 AIMoveTo

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

#### Blueprint 处理器 — Stop Moving

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

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

    // 停止 pawn 移动
    AIController 上的 StopMovement

    HandleActionCompletion(IsSuccessful = true)
```

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

***

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

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

#### 配置

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

* `名称`: `"Administer Treatment"`
* `说明`: `"Administer a specific treatment to the patient"`
* 参数：
  * `名称`: `"treatment"`
  * `类型`: `字符串`
  * `选项`: `["CPR", "Defibrillation", "IV Fluids", "Oxygen Mask"]`

#### 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
            )
            返回

    // 等待动画
    延迟 2.0 秒

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

***

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

**场景：** 一名企业入职引导 NPC 会根据指令改变姿态。

#### 配置

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

添加一个自定义动作：

* `名称`: `"Change Posture"`
* 参数：
  * `名称`: `"posture"`
  * `类型`: `枚举`
  * `枚举类型`: `ENPCPosture`

#### 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 提供的文本打印到屏幕上。

#### 配置

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

* `名称`: `"Print"`
* 参数：
  * `名称`: `"text"`
  * `类型`: `字符串`
  * `说明`：留空或使用简短提示

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

#### Blueprint 处理器

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

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

***

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

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

#### 配置

1. 创建一个 `Anim Montage` 用于每种舞蹈风格。调整每个蒙太奇的淡入/淡出。
2. 添加动作 `Dance` ，带一个参数：
   * `名称`: `"type"`
   * `类型`: `字符串`
   * `选项`: `["groove", "disco", "g-style"]`

#### 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
            )
            返回

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

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

***

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

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

#### 配置

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

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

当 Convai 生成响应 `"Announce, Move To ExitSign"` 且动作队列为空时，插件会：

1. 接收 `Announce` 作为新序列中的第一个动作。
2. 因为 `Announce` 已勾选 `bWaitForBotSpeech = true`，会等待角色语音开始、语音结束、无响应路径触发，或动作等待超时。
3. 触发 `Announce` 在等待条件解析后加上 `0.5` 秒。
4. 推进到 `移动到` 在 `Announce` 处理器调用 `HandleActionCompletion(true)`.

#### Blueprint 处理器 — Announce

```
// 蓝图伪代码
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 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-unreal-engine-plugin/features/character-actions/character-actions-examples.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.