运行时设置 API

IConvaiRuntimeSettingsService 的参考——从代码中读取当前设置、应用补丁、响应变更并重置为默认值。

IConvaiRuntimeSettingsService 是内置设置面板下方的脚本层。任何脚本都可以读取当前设置快照、以原子方式应用补丁、订阅变更事件，并控制公开哪些转录模式——即使场景中没有该面板。

通过以下方式访问该服务 ConvaiManager:

ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings);

IConvaiRuntimeSettingsService

成员	类型	说明
当前	ConvaiRuntimeSettingsSnapshot	所有当前设置值的不可变快照
SupportedTranscriptModes	IReadOnlyCollection<ConvaiTranscriptMode>	当前注册为可供选择的转录模式
已更改	event Action<ConvaiRuntimeSettingsChanged>	每当任意设置发生变化时触发
Apply(ConvaiRuntimeSettingsPatch patch)	ConvaiRuntimeSettingsApplyResult	以原子方式应用一个或多个设置。补丁中留空的字段 null 保持不变
ResetToDefaults()	ConvaiRuntimeSettingsApplyResult	将所有设置重置为项目默认值
SetSupportedTranscriptModes(IReadOnlyCollection<ConvaiTranscriptMode> modes)	void	替换可供选择的转录模式集合。用于限制设置面板下拉框公开的模式

ConvaiRuntimeSettingsSnapshot

由以下方法返回的不变结构体 当前 并包含在应用结果和变更事件中。所有字段都反映快照生成时刻的状态。

字段	类型	说明
PlayerDisplayName	string	转录气泡中显示的当前玩家显示名
TranscriptEnabled	bool	是否启用转录 UI
NotificationsEnabled	bool	是否启用场景内通知弹窗
PreferredMicrophoneDeviceId	string	首选麦克风输入的设备 ID
TranscriptMode	ConvaiTranscriptMode	当前转录显示模式（聊天 或 字幕)

ConvaiRuntimeSettingsPatch

传入 Apply()。任何留空的字段 null 在应用后保持不变。

字段	类型	说明
PlayerDisplayName	string	设置新的玩家显示名。 null = 无更改
TranscriptEnabled	bool?	启用或禁用转录 UI。 null = 无更改
NotificationsEnabled	bool?	启用或禁用通知。 null = 无更改
PreferredMicrophoneDeviceId	string	设置首选麦克风设备 ID。 null = 无更改
TranscriptMode	ConvaiTranscriptMode?	切换转录显示模式。 null = 无更改

ConvaiRuntimeSettingsApplyResult

由以下内容返回 Apply() 是位于 ResetToDefaults().

字段	类型	说明
Success	bool	true 如果应用操作成功
快照	ConvaiRuntimeSettingsSnapshot	应用后的最终设置状态
AppliedMask	ConvaiRuntimeSettingsChangeMask	实际更改字段的位掩码
ValidationMessage	string	失败原因，当 Success == false。成功时为空

ConvaiRuntimeSettingsChanged

传递给 已更改 订阅者的负载。

字段	类型	说明
Previous	ConvaiRuntimeSettingsSnapshot	更改前的设置状态
当前	ConvaiRuntimeSettingsSnapshot	更改后的设置状态
Mask	ConvaiRuntimeSettingsChangeMask	指示哪些字段已更改的位掩码

ConvaiRuntimeSettingsChangeMask

A [Flags] 在以下位置使用的枚举 AppliedMask 是位于 ConvaiRuntimeSettingsChanged.Mask。通过按位与比较来检测特定更改。

值	说明
无	没有字段更改
PlayerDisplayName	玩家显示名已更改
TranscriptEnabled	转录已启用状态已更改
NotificationsEnabled	通知已启用状态已更改
PreferredMicrophoneDeviceId	麦克风选择已更改
TranscriptMode	转录模式已更改
全部	所有字段

面板中的转录模式限制

该 转录样式 设置面板中的下拉框仅显示在 SupportedTranscriptModes中注册的模式。默认情况下， SettingsPanelPresenter 将其初始化为 { ConvaiTranscriptMode.Chat } 仅此而已。

要在面板下拉框中公开其他模式，请在 SetSupportedTranscriptModes() 之前调用：

if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
{
    settings.SetSupportedTranscriptModes(new[]
    {
        ConvaiTranscriptMode.Chat,
        ConvaiTranscriptMode.Subtitle
    });
}

若要在完全绕过面板的情况下切换到字幕模式，请直接使用 Apply() ：

settings.Apply(new ConvaiRuntimeSettingsPatch
{
    TranscriptMode = ConvaiTranscriptMode.Subtitle
});

请参见 聊天和字幕模式 以了解完整的模式切换细节。

使用示例

读取当前设置

using Convai.Runtime.Components;
using Convai.Shared.Types;
using UnityEngine;

public class SettingsReader : MonoBehaviour
{
    private void Start()
    {
        if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
        {
            ConvaiRuntimeSettingsSnapshot current = settings.Current;
            Debug.Log($"玩家名称：{current.PlayerDisplayName}");
            Debug.Log($"转录已开启：{current.TranscriptEnabled}");
            Debug.Log($"模式：{current.TranscriptMode}");
        }
    }
}

应用设置补丁

if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
{
    var result = settings.Apply(new ConvaiRuntimeSettingsPatch
    {
        PlayerDisplayName = "Dr. Kaan",
        TranscriptEnabled = true,
        TranscriptMode = ConvaiTranscriptMode.Subtitle
    });

    如果 !result.Success
        Debug.LogWarning($"设置应用失败：{result.ValidationMessage}");
}

响应设置更改

using Convai.Runtime.Components;
using Convai.Shared.Abstractions;
using Convai.Shared.Types;
using UnityEngine;

public class SettingsChangeReactor : MonoBehaviour
{
    private IConvaiRuntimeSettingsService _settings;

    private void OnEnable()
    {
        if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out _settings))
            _settings.Changed += OnSettingsChanged;
    }

    private void OnDisable()
    {
        if (_settings != null)
            _settings.Changed -= OnSettingsChanged;
    }

    private void OnSettingsChanged(ConvaiRuntimeSettingsChanged changed)
    {
        if ((changed.Mask & ConvaiRuntimeSettingsChangeMask.PreferredMicrophoneDeviceId) != 0)
        {
            Debug.Log($"麦克风已更改为：{changed.Current.PreferredMicrophoneDeviceId}");
            ApplyMicrophoneChange(changed.Current.PreferredMicrophoneDeviceId);
        }

        if ((changed.Mask & ConvaiRuntimeSettingsChangeMask.PlayerDisplayName) != 0)
        {
            UpdatePlayerNameDisplay(changed.Current.PlayerDisplayName);
        }
    }
}

分析 — 跟踪设置更改

培训平台会记录学员何时更改其麦克风设备，以进行会话质量分析：

private void OnSettingsChanged(ConvaiRuntimeSettingsChanged changed)
{
    if ((changed.Mask & ConvaiRuntimeSettingsChangeMask.PreferredMicrophoneDeviceId) != 0)
    {
        AnalyticsTracker.LogEvent("microphone_changed", new Dictionary<string, object>
        {
            { "previous", changed.Previous.PreferredMicrophoneDeviceId },
            { "current", changed.Current.PreferredMicrophoneDeviceId }
        });
    }
}

故障排查

症状	可能原因	修复
Apply() 返回 Success == false	验证失败	检查 result.ValidationMessage 原因是
已更改 事件未触发	未订阅，或在设置更改后才订阅	在以下位置订阅 OnEnable 在会话开始前
ResetToDefaults() 未检查结果	忽略返回值	ResetToDefaults() 返回 ConvaiRuntimeSettingsApplyResult — 检查 result.Success 如果需要验证重置

下一步

设置面板聊天与字幕模式