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

# 对话可用性参考

用于控制 Convai Unity SDK 中玩家输入的对话可用状态、事件和方法的参考。

在生命周期和调用顺序中，参与检查角色是否能听到玩家的所有公共成员。

### `ConvaiConversationAvailability` 枚举

| 值             | 含义                                             |
| ------------- | ---------------------------------------------- |
| `无角色`         | 当前没有正在被对话的角色，或者尚未设置。                           |
| `离线`          | 没有房间。没有任何内容在监听。                                |
| `连接中`         | 房间正在建立。                                        |
| `Preparing`   | 房间已连接，但此角色尚未得到服务确认。现在发送的消息会丢失。                 |
| `Ready`       | 角色可以听到玩家。                                      |
| `Answering`   | 角色正在回答。仍然接受输入——这就是打断插话（barge-in）。              |
| `Unavailable` | 角色启动失败，或已离开房间。不同于 `连接中` 和 `Preparing`，这不会自行恢复。 |

值按生命周期顺序列出。不要将它们与 `<` 或 `>` —— 接受输入的两个状态， `Ready` 和 `Answering`，并不相邻。

### `ConvaiConversationAvailabilityExtensions`

| 成员                       | 返回     | 说明                                                            |
| ------------------------ | ------ | ------------------------------------------------------------- |
| `CanAcceptPlayerInput()` | `bool` | 现在发送的消息——无论键入还是口述——是否会到达角色。为 True 的情况： `Ready` 和 `Answering`. |
| `IsSettling()`           | `bool` | 给它一点时间后，该状态是否会自行解除。为 True 的情况： `连接中` 和 `Preparing`.           |

### `ConvaiManager` 成员

| 成员                                | 类型                                          | 说明                                                                   |
| --------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |
| `ConversationAvailability`        | `ConvaiConversationAvailability`            | 玩家是否可以与 `AddressedCharacter` 当前交谈；如果不可以，阻碍是什么。                       |
| `ConversationAvailabilityChanged` | `事件 Action<ConvaiConversationAvailability>` | 在以下情况触发： `ConversationAvailability` 发生变化——包括玩家开始对话另一角色，而其可用性可能不同的时候。 |
| `AddressedCharacter`              | `ConvaiCharacter`                           | 玩家正在对话的角色，无论房间以何种形式存在，甚至在二者都尚不存在之前。                                  |

### `ConvaiCharacter` 成员

| 成员                         | 类型                               | 说明                                                                                                        |
| -------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `ConversationAvailability` | `ConvaiConversationAvailability` | 玩家当前是否可以与此角色对话；如果不可以，阻碍是什么。                                                                               |
| `CanAcceptPlayerInput`     | `bool`                           | 现在发送给此角色的消息——无论键入还是口述——是否会到达它。等同于 `ConversationAvailability.CanAcceptPlayerInput()`.                      |
| `IsCharacterReady`         | `bool`                           | 此角色是否已收到来自 Convai 的 bot-ready 信号。仅由该信号设置，而不是由房间连接设置——与以下项不同： `ConversationAvailability`，它还会考虑房间状态和成员名册归属。 |

### `ConversationAvailabilityChanged` 领域事件

发布到 SDK 的事件总线，并作为类型化属性暴露于 `ConvaiEvents.OnConversationAvailabilityChanged`.

| 成员                     | 类型                               | 说明                                 |
| ---------------------- | -------------------------------- | ---------------------------------- |
| `可用性`                  | `ConvaiConversationAvailability` | 当前判定。                              |
| `PreviousAvailability` | `ConvaiConversationAvailability` | 被替换掉的判定。                           |
| `CharacterId`          | `string`                         | 正在被对话的角色的 Convai Character ID（如有）。 |
| `CharacterName`        | `string`                         | 该角色的显示名称，用于日志和界面。                  |
| `时间戳`                  | `DateTime`                       | 判定变更时间，UTC。                        |
| `CanAcceptPlayerInput` | `bool`                           | 玩家当前是否可以发送语音或文本。                   |

### `LocalPlayerActivityChanged` 领域事件

发布到 SDK 的事件总线，在以下对象上没有类型化属性： `ConvaiEvents` —— 请通过以下方式订阅： `ConvaiEvents.Raw`.

| 成员         | 类型                          | 说明                                                               |
| ---------- | --------------------------- | ---------------------------------------------------------------- |
| `IsActive` | `bool`                      | 是否 `来源` 当前能看到玩家。                                                 |
| `来源`       | `LocalPlayerActivitySource` | 此事件报告的是哪一种本地证据。                                                  |
| `级别`       | `float`                     | 当音量门限触发此事件时，麦克风的音量相对于其已稳定到的噪声水平有多大。对于以下情况为零： `PushToTalk` 以及下降沿。 |
| `时间戳`      | `DateTime`                  | 本地证据变更时间，UTC。                                                    |

#### `LocalPlayerActivitySource` 枚举

| 值            | 含义                     |
| ------------ | ---------------------- |
| `麦克风`        | 开放麦克风听到的声音足够大，像是有人在说话。 |
| `PushToTalk` | 玩家正在按住按键通话控制。          |

同一事件总线还会发布 `RoomRosterChanged` —— 连接的房间中角色加入、离开或被拒绝——并作为以下项暴露： `ConvaiEvents.OnRoomRosterChanged`。这不是可用性信号；请参见 [处理房间事件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/handle-roster-events.md) 以了解其字段和订阅方式。

### `ConvaiPlayer` 成员

| 成员                   | 签名                                                           | 说明                                     |
| -------------------- | ------------------------------------------------------------ | -------------------------------------- |
| `SendTextMessage`    | `void SendTextMessage(string message)`                       | 向正在对话的角色发送文本消息。若被拒绝，会记录警告并不执行任何操作。     |
| `TrySendTextMessage` | `bool TrySendTextMessage(string message, out string reason)` | 发送文本消息，并报告其被拒绝的原因。返回 `true` 当消息已交给房间时。 |

### 相关

{% content-ref url="/pages/416bc976c2de7ded4dd1e60ced7894e179974b5b" %}
[对话可用性如何运作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-availability/how-availability-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/66ee7fe1bbd8fe5aba610cee8f0dfd2573443acf" %}
[根据可用性控制 UI](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-availability/gate-your-ui.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-availability/availability-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.