> 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/unreal-engine-plugin-beta-overview/dynamic-context-inside-unreal-engine.md).

# Unreal Engine 中的动态上下文

{% hint style="info" %}
本指南假设你已经 [Convai Unreal Engine 插件](https://www.fab.com/sellers/Convai?lang=en) 安装，并且场景中已经设置好了一个由 Convai 驱动的 AI 角色。如果没有，请参考 [安装和设置文档](https://docs.convai.com/api-docs/plugins-and-integrations/unreal-engine-plugin-beta-overview/installation-and-setup).
{% endhint %}

Dynamic Context 是 Convai 的一项功能，它可以为你的 AI 角色提供游戏中正在发生的一切的实时信息流。与只会回应玩家所说内容的角色不同，Dynamic Context 使角色能够对虚拟世界的实际状态作出反应——分数、库存变化、环境事件等等——这些内容都会以命名变量的形式被跟踪，并实时注入到角色的推理过程中。

### 关键蓝图函数

| 函数                  | 用途              | 何时使用              |
| ------------------- | --------------- | ----------------- |
| `调用语音`              | 触发角色主动发言        | 场景开始、脚本事件         |
| `Add Context Event` | 向角色发送一次性事件通知    | 离散状态变化（例如玩家捡起武器）  |
| `设置上下文状态`           | 跟踪一个可持久化、可递增的变量 | 持续计数（例如得分、发射的子弹数） |
| `获取上下文状态值`          | 获取已跟踪变量的当前值     | 在递增计数器之前          |

### 响应模式

每个 Dynamic Context 函数都允许你控制角色在接收更新后是否发言：

| 模式     | 行为               | 最适合            |
| ------ | ---------------- | -------------- |
| `始终`   | 角色在更新后立即发言       | 值得回应的一次性事件     |
| `Auto` | 由角色自行决定何时评论      | 重复发生的事件，例如命中得分 |
| `从不`   | 上下文会被静默记录，不会触发响应 | 高频事件，例如发射子弹    |

### 教程：虚拟射击场

下面的演练使用一个虚拟射击场来同时演示这三个 Dynamic Context 函数。该场景包含一个 MetaHuman 教官角色、一把可拾取武器，以及一组目标圆锥。

{% embed url="<https://youtu.be/zGIBCWSElXs>" %}

#### 步骤 1 — 在场景加载时触发欢迎信息

<figure><img src="/files/ccd3cb300760c3f7bf7ac6de2eaafe018ac3cd02" alt=""><figcaption></figcaption></figure>

* 在场景中选择你的 AI 角色，然后点击 **编辑蓝图**.
* 在 **开始游戏** 事件，然后获取 `Convai Chatbot 组件`.
* 调用 **调用语音** 并设置一个 `触发消息` 用于描述开场场景——例如： *“欢迎玩家来到虚拟训练场。保持简洁。”*
* 留空 **生成操作** 是位于 **在网络上复制** 已禁用（仍在开发中）。
* 编译并保存。

{% hint style="info" %}
添加 **“保持简洁”** 到你的触发消息中，可以防止角色发表冗长的开场独白。欢迎信息应当快速让玩家了解情况。
{% endhint %}

#### 步骤 2 — 当玩家捡起武器时通知角色

<figure><img src="/files/4ba7ecdb64de79638f9940aa28b0e81660d411c2" alt=""><figcaption></figcaption></figure>

使用 `Add Context Event` 用于离散的一次性状态变化。

1. 选择 **武器 Actor** 在你的场景中，然后点击 **编辑蓝图**.
2. 找到 **重叠事件** 用于处理拾取机制——具体来说，是在 Actor 自我销毁之前将武器组件添加到玩家的节点序列。
3. 在 **Destroy Actor** 节点之前，添加对 `Convai Chatbot 组件` 的引用，使用 **Get First Convai Chatbot Component**.
4. 调用 **Add Context Event** 并设置消息： *“玩家已经捡起了枪。”*
5. 设置 **响应模式** 到 `始终` ——这是一个重要的状态变化，值得立即确认。
6. 将该节点连接到你现有的执行链中，然后编译并保存。

**原因 `Add Context Event` 而不是 `设置上下文状态`?** `Add Context Event` 用于只发生一次且不应累积的事情——是通知，不是计数器。 `设置上下文状态` 用于角色需要跨多个回合跟踪的变量。

#### 步骤 3 — 跟踪击中的目标

<figure><img src="/files/e0749faabb53571cdca057809d39bd2367fa0814" alt=""><figcaption></figcaption></figure>

使用 `设置上下文状态` ，并使用递增逻辑为角色提供一个击中目标的持续计数。

1. 选择一个 **目标圆锥** 并点击 **编辑蓝图**.
2. 滚动到 **事件** 并添加 **On Component Hit** ——每当圆锥被投射物击中时都会触发。
3. 获取 `Convai Chatbot 组件` 并调用 **设置上下文状态**.
4. 将变量名设置为 `targets_shot`.
5. 对于值，实现递增逻辑：
   * 复制 Chatbot Component 引用并调用 **获取上下文状态值** ，名称为 `targets_shot`.
   * 添加一个 **Branch** 节点：
     * **找到：** 使用 **String To Integer**，则添加 `1`将返回的字符串转换为整数，并将结果输入到 `设置上下文状态` 值引脚。
     * **未找到：** 传入 `1` 作为初始值。
6. 设置 **响应模式** 到 `Auto` ——角色会自行决定何时评论，而不是每次命中都发言。
7. 编译并保存。在场景中的所有目标 Actor 上重复此蓝图（或者使用父类来共享逻辑）。

#### 步骤 4 — 跟踪发射的子弹数

<figure><img src="/files/55e8fde49262c0080f7da43016a7ccedc3e1272a" alt=""><figcaption></figcaption></figure>

静默跟踪子弹数量，这样角色就可以在不打断游戏流程的情况下计算命中率。

1. 打开 **BP\_WeaponComponent** （位于你的第一人称蓝图下）。
2. 找到 **Left Mouse Button** 生成投射物的事件。
3. 复制完整的 `设置上下文状态` 步骤 3 中的递增逻辑，并将其粘贴到这个蓝图中。
4. 将变量重命名为 `bullets_shot`.
5. 设置 **响应模式** 到 `从不` ——角色应记录子弹数量，而不是每次开火都说话。
6. 编译并保存。

在 `targets_shot` 是位于 `bullets_shot` 两者都跟踪后，角色现在可以在任何回合计算命中率，而无需你在任何地方编写该逻辑。例如：6 发中击中 3 个目标 → 角色会自动得出 50%。

#### 步骤 5 — 添加视觉，让角色能够看到环境

<figure><img src="/files/662310dc09c910feec65bbbb59087ec5959d3cae" alt=""><figcaption></figcaption></figure>

Dynamic Context 覆盖角色 **知道的内容** 关于游戏状态的信息。Vision 覆盖角色能够 **看到的内容**.

1. 选择你的 AI 角色并点击 **编辑蓝图**.
2. 在 **组件** 面板中，点击 **+ 添加** 并搜索 `Environment Webcam`。将其添加到角色中。
3. 在 **视口**，将 `EnvironmentWebcam` 组件放置在角色的眼睛高度，并略微向前推，以避免与网格发生碰撞。
4. 在 **内容浏览器**，创建一个名为 `convai_vision`.
5. 在其中，右键单击 → **Convai** → **Create Vision Render Target**。将其命名为 `RT_Vision`.
6. 返回角色蓝图，选择 `EnvironmentWebcam` 组件，并设置 **Convai Render Target** 到 `RT_Vision`.
7. 启用 **Auto Start Vision**.
8. 编译并保存。

渲染目标现在会准确显示角色所看到的内容。玩家可以提出如下问题 *“你看到了多少个目标？”* ，角色会根据自己的摄像机视角进行计数——无需预先编写脚本。

{% hint style="info" %}
**Dynamic Context + Vision 结合起来：** Dynamic Context 告诉角色游戏中发生了什么。Vision 告诉角色它面前有什么。两者结合使用时，角色既具备态势感知，也具备环境感知。
{% endhint %}

### 超越射击场

同样的蓝图模式可以推广到任何项目：

* **培训模拟** ——跟踪哪些流程已完成，实时标记遗漏步骤，让 AI 评估器参考完整会话并按评分标准给出分数。
* **RPG 和开放世界** ——跟踪任务进度、阵营声望、收集的物品。NPC 会对玩家实际的游戏状态作出反应，而不是脚本化的分支树。
* **多人游戏** ——每个玩家会话都有自己的上下文；角色可以根据分数或交互历史直接与单个玩家对话。
* **企业模拟** ——在合规或销售场景中跟踪受训者的响应，并自动发现差距。


---

# 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/unreal-engine-plugin-beta-overview/dynamic-context-inside-unreal-engine.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.