> 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/scripting-reference/character-events.md).

# 角色事件

角色事件参考文档，涵盖语音、情绪、转录文本、回合变更和动作，可通过 Inspector 中继器或脚本接入。

角色事件让你能够根据 AI 角色所说、所感和所做的内容，驱动 UI、动画、游戏玩法和评估逻辑。SDK 提供了两个 Inspector 中继组件，用于无代码连接；还提供了一个类型化的 C# 事件中心，用于通过脚本响应。这两种方式监听的都是同一组底层事件。

{% hint style="info" %}
**中继组件与 C# 订阅：** 中继组件会触发一组经过筛选的事件。对于 `OnRemoteAudioEnabledChanged` 和 `OnSessionStateChanged` （针对单个角色），请直接在 C# 中订阅 `ConvaiCharacter` ——这些事件不会通过中继组件公开。
{% endhint %}

***

### `ConvaiCharacterEventRelay`

**添加组件的路径：** Convai → Events → Convai Character Event Relay

将其添加到与 `ConvaiCharacter`相同的 GameObject 上，或添加到启用了 **Auto Resolve Character** 的任意 GameObject 上，以便在运行时获取同一对象上的 `ConvaiCharacter` 。

{% tabs %}
{% tab title="Inspector" %}
添加该组件，然后在 Inspector 中将回调连接到六个 UnityEvent 中的任意一个。启用 **Auto Resolve Character** ，或显式指定 `ConvaiCharacter` 字段。
{% endtab %}

{% tab title="脚本编写" %}

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

public class CharacterReactionHandler : MonoBehaviour
{
    private void OnEnable()
    {
        var events = ConvaiManager.ActiveManager?.Events;
        if (events == null) return;

        events.OnCharacterSpeechStateChanged += HandleSpeech;
        events.OnCharacterEmotionChanged     += HandleEmotion;
    }

    private void OnDisable()
    {
        var events = ConvaiManager.ActiveManager?.Events;
        if (events == null) return;

        events.OnCharacterSpeechStateChanged -= HandleSpeech;
        events.OnCharacterEmotionChanged     -= HandleEmotion;
    }

    private void HandleSpeech(CharacterSpeechStateChanged e)
    {
        if (e.IsStartOfSpeech) Debug.Log($"{e.CharacterId} started speaking.");
        if (e.IsEndOfSpeech)   Debug.Log($"{e.CharacterId} stopped speaking.");
    }

    private void HandleEmotion(CharacterEmotionChanged e) =>
        Debug.Log($"{e.CharacterId}: {e.Emotion} ({e.NormalizedIntensity:P0})");
}
```

{% endtab %}
{% endtabs %}

#### 事件

| 事件                     | 参数                                | 触发时机            |
| ---------------------- | --------------------------------- | --------------- |
| `OnTranscriptReceived` | `CharacterTranscriptRelayData`    | 收到转录文本（临时或最终文本） |
| `OnSpeechStarted`      | —                                 | 角色开始说话          |
| `OnSpeechStopped`      | —                                 | 角色停止说话          |
| `OnTurnCompleted`      | `CharacterTurnCompletedRelayData` | 角色的完整对话轮次结束     |
| `OnCharacterReady`     | —                                 | 角色已初始化，可以开始对话   |
| `OnEmotionChanged`     | `CharacterEmotionRelayData`       | 检测到的角色情绪发生变化    |

#### `CharacterTranscriptRelayData` 字段

| 字段              | 类型       | 说明                 |
| --------------- | -------- | ------------------ |
| `CharacterId`   | `string` | 角色的标识符             |
| `CharacterName` | `string` | 角色的显示名称            |
| `Text`          | `string` | 当前转录文本（可能是临时文本）    |
| `IsFinal`       | `bool`   | 当此话语不会再收到更新时为 True |

#### `CharacterEmotionRelayData` 字段

| 字段              | 类型       | 说明                                    |
| --------------- | -------- | ------------------------------------- |
| `CharacterId`   | `string` | 角色的标识符                                |
| `CharacterName` | `string` | 角色的显示名称                               |
| `Emotion`       | `string` | 情绪标签，例如 `"Joy"`, `"Sadness"`          |
| `Intensity`     | `int`    | 原始强度值；范围为 **1–3** （1 = 低，2 = 中，3 = 高） |

该中继会公开原始的 `Intensity` 整数（1–3）。若要将其归一化到 0.0–1.0，请计算 `(Intensity - 1) / 2f`。如需获取归一化值和布尔辅助属性（`IsNeutral`, `IsHighIntensity`），请在 C# 中订阅 `ConvaiEvents.OnCharacterEmotionChanged` ——领域事件负载包含这些字段。

#### `CharacterTurnCompletedRelayData` 字段

| 字段               | 类型       | 说明                   |
| ---------------- | -------- | -------------------- |
| `CharacterId`    | `string` | 角色的标识符               |
| `CharacterName`  | `string` | 角色的显示名称              |
| `WasInterrupted` | `bool`   | 当回合因玩家打断角色而结束时为 True |

***

### `ConvaiTranscriptEventRelay`

**添加组件路径：** Convai → Events → Convai Transcript Event Relay

当你需要同时响应角色和玩家的转录流时，可使用此中继，例如用于显示字幕、自定义聊天界面或记录转录内容。

#### 筛选属性

| 属性                     | 默认值     | 说明                                     |
| ---------------------- | ------- | -------------------------------------- |
| `FinalOnly`            | `false` | 当 `true`时，只有最终转录内容会传递到回调。非最终更新会被完全丢弃。  |
| `IgnoreInterimUpdates` | `true`  | 当 `true`时，临时更新会被筛除。稳定的非最终、非临时更新仍会继续传递。 |
| `CharacterIdFilter`    | `""`    | 当值不为空时，只有与此 ID 匹配的角色转录内容会传递到角色回调。      |

{% hint style="info" %}
`FinalOnly` 和 `IgnoreInterimUpdates` 是不同的筛选器。 `FinalOnly = true` 最严格的设置——除已确认的最终转录外，其他内容都会被丢弃。 `IgnoreInterimUpdates = true` （默认设置）会丢弃进行中的部分词语，但允许稳定的中间更新通过，从而让字幕渲染更加流畅。
{% endhint %}

#### 事件

| 事件                                   | 参数                             | 触发时机                                 |
| ------------------------------------ | ------------------------------ | ------------------------------------ |
| `OnTranscriptReceived`               | `TranscriptUpdateRelayData`    | 任何转录更新都会先于下方按角色划分的事件到达，无论是角色还是玩家的转录。 |
| `OnCharacterTranscriptReceived`      | `CharacterTranscriptRelayData` | 角色转录到达（遵循筛选条件）                       |
| `OnPlayerTranscriptReceived`         | `PlayerTranscriptRelayData`    | 玩家转录到达（遵循筛选条件）                       |
| `OnFinalCharacterTranscriptReceived` | `CharacterTranscriptRelayData` | 角色转录已定稿                              |
| `OnFinalPlayerTranscriptReceived`    | `PlayerTranscriptRelayData`    | 玩家转录已定稿                              |

#### `PlayerTranscriptRelayData` 字段

| 字段              | 类型       | 说明                    |
| --------------- | -------- | --------------------- |
| `PlayerId`      | `string` | 本地玩家标识符               |
| `PlayerName`    | `string` | 玩家的显示名称               |
| `SpeakerId`     | `string` | 服务器分配的说话者 ID          |
| `SpeakerName`   | `string` | 服务器分配的说话者显示名称         |
| `ParticipantId` | `string` | 房间参与者标识符              |
| `TurnId`        | `string` | 此轮对话的标识符              |
| `MessageId`     | `string` | 此条转录消息的标识符            |
| `Text`          | `string` | 转录文本（可能是中间结果）         |
| `IsFinal`       | `bool`   | 如果这是该轮对话的最终转录，则为 True |

***

### C# 事件中心 — 按角色划分的事件

通过以下对象访问： `ConvaiManager.ActiveManager.Events`。这些事件在整个房间范围内触发——存在多个角色时，请按 `CharacterId` 筛选，以便将响应限定到特定角色。

#### 角色事件

| 事件                              | 会话范围的事件                       | 触发时机                   |
| ------------------------------- | ----------------------------- | ---------------------- |
| `OnCharacterTranscriptReceived` | `CharacterTranscriptReceived` | 角色转录到达                 |
| `OnCharacterSpeechStateChanged` | `CharacterSpeechStateChanged` | 角色开始或停止说话              |
| `OnCharacterEmotionChanged`     | `CharacterEmotionChanged`     | 角色情绪发生变化               |
| `OnCharacterReady`              | `CharacterReady`              | 角色已准备好进行对话             |
| `OnCharacterTurnCompleted`      | `CharacterTurnCompleted`      | 角色回合结束                 |
| `OnCharacterActionReceived`     | `CharacterActionReceived`     | Convai 为此角色发送结构化的场景内动作 |
| `OnLlmNoResponseReceived`       | `LlmNoResponseReceived`       | Convai 已处理输入，但未生成语音回复  |

#### 玩家事件

| 事件                                 | 会话范围的事件                          | 触发时机                   |
| ---------------------------------- | -------------------------------- | ---------------------- |
| `OnPlayerTranscriptReceived`       | `PlayerTranscriptReceived`       | 收到玩家转录文本               |
| `OnPlayerSpeakingStateChanged`     | `PlayerSpeakingStateChanged`     | 玩家开始或停止说话              |
| `OnFinalUserTranscriptionReceived` | `FinalUserTranscriptionReceived` | 玩家的转录文本已定稿             |
| `OnVadSttStateChanged`             | `VadSttStateChanged`             | 语音活动检测 / 语音转文本管线状态发生变化 |

#### 跨功能事件

| 事件                          | 会话范围的事件                   | 备注                             |
| --------------------------- | ------------------------- | ------------------------------ |
| `OnNarrativeSectionChanged` | `NarrativeSectionChanged` | 角色的叙事设计部分发生变化。完整详情请参阅“叙事设计”部分。 |

#### 内部 / 高级事件

| 事件                              | 注意                                                                         |
| ------------------------------- | -------------------------------------------------------------------------- |
| `OnModerationResponseReceived`  | Convai 返回审核判定时触发。可用于在安全关键型培训模拟中对标记内容做出响应。通过以下方式访问原始字段： `ConvaiEvents.Raw`. |
| `OnBlendshapeTurnStatsReceived` | 内部唇形同步性能统计信息，不适用于一般用途。                                                     |

***

### 直接 `ConvaiCharacter` C# 事件

这些事件位于 `ConvaiCharacter` 组件本身上，而非位于 `ConvaiEvents`上。直接在角色实例上订阅这些事件。它们适用于中继或中心未公开的逐角色音频和逐角色会话状态。

| 事件                            | 签名                     | 触发时机                     |
| ----------------------------- | ---------------------- | ------------------------ |
| `OnRemoteAudioEnabledChanged` | `Action<bool>`         | 角色的远程音频输出已启用或禁用          |
| `OnSessionStateChanged`       | `Action<SessionState>` | 此角色自身的会话状态发生变化（区别于房间级状态） |

```csharp
using Convai.Runtime.Components;
using UnityEngine;

public class CharacterAudioIndicator : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _character;
    [SerializeField] private GameObject     _muteIcon;

    private void OnEnable()
    {
        if (_character == null) return;
        _character.OnRemoteAudioEnabledChanged += OnAudioChanged;
    }

    private void OnDisable()
    {
        if (_character == null) return;
        _character.OnRemoteAudioEnabledChanged -= OnAudioChanged;
    }

    private void OnAudioChanged(bool isEnabled) =>
        _muteIcon.SetActive(!isEnabled);
}
```

`OnSessionStateChanged` 上 `ConvaiCharacter` 反映的是此角色的单独会话，而非房间级状态。在多角色场景中，每个角色都有自己的会话状态。请使用 `ConvaiManager.ActiveManager.Events.OnSessionStateChanged` 获取房间级状态。

***

### 领域事件载荷类型

#### `CharacterTranscriptReceived`

| 字段              | 类型                  | 说明                         |
| --------------- | ------------------- | -------------------------- |
| `CharacterId`   | `string`            | 角色标识符                      |
| `CharacterName` | `string`            | 角色显示名称                     |
| `Text`          | `string`            | 转录文本                       |
| `IsFinal`       | `bool`              | 为 true 时表示不会再有后续更新         |
| `IsInterim`     | `bool`              | 为 true 时表示转录内容仍在生成中，属于部分内容 |
| `Timestamp`     | `DateTime`          | 事件发生的 UTC 时间               |
| `Message`       | `TranscriptMessage` | 包含其他元数据的完整消息对象             |

#### `CharacterSpeechStateChanged`

| 字段                | 类型         | 说明                  |
| ----------------- | ---------- | ------------------- |
| `CharacterId`     | `string`   | 角色标识符               |
| `IsSpeaking`      | `bool`     | 为 true 时表示角色正在说话    |
| `IsStartOfSpeech` | `bool`     | 在语音片段的第一个事件中为 true  |
| `IsEndOfSpeech`   | `bool`     | 在语音片段的最后一个事件中为 true |
| `IsSilent`        | `bool`     | 为 true 时表示角色未说话     |
| `UtteranceId`     | `string`   | 此语音片段的标识符           |
| `Timestamp`       | `DateTime` | 事件发生的 UTC 时间        |

#### `CharacterEmotionChanged`

| 字段                    | 类型         | 说明                           |
| --------------------- | ---------- | ---------------------------- |
| `CharacterId`         | `string`   | 角色标识符                        |
| `Emotion`             | `string`   | Convai 分类体系中的情绪标签，例如 `"Joy"` |
| `Intensity`           | `int`      | 原始强度值；范围为 1–3                |
| `NormalizedIntensity` | `float`    | 归一化到 0.0–1.0 的强度值            |
| `IsNeutral`           | `bool`     | 角色恢复到中性状态时为 true             |
| `IsHighIntensity`     | `bool`     | 高强度情绪时为 true                 |
| `IsLowIntensity`      | `bool`     | 低强度情绪时为 true                 |
| `Timestamp`           | `DateTime` | 事件发生的 UTC 时间                 |

#### `CharacterReady`

| 字段                    | 类型         | 说明                                 |
| --------------------- | ---------- | ---------------------------------- |
| `CharacterId`         | `string`   | 角色标识符                              |
| `ParticipantId`       | `string`   | 此角色在房间中的参与者标识符                     |
| `MembershipId`        | `string`   | 此就绪信号在多角色房间中所属的成员关系。在单角色会话中为空字符串。  |
| `CharacterSessionId`  | `string`   | 此成员关系在多角色房间中的角色会话标识符。在单角色会话中为空字符串。 |
| `ParticipantIdentity` | `string`   | 此成员关系在多角色房间中的传输参与者身份。在单角色会话中为空字符串。 |
| `Timestamp`           | `DateTime` | 角色就绪时的 UTC 时间                      |

请参阅 [角色身份与寻址](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/character-identity.md) 了解这些字段如何用于定位共享房间中的成员关系。

#### `CharacterTurnCompleted`

| 字段               | 类型         | 说明                |
| ---------------- | ---------- | ----------------- |
| `CharacterId`    | `string`   | 角色标识符             |
| `ParticipantId`  | `string`   | 房间参与者标识符          |
| `WasInterrupted` | `bool`     | 因玩家打断而结束回合时为 true |
| `Timestamp`      | `DateTime` | 回合完成时的 UTC 时间     |

#### `CharacterActionReceived`

| 字段            | 类型                                   | 说明                |
| ------------- | ------------------------------------ | ----------------- |
| `CharacterId` | `string`                             | 角色标识符             |
| `Actions`     | `IReadOnlyList<ConvaiActionCommand>` | 此回合中按顺序排列的场景内操作列表 |
| `Timestamp`   | `DateTime`                           | 事件发生的 UTC 时间      |

#### `LlmNoResponseReceived`

| 字段              | 类型         | 说明                |
| --------------- | ---------- | ----------------- |
| `CharacterId`   | `string`   | 角色标识符             |
| `ParticipantId` | `string`   | 房间参与者标识符          |
| `Reason`        | `string`   | Convai 未生成语音回复的原因 |
| `Timestamp`     | `DateTime` | 事件发生的 UTC 时间      |

#### `PlayerSpeakingStateChanged`

| 字段                | 类型         | 说明                    |
| ----------------- | ---------- | --------------------- |
| `SessionId`       | `string`   | 会话标识符                 |
| `IsSpeaking`      | `bool`     | 玩家正在说话时为 true         |
| `IsStartOfSpeech` | `bool`     | 在玩家语音片段的第一个事件中为 true  |
| `IsEndOfSpeech`   | `bool`     | 在玩家语音片段的最后一个事件中为 true |
| `IsSilent`        | `bool`     | 玩家未说话时为 true          |
| `Timestamp`       | `DateTime` | 事件发生的 UTC 时间          |

#### `FinalUserTranscriptionReceived`

| 字段              | 类型            | 说明           |
| --------------- | ------------- | ------------ |
| `Text`          | `string`      | 玩家最终转录的文本    |
| `SpeakerId`     | `string`      | 服务器分配的说话者 ID |
| `SpeakerName`   | `string`      | 说话者显示名称      |
| `ParticipantId` | `string`      | 房间参与者标识符     |
| `MessageId`     | `string`      | 消息标识符        |
| `Timestamp`     | `DateTime`    | 事件发生的 UTC 时间 |
| `SpeakerInfo`   | `SpeakerInfo` | 结构化说话者身份信息   |

#### `VadSttStateChanged`

| 字段          | 类型         | 说明                            |
| ----------- | ---------- | ----------------------------- |
| `IsActive`  | `bool`     | 当语音活动检测 / STT 管道正在处理音频时为 True |
| `Timestamp` | `DateTime` | 事件发生的 UTC 时间                  |

***

### 支持类型

#### `SpeakerInfo` 结构体

| 字段                | 类型            | 说明                 |
| ----------------- | ------------- | ------------------ |
| `SpeakerId`       | `string`      | 服务器分配的说话者标识符       |
| `SpeakerName`     | `string`      | 显示名称               |
| `ParticipantId`   | `string`      | 房间参与者标识符           |
| `SpeakerType`     | `SpeakerType` | 该说话者的角色            |
| `IsValid`         | `bool`        | 当所有身份字段均已填充时为 True |
| `IsDefaultPlayer` | `bool`        | 对于默认本地玩家身份为 True   |

#### `SpeakerType` 枚举

| 值               | 说明        |
| --------------- | --------- |
| `Unknown` (0)   | 尚未确定说话者类型 |
| `Character` (1) | AI 角色     |
| `Player` (2)    | 人类玩家      |
| `System` (3)    | 系统生成的消息   |

***

### Inspector 中继与 C# 事件 — 如何选择

在以下情况下使用 **Inspector 中继组件** ：

* 在 Inspector 中将 Animator 参数、UI 组件或音频源连接起来
* 逻辑简单且基于组件，无需分支处理
* 优先考虑通过拖放连接实现零代码配置

在以下情况下使用 **C# 订阅** 通过 `ConvaiEvents` ：

* 在运行时动态按 `CharacterId` 筛选
* 处理程序包含条件逻辑，或会调用异步方法 / 协程方法
* 为场景中所有角色的事件使用同一个处理程序

在以下情况下使用 **直接 `ConvaiCharacter` 订阅** ：

* 响应 `OnRemoteAudioEnabledChanged` 或针对每个角色的 `OnSessionStateChanged`
* 这些事件在中继组件上不可用

***

### 使用示例

#### 示例 1 — 实时转录字幕显示

军事训练模拟中的屏幕底部会显示字幕栏，实时呈现 AI 教官的语音，并在每次收到中间转录结果时更新。

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

public class SubtitleDisplay : MonoBehaviour
{
    [SerializeField] private TMP_Text _label;
    [SerializeField] private string   _targetCharacterId;

    private void OnEnable()  => ConvaiManager.ActiveManager?.Events.OnCharacterTranscriptReceived += OnTranscript;
    private void OnDisable() => ConvaiManager.ActiveManager?.Events.OnCharacterTranscriptReceived -= OnTranscript;

    private void OnTranscript(CharacterTranscriptReceived e)
    {
        if (e.CharacterId != _targetCharacterId) return;
        _label.text = e.IsFinal ? string.Empty : e.Text;
    }
}
```

#### 示例 2 — 根据情绪切换材质

在互动体验中，根据检测到的情绪强度更改角色的自发光材质颜色：高强度情绪使用较暖的色调，低强度情绪则使用较冷的色调。

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

public class EmotionMaterialDriver : MonoBehaviour
{
    [SerializeField] private Renderer _characterRenderer;
    [SerializeField] private string   _targetCharacterId;
    [SerializeField] private Color    _highIntensityColor = Color.red;
    [SerializeField] private Color    _lowIntensityColor  = Color.blue;
    [SerializeField] private Color    _neutralColor       = Color.white;

    private static readonly int EmissionColor = Shader.PropertyToID("_EmissionColor");

    private void OnEnable()  => ConvaiManager.ActiveManager?.Events.OnCharacterEmotionChanged += OnEmotion;
    private void OnDisable() => ConvaiManager.ActiveManager?.Events.OnCharacterEmotionChanged -= OnEmotion;

    private void OnEmotion(CharacterEmotionChanged e)
    {
        if (e.CharacterId != _targetCharacterId) return;

        Color target = e.IsNeutral
            ? _neutralColor
            : Color.Lerp(_lowIntensityColor, _highIntensityColor, e.NormalizedIntensity);

        _characterRenderer.material.SetColor(EmissionColor, target);
    }
}
```

#### 示例 3 — 无响应时显示“思考中”转圈图标

企业入职培训模拟会在 AI 角色收到输入、但尚未开始语音回应时显示转圈图标，避免学员误以为系统卡住了。

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

public class ThinkingSpinner : MonoBehaviour
{
    [SerializeField] private GameObject _spinnerRoot;
    [SerializeField] private string     _targetCharacterId;

    private void OnEnable()
    {
        var events = ConvaiManager.ActiveManager?.Events;
        if (events == null) return;
        events.OnLlmNoResponseReceived       += ShowSpinner;
        events.OnCharacterSpeechStateChanged += HideSpinnerOnSpeech;
    }

    private void OnDisable()
    {
        var events = ConvaiManager.ActiveManager?.Events;
        if (events == null) return;
        events.OnLlmNoResponseReceived       -= ShowSpinner;
        events.OnCharacterSpeechStateChanged -= HideSpinnerOnSpeech;
    }

    private void ShowSpinner(LlmNoResponseReceived e)
    {
        if (e.CharacterId != _targetCharacterId) return;
        _spinnerRoot.SetActive(true);
    }

    private void HideSpinnerOnSpeech(CharacterSpeechStateChanged e)
    {
        if (e.CharacterId != _targetCharacterId) return;
        if (e.IsStartOfSpeech) _spinnerRoot.SetActive(false);
    }
}
```

***

### 故障排查

| 症状                                                   | 可能原因                                                           | 解决方法                                                   |
| ---------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
| `ConvaiCharacterEventRelay` 回调从未触发                   | `AutoResolveCharacter` 已关闭，且未分配角色                              | 启用 **自动解析角色** 或分配 `ConvaiCharacter` 字段                 |
| 转录 UI 显示重复内容                                         | 同时订阅了中继组件和 `ConvaiEvents.OnCharacterTranscriptReceived` 对于同一事件 | 每项功能只使用一种方式——中继 OR C# 订阅，不要同时使用                        |
| `CharacterIdFilter` 不起作用                             | 筛选器中包含多余空格或大小写错误                                               | 比较不区分大小写；检查开头或结尾是否有空格                                  |
| `OnFinalCharacterTranscriptReceived` 从未触发            | `FinalOnly = false` 且转录内容始终不会标记为 `IsFinal = true`              | 检查 `ConvaiCharacter.EnableRemoteAudioOnStart`；角色必须完全连接 |
| `OnEmotionChanged` 会触发，但 `NormalizedIntensity` 始终为 0 | 未在 Convai 控制面板中为角色启用情绪功能                                       | 在角色的 Convai 配置中启用情绪输出                                  |
| `OnRemoteAudioEnabledChanged` 从未触发                   | 订阅了中继，而不是直接订阅 `ConvaiCharacter` 上的 C# 事件                       | 订阅 `character.OnRemoteAudioEnabledChanged` ——此事件不在中继上  |

***

### 后续步骤

接好角色事件后，可以探索 [转录 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md) 以通过拉取方式访问时间线，或探索 [角色与玩家 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/character-and-player-api.md) 以通过脚本控制角色会话、音频和注意力。


---

# 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/scripting-reference/character-events.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.
