> 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/dynamic-context/dynamic-context-quick-start.md).

# 动态上下文快速开始

在 Blueprint 中向已连接的 Convai 角色推送一个状态属性和一个上下文事件，并验证更新是否到达上下文管道。

推送一个 **状态** 和一个 **事件** 从蓝图发送到 Convai 角色，然后在对话中测试之前，先确认更新已保存在本地。

{% embed url="<https://www.youtube.com/watch?v=zGIBCWSElXs>" %}
动态上下文演练
{% endembed %}

| 术语 | 含义        | 示例                            |
| -- | --------- | ----------------------------- |
| 状态 | 可以替换的当前事实 | `Health` 是 `50`               |
| 事件 | 会话中的一次性事件 | `Alarm triggered in sector 4` |

### 前提条件

开始之前，请确认：

* [ ] 已安装 Convai Unreal Engine 插件版本 <code class="expression">space.vars.unreal\_plugin\_version</code> 或更高版本，并已配置 API 密钥。
* [ ] 关卡中有一个包含 `Convai Chatbot` 组件（`UConvaiChatbotComponent`），且已设置 `CharacterID` 。
* [ ] 角色可以启动会话：要么 `bAutoInitializeSession` 为 `true`，要么由 Actor 在 `Start Session` 的 `BeginPlay`.
* [ ] 你熟悉如何在 Actor 上创建蓝图图表。

### 推送状态更新

跟踪玩家的生命值，让角色在被问及时能够引用该信息。

{% stepper %}
{% step %}

#### 打开角色蓝图

打开拥有 `Convai Chatbot` 组件的 Actor 蓝图，例如 `BP_ConvaiCharacter`。导航到 **事件图表**.
{% endstep %}

{% step %}

#### 添加测试入口

在图表中右键单击，然后添加一个 **自定义事件** 节点。将其命名为 `TestHealthUpdate`。你可以从关卡蓝图、触发体积或其他 Actor 调用此事件，在编辑器中试玩时触发更新。
{% endstep %}

{% step %}

#### 获取 Convai Chatbot 组件

将 `Convai Chatbot` 组件从 **组件** 将面板拖入图表中，以创建一个 **获取** 引用节点。
{% endstep %}

{% step %}

#### 调用 Set Context State

从 `Convai Chatbot` 引用引脚拖出，并搜索 **Set Context State**。将其连接到 `TestHealthUpdate` 事件执行引脚。

按以下方式设置节点引脚：

| 引脚       | 值        |
| -------- | -------- |
| **名称**   | `Health` |
| **值**    | `50`     |
| **是否应答** | `Never`  |

将 `bFlushImmediately` 保留为默认值（`false`).

`Should Respond = Never` 会存储该值，但不会在每次健康值变化时请求语音回复。
{% endstep %}

{% step %}

#### 确认本地跟踪器已接受该值

从 **Set Context State** 的输出执行引脚拖出，并添加 **Get Context State Value**。将 **名称** 设为 `Health`，然后使用 `OutValue` 和布尔返回值来调用 **Print String**.

编译角色蓝图。运行时，返回值应为 `true` ，且 `OutValue` 应显示 `50`。这表明本地跟踪器在任何网络刷新之前已接受此更新。
{% endstep %}
{% endstepper %}

### 推送事件更新

通知角色警报已触发。事件记录一次性时刻；它们不像状态值那样会被替换。

{% stepper %}
{% step %}

#### 串接 Add Context Event

从 **Set Context State** 节点的输出执行引脚拖出。搜索 **Add Context Event** 并将其连接。
{% endstep %}

{% step %}

#### 配置事件

设置 **文本** 固定到 `Alarm triggered in sector 4`。设置 **应响应** 为 `Auto`.
{% endstep %}
{% endstepper %}

### 从游戏运行过程中触发更新

调用 `TestHealthUpdate` 在任何已能访问角色 Actor 的蓝图图表中调用。

{% stepper %}
{% step %}

#### 获取角色 Actor 的引用

使用项目中常用的蓝图模式，引用拥有 `Convai Chatbot` 组件的 Actor — 例如，已放置的 `BP_ConvaiCharacter` 引用，或由生成逻辑设置的变量。
{% endstep %}

{% step %}

#### 在设置过程中调用 TestHealthUpdate

调用 `TestHealthUpdate` ，确保角色 Actor 引用有效。进行基本测试时，可在准备关卡的同一启动流程中调用它。
{% endstep %}

{% step %}

#### 编译 Blueprint

编译调用 `TestHealthUpdate`.
{% endstep %}
{% endstepper %}

### 的蓝图

{% stepper %}
{% step %}

#### 进入 Play In Editor 并等待连接

在 Play In Editor 中运行关卡。等待角色会话连接 — 如果启用了 `bAutoInitializeSession` ，会话将自动启动。

游戏逻辑图会触发 `TestHealthUpdate`，暂存状态更新和上下文事件。
{% endstep %}

{% step %}

#### 检查本地值并等待防抖时间窗口

检查 **Get Context State Value**的调试输出。返回值应为 `true` ，并且 `OutValue` 应显示 `50`.

默认情况下，插件会在最后一次暂存更新后等待 `0.5`  秒（`ContextDebounceWindow`），然后再发送到 Convai。进行依赖此上下文的对话测试前，请至少等待一个防抖周期。
{% endstep %}

{% step %}

#### 在对话中验证

与角色交谈或使用文本输入。等待防抖时间窗口结束后，提问 `How is my health?` 或 `What is happening in the facility?` ，进行端到端运行时测试。具体回复措辞取决于角色配置。

如果角色没有提及这两个值中的任何一个，请参阅 [动态上下文故障排除](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/troubleshoot-dynamic-context.md).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
如果 **获取上下文状态值** 返回 `Health = 50` 并且你在测试前等待防抖时间窗口结束，那么动态上下文管线的蓝图端配置就是正确的。
{% endhint %}

### 后续步骤

阅读 [动态上下文的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/how-dynamic-context-works.md) 了解其概念模型，然后阅读 [动态上下文用法示例](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-usage-examples.md) 了解更多蓝图模式。

{% content-ref url="/pages/8ef7dcd046dad07f4afcb544f96d3beda6feb0ad" %}
[动态上下文的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/how-dynamic-context-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/4c32f5b1e84d192a1af40b32548e3cf5f7f90478" %}
[动态上下文使用示例](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/a80705d8480f2f63dc8b84ea2e437c9dac45b7c5" %}
[动态上下文 Blueprint 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-blueprint-reference.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/dynamic-context/dynamic-context-quick-start.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.
