> 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` | —         | 如何选择玩家正在对话的角色。                                                                        |
| `最大距离`   | `float`                     | `30`     | `≥ 0`     | 角色在多少米内仍可被选为对话对象。                                                                     |
| `最大角度`   | `float`                     | `35`     | `1`–`180` | 角色偏离视野中心多少度内仍可符合条件。以视线方向为基准测量，因此默认值对应一个 70 度锥形范围。                                     |
| `切换余量`   | `float`                     | `10`     | `0`–`90`  | 另一个角色必须在评分上好多少度，对话才会切换到他们。适用于 `LookAt` 。                                              |
| `切换延迟秒数` | `float`                     | `0.2`    | `≥ 0`     | 另一个角色必须保持最佳选择多久，对话才会切换到他们。低于 `Proximity`，这就是区分两个等距角色的条件，因为 `切换余量` 对于以米为单位衡量的规则来说没有意义。 |

分配给 `最大角度`, `切换余量`, `最大距离`，或 `切换延迟秒数` 的超出范围值会被钳制到其有效范围，而不会抛出异常。

#### `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` 以保持对话现状，或者一个不在 `candidates` ——这同样会让对话保持原状。 `candidates` 以稳定顺序列出当前房间中的每个角色，并且在调用时绝不为 null 或为空。 `第二个触发。响应` 是当前正在进行对话的角色，或者 `null` 当没有任何角色符合时。 |

### `ConversationTargetSwitchVerdict`

由以下对象返回 `ConvaiManager.ConversationTargetingStatus`。命名上一次目标选择决策如此进行的原因。

| 值           | 说明                      |
| ----------- | ----------------------- |
| `已处于活动`     | 提议的目标与当前正在进行对话的角色相同。    |
| `提交`        | 更改已获准并已发送。              |
| `因延迟而暂缓`    | 暂缓：该提议还没有作为最佳选择持续足够长时间。 |
| `因玩家发言而暂缓`  | 暂缓：玩家正在说话中。             |
| `因待处理命令而暂缓` | 暂缓：先前的更改仍在处理中。          |

### `ConvaiManager` 目标选择成员

| 成员                              | 签名                                                                         | 说明                                                           |
| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `ConversationTargeting`         | `ConversationTargetingOptions ConversationTargeting { get; }`              | 用于自动对话目标选择的调优。绝不 `null`.                                     |
| `ConversationTarget`            | `ConvaiCharacter ConversationTarget { get; }`                              | 玩家当前正在对话的角色，或者 `null` 当房间没有多角色会话时。                           |
| `ConversationTargetingStatus`   | `ConversationTargetSwitchVerdict ConversationTargetingStatus { get; }`     | 最近一次目标评估的结果。                                                 |
| `初始角色`                          | `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 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/conversation-targeting/targeting-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.