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

# 动态上下文快速入门

本指南将引导你完成最少的设置，以验证你的 Convai 角色是否能识别场景中的实时条件。你将添加 `ConvaiDynamicContextCommand` 组件，并配置一个 `SetState` 命令，将其连接到一个 UI 按钮，并确认角色会引用你发送的状态。

### 先决条件

开始前，请确认：

* [ ] A `ConvaiCharacter` 已在场景中，并且在 Play Mode 中能对语音作出响应

{% stepper %}
{% step %}

#### 添加命令组件

在 Hierarchy 中选中 NPC 的 GameObject。在 Inspector 中，点击 **添加组件** 并搜索 **Convai 动态上下文命令**，或者导航到 **Convai → Dynamic Context → Convai Dynamic Context Command**.

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

<figure><img src="/files/4b3c1fb011093a8fa64d46440c3abe1febd5810f" alt="Unity Inspector showing ConvaiDynamicContextCommand added to the NPC GameObject, with Target, Command, and Events sections visible"><figcaption><p>NPC 上添加了 ConvaiDynamicContextCommand——会显示三个部分：Target 用于解析角色，Command 用于定义上下文操作，Events 用于公开执行回调。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 验证角色解析

在 **目标** 部分，确认 **自动解析角色** 已启用（默认设置）。该组件会找到 `ConvaiCharacter` 并自动定位到同一 GameObject 上。

如果 `ConvaiCharacter` 位于另一个 GameObject 上，请禁用 **自动解析角色** 并拖入正确的 `ConvaiCharacter` 到 **角色** 字段中。
{% endstep %}

{% step %}

#### 配置命令

在 **命令** 部分下：

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

该组件现在已配置为设置一个名为以下内容的跟踪状态： `位置` 到 `火灾出口走廊` 每当 `Execute()` 被调用。
{% endstep %}

{% step %}

#### 连接触发器

在 **事件** 部分（如果需要，可先创建一个临时按钮），找到 **On Click ()**.

单击 **+** 以添加监听器，将 NPC 的 GameObject 拖到对象字段中，并选择 **ConvaiDynamicContextCommand → Execute ()** 在函数下拉菜单中。

<figure><img src="/files/74644ad53864d58514a398522b1b3f951566ad7c" alt="Unity Inspector showing a UI Button&#x27;s On Click event wired to ConvaiDynamicContextCommand.Execute() on the NPC GameObject"><figcaption><p>已将 Execute() 连接到按钮的 On Click 事件——在运行时按下按钮会将配置好的上下文更新发送给 Convai，并根据所配置的 Reaction Mode 触发角色反应。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 在播放模式下测试

进入 Play Mode 并与角色开始对话。点击你在上一步连接的按钮，然后问角色你现在在哪里。

角色应该会提到该位置——例如： *“你现在在火警出口走廊。继续前请确保你了解疏散程序。”*

如果角色没有表现出位置感知，请打开 Unity Console 并检查是否有 `[ConvaiDynamicContextCommand]` 警告。参见 [动态上下文故障排除](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/troubleshoot-dynamic-context.md) 以获取完整的诊断清单。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
你的角色现在已具备上下文感知能力。 `位置` 状态会在本地跟踪，并在对话处于活动状态时发送给 Convai。任何未来的 `SetState` 对同名的调用都会更新该值，并自动通知角色。
{% endhint %}

### 无需自定义代码进行测试

SDK 包含一个预置的测试 UI，可在不编写任何集成代码的情况下探索完整的 Dynamic Context 系统。

**预制体路径：** Packages/<code class="expression">space.vars.sdk\_package\_id</code>/Prefabs/SampleDynamicContextUI.prefab

将其拖入场景，分配你的 `ConvaiCharacter`在 Inspector 中的组件。如果 **设置状态** 按钮发送已知值。如果角色通过 Sample UI 能正确响应，但通过你自己的集成不能，问题就在你的代码中——而不在 Dynamic Context 系统本身。

### 下一步

{% content-ref url="/pages/fe2e3da29009b41a36bf622ae1efd7921e09aab7" %}
[命令组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/command-component-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/5c3f9bcc544ac6f441fe54139ac1c670eeb5c958" %}
[动态上下文脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/493c8451db0d99cc31b81e26c17158c645622f0e" %}
[动态上下文使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-usage-examples.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 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/convai-unity-sdk/features/dynamic-context/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.