> 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 的 **Details** 面板，在 **Convai Chatbot > Environment**:

1. **启用操作** 被勾选。
2. `动作` 数组包含一个 `Move To` 条目，带有一个 `destination` 参数，类型为 **Actor Reference** （这是默认值）。
3. `Objects` 数组包含一个条目：
   * `名称`: `"SafetyValve"`
   * `Ref`：关卡中的阀门 Actor
   * `移动目标模式`: `将 Actor 作为目标`
   * `接受半径`: `100.0`

#### Blueprint 处理器 — Move To

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

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

    // 将条目解析为 AI Move To 输入
    ResolveGoalLocation(
        Entry = DestEntry,
        SourceActor = Self,
        // 输出：
        OutGoalActor, OutGoalComponent, OutGoalLocation,
        OutAcceptanceRadius, OutMode,
        bSuccess, bAlreadyThere, bReachable, PathEnd, PathPoints
    )

    如果不是 bSuccess：
        AbortActionSequence(
            EventText = "Destination actor no longer exists",
            ShouldRespond = Always
        )
        return

    如果 bAlreadyThere：
        HandleActionCompletion(IsSuccessful = true)
        return

    // 根据 Out Mode 分支——将正确的引脚连接到 AI Move To
    如果 OutMode == Actor：
        AIMoveTo(Target = OutGoalActor, AcceptanceRadius = OutAcceptanceRadius)
    else:
        AIMoveTo(Destination = OutGoalLocation, AcceptanceRadius = OutAcceptanceRadius)

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

{% hint style="info" %}
始终基于 `bOut Success` 是位于 `bOut Already There` 在发出 `AI 移动到`之前。将一个已销毁的 Actor 传给 `AI 移动到` 在 Actor 模式下会静默无操作，或在 Vector 模式下把 pawn 发送到过时的位置。
{% endhint %}

***

### 示例 2：跟随角色

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

#### 配置

1. `动作` 数组包含 `跟随` （名称： `"Follow"`，参数： `character`，输入 **Actor Reference**）以及 `停止移动` （名称： `"Stop Moving"`，无参数）——两者都是默认值。
2. `Characters` 数组包含：
   * `名称`: `"Player"` 或者匹配玩家的 `PlayerName` 字段在 `Convai 玩家` 组件。
   * `Ref`：玩家 pawn Actor。

#### Blueprint 处理器 — Follow

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

    如果 TargetEntry.Ref 为空：
        AbortActionSequence(
            EventText = "Cannot find the character to follow",
            ShouldRespond = Always
        )
        return

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

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

#### Blueprint 处理器 — Stop Moving

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

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

    // 停止 pawn 移动
    AIController 上的 StopMovement

    HandleActionCompletion(IsSuccessful = true)
```

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

***

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

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

#### 配置

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

* `名称`: `"Administer Treatment"`
* `说明`: `"向患者施行特定治疗"`
* 参数：
  * `名称`: `"treatment"`
  * `类型`: `字符串`
  * `Choices`: `["CPR", "Defibrillation", "IV Fluids", "Oxygen Mask"]`

#### 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 = "Unknown treatment: " + TreatmentName,
                ShouldRespond = Always
            )
            return

    // 等待动画
    延迟 2.0 秒

    HandleActionCompletion(
        IsSuccessful = true,
        bAutoReport = true,
        AdditionalNote = TreatmentName + " administered"
    )
```

***

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

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

#### 配置

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

添加一个自定义动作：

* `名称`: `"Change Posture"`
* 参数：
  * `名称`: `"posture"`
  * `类型`: `枚举`
  * `枚举类型`: `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 提供的文本打印到屏幕上。

#### 配置

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

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

编译 Blueprint，然后用以下内容搭建处理器框架 **创建 Convai 动作处理器**.

#### Blueprint 处理器

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

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

***

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

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

#### 配置

1. 创建一个 `Anim Montage` 用于每种舞蹈风格。调整每个蒙太奇的淡入/淡出。
2. 添加动作 `Dance` ，带有一个参数：
   * `名称`: `"type"`
   * `类型`: `字符串`
   * `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 舞蹈。"` （播放蒙太奇）， `"做 ballet 舞蹈。"` （回退分支——角色解释该风格不可用）。

***

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

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

#### 配置

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

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

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

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

#### Blueprint 处理器 — Announce

```
// 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" %}
[Actions 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:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.