> 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 %}

动态上下文是 Convai 的一项功能，它会为你的 AI 角色提供游戏中正在发生的一切的实时信息流。它不再只是让角色响应玩家所说的话，而是让角色对虚拟世界的实际状态作出反应——分数、库存变化、环境事件等等——所有这些都作为命名变量被跟踪，并实时注入角色的推理过程中。

### 关键蓝图函数

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

### 响应模式

每个动态上下文函数都允许你控制角色在接收到更新后是否发言：

| 模式     | 行为               | 适用于           |
| ------ | ---------------- | ------------- |
| `总是`   | 角色在更新后立即发言       | 值得回应的一次性事件    |
| `Auto` | 角色自行决定何时评论       | 类似击中得分之类的重复事件 |
| `从不`   | 上下文被静默记录，不触发任何响应 | 高频事件，例如发射子弹   |

### 教程：虚拟射击场

下面的演示将使用一个虚拟射击场来同时展示这三个动态上下文函数。该场景包括一个 MetaHuman 教官角色、一把可拾取武器和一组目标锥体。

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

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

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

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

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

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

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

在每个阶段加载时，对聊天机器人组件使用 `添加上下文事件` 适用于离散的一次性状态变化。

1. 选中 **武器 Actor** 在场景中并点击 **编辑蓝图**.
2. 找到 **重叠事件** 处理拾取机制的部分——具体是武器组件在 Actor 自毁之前被添加到玩家身上的节点序列。
3. 在 **Destroy Actor** 节点之前，添加对 `Convai 聊天机器人组件` 使用 **Get First Convai Chatbot Component**.
4. 调用 **添加上下文事件** 的引用，并将消息设置为： *"玩家已拾取枪支。"*
5. 设置 **响应模式** 为 `总是` ——这是一个重要的状态变化，值得立即确认。
6. 将该节点连接到现有执行链中，然后编译并保存。

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

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

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

在每个阶段加载时，对聊天机器人组件使用 `设置上下文状态` 配合递增逻辑，为角色提供命中目标的实时计数。

1. 选中一个 **目标锥体** 并点击 **编辑蓝图**.
2. 滚动到 **事件** 并添加 **On Component Hit** ——每当锥体被抛射物击中时都会触发。
3. 获取 `Convai 聊天机器人组件` 并调用 **设置上下文状态**.
4. 将变量名设置为 `targets_shot`.
5. 对于值，实现递增逻辑：
   * 复制聊天机器人组件引用并调用 **获取上下文状态值** ，名称为 `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>

动态上下文涵盖角色 **所知道的** 关于游戏状态的内容。视觉涵盖角色能够 **看到的内容**.

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

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

{% hint style="info" %}
**动态上下文 + 视觉结合：** 动态上下文告诉角色游戏中发生了什么。视觉告诉角色它前方有什么。两者结合后，角色既具备情境感知，也具备环境感知。
{% 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, and the optional `goal` 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>&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.