中继组件参考

Dynamic Context 中继组件参考，涵盖其 Inspector 字段、公共方法、事件以及角色解析行为。

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

ConvaiDynamicContextRelay

通过以下方式添加该组件： Convai → Dynamic Context → Convai Dynamic Context Relay. ConvaiDynamicContextRelay 被标记为 [DisallowMultipleComponent] ——Unity 会阻止向同一个 GameObject 添加第二个实例。参见 每个 NPC 可有多个中继器 以从一个 NPC 驱动多个彼此独立的更新。

目标字段

控制以下哪一个 ConvaiCharacter 中继器所作用的对象。

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

解析顺序： 如果 角色 已分配，则中继器将使用它，而不管 自动解析角色。如果 角色 为空并且 自动解析角色 已启用，则中继器会搜索同一个 GameObject。如果两者都无法解析出角色，则方法调用会直接返回，不发送更新，并且 On Skipped 触发。

默认字段

字段	类型	默认值	描述
Reaction Mode	ConvaiRespondMode	Silent	应用于此中继器上的每次方法调用。参见 ConvaiRespondMode 下方。
Flush Immediately	bool	false	启用后，除 Flush 外的每次方法调用都会立即发送已暂存的更新，而不是等待角色的正常批处理窗口。

Reaction Mode 默认为 Silent 并应用于中继器上的每个方法——没有按调用覆盖的选项。在将中继器接入游戏玩法事件之前，请确认这与您期望的反应一致； Silent 绝不会产生即时响应。

方法

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

Reaction Mode 和 Flush Immediately 仅适用于 SetState, AddEvent, SetCurrentAttentionObject，以及 ClearCurrentAttentionObject. ResetContext(), ResetContext(bool)，以及 Flush() 不采用反应模式——没有任何可供反应模式升级的内容，而且 Flush() 始终会立即发送，不受 Flush Immediately 字段。

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	立即发送任何已暂存的动态上下文和场景元数据更改。与其他方法不同， Flush 不受 Flush Immediately 影响——发送始终无条件发生。

有关完整的动态上下文操作集，包括 SetStates, RemoveState, TryGetStateValue，以及 Apply，请参见 动态上下文脚本 API.

事件

事件	类型	当……时触发
On Queued	UnityEvent	在方法调用解析角色并暂存（或者，在 Flush Immediately 启用时，发送）更新后触发。也会在 Flush() 完成后触发。
On Skipped	UnityEvent	当方法调用无法解析 ConvaiCharacter时。Unity Console 会记录原因。

ConvaiRespondMode

ConvaiRespondMode 是动态上下文和动态视觉输入之间共享的响应模式词汇。

值	行为
Silent	更新会被吸收到角色的感知中。角色不会产生即时响应。
Auto	Convai 决定该更新是否需要即时响应。
MustRespond	该更新始终会触发即时响应。

每个 NPC 可有多个中继器

[DisallowMultipleComponent] 阻止同一个 ConvaiDynamicContextRelay 在同一 GameObject 上存在多个。要从一个 NPC 驱动多个彼此独立的更新：

1. 在 NPC 下创建一个子 GameObject。
2. 添加 ConvaiDynamicContextRelay 到该子对象。
3. 在 目标字段，禁用 自动解析角色 ——自动解析只会搜索同一个 GameObject。
4. 将 NPC 的 ConvaiCharacter 到 角色 字段显式拖入。
5. 对每个额外的中继器重复上述操作，并配置其自己的 Reaction Mode 和 Flush Immediately.

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

验证警告

当角色解析失败时， ConvaiDynamicContextRelay 会在 Unity Console 中记录警告并触发 On Skipped。不会发送任何上下文更新。

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

下一步

动态上下文使用示例动态上下文脚本 API同步行为与时序