> 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 角色推送一个状态属性和一个上下文事件，并验证更新是否到达上下文管道。

推送一个 **状态** 以及一个 **事件** 从 Blueprint 向 Convai 角色发送更新，然后在测试对话前确认该更新已本地存储。

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

| 术语 | 含义        | 示例           |
| -- | --------- | ------------ |
| 状态 | 可被替换的当前事实 | `生命值` 是 `50` |
| 事件 | 会话中的一次性时刻 | `4区触发警报`     |

### 前提条件

开始前，请验证：

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

### 推送状态更新

跟踪玩家的生命值，以便角色在被询问时可以引用它。

{% stepper %}
{% step %}

#### 打开角色 Blueprint

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

{% step %}

#### 添加一个测试入口点

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

{% step %}

#### 获取 Convai Chatbot 组件

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

{% step %}

#### 调用 Set Context State

从 `Convai Chatbot` 引用引脚拖出并搜索 **设置上下文状态**。将其连接到 `TestHealthUpdate` 事件执行引脚。

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

| 引脚      | 值       |
| ------- | ------- |
| **名称**  | `生命值`   |
| **值**   | `50`    |
| **应响应** | `Never` |

保留 `bFlushImmediately` 保持默认（`false`).

`Should Respond = Never` 会在不要求每次生命值变化都进行语音响应的情况下存储该值。
{% endstep %}

{% step %}

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

从 **设置上下文状态** 的输出执行引脚拖出并添加 **Get Context State Value**。将 **名称** 到 `生命值`，然后打印 `OutValue` 以及布尔返回值，使用 **Print String**.

编译角色 Blueprint。运行时，返回值应该是 `true` 和 `OutValue` 应显示为 `50`。这确认了在任何网络刷新之前，本地跟踪器已接受该更新。
{% endstep %}
{% endstepper %}

### 推送事件更新

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

{% stepper %}
{% step %}

#### 串联 Add Context Event

从该 **设置上下文状态** 节点的输出执行引脚拖出。搜索 **添加上下文事件** 并将其连接起来。
{% endstep %}

{% step %}

#### 配置事件

设置 **文本** 引脚为 `4区触发警报`。将 **应响应** 到 `自动`.
{% endstep %}
{% endstepper %}

### 从游戏玩法中触发更新

调用 `TestHealthUpdate` 从任何已经可以访问该角色 Actor 的 Blueprint 图表中。

{% stepper %}
{% step %}

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

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

{% step %}

#### 在初始化期间调用 TestHealthUpdate

调用 `TestHealthUpdate` 在角色 Actor 引用有效之后。对于基本测试，可以从准备关卡的同一启动流程中调用它。
{% endstep %}

{% step %}

#### 编译 Blueprint

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

### 在编辑器中运行测试

{% stepper %}
{% step %}

#### 进入编辑器中运行并等待连接

在编辑器中运行关卡。等待角色会话连接——当 `bAutoInitializeSession` 启用时，会话会自动开始。

你的游戏玩法图表触发 `TestHealthUpdate`，暂存状态更新和上下文事件。
{% endstep %}

{% step %}

#### 检查本地值并等待去抖窗口

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

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

{% step %}

#### 在对话中验证

与角色对话或使用文本输入。询问 `我的生命值如何？` 或 `设施里发生了什么？` 作为去抖窗口结束后的端到端运行时测试。准确的响应措辞取决于角色配置。

如果角色没有引用任一值，请参见 [动态上下文故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/troubleshoot-dynamic-context.md).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
如果 **Get Context State Value** 返回 `生命值 = 50` 并且你在测试前让去抖窗口经过，那么动态上下文管线的 Blueprint 侧配置就是正确的。
{% endhint %}

### 下一步

读取 [动态上下文的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/how-dynamic-context-works.md) 了解其思维模型，然后 [动态上下文使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-usage-examples.md) 查看更多 Blueprint 模式。

{% content-ref url="/pages/8ef7dcd046dad07f4afcb544f96d3beda6feb0ad" %}
[动态上下文的工作原理](/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" %}
[动态上下文使用示例](/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 参考](/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.