> 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 中的动态上下文

使用动态上下文，让 AI 角色实时感知游戏状态、玩家行为和环境。

{% 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 函数都允许你控制角色在收到更新后是否发言：

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

### 教程：虚拟射击场

下面的演示将使用一个虚拟射击场来同时展示这三个 Dynamic Context 函数。场景中包含一个 MetaHuman 教官角色、可拾取武器和一组目标锥桶。

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

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

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FXwqcC2dZRbWQvhfFSxEx%2Fimage.png?alt=media&amp;token=04a32b8e-d4dc-4c4b-ad14-12353269ac25" alt=""><figcaption></figcaption></figure>

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

{% hint style="info" %}
添加 **“保持简洁”** 到你的触发消息中，可以避免角色发表冗长的开场独白。欢迎消息应当快速引导玩家。
{% endhint %}

#### 步骤 2 — 当玩家拾取武器时通知角色

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FyFxSkVKBWMhDhBVEcpLL%2Fimage.png?alt=media&amp;token=42509e49-4248-47c8-8935-6f0838efb369" alt=""><figcaption></figcaption></figure>

使用 `添加上下文事件` 用于离散的一次性状态变化。

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

**为什么 `添加上下文事件` 而不是 `设置上下文状态`?** `添加上下文事件` 用于只发生一次且不应累积的事情——这是通知，不是计数器。 `设置上下文状态` 用于角色需要在多个回合中跟踪的变量。

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

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FecLiKYpy4CKPf7Fy4zjC%2Fimage.png?alt=media&amp;token=a01ebef7-6f28-4766-a2e0-29f6f2c19cf8" alt=""><figcaption></figcaption></figure>

使用 `设置上下文状态` 并使用递增逻辑，让角色获得已命中目标的持续计数。

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

#### 步骤 4 — 跟踪已发射子弹

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FVo0nOgq7qlituIsYjhQm%2Fimage.png?alt=media&amp;token=b8497213-423d-43cf-a5a6-c08283b922c1" alt=""><figcaption></figcaption></figure>

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

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

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

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

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FWrEXs6ZwA6WW3ld0uP0K%2Fimage.png?alt=media&amp;token=6143337b-f8e0-4b19-9ea6-a625cb43bc38" alt=""><figcaption></figcaption></figure>

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

1. 选中你的 AI 角色并点击 **编辑蓝图**.
2. 在 **组件** 面板中，点击 **+ 添加** 中搜索 `环境摄像头`。将其添加到角色。
3. 在 **视口**，将 `EnvironmentWebcam` 组件放在角色的眼睛高度，并稍微向前推一点，以避免与网格碰撞。
4. 在 **内容浏览器**，创建一个名为 `convai_vision`.
5. 在其中右键单击 → **Convai** → **创建视觉渲染目标**。将其命名为 `RT_Vision`.
6. 返回角色蓝图，选择 `EnvironmentWebcam` 组件，并设置 **Convai 渲染目标** 为 `RT_Vision`.
7. 启用 **自动开始视觉**.
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 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/unreal-engine-plugin-beta-overview/dynamic-context-inside-unreal-engine.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.