> 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/unity-plugin-beta-overview/features/dynamic-context/quick-start.md).

# 快速开始

## 让你的第一个具备上下文感知的角色运行起来

本指南将带你完成一个完整且可运行的示例：一个角色能够知道玩家当前站在哪个位置，并通过按钮点击来更新——无需编写脚本。你将添加一个组件，配置一个命令，连接一个事件，并在 Play Mode 中测试所有内容，全部都在 Unity Inspector 中完成。

{% hint style="info" %}
**先决条件**

* 一个 Unity 场景，其中有一个 `ConvaiCharacter` 组件已经设置并正常工作（角色应该会对语音做出回应）。
* 你的 Convai API 密钥已在以下位置配置： **工具 → Convai → 配置**.
  {% endhint %}

## 逐步设置

{% stepper %}
{% step %}
**添加 Dynamic Context Command 组件**

在选中 NPC GameObject 的情况下，点击 **添加组件** 并导航到：

**Convai → Dynamic Context → Convai Dynamic Context Command**

该组件会以三个部分显示在 Inspector 中： **目标**, **命令**，以及 **事件**.

<figure><img src="/files/4b3c1fb011093a8fa64d46440c3abe1febd5810f" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**验证自动解析角色**

在 **目标** 部分，确认 **自动解析角色** 已启用（默认开启）。这会告诉组件自动查找同一 GameObject 上的 `ConvaiCharacter` ，你无需手动分配它。

{% hint style="warning" %}
如果 Inspector 显示类似这样的警告： *“在此 GameObject 上未找到 ConvaiCharacter。请分配一个或禁用自动解析角色。”*，请确认这两个组件都在同一个 GameObject 上。
{% endhint %}
{% endstep %}

{% step %}
**配置 SetState 命令**

在 **命令** 部分下：

* 设置 **命令类型** 到 `SetState` （默认值）。
* 设置 **状态名称** 到 `位置`.
* 设置 **状态值** 到 `火灾出口走廊`.
* 留空 **反应** 设置为 `Auto`.

此命令会告诉角色当前的位置是火灾出口走廊。
{% endstep %}

{% step %}
**将 Execute() 连接到一个触发器**

选择任何应该触发上下文更新的事件源。为了快速测试，可以使用一个 UI **按钮**:

1. 在场景中选中你的按钮。如果你还没有按钮，请先创建一个按钮。
2. 在 **On Click ()** 事件列表，点击 **+** 按钮。
3. 将 NPC GameObject 拖到对象槽中。
4. 在函数下拉菜单中，选择 **ConvaiDynamicContextCommand → Execute**.

<figure><img src="/files/74644ad53864d58514a398522b1b3f951566ad7c" alt=""><figcaption></figcaption></figure>

你也可以连接 `Execute()` 到 `OnTriggerEnter`、动画时间线信号，或任何其他 `UnityEvent`.
{% endstep %}

{% step %}
**进入 Play Mode 并测试**

按 **播放**。先与角色开始对话，然后点击按钮（或触发该事件）。向角色询问 *“我在哪里？”* 或 *“这里是什么地方？”* 并确认它会以对火灾出口走廊的感知作出回应。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**预期结果：** 在触发 `Execute()`之后，角色的下一次回应会引用你设置的位置。如果角色没有识别该位置，请打开 Unity Console，并查看由 `ConvaiDynamicContextCommand`记录的警告。请参阅 [故障排除与诊断](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/troubleshooting-and-diagnostics.md) 以获取完整的诊断指南。
{% endhint %}

## 刚刚发生了什么

当你点击按钮时，会发生以下情况：

1. 按钮的 **On Click** 事件调用了 `Execute()` 在 `ConvaiDynamicContextCommand` 组件。
2. 该组件解析了 `ConvaiCharacter` 并验证了配置。
3. `SetState("Location", "Fire Exit Corridor")` 在角色的 Dynamic Context 接口上被调用。
4. SDK 的内部跟踪器记录了新的状态。
5. 由于角色当时已经在对话中， `上下文更新` 消息会立即发送到 Convai 后端。
6. 后端会将上下文注入角色的推理中，使其可用于下一轮对话。

如果 `Execute()` 如果在对话开始前就触发了，它会被排队，并在会话开始时自动发送——不会丢失任何内容。有关所有时序场景的精确说明，请参阅 [同步行为与时序](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/sync-behavior-and-timing.md).

{% hint style="info" %}
SDK 附带了一个现成的 **示例动态上下文 UI** 预制体，可用于在运行时测试所有上下文操作，而无需构建自定义 UI。你可以在以下路径找到它： `Packages/com.convai.convai-sdk-for-unity/Prefabs/SampleDynamicContextUI.prefab` ——将它拖入场景，并分配角色引用。
{% endhint %}

## 接下来做什么

* [命令组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/command-component-reference.md) ——完整详解全部六种命令类型、每个字段以及所有验证警告。
* [连接时的静态上下文](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/static-context-at-connection-time.md) ——设置一个固定的场景描述，让角色在说出第一句话之前就已知晓。
* [脚本 API 参考 ](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/scripting-api-reference.md)——当你的游戏逻辑需要时，可通过 C# 驱动 Dynamic Context。

## 结论

你已经拥有一个可工作的 Dynamic Context 集成，并且完全由 Inspector 驱动。 `ConvaiDynamicContextCommand` 组件和 `ConvaiCharacter.DynamicContext` 脚本 API 共享同一个底层跟踪器——你在这里设置的一切都可以直接扩展到脚本系统中。探索 [命令组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/dynamic-context/command-component-reference.md) 以了解可用命令类型的完整范围。


---

# 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/unity-plugin-beta-overview/features/dynamic-context/quick-start.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.