> 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/relay-component-reference.md).

# 中继组件参考

动态上下文中继组件的参考，涵盖其 Inspector 字段、公共方法、事件和角色解析行为。

`ConvaiDynamicContextRelay` 是一种便于在 Inspector 中使用的中继器，用于将 Unity 游戏事件绑定到某个角色的动态上下文。它提供公开方法，用于暂存状态、事件、关注对象和重置更新，而无需脚本直接引用它 `IConvaiDynamicContext` 直接引用。

### `ConvaiDynamicContextRelay`

通过以下方式添加该组件 **Convai → Dynamic Context → Convai Dynamic Context Relay**. `ConvaiDynamicContextRelay` 被标记为 `[DisallowMultipleComponent]` —— Unity 会阻止向同一个 GameObject 添加第二个实例。参见 [每个 NPC 使用多个中继器](#multiple-relays-per-npc) 以便从一个 NPC 驱动多个独立更新。

#### 目标字段

控制哪个 `ConvaiCharacter` 是该中继器操作的对象。

| 字段          | 类型                | 默认值    | 说明                                                                                       |
| ----------- | ----------------- | ------ | ---------------------------------------------------------------------------------------- |
| `Character` | `ConvaiCharacter` | `None` | 显式角色引用。赋值后优先于自动解析。适用于中继器与 NPC 位于不同 GameObject 的情况。                                       |
| `自动解析角色`    | `bool`            | `true` | 当 `Character` 为空且已启用此项时，中继器会调用 `GetComponent<ConvaiCharacter>()` 并在调用时作用于同一个 GameObject。 |

**解析顺序：** 如果 `Character` 已赋值，则中继器会使用它，而不管 `自动解析角色`。如果 `Character` 为空且 `自动解析角色` 已启用，中继器会搜索同一个 GameObject。若二者都无法解析出角色，则方法调用会在不发送更新的情况下返回，并且 `跳过时触发` 触发，空状态名或空值仍会记录 Console 警告。

#### 默认字段

| 字段     | 类型                  | 默认值     | 说明                                                               |
| ------ | ------------------- | ------- | ---------------------------------------------------------------- |
| `响应模式` | `ConvaiRespondMode` | `静默`    | 应用于该中继器上的每次方法调用。参见 [`ConvaiRespondMode`](#convairespondmode) 下文。 |
| `立即刷新` | `bool`              | `false` | 启用后，除 `刷新` 之外的每次方法调用都会立即发送已暂存的更新，而不是等待角色的正常批处理窗口。                |

{% hint style="warning" %}
`响应模式` 默认值为 `静默` 并且会应用于该中继器上的每个方法——没有按调用覆盖的选项。在将中继器接到游戏玩法事件之前，请确认这符合你想要的反应； `静默` 绝不会产生即时响应。
{% endhint %}

### 方法

所有方法都返回 `void`。每个方法首先解析角色（参见 **解析顺序** 上文）；如果解析失败，方法会立即返回，并且 `跳过时触发` 会触发。否则，该方法会在已解析角色的 `DynamicContext` 上调用对应成员，然后触发 `入队时触发`.

`响应模式` 和 `立即刷新` 仅适用于 `SetState`, `AddEvent`, `SetCurrentAttentionObject`，以及 `ClearCurrentAttentionObject`. `ResetContext()`, `ResetContext(bool)`，以及 `Flush()` 不采用反应模式——没有可供反应模式升级的内容，而且 `Flush()` 无论 `立即刷新` 字段从其他 GameObject 分配一个角色。

Unity 的 Inspector 持久监听器面板只列出零个或一个参数的方法。 `SetState` 需要两个参数，因此不能作为持久 `UnityEvent` 监听器连接——请改为从脚本中调用它。

| 方法                                             | 返回     | 说明                                                           |
| ---------------------------------------------- | ------ | ------------------------------------------------------------ |
| `SetState(string name, string value)`          | `void` | 设置或更新一条已跟踪的状态项。                                              |
| `AddEvent(string text)`                        | `void` | 追加一条按时间顺序排列的事件记录。                                            |
| `SetCurrentAttentionObject(string objectName)` | `void` | 设置角色当前关注的场景内对象。                                              |
| `ClearCurrentAttentionObject()`                | `void` | 清除当前关注对象。                                                    |
| `ResetContext()`                               | `void` | 清除所有已跟踪的状态和事件。等同于 `ResetContext(false)`.                     |
| `ResetContext(bool removeStatic)`              | `void` | 清除所有已跟踪的状态和事件。当 `removeStatic` 是 `true`时，还会请求移除角色的静态初始动态上下文。 |
| `Flush()`                                      | `void` | 立即发送任何已暂存的动态上下文和场景元数据更改。与其他方法不同， `刷新` 不受 `立即刷新` ——发送始终无条件发生。 |

有关完整的动态上下文操作集，包括 `SetStates`, `RemoveState`, `TryGetStateValue`，以及 `应用`，请参见 [动态上下文脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md).

### 事件

| 事件      | 类型           | 在以下情况触发：                                                  |
| ------- | ------------ | --------------------------------------------------------- |
| `入队时触发` | `UnityEvent` | 在方法调用解析角色并暂存（或者，在 `立即刷新` 启用时，发送）更新之后。也会在 `Flush()` 完成后调用。 |
| `跳过时触发` | `UnityEvent` | 当方法调用无法解析出 `ConvaiCharacter`时，Unity Console 会记录原因。        |

### `ConvaiRespondMode`

`ConvaiRespondMode` 是在动态上下文和动态视觉输入中通用的响应模式词汇。

| 值      | 行为                         |
| ------ | -------------------------- |
| `静默`   | 该更新会被吸收进角色的感知中。角色不会生成即时响应。 |
| `自动`   | Convai 会决定该更新是否值得即时响应。     |
| `必须响应` | 该更新始终会触发即时响应。              |

### 每个 NPC 使用多个中继器

`[DisallowMultipleComponent]` 阻止超过一个 `ConvaiDynamicContextRelay` 出现在同一个 GameObject 上。要从一个 NPC 驱动多个独立更新：

1. 在 NPC 下创建一个子 GameObject。
2. 添加 `ConvaiDynamicContextRelay` 到子对象上。
3. 在 **目标字段**，禁用 `自动解析角色` ——自动解析只会搜索同一个 GameObject。
4. 将 NPC 的 `ConvaiCharacter` 到 `Character` 字段显式拖入。
5. 对每个额外的中继器重复此操作，并配置其各自的 `响应模式` 和 `立即刷新`.

每个子中继器都是独立的——将其连接到不同的游戏玩法事件，并配置其自己的默认值。

### 验证警告

当角色解析失败时， `ConvaiDynamicContextRelay` 会向 Unity Console 记录一条警告并触发 `跳过时触发`。不会发送任何上下文更新。

| 控制台消息                              | 原因                                                                                     | 修复                                                            |
| ---------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `请分配一个 ConvaiCharacter，或启用自动解析角色。` | `Character` 为空且 `自动解析角色` 已禁用，或者 `自动解析角色` 已启用但没有 `ConvaiCharacter` 存在于同一个 GameObject 上。 | 分配 `Character` 显式指定，或启用 `自动解析角色` 并将中继器放置在 NPC 的 GameObject 上。 |

### 下一步

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

{% 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/bb1aef3496a2be08987c770aa7b8072e7d8c5cd6" %}
[同步行为与时序](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/sync-behavior-and-timing.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-unity-sdk/features/dynamic-context/relay-component-reference.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.