> 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/core-concepts/event-system.md).

# 事件系统

Convai 事件中继组件参考，包括可用事件、载荷字段以及用于场景逻辑的订阅模式。

Convai SDK 会通过一组中继组件传递会话期间发生的事件——连接、角色语音、转录文本、情绪等。将其中一个 MonoBehaviour 添加到场景中的 GameObject，在 Inspector 中配置 UnityEvents，或在代码中订阅事件，即可让场景逻辑响应 SDK 广播的内容。

***

### 两种配置方式

{% tabs %}
{% tab title="Inspector（UnityEvents）" %}

1. 通过以下路径将中继组件添加到场景中的任意 GameObject： **Add Component → Convai → Events**.
2. 在 Inspector 中指定所需的引用（`ConvaiManager` 或 `ConvaiCharacter`），或启用 **自动解析** ，让组件自动查找引用。
3. 在 Inspector 中为 UnityEvent 字段配置处理程序——无需编写代码。

适用场景：连接状态指示器、动画触发器、UI 显示切换等由单个事件驱动且无需条件逻辑的功能。
{% endtab %}

{% tab title="C# 脚本" %}
在代码中订阅中继组件的事件：

```csharp
public class MyHandler : MonoBehaviour
{
    [SerializeField] private ConvaiCharacterEventRelay _relay;

    private void OnEnable()
    {
        _relay.OnEmotionChanged.AddListener(HandleEmotion);
        _relay.OnSpeechStarted.AddListener(HandleSpeechStarted);
    }

    private void OnDisable()
    {
        _relay.OnEmotionChanged.RemoveListener(HandleEmotion);
        _relay.OnSpeechStarted.RemoveListener(HandleSpeechStarted);
    }

    private void HandleEmotion(CharacterEmotionRelayData data) { /* … */ }
    private void HandleSpeechStarted() { /* … */ }
}
```

适用场景：条件逻辑、多事件协调，以及在多个系统之间路由数据。
{% endtab %}
{% endtabs %}

***

### 中继组件快速参考

| 组件                           | Inspector 菜单路径                              | 适用场景                             |
| ---------------------------- | ------------------------------------------- | -------------------------------- |
| `ConvaiSessionEventRelay`    | Convai/Events/Convai Session Event Relay    | 跟踪会话连接状态、处理错误、驱动连接界面             |
| `ConvaiCharacterEventRelay`  | Convai/Events/Convai Character Event Relay  | 响应特定角色的语音、转录文本、回合和情绪             |
| `ConvaiTranscriptEventRelay` | Convai/Events/Convai Transcript Event Relay | 提供整个场景范围的转录文本流，并可按角色或是否为最终结果进行筛选 |

***

### `ConvaiSessionEventRelay`

跟踪整个场景的会话生命周期。每个场景添加一个——它会监控由 `ConvaiManager`.

{% hint style="info" %}
如果 `ConvaiManager` 在中继组件的 `OnEnable` 之后才初始化（例如，由于脚本执行顺序），中继组件会在启用期间于 `LateUpdate()` 中自动重试订阅。无需手动编写重试逻辑。
{% endhint %}

**Inspector 字段：**

| 字段                   | 说明                                                                    |
| -------------------- | --------------------------------------------------------------------- |
| `Manager`            | 对 `ConvaiManager` 在场景中。                                               |
| `AutoResolveManager` | 启用后，组件会在运行时查找 `ConvaiManager.ActiveManager` 。如果有多个管理器，或需要显式绑定，请禁用此选项。 |

**事件：**

| 事件                                | 负载                                | 触发时机                                                                                                                                              |
| --------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OnConnected`                     | —                                 | 首次建立连接（`Connecting` → `Connected`）。重新连接时不会触发——请参阅 `OnReconnected`.                                                                                |
| `OnDisconnected`                  | —                                 | 会话进入 `Disconnected` 状态。                                                                                                                           |
| `OnReconnecting`                  | —                                 | 开始尝试重新连接（会话原先处于 `Connected`状态，后连接中断）。                                                                                                             |
| `OnReconnected`                   | —                                 | 重新连接尝试成功。会话再次处于 `Connected` 状态。                                                                                                                   |
| `OnUsageLimitReached`             | —                                 | 账户的 API 使用配额已超出。                                                                                                                                  |
| `OnUserIdleWarning`               | `UserIdleWarningRelayData`        | 达到用户空闲警告阈值。触发此警告的超时策略请参阅 [会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/session-lifecycle.md) 。 |
| `OnUserIdleTimeout`               | `UserIdleTimeoutRelayData`        | 发出警告后，若未调用 `ExtendIdleTimeout`/`ResetIdleTimer` ，本地推算的空闲截止时间就会到期。                                                                                 |
| `OnRuntimeBackgroundStateChanged` | `RuntimeBackgroundStateRelayData` | 应用进入或离开后台，或其实际后台策略发生变化。                                                                                                                           |
| `OnSessionStateChanged`           | `SessionStateChangedRelayData`    | 会话状态发生任何转换时触发。每次状态变化都会触发。                                                                                                                         |
| `OnSessionError`                  | `SessionErrorRelayData`           | 收到会话发出的错误事件。                                                                                                                                      |

#### `SessionStateChangedRelayData`

| 属性                         | 类型             | 说明                                                         |
| -------------------------- | -------------- | ---------------------------------------------------------- |
| `OldState`                 | `SessionState` | 转换前的状态。                                                    |
| `NewState`                 | `SessionState` | 转换后的状态。                                                    |
| `SessionId`                | `string`       | 当前会话标识符。没有活动会话时为空。                                         |
| `ErrorCode`                | `string`       | 如果转换由错误引起，则为错误代码；否则为空。                                     |
| `IsError`                  | `bool`         | 计算得出： `NewState == Error`.                                 |
| `IsReconnecting`           | `bool`         | 计算得出： `OldState == Connected && NewState == Reconnecting`. |
| `IsConnectionEstablished`  | `bool`         | 计算得出： `OldState == Connecting && NewState == Connected`.   |
| `IsReconnectionSuccessful` | `bool`         | 计算得出： `OldState == Reconnecting && NewState == Connected`. |
| `IsDisconnected`           | `bool`         | 计算得出： `NewState == Disconnected`.                          |

#### `SessionErrorRelayData`

| 属性                  | 类型                  | 说明                           |
| ------------------- | ------------------- | ---------------------------- |
| `ErrorCode`         | `string`            | 机器可读的错误代码。                   |
| `Message`           | `string`            | 人类可读的错误说明。                   |
| `SessionId`         | `string`            | 发生错误时的会话标识符。                 |
| `IsRecoverable`     | `bool`              | SDK 是否会尝试自动恢复。               |
| `Stage`             | `SessionErrorStage` | 错误发生在连接生命周期的哪个阶段。            |
| `HttpStatusCode`    | `int`               | 如果错误源自 API 调用，则为 HTTP 状态代码。  |
| `HasHttpStatusCode` | `bool`              | 是否 `HttpStatusCode` 包含有意义的值。 |

`SessionErrorStage` 取值： `Unknown`, `Configuration`, `ConnectApi`, `Transport`, `SessionRecovery`, `Runtime`.

#### `UserIdleWarningRelayData`

| 属性                 | 类型       | 说明                 |
| ------------------ | -------- | ------------------ |
| `RemainingSeconds` | `int`    | 本地推导的空闲期限到期前剩余的秒数。 |
| `Message`          | `string` | 人类可读的空闲警告消息。       |

#### `UserIdleTimeoutRelayData`

| 属性                     | 类型       | 说明                         |
| ---------------------- | -------- | -------------------------- |
| `WarningReceivedAtUtc` | `string` | 收到空闲警告时的 ISO 8601 时间戳。     |
| `DeadlineUtc`          | `string` | 本地推导的空闲期限对应的 ISO 8601 时间戳。 |

#### `RuntimeBackgroundStateRelayData`

| 属性                     | 类型                        | 说明                                                             |
| ---------------------- | ------------------------- | -------------------------------------------------------------- |
| `IsBackgrounded`       | `bool`                    | 应用当前是否处于后台。                                                    |
| `RequestedPolicy`      | `RuntimeBackgroundPolicy` | 项目配置的后台策略。                                                     |
| `EffectivePolicy`      | `RuntimeBackgroundPolicy` | 实际生效的后台策略。在某些平台强制使用回退策略时，它可能与 `RequestedPolicy` 不同。            |
| `Reason`               | `RuntimePauseReason`      | 状态发生变化的原因，例如 `ApplicationBackground` 或 `ApplicationFocusLost`. |
| `UsedPlatformFallback` | `bool`                    | 计算结果： `true` 当 `RequestedPolicy != EffectivePolicy`.           |

`RuntimeBackgroundPolicy` 以及完整的暂停/恢复/重新连接 API，请参阅 [会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/session-lifecycle.md)；本页仅介绍事件负载。

**代码示例 — 显示连接状态指示器：**

```csharp
public class ConnectionIndicator : MonoBehaviour
{
    [SerializeField] private ConvaiSessionEventRelay _relay;
    [SerializeField] private GameObject _connectingOverlay;

    private void OnEnable()
    {
        _relay.OnConnected.AddListener(OnConnected);
        _relay.OnDisconnected.AddListener(OnDisconnected);
        _relay.OnReconnecting.AddListener(OnReconnecting);
    }

    private void OnDisable()
    {
        _relay.OnConnected.RemoveListener(OnConnected);
        _relay.OnDisconnected.RemoveListener(OnDisconnected);
        _relay.OnReconnecting.RemoveListener(OnReconnecting);
    }

    private void OnConnected()    => _connectingOverlay.SetActive(false);
    private void OnDisconnected() => _connectingOverlay.SetActive(true);
    private void OnReconnecting() => _connectingOverlay.SetActive(true);
}
```

***

### `ConvaiCharacterEventRelay`

跟踪单个 `ConvaiCharacter`的事件。每个需要驱动场景响应的角色都添加一个。

**Inspector 字段：**

| 字段                     | 说明                                                    |
| ---------------------- | ----------------------------------------------------- |
| `Character`            | 对此 `ConvaiCharacter` 的引用；中继组件会监视该对象。                  |
| `AutoResolveCharacter` | 启用后，组件会在中继组件所在的同一个 GameObject 上查找 `ConvaiCharacter` 。 |

**事件：**

| 事件                     | 负载                                | 触发时机                           |
| ---------------------- | --------------------------------- | ------------------------------ |
| `OnTranscriptReceived` | `CharacterTranscriptRelayData`    | 每个转录文本片段到达时都会触发，包括临时（部分）和最终片段。 |
| `OnSpeechStarted`      | —                                 | 角色开始说话（音频开始播放）。                |
| `OnSpeechStopped`      | —                                 | 角色停止说话（音频播放结束）。                |
| `OnTurnCompleted`      | `CharacterTurnCompletedRelayData` | 角色本轮完整回复已完成。                   |
| `OnCharacterReady`     | —                                 | 角色已完成初始化并连接到会话。                |
| `OnEmotionChanged`     | `CharacterEmotionRelayData`       | 收到来自 Convai 的新情绪信号。            |

#### 多角色房间中的事件

在多角色会话处于活动状态时， `ConvaiCharacterEventRelay` 以及 `ConvaiEvents` 上的各角色事件会通过房间成员关系，而不是仅通过 `CharacterId` 来解析传入消息。成员列表可以包含两个具有相同 `CharacterId`的成员，只有成员关系才能区分它们；仅按 `CharacterId` 筛选的代码无法区分二者。请参阅 [处理房间事件](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/handle-roster-events.md) ，了解 `MultiCharacterRoomSession`.

#### `CharacterTranscriptRelayData`

| 属性              | 类型       | 说明                                  |
| --------------- | -------- | ----------------------------------- |
| `CharacterId`   | `string` | 角色的 ID。                             |
| `CharacterName` | `string` | 角色的显示名称。                            |
| `Text`          | `string` | 转录文本。如果 `IsFinal` 为 false，则文本可能不完整。 |
| `IsFinal`       | `bool`   | 底层转录轮次是否已提交、中断或更正。                  |
| `TurnId`        | `string` | 标识此转录片段所属的轮次。                       |
| `MessageId`     | `string` | 此转录消息的唯一标识符。                        |
| `ResponseId`    | `string` | 标识此轮次所属的角色回复。                       |

#### `CharacterTurnCompletedRelayData`

| 属性               | 类型       | 说明               |
| ---------------- | -------- | ---------------- |
| `CharacterId`    | `string` | 角色的 ID。          |
| `CharacterName`  | `string` | 角色的显示名称。         |
| `WasInterrupted` | `bool`   | 此轮次是否因用户打断角色而结束。 |

#### `CharacterEmotionRelayData`

| 属性              | 类型       | 说明                                                  |
| --------------- | -------- | --------------------------------------------------- |
| `CharacterId`   | `string` | 角色的 ID。                                             |
| `CharacterName` | `string` | 角色的显示名称。                                            |
| `Emotion`       | `string` | 情绪名称（例如， `"joy"`, `"fear"`, `"sadness"`）。请参阅情绪功能参考。 |
| `Intensity`     | `int`    | 情绪强度，范围为 `1`–`3` ，其中 `1` 表示微弱， `3` 表示强烈。            |

**代码示例 — 情绪变化时触发动画：**

```csharp
public class CharacterEmotionAnimator : MonoBehaviour
{
    [SerializeField] private ConvaiCharacterEventRelay _relay;
    [SerializeField] private Animator _animator;

    private static readonly int EmotionHash = Animator.StringToHash("Emotion");

    private void OnEnable() => _relay.OnEmotionChanged.AddListener(HandleEmotion);
    private void OnDisable() => _relay.OnEmotionChanged.RemoveListener(HandleEmotion);

    private void HandleEmotion(CharacterEmotionRelayData data)
    {
        _animator.SetTrigger(data.Emotion);
        _animator.SetFloat("EmotionIntensity", data.Intensity / 3f);
    }
}
```

***

### `ConvaiTranscriptEventRelay`

提供覆盖整个场景的转录文本流。与 `ConvaiCharacterEventRelay`不同，此中继器通过单个组件监控所有角色和玩家。可用它驱动字幕 UI、会话日志或评估系统。

**Inspector 字段：**

| 字段                     | 类型              | 默认值     | 说明                                                                               |
| ---------------------- | --------------- | ------- | -------------------------------------------------------------------------------- |
| `Manager`              | `ConvaiManager` | —       | 要监控的 `ConvaiManager` 。                                                           |
| `AutoResolveManager`   | `bool`          | —       | 自动查找 `ActiveManager` 。                                                           |
| `FinalOnly`            | `bool`          | `false` | 启用后，只有最终转录文本（已提交、中断或更正）才会触发事件。中间的部分转录文本会被抑制。                                     |
| `IgnoreInterimUpdates` | `bool`          | `true`  | 忽略仍处于 `Listening` 或 `Streaming` 状态的回合。稳定且已提交的回合仍会传递。如果 UI 需要在角色说话时显示部分文本，请禁用此字段。 |
| `CharacterIdFilter`    | `string`        | `""`    | 设置后，只有来自具有此 ID 的角色的转录文本才会触发事件。留空则表示所有角色。                                         |

**事件：**

| 事件                                   | 负载                             | 触发时机                                                     |
| ------------------------------------ | ------------------------------ | -------------------------------------------------------- |
| `OnTranscriptReceived`               | `TranscriptUpdateRelayData`    | 任何角色或玩家的转录文本更新，采用统一的数据结构（受筛选条件和 `IgnoreInterimUpdates`). |
| `OnCharacterTranscriptReceived`      | `CharacterTranscriptRelayData` | 任何角色的转录文本（受筛选条件和 `IgnoreInterimUpdates`).                |
| `OnPlayerTranscriptReceived`         | `PlayerTranscriptRelayData`    | 任何玩家的转录文本。                                               |
| `OnFinalCharacterTranscriptReceived` | `CharacterTranscriptRelayData` | 仅最终角色转录文本，不受 `FinalOnly` 设置影响。                           |
| `OnFinalPlayerTranscriptReceived`    | `PlayerTranscriptRelayData`    | 仅最终玩家转录文本。                                               |

#### `TranscriptUpdateRelayData`

如果场景需要用一个事件和一种数据结构处理角色及玩家的转录文本更新，而不是分别订阅角色和玩家事件，请使用此载荷。

| 属性                    | 类型                            | 说明                                                       |
| --------------------- | ----------------------------- | -------------------------------------------------------- |
| `MessageId`           | `string`                      | 此转录消息的唯一标识符。                                             |
| `TurnId`              | `string`                      | 标识此更新所属的回合。                                              |
| `ResponseId`          | `string`                      | 标识此轮次所属的角色回复。                                            |
| `SpeakerType`         | `SpeakerType`                 | `Character` 或 `Player`.                                  |
| `PlayerOrCharacterId` | `string`                      | 说话角色或玩家的 ID。                                             |
| `DisplayName`         | `string`                      | 说话者的显示名称。                                                |
| `ParticipantId`       | `string`                      | 房间参与者标识符。                                                |
| `Text`                | `string`                      | 转录文本。如果 `IsFinal` 为 false，则文本可能不完整。                      |
| `Lifecycle`           | `TranscriptLifecycle`         | `Streaming`, `Stable`，或 `Completed` —表示此次更新中的文本已稳定到何种程度。 |
| `IsFinal`             | `bool`                        | 计算得出： `Lifecycle != Streaming`.                          |
| `SourceKind`          | `TranscriptSegmentSourceKind` | 文本来源，例如 `PlayerAsr` 或 `BotOutput`.                       |

#### `PlayerTranscriptRelayData`

| 属性              | 类型       | 说明                                  |
| --------------- | -------- | ----------------------------------- |
| `PlayerId`      | `string` | 本地玩家的标识符。                           |
| `PlayerName`    | `string` | 玩家的显示名称。                            |
| `SpeakerId`     | `string` | 说话者标识符（在多参与者房间中可能与 `PlayerId` 不同）。  |
| `SpeakerName`   | `string` | 说话者的显示名称。                           |
| `ParticipantId` | `string` | 房间参与者标识符。                           |
| `TurnId`        | `string` | 标识此转录片段所属的轮次。                       |
| `MessageId`     | `string` | 此转录消息的唯一标识符。                        |
| `Text`          | `string` | 转录文本。如果 `IsFinal` 为 false，则文本可能不完整。 |
| `IsFinal`       | `bool`   | 底层转录轮次是否已提交、中断或更正。                  |

**代码示例 — 用于训练日志的多角色转录信息流：**

```csharp
public class TrainingTranscriptLog : MonoBehaviour
{
    [SerializeField] private ConvaiTranscriptEventRelay _relay;
    [SerializeField] private TMP_Text _logText;

    private readonly System.Text.StringBuilder _log = new();

    private void OnEnable()
    {
        _relay.OnFinalCharacterTranscriptReceived.AddListener(OnCharacterLine);
        _relay.OnFinalPlayerTranscriptReceived.AddListener(OnPlayerLine);
    }

    private void OnDisable()
    {
        _relay.OnFinalCharacterTranscriptReceived.RemoveListener(OnCharacterLine);
        _relay.OnFinalPlayerTranscriptReceived.RemoveListener(OnPlayerLine);
    }

    private void OnCharacterLine(CharacterTranscriptRelayData data)
    {
        _log.AppendLine($"[{data.CharacterName}]: {data.Text}");
        _logText.text = _log.ToString();
    }

    private void OnPlayerLine(PlayerTranscriptRelayData data)
    {
        _log.AppendLine($"[Learner]: {data.Text}");
        _logText.text = _log.ToString();
    }
}
```

***

### 订阅生命周期

Relay MonoBehaviour 组件会自动管理自身的订阅。它们会在 `OnEnable` 运行时订阅，并在 `OnDisable` 运行时。

通过 C# 订阅时，请遵循相同的模式：

```csharp
private void OnEnable()  => _relay.OnConnected.AddListener(MyHandler);
private void OnDisable() => _relay.OnConnected.RemoveListener(MyHandler);
```

{% hint style="warning" %}
不要在 `Start()` 中订阅，却不在 `OnDestroy()`中取消订阅。中继组件可以禁用后重新启用；从 `Start()` 订阅却未清理，会导致处理程序重复，或在中继禁用后出现空引用错误。
{% endhint %}

***

### 对话目标和可用性事件

这些事件没有中继组件。请通过以下类型化事件中心订阅，而不要向场景添加组件： `ConvaiManager.ActiveManager.Events` 。

**事件：**

| 事件                                  | 负载                                | 触发时机                                                            |
| ----------------------------------- | --------------------------------- | --------------------------------------------------------------- |
| `OnConversationTargetChanged`       | `ConversationTargetChanged`       | 在多角色房间中，对话从一个角色切换到另一个角色时触发——请求切换时触发一次，服务确认切换时触发一次，切换被拒绝时也会触发一次。 |
| `OnConversationAvailabilityChanged` | `ConversationAvailabilityChanged` | 对于当前交谈对象角色，“玩家现在能否交谈”的状态发生变化。                                   |
| `OnRoomRosterChanged`               | `RoomRosterChanged`               | 连接中的房间名单在运行期间被修改——有角色加入、离开，或修改被拒绝。                              |

**代码示例——响应目标切换和名单变更：**

```csharp
using Convai.Domain.DomainEvents.Runtime;
using Convai.Runtime.Facades;
using UnityEngine;

public class ConversationTargetingMonitor : MonoBehaviour
{
    private void OnEnable()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null) return;

        manager.Events.OnConversationTargetChanged += HandleTargetChanged;
        manager.Events.OnRoomRosterChanged += HandleRosterChanged;
    }

    private void OnDisable()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null) return;

        manager.Events.OnConversationTargetChanged -= HandleTargetChanged;
        manager.Events.OnRoomRosterChanged -= HandleRosterChanged;
    }

    private void HandleTargetChanged(ConversationTargetChanged e)
    {
        if (e.Phase == ConversationTargetChangePhase.Confirmed)
            Debug.Log($"Now talking to {e.CharacterName}.");
    }

    private void HandleRosterChanged(RoomRosterChanged e)
    {
        if (e.Change == RoomRosterChange.Joined)
            Debug.Log($"{e.CharacterName} joined the room.");
    }
}
```

#### `ConversationTargetChanged`

| 属性              | 类型                              | 说明                                         |
| --------------- | ------------------------------- | ------------------------------------------ |
| `Phase`         | `ConversationTargetChangePhase` | 切换进度： `Requested`, `Confirmed`，或 `Failed`. |
| `CharacterId`   | `string`                        | 对话将切换到的角色的 Convai Character ID。            |
| `CharacterName` | `string`                        | 该角色的显示名称。                                  |
| `MembershipId`  | `string`                        | 此次切换所针对的房间成员。                              |
| `Reason`        | `string`                        | 切换被拒绝的原因。除非 `Phase` 为 `Failed`.            |
| `Timestamp`     | `DateTime`                      | 到达该阶段的 UTC 时间。                             |

`ConversationTargetChangePhase` 取值： `Requested` （管理器已声明路由时段，即将发送迁移请求）， `Confirmed` （服务响应已同步权威路由）， `Failed` （请求的迁移被拒绝）。

#### `ConversationAvailabilityChanged`

| 属性                     | 类型                               | 说明                         |
| ---------------------- | -------------------------------- | -------------------------- |
| `Availability`         | `ConvaiConversationAvailability` | 当前判定结果。                    |
| `PreviousAvailability` | `ConvaiConversationAvailability` | 被当前结果取代的判定结果。              |
| `CharacterId`          | `string`                         | 被寻址角色的 Convai 角色 ID（如果存在）。 |
| `CharacterName`        | `string`                         | 该角色的显示名称。                  |
| `Timestamp`            | `DateTime`                       | 判定发生变化的 UTC 时间。            |
| `CanAcceptPlayerInput` | `bool`                           | 玩家此刻是否可以发送语音或文本。           |

`ConvaiConversationAvailability` 取值（按生命周期顺序排列）： `NoCharacter`, `Offline`, `Connecting`, `Preparing`, `Ready`, `Answering`, `Unavailable`。只有 `Ready` 和 `Answering` 接受玩家输入。

#### `RoomRosterChanged`

| 属性              | 类型                 | 说明                                  |
| --------------- | ------------------ | ----------------------------------- |
| `Change`        | `RoomRosterChange` | 发生的情况： `Joined`, `Left`或 `Refused`. |
| `MembershipId`  | `string`           | 受影响的房间成员。对于从未加入房间的加入请求，此字段为空。       |
| `CharacterId`   | `string`           | 此事件涉及的 Convai Character ID。         |
| `CharacterName` | `string`           | 该角色的显示名称。                           |
| `RosterSize`    | `int`              | 此次更改后房间可容纳的角色数量。                    |
| `Reason`        | `string`           | 编辑被拒绝的原因。除非 `Change` 为 `Refused`.   |
| `Timestamp`     | `DateTime`         | 成员列表发生变更的 UTC 时间。                   |

#### `LocalPlayerActivityChanged`

SDK 对玩家是否已开始说话的本地判断——这只是提示，并非服务本身的判定。它在 `ConvaiEvents`中没有对应属性；请改为通过原始事件中心订阅：

```csharp
using Convai.Domain.DomainEvents.Runtime;
using Convai.Domain.EventSystem;
using UnityEngine;

public class LocalPlayerActivityMonitor : MonoBehaviour
{
    private SubscriptionToken _token;

    private void OnEnable()
    {
        var hub = ConvaiManager.ActiveManager?.Events?.Raw;
        if (hub == null) return;
        _token = hub.Subscribe<LocalPlayerActivityChanged>(HandleActivity);
    }

    private void OnDisable() => ConvaiManager.ActiveManager?.Events?.Raw?.Unsubscribe(_token);

    private void HandleActivity(LocalPlayerActivityChanged e) =>
        Debug.Log(e.IsActive ? "Player started talking." : "Player stopped talking.");
}
```

| 属性          | 类型                          | 说明                                          |
| ----------- | --------------------------- | ------------------------------------------- |
| `IsActive`  | `bool`                      | 是否 `Source` 当前检测到玩家。                        |
| `Source`    | `LocalPlayerActivitySource` | 触发此状态的本地证据是： `Microphone` 或 `PushToTalk`.   |
| `Level`     | `float`                     | 麦克风相对于其测得噪声底的音量。对于 `PushToTalk` 以及下降沿，该值为零。 |
| `Timestamp` | `DateTime`                  | 本地证据发生变化的 UTC 时间。                           |

只将此视为“有人要开始对我说话”，除此之外不要做任何处理——绝不要据此转发消息、提交轮次或产生任何费用。服务自身的判定是 `PlayerSpeakingStateChanged`.

***

### `ConvaiNotificationEventBridge`

`ConvaiNotificationEventBridge` 不是中继组件。它是一个内部服务，用于将会话错误域事件桥接到通知 UI 系统，并通过冷却去重机制防止同一错误通知反复出现。

| 属性                | 类型      | 默认值  | 说明                   |
| ----------------- | ------- | ---- | -------------------- |
| `CooldownSeconds` | `float` | `10` | 再次显示相同通知类型之前的最短间隔秒数。 |

大多数项目都不会直接与此类交互。它由 SDK 引导程序实例化并管理。如果你正在使用 `IConvaiNotificationService`构建自定义通知系统，可以使用 `ConvaiNotificationEventBridge` 将会话错误事件集成到你的系统中。与上面的中继组件不同， `ConvaiNotificationEventBridge` 它不会通过 **添加组件** 添加到场景中，而是在 SDK 启动期间以编程方式实例化。

***

### 使用示例

#### 示例 1：培训模拟——连接状态遮罩层

会话尚未建立时，显示“正在连接…”遮罩层。

```csharp
[SerializeField] private ConvaiSessionEventRelay _sessionRelay;
[SerializeField] private CanvasGroup _loadingOverlay;

private void OnEnable()
{
    _sessionRelay.OnConnected.AddListener(OnConnected);
    _sessionRelay.OnDisconnected.AddListener(OnDisconnected);
    _sessionRelay.OnReconnecting.AddListener(OnReconnecting);
}

private void OnDisable()
{
    _sessionRelay.OnConnected.RemoveListener(OnConnected);
    _sessionRelay.OnDisconnected.RemoveListener(OnDisconnected);
    _sessionRelay.OnReconnecting.RemoveListener(OnReconnecting);
}

private void OnConnected()    => _loadingOverlay.alpha = 0f;
private void OnDisconnected() => _loadingOverlay.alpha = 1f;
private void OnReconnecting() => _loadingOverlay.alpha = 0.5f;
```

**预期结果：** 会话未连接时，遮罩层淡入；连接建立后，遮罩层淡出。

***

#### 示例 2：医疗培训模拟——由情绪触发角色回应

患者角色的面部表情和姿势会根据 Convai 检测到的情绪变化。

```csharp
[SerializeField] private ConvaiCharacterEventRelay _patientRelay;
[SerializeField] private PatientExpressionController _expressionController;

private void OnEnable() => _patientRelay.OnEmotionChanged.AddListener(ApplyEmotion);
private void OnDisable() => _patientRelay.OnEmotionChanged.RemoveListener(ApplyEmotion);

private void ApplyEmotion(CharacterEmotionRelayData data)
{
    _expressionController.SetExpression(data.Emotion, data.Intensity / 3f);
}
```

**预期结果：** 随着 Convai 的情绪信号传入，患者角色的视觉表情会实时更新。

***

#### 示例 3：仅显示某个角色的共享转录文本

企业入职培训模拟中有多个 NPC 角色，但字幕面板只显示主讲导师的台词。

在 `ConvaiTranscriptEventRelay` Inspector 中的组件上：

* 将 `CharacterIdFilter` 设为讲师角色的 ID（例如， `"abc123"`).
* 启用 `FinalOnly` 以仅显示已确认的转录文本行。
* 将 `OnFinalCharacterTranscriptReceived` 连接到字幕 UI。

**预期结果：** 字幕面板中只会显示讲师已完成的句子。场景中的其他角色不会影响 UI。

***

### 故障排查

| 症状                                        | 可能原因                                       | 解决方法                                                                                                             |
| ----------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| 场景启动后中继器不触发任何事件                           | `ConvaiManager` 在中继器的 `OnEnable` 运行之前尚未初始化 | 无需操作 — 中继器在启用期间会于 `LateUpdate()` 中重试。确认场景中存在且已激活 `ConvaiManager` 。                                               |
| `ConvaiCharacterEventRelay` 不触发任何事件       | `ConvaiCharacter` 未在指定的 GameObject 上找到     | 确认 `ConvaiCharacter` 位于中继器所在的 **同一个** GameObject 上，或显式指定该引用。 `AutoResolveCharacter` 只会搜索同一个 GameObject，不会搜索父级对象。 |
| 未收到中间转录文本更新                               | `IgnoreInterimUpdates` 默认值为 `true` 。       | 在 `IgnoreInterimUpdates = false` 上设置 `ConvaiTranscriptEventRelay` 即可接收部分转录文本更新。                                  |
| 单个事件的事件处理程序被触发多次                          | 事件处理程序在 `Start()` 中订阅后未清理；中继器曾被禁用并重新启用     | 将订阅移至 `OnEnable()` 并在 `OnDisable()`.                                                                             |
| `OnCharacterTranscriptReceived` 未针对预期角色触发 | `CharacterIdFilter` 设置为其他角色 ID             | 清除 `CharacterIdFilter` 或将其设置为正确的角色 ID。                                                                           |

***

### 后续步骤

现在，您已获得所有中继组件、事件负载和订阅模式的完整参考。接下来，请前往“功能”部分，了解各项 SDK 功能。

{% content-ref url="/pages/8c561f7c198c46628ed5818040fdaa9af3397caf" %}
[功能](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features.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/core-concepts/event-system.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.
