事件系统

Convai 事件中继组件参考——可用事件、负载字段、订阅模式以及 ConvaiNotificationEventBridge 服务。

Convai SDK 通过一组中继组件来传达会话期间发生的事情——连接、角色语音、转录、情绪等。将这些 MonoBehaviour 之一添加到场景中的 GameObject 上，在 Inspector 中连接 UnityEvents，或者在代码中订阅，场景逻辑就会对 SDK 广播的内容做出响应。

---

两种接线方式

Inspector（UnityEvents）

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

适用场景：连接指示器、动画触发、UI 显示切换——任何由单个事件驱动且不需要条件逻辑的功能。

C# 脚本

---

中继组件快速参考

组件	Inspector 菜单路径	适用时机
ConvaiSessionEventRelay	Convai/Events/Convai Session Event Relay	跟踪会话连接状态、处理错误、驱动连接 UI
ConvaiCharacterEventRelay	Convai/Events/Convai Character Event Relay	响应特定角色的语音、转录、轮次和情绪
ConvaiTranscriptEventRelay	Convai/Events/Convai Transcript Event Relay	场景级转录流，可按角色或最终性进行可选过滤

---

ConvaiSessionEventRelay

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

如果 ConvaiManager 初始化于中继的 OnEnable 之后（例如由于脚本执行顺序），中继会在 LateUpdate() 期间自动重试订阅。无需手动重试逻辑。

Inspector 字段：

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

事件：

事件	负载	触发时机
OnConnected	—	初始连接已建立（连接中 → 已连接）。不会在重连时触发——参见 OnReconnected.
OnDisconnected	—	会话进入 已断开 状态。
OnReconnecting	—	重连尝试开始（会话已 已连接，连接已断开）。
OnReconnected	—	重连尝试成功。会话再次 已连接 。
OnUsageLimitReached	—	该账户的 API 使用配额已超出。
OnSessionStateChanged	SessionStateChangedRelayData	任意会话状态转换。每次状态变更都会触发。
OnSessionError	SessionErrorRelayData	从会话收到一个错误事件。

SessionStateChangedRelayData

属性	类型	说明
OldState	SessionState	转换前的状态。
NewState	SessionState	转换后的状态。
SessionId	string	当前会话标识符。若无活动会话则为空。
错误代码	string	如果转换是由错误导致，则为错误代码；否则为空。
IsError	bool	计算结果： NewState == Error.
IsReconnecting	bool	计算结果： NewState == Reconnecting.
IsConnectionEstablished	bool	计算结果： OldState == Connecting && NewState == Connected.
IsReconnectionSuccessful	bool	计算结果： OldState == Reconnecting && NewState == Connected.
IsDisconnected	bool	计算结果： NewState == Disconnected.

SessionErrorRelayData

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

SessionErrorStage 值： 未知, 配置, ConnectApi, Transport, SessionRecovery, 运行时.

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

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 字段：

字段	说明
角色	对场景中 ConvaiCharacter 该中继监视。
AutoResolveCharacter	启用后，组件会搜索 ConvaiCharacter ，位于中继所在的同一个 GameObject 上。

事件：

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

CharacterTranscriptRelayData

属性	类型	说明
CharacterId	string	角色的 ID。
CharacterName	string	角色的显示名称。
文本	string	转录文本。若 IsFinal 为 false，则可能是部分内容。
IsFinal	bool	此片段是否为已提交的最终转录。

CharacterTurnCompletedRelayData

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

CharacterEmotionRelayData

属性	类型	说明
CharacterId	string	角色的 ID。
CharacterName	string	角色的显示名称。
情绪	string	情绪名称（例如， "joy", “恐惧”, “悲伤”）。请参见情绪功能参考。
强度	int	情绪强度（0–100）。

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

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 / 100f);
    }
}

---

ConvaiTranscriptEventRelay

提供场景级转录流。不同于 ConvaiCharacterEventRelay，这个中继通过单个组件监视所有角色和玩家。可用于驱动字幕 UI、会话日志或评估系统。

Inspector 字段：

字段	类型	默认值	说明
管理器	ConvaiManager	—	该 ConvaiManager 要监视。
AutoResolveManager	bool	—	查找 ActiveManager 自动。
FinalOnly	bool	false	启用后，只有最终（已提交）的转录才会触发事件。中间的部分转录会被抑制。
IgnoreInterimUpdates	bool	true	抑制中间转录更新。最终更新仍会通过。如果你的 UI 需要在角色说话时显示部分文本，请禁用此字段。
CharacterIdFilter	string	""	如果设置，则只有来自该 ID 角色的转录才会触发事件。留空则表示所有角色。

事件：

事件	负载	触发时机
OnCharacterTranscriptReceived	CharacterTranscriptRelayData	任意角色转录（受过滤条件和 IgnoreInterimUpdates).
OnPlayerTranscriptReceived	PlayerTranscriptRelayData	任意玩家转录。
OnFinalCharacterTranscriptReceived	CharacterTranscriptRelayData	仅最终角色转录，不论 FinalOnly 设置。
OnFinalPlayerTranscriptReceived	PlayerTranscriptRelayData	仅最终玩家转录。

PlayerTranscriptRelayData

属性	类型	说明
PlayerId	string	本地玩家的标识符。
PlayerName	string	玩家的显示名称。
SpeakerId	string	说话者标识符（在多人房间中可能与 PlayerId 不同）。
SpeakerName	string	说话者的显示名称。
ParticipantId	string	房间参与者标识符。
TurnId	string	标识此转录片段所属的轮次。
MessageId	string	此转录消息的唯一标识符。
文本	string	转录文本。若 IsFinal 为 false，则可能是部分内容。
IsFinal	bool	为 true，则表示这是已提交的最终转录。

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

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($"[学习者]: {data.Text}");
        _logText.text = _log.ToString();
    }
}

---

订阅生命周期

中继 MonoBehaviour 组件会自动管理自己的订阅。它们会在 OnEnable 运行时订阅，并在 OnDisable 运行之前异步获取凭据。

被调用时取消订阅。

通过 C# 订阅时，请遵循相同模式：
private void OnEnable()  => _relay.OnConnected.AddListener(MyHandler);

不要在 Start() 中订阅，而不在 OnDestroy()中进行匹配的取消订阅。中继组件可以被禁用并重新启用；来自 Start() 的订阅若未清理，在中继被禁用后会导致重复处理器或空引用错误。

---

ConvaiNotificationEventBridge

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

属性	类型	默认值	说明
CooldownSeconds	float	10	显示相同通知类型之间的最少秒数。

大多数项目不会直接与此类交互。它由 SDK 引导程序实例化并管理。如果你正在使用 IConvaiNotificationService构建自定义通知系统，你可以使用 ConvaiNotificationEventBridge 将会话错误事件集成到你的系统中。

ConvaiNotificationEventBridge 不会通过 添加组件添加到场景中。它会在 SDK 启动期间以编程方式实例化。

---

使用示例

示例 1：训练模拟——连接遮罩

在会话尚未建立时显示“Connecting…”遮罩。

[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 检测到的情绪而变化。

[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 / 100f);
}

预期结果： 当来自 Convai 的情绪信号到达时，患者角色的视觉表情会实时更新。

---

示例 3：过滤到单个角色的共享转录流

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

在 ConvaiTranscriptEventRelay 组件的检查器中：

• 设置 CharacterIdFilter 到讲解员角色的 ID（例如， “abc123”).
• 启用 FinalOnly 以仅显示已提交的转录行。
• 连接 OnFinalCharacterTranscriptReceived 到你的字幕 UI。

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

---

故障排查

症状	可能原因	修复
场景开始后中继没有触发任何事件	ConvaiManager 在中继的 OnEnable 运行之前未初始化	无需操作——中继会在 LateUpdate() 期间重试，同时保持启用。请确认 ConvaiManager 存在并在场景中处于激活状态。
ConvaiCharacterEventRelay 没有触发任何事件	ConvaiCharacter 未在分配的 GameObject 上找到	验证 ConvaiCharacter 位于 同一个 GameObject 上，或者显式分配该引用。 AutoResolveCharacter 只搜索同一个 GameObject——不包括父对象。
中间转录更新未到达	IgnoreInterimUpdates 为 true 默认情况下	设置 IgnoreInterimUpdates = false on ConvaiTranscriptEventRelay 以接收部分转录更新。
单个事件触发多次事件处理器	处理器已在 Start() 中订阅但未清理；中继被禁用并重新启用	将订阅移至 OnEnable() 中订阅这些事件，并在 OnDisable().
OnCharacterTranscriptReceived 未对预期角色触发	CharacterIdFilter 被设置为不同的角色 ID	清空 CharacterIdFilter ，或者将其设置为正确的角色 ID。

---

下一步

现在你已经拥有所有中继组件、事件负载和订阅模式的完整参考。继续前往 Features 部分，探索各项 SDK 功能。

功能