> 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 提供了两个用于无代码连接的检视面板中继组件，以及一个用于脚本化响应的强类型 C# 事件中心。两种方式都监听同一底层事件。

{% hint style="info" %}
**中继 vs. C# 订阅：** 中继组件会触发一组精选事件。对于 `OnRemoteAudioEnabledChanged` 和 `OnSessionStateChanged` （按角色），请订阅 `ConvaiCharacter` 直接在 C# 中订阅——这些不会在中继上公开。
{% endhint %}

***

### `ConvaiCharacterEventRelay`

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

放在与以下对象相同的 GameObject 上： `ConvaiCharacter`，或者放在任何具有 **Auto Resolve Character** 已启用，以便拾取 `ConvaiCharacter` 运行时同一对象上的角色。

{% tabs %}
{% tab title="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} 开始说话。");
        if (e.IsEndOfSpeech)   Debug.Log($"{e.CharacterId} 停止说话。");
    }

    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`   | 当此发言不再有后续更新时为真  |

#### `CharacterEmotionRelayData` 字段

| 字段              | 类型       | 说明                                   |
| --------------- | -------- | ------------------------------------ |
| `CharacterId`   | `string` | 角色标识符                                |
| `CharacterName` | `string` | 角色显示名称                               |
| `情绪`            | `string` | 情绪标签，例如 `“喜悦”`, `“悲伤”`               |
| `强度`            | `int`    | 原始强度值；范围 **1–3** （1 = 低，2 = 中，3 = 高） |

中继公开原始 `强度` 整数（1–3）。要归一化到 0.0–1.0，请计算 `(Intensity - 1) / 2f`。对于归一化值和布尔辅助项（`IsNeutral`, `IsHighIntensity`），请订阅 `ConvaiEvents.OnCharacterEmotionChanged` 请在 C# 中订阅——领域事件负载包含这些字段。

#### `CharacterTurnCompletedRelayData` 字段

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

***

### `ConvaiTranscriptEventRelay`

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

当你需要同时响应角色和玩家的转录流时，请使用此中继——用于字幕显示、自定义聊天 UI 或转录记录。

#### 过滤属性

| 属性                     | 默认      | 说明                                 |
| ---------------------- | ------- | ---------------------------------- |
| `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`   | 当这是该回合的最终转录时为真 |

***

### 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`              | 当不再有后续更新时为真    |
| `IsInterim`     | `bool`              | 进行中的部分转录时为真    |
| `时间戳`           | `DateTime`          | 事件的 UTC 时间     |
| `Message`       | `TranscriptMessage` | 包含附加元数据的完整消息对象 |

#### `CharacterSpeechStateChanged`

| 字段                | 类型         | 说明              |
| ----------------- | ---------- | --------------- |
| `CharacterId`     | `string`   | 角色标识符           |
| `IsSpeaking`      | `bool`     | 当角色正在说话时为真      |
| `IsStartOfSpeech` | `bool`     | 在语音片段的第一个事件上为真  |
| `IsEndOfSpeech`   | `bool`     | 在语音片段的最后一个事件上为真 |
| `IsSilent`        | `bool`     | 不说话时为真          |
| `UtteranceId`     | `string`   | 此语音片段的标识符       |
| `时间戳`             | `DateTime` | 事件的 UTC 时间      |

#### `CharacterEmotionChanged`

| 字段                    | 类型         | 说明                            |
| --------------------- | ---------- | ----------------------------- |
| `CharacterId`         | `string`   | 角色标识符                         |
| `情绪`                  | `string`   | 来自 Convai 分类体系的情绪标签，例如 `“喜悦”` |
| `强度`                  | `int`      | 原始强度值；范围 1–3                  |
| `NormalizedIntensity` | `float`    | 归一化到 0.0–1.0 的强度              |
| `IsNeutral`           | `bool`     | 当角色回到中性状态时为真                  |
| `IsHighIntensity`     | `bool`     | 对于高强度情绪为真                     |
| `IsLowIntensity`      | `bool`     | 对于低强度情绪为真                     |
| `时间戳`                 | `DateTime` | 事件的 UTC 时间                    |

#### `CharacterReady`

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

参见 [角色身份与寻址](/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`     | 当回合因玩家打断而结束时为真 |
| `时间戳`            | `DateTime` | 回合完成时的 UTC 时间  |

#### `CharacterActionReceived`

| 字段            | 类型                                   | 说明            |
| ------------- | ------------------------------------ | ------------- |
| `CharacterId` | `string`                             | 角色标识符         |
| `动作`          | `IReadOnlyList<ConvaiActionCommand>` | 此回合的场景内动作有序列表 |
| `时间戳`         | `DateTime`                           | 事件的 UTC 时间    |

#### `LlmNoResponseReceived`

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

#### `PlayerSpeakingStateChanged`

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

#### `FinalUserTranscriptionReceived`

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

#### `VadSttStateChanged`

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

***

### 支持类型

#### `SpeakerInfo` 结构体

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

#### `SpeakerType` 枚举

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

***

### 检视面板中继 vs. C# 事件——何时选择

使用 **检视面板中继组件** 当：

* 在检视面板中连接 Animator 参数、UI 组件或 Audio 源
* 逻辑简单、基于组件且无分支
* 优先考虑零代码的拖放连接

使用 **C# 订阅** ，通过 `ConvaiEvents` 当：

* 按……过滤 `CharacterId` 在运行时动态地
* 处理程序具有条件逻辑或会调用 async / 协程方法
* 用于场景中所有角色事件的单一处理程序

使用 **直接 `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` 已关闭且未分配角色                           | 启用 **Auto Resolve Character** 或分配 `ConvaiCharacter` 字段 |
| 转录 UI 显示重复内容                                       | 同时订阅了中继和 `ConvaiEvents.OnCharacterTranscriptReceived` 相同事件 | 每个功能只用一种方式——中继或 C# 订阅，不要两者都用                           |
| `CharacterIdFilter` 没有效果                           | 过滤器包含多余空格或大小写错误                                            | 比较不区分大小写；请检查首尾空格                                       |
| `OnFinalCharacterTranscriptReceived` 从未触发          | `FinalOnly = false` 而转录从未标记为 `IsFinal = true`              | 检查 `ConvaiCharacter.EnableRemoteAudioOnStart`；角色必须完全连接 |
| `OnEmotionChanged` 触发但 `NormalizedIntensity` 始终为 0 | Convai 控制台中未为该角色启用情绪功能                                     | 在角色的 Convai 配置中启用情绪输出                                  |
| `OnRemoteAudioEnabledChanged` 从未触发                 | 订阅了中继而不是以下角色上的 C# 事件： `ConvaiCharacter` 直接                 | 订阅 `character.OnRemoteAudioEnabledChanged` ——此事件不在中继上  |

***

### 下一步

完成角色事件接线后，请查看 [转录 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md) 以获取拉取式时间线访问，或查看 [角色与玩家 API](/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.