> 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/conversation-targeting/targeting-reference.md).

# 对话目标选择参考

控制 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`

在注册时会直接替换内置模式。参见 [编写自定义目标选择规则](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-targeting/custom-targeting-rule.md).

| 成员              | 签名                                                                                                  | 说明                                                                                                                                                      |
| --------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`时移动被拒绝的原因。参见 [事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/event-system.md) 完整字段参考和订阅示例。

### 错误和约束

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

### 相关参考

{% content-ref url="/pages/bf13178545671bf5315d6096bbd1d925cf1b57a5" %}
[对话目标选择如何运作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-targeting/how-conversation-targeting-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/837e187dde6ef107490d678933eda069ab0635b1" %}
[ConvaiManager API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/convaimanager-api.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/conversation-targeting/targeting-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.