对话目标选择参考

控制 Convai Unity SDK 如何选择玩家正在与哪个角色对话的每个字段、默认值和事件的参考。

公共类型和 ConvaiManager 驱动会话目标选择的成员，包括每个字段、默认值和事件。

ConversationTargetingMode

值	数字	说明
LookAt	0 （默认）	离玩家视野中心最近的角色，按角度评分，距离作为平分决胜项。读取的是视线方向，而不是发射射线，因此不需要碰撞体、层，也不需要输入连线。
Proximity	1	无论玩家看向哪里，最近的角色。
手动	2	除了游戏本身，没有任何东西会更改目标，通过 ConvaiManager.TalkTo.

ConversationTargetingOptions

公开为 ConvaiManager.ConversationTargeting。从不 null。每个字段都有可用的默认值；即使场景不更改其中任何一个，也仍然会正确地选择目标。

字段	类型	默认	有效范围	说明
模式	ConversationTargetingMode	LookAt	—	玩家正在对话的角色是如何被选中的。
MaxDistance	float	30	≥ 0	角色可以离多远（以米为单位）仍然有资格被呼叫。
MaxAngle	float	35	1–180	角色可以离视野中心多远（以度为单位）仍然有资格。以视线方向为基准测量，因此默认值给出一个 70 度的锥形范围。
SwitchMargin	float	10	0–90	另一个角色必须在多少度上更有优势，才会让对话切换到他们。仅适用于 LookAt 。
SwitchDelaySeconds	float	0.2	≥ 0	另一个角色必须保持最佳选择多久，对话才会切换到他们。在 Proximity下，这就是区分两个等距角色的因素，因为 SwitchMargin 对于以米为单位测量的规则来说没有意义。

分配给 MaxAngle, SwitchMargin, MaxDistance，或 SwitchDelaySeconds 的越界值会被钳制到其有效范围内，而不是抛出异常。

ConversationTargetingOptions 成员

成员	签名	说明
Validate()	void Validate()	将每个字段钳制到其支持范围内。
CreateDefault()	static ConversationTargetingOptions CreateDefault()	返回一个带有随附默认值的新实例。

IConversationTargetProvider

在注册时会直接替换内置模式。参见 编写自定义目标选择规则.

成员	签名	说明
ResolveTarget	ConvaiCharacter ResolveTarget(IReadOnlyList<ConvaiCharacter> candidates, ConvaiCharacter current)	返回玩家应该正在对话的角色， null 以便让对话保持原样，或者返回一个不在 候选角色 中的角色——这也会让对话保持原样。 候选角色 按稳定顺序列出当前房间中的每个角色，并且在调用时绝不会为 null 或为空。 当前角色 是当前正在掌控对话的角色，或者 null 当没有任何角色时。

ConversationTargetSwitchVerdict

由 ConvaiManager.ConversationTargetingStatus返回。命名上说明了上一次目标选择决策为何会如此。

值	说明
AlreadyActive	建议的目标与已持有会话的角色相匹配。
提交	该更改已获准并已发送。
HeldForDelay	Held：该提议还没有保持足够长时间成为最佳选择。
HeldForPlayerSpeech	Held：玩家正在说话的过程中。
HeldForPendingCommand	Held：先前的更改仍在处理中。

ConvaiManager 目标选择成员

成员	签名	说明
ConversationTargeting	ConversationTargetingOptions ConversationTargeting { get; }	自动会话目标选择的调优参数。从不 null.
ConversationTarget	ConvaiCharacter ConversationTarget { get; }	玩家当前正在对话的角色，或者 null 当房间没有多角色会话时。
ConversationTargetingStatus	ConversationTargetSwitchVerdict ConversationTargetingStatus { get; }	最近一次目标评估的结果。
InitialCharacter	ConvaiCharacter InitialCharacter { get; }	房间打开时对应的角色，或者 null 当没有选中任何对象时。的读取部分 SetInitialCharacter.
TalkTo	void TalkTo(ConvaiCharacter character)	将对话指向某个角色。任何时候调用都安全；当房间不是多角色房间或该角色不在房间内时，不会执行任何操作。
SetInitialCharacter	void SetInitialCharacter(ConvaiCharacter character)	选择房间连接时哪个角色先发言。对已连接的房间调用它会排队重新连接，而不是移动当前对话。
SetConversationTargetProvider	void SetConversationTargetProvider(IConversationTargetProvider provider)	替换 SDK 的目标选择规则。传入 null 以恢复由 ConversationTargeting.

事件

事件	签名	在……时触发
ConversationTargetRequested	event Action<ConvaiCharacter> ConversationTargetRequested	在 SDK 关闭玩家输入之后、并且在尝试发送目标更改之前立即触发。发送仍然可能失败。
ConversationTargetChanged	event Action<ConvaiCharacter> ConversationTargetChanged	当来自 Convai 的权威响应重新协调目标时——即在 ConversationTargetRequested之后的一次往返。该参数可以是 null 当权威响应清除路由时。

这两个 ConvaiManager 事件是对目标移动做出单一响应的最短路径。已标准化为领域事件总线的项目则会改用 ConvaiEvents.OnConversationTargetChanged — Action<ConversationTargetChanged> ——它携带阶段（Requested, Confirmed, Failed）以及在 Failed时移动被拒绝的原因。参见 事件系统 完整字段参考和订阅示例。

错误和约束

条件	结果
TalkTo 在当前房间中调用时，角色不在房间内	该调用被拒绝；控制台会记录一条警告，指出该角色的名称。
TalkTo 在玩家说话尚未结束时调用	请求会被保持，直到发言结束，然后再发送。
已注册的 IConversationTargetProvider.ResolveTarget 会抛出	异常会被捕获并记录；对话将保持原样。
房间只有一个角色	目标选择逻辑从不运行——这个单独的角色持有对话。

相关参考

对话目标选择如何运作ConvaiManager API