> 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).

# 中继组件参考

`ConvaiDynamicContextRelay` 是一种适合在检视器中使用的中继器，用于将 Unity 玩法事件绑定到某个角色的动态上下文。它公开了用于暂存状态、事件、注意对象和重置更新的公共方法，而无需脚本引用 `IConvaiDynamicContext` 。

### `ConvaiDynamicContextRelay`

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

#### 目标字段

控制 `ConvaiCharacter` 该中继器所作用的角色。

| 字段                       | 类型                | 默认值    | 描述                                                                                       |
| ------------------------ | ----------------- | ------ | ---------------------------------------------------------------------------------------- |
| `Character`              | `ConvaiCharacter` | `无`    | 显式角色引用。赋值后优先于自动解析。若中继器位于与 NPC 不同的 GameObject 上，请使用此项。                                    |
| `Auto Resolve Character` | `bool`            | `true` | 当 `Character` 为空且已启用此项时，中继器会调用 `GetComponent<ConvaiCharacter>()` 在调用时位于同一个 GameObject 上。 |

**解析顺序：** 如果 `Character` 已赋值，则中继器会无视 `Auto Resolve Character`。如果 `Character` 为空且 `Auto Resolve Character` 已启用时，中继器会搜索同一个 GameObject。若两者都无法解析出角色，方法调用将直接返回，不发送更新，并且 `跳过时触发` 会被触发。

#### 默认字段

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

{% hint style="warning" %}
`响应模式` 默认为 `静默` 并会应用到中继器上的每个方法——没有单次调用覆盖。请在将中继器连接到玩法事件之前，确认这与您想要的反应一致； `静默` 绝不会产生即时响应。
{% endhint %}

### 方法

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

`响应模式` 和 `立即刷新` 仅适用于 `SetState`, `AddEvent`, `SetCurrentAttentionObject`，以及 `ClearCurrentAttentionObject`. `ResetContext()`, `ResetContext(bool)`，以及 `Flush()` 不接受反应模式——反应模式没有可升级的内容，而且 `Flush()` 始终会立即发送，不受 `立即刷新` 字段。

Unity 检视器中的持久监听器面板只会列出零个或一个参数的方法。 `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`，以及 `应用`的 SDK 方法，请参见 [动态上下文脚本 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 控制台会记录原因。           |

### `ConvaiRespondMode`

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

| 值             | 行为                          |
| ------------- | --------------------------- |
| `静默`          | 该更新会被吸收进角色的感知中。角色绝不会生成即时响应。 |
| `自动`          | Convai 会判断该更新是否需要立即响应。      |
| `MustRespond` | 该更新始终会触发即时响应。               |

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

`[DisallowMultipleComponent]` 阻止在同一个 `ConvaiDynamicContextRelay` 上存在多个

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

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

### 验证警告

当角色解析失败时， `ConvaiDynamicContextRelay` 会向 Unity 控制台记录警告并触发 `跳过时触发`。不会发送上下文更新。

| 控制台消息                              | 原因                                                                                                                      | 修复方法                                                                        |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `请分配一个 ConvaiCharacter，或启用自动解析角色。` | `Character` 为空且 `Auto Resolve Character` 已禁用，或 `Auto Resolve Character` 已启用，但同一 `ConvaiCharacter` 不存在于同一个 GameObject 上。 | 请显式分配 `Character` ，或启用 `Auto Resolve 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.