使用示例

实际场景示例，展示情感系统的运行：危险响应、脚本化问候、自适应分支、分析和创作工作流。

实践中的情绪：示例场景

下面的示例展示了 Emotion 系统的配置与脚本 API 如何结合起来满足真实的应用需求。每个场景都是独立的：先描述 Inspector 设置，然后给出完成该行为所需的任何运行时代码。配置文件和绑定字段的参考见 Emotion Profile 和 Output Bindings；完整的脚本接口见 Scripting API。

场景 1 — 安全培训：动态危险响应

情境： 一名讲师 NPC 引导受训者完成火灾疏散模拟。当受训者进入标记的危险区域时，讲师的表情应迅速转为恐惧或紧迫，以强化情境的严重性。当受训者离开该区域时，表情恢复为服务器驱动的状态。

配置文件设置

打开 ConvaiEmotionProfile 分配给讲师 NPC 并调整：

• lerpSpeed → 12 — 快速上升，使恐惧表情不延迟地出现。
• microBurstOvershoot → 1.6 — 明显的爆发使过渡在视觉上更有冲击力。
• microBurstDuration → 0.2 秒 — 表情稳定前的短暂爆发。

输出绑定

添加一个插槽到 Blendshape Binding:

emotionLabel	blendshapeNames	weightMultiplier	fullBlendshapeWeight
fear	Brow_Raise_Inner_L, Brow_Raise_Inner_R, Eye_Wide_L, Eye_Wide_R	1.0	85

运行时脚本

using Convai.Modules.Emotion.Components;
using UnityEngine;

public sealed class HazardZoneTrigger : MonoBehaviour
{
    [SerializeField] private ConvaiEmotionController instructorEmotion;

    private void OnTriggerEnter(Collider other)
    {
        if (other.CompareTag("Trainee"))
            instructorEmotion.SetEmotionOverride("fear", 0.9f);
    }

    private void OnTriggerExit(Collider other)
    {
        if (other.CompareTag("Trainee"))
            instructorEmotion.ClearEmotionOverride();
    }
}

SetEmotionOverride 会在服务器当前发送的任何内容之上叠加恐惧分数。累加器会在配置的 lerpSpeed处将其融合，因此覆盖会快速但自然地到达。 ClearEmotionOverride 在触发器退出时调用，让服务器可以重新获得完全控制权。

---

场景 2 — 员工入职：锁定欢迎表情

情境： 一名迎宾 NPC 站在入职模拟的入口处。在欢迎流程期间——也就是受训者开始说话之前——无论连接握手期间后端可能发送什么情绪信号，这个角色都应始终显得热情且平易近人。

运行时脚本

using Convai.Modules.Emotion.Components;
using UnityEngine;

public sealed class WelcomeSequenceController : MonoBehaviour
{
    [SerializeField] private ConvaiEmotionController greeterEmotion;

    private void Start()
    {
        // 从第一帧起保持温和、欢迎的表情
        greeterEmotion.LockEmotion("joy", 0.65f);
    }

    public void OnWelcomeSequenceComplete()
    {
        // 释放锁定，让角色自然地对对话作出反应
        greeterEmotion.UnlockEmotion();
    }
}

锁定的强度为 0.65 会产生一个明显但不过分夸张的微笑——适合专业场景。 UnlockEmotion 会在模拟切换到开放对话时调用，此时角色开始响应实时 AI 信号。

---

场景 3 — 自适应评估：具备情绪感知的分支逻辑

情境： 医疗沟通评估中的一名虚拟患者 NPC，在受训者的回答被视为轻慢时会变得不安。导演脚本会监视该 NPC 的情绪状态，如果检测到持续的不安，就将场景分支到缓和冲突的路径。

运行时脚本

using Convai.Domain.Embodiment.Readings;
using Convai.Modules.Emotion.Components;
using UnityEngine;
using UnityEngine.Events;

public sealed class EmotionBranchDirector : MonoBehaviour
{
    [SerializeField] private ConvaiEmotionController patientEmotion;
    [SerializeField] private float distressThreshold = 0.6f;
    [SerializeField] private float sustainedDistressSeconds = 4f;
    [SerializeField] private UnityEvent onDistressBranchTriggered;

    private bool _branchTriggered;

    private void Update()
    {
        if (_branchTriggered) return;

        EmotionReading reading = patientEmotion.Current;

        bool isSadOrFearful = reading.DominantLabel is "sadness" or "fear"
                              && reading.DominantScore >= distressThreshold;

        if (isSadOrFearful && reading.DominantHoldSeconds >= sustainedDistressSeconds)
        {
            _branchTriggered = true;
            onDistressBranchTriggered.Invoke();
        }
    }
}

DominantHoldSeconds 用于跟踪当前主导情绪被持续保持了多久。将它与分数阈值一起使用，可避免短暂峰值触发分支——只有真正持续的不安才会推动场景前进。

---

场景 4 — 会话分析：记录情绪弧线

情境： 一个培训平台需要记录 AI 角色在会话中经历的每一次情绪变化，包括原始服务器标签和强度，以便讲师在会话后报告中回顾对话的情绪弧线。

运行时脚本

using Convai.Domain.DomainEvents.Runtime;
using Convai.Runtime.Components;
using System.Collections.Generic;
using UnityEngine;

public sealed class EmotionSessionLogger : MonoBehaviour
{
    [SerializeField] private ConvaiManager convaiManager;

    private readonly List<string> _emotionLog = new();

    private void OnEnable()
    {
        convaiManager.Events.OnCharacterEmotionChanged += HandleEmotionChanged;
    }

    private void OnDisable()
    {
        convaiManager.Events.OnCharacterEmotionChanged -= HandleEmotionChanged;
    }

    private void HandleEmotionChanged(CharacterEmotionChanged e)
    {
        string entry = $"[{e.Timestamp:HH:mm:ss.fff}] {e.CharacterId}: {e.Emotion} (scale {e.Intensity})";
        _emotionLog.Add(entry);
        Debug.Log(entry);
    }

    public IReadOnlyList<string> GetLog() => _emotionLog;
}

OnCharacterEmotionChanged 会在来自后端的每一个情绪信号上触发，且发生在控制器对其进行平滑处理之前。这让分析代码可以访问原始信号，而不是插值后的视觉状态，这对会话回顾更有意义。

---

场景 5 — 无代码 UI：由 Inspector 驱动的情绪显示

情境： 一位不会编程的人希望在角色当前情绪变化时更新显示该情绪的 UI 标签，而无需编写任何代码。

设置

1. 添加 ConvaiCharacterEventRelay 到 NPC 根 GameObject（Convai → Events → Convai Character Event Relay）。它会自动解析同一对象上的 ConvaiCharacter 。
2. 在 On Emotion Changed Unity Event 列表中，点击 +.
3. 将你的 UI Text （或 TMP_Text）组件拖到对象字段中。
4. 从函数下拉菜单中选择 Text → string text （或 TMP_Text → string text).

现在，每当角色的情绪发生变化时，来自 Emotion 属性的 CharacterEmotionRelayData 会直接写入标签——无需代码。

ConvaiCharacterEventRelay 会传递原始服务器标签（例如 "happy"）。如果你需要更友好的显示名称（例如 "Joy" 而不是 "happy"），添加一个小型格式化脚本，将原始标签映射为显示字符串，或者在 UnityEvent 目标方法中对字符串进行后处理。

---

场景 6 — 内容创作：在编辑器中预览表情

情境： 你已经为一个新角色添加了 blendshape 插槽，并希望在进入 Play Mode 之前确认每种情绪是否将正确的形状驱动到正确的权重。

步骤

1. 选择 NPC 的根 GameObject。
2. 在 ConvaiEmotionController 组件上，启用 Lock Emotion.
3. 将 Locked Emotion Label 设置为你想要预览的规范标签（例如 "anger").
4. 将 Locked Intensity 设为 1.0.

Scene 视图会立即更新——blendshape 会在 Edit Mode 中应用，因为 ConvaiEmotionController 是 [ExecuteAlways]。在你的分类体系中切换这些标签，以可视化方式验证每个插槽的映射。

将 Lock Emotion 改回 false ，然后再发布构建。该字段是序列化保存的——如果它保持启用，角色在生产环境中将忽略所有后端情绪信号。

结论

这六个场景涵盖了最常见的情绪集成模式——从危险触发器和脚本锁定，到无代码 Unity Event 连接和编辑器创作工作流。关于上面配置设置所用参数的完整参考，请参见 Emotion Profile。关于完整的脚本接口，请参见 Scripting API。如果任何场景没有产生预期结果，请参见 故障排除.