心情

从代码中设置和清除 Convai 角色的常驻心情，并了解心情与短暂情绪反应的区别。

调用 SetMood 和 ClearMood 在 ConvaiEmotionController 要从你自己的代码中改变角色的静止心境，而不受 Convai 响应在那一刻驱动的任何瞬时情绪影响。只在 Emotion 正在运行，并且你希望角色的心境反映对话之外发生的事情——任务结果、游戏事件、脚本化剧情节点——时使用此页面。

---

心境与情绪

ConvaiEmotionController 每一帧都会跟踪两个独立的值，而本页讲的是第二个：

• 瞬时情绪（CurrentResolvedEmotion / CurrentNormalizedIntensity）是角色对最近一句话的反应。Convai 的响应驱动它，并会在反应消退后衰减回下方的心境。
• 心境（CurrentMoodLabel / CurrentMoodScore）是角色在反应之间保持的静止状态。它由角色的人格基线决定，或者通过你自己的代码经由 SetMood设置，并会跨回合持续，直到有东西改变它。

角色可以在 惊讶 时主动反应，同时底下保持一个 喜悦 心境——瞬时状态永远不会覆盖心境，而心境也永远不会显示为活动情绪。参见 情绪系统的工作原理 以查看这两个通道所在的完整流程。

---

设置心境

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

public class QuestMoodExample : MonoBehaviour
{
    [SerializeField] private GameObject character;
    private ConvaiEmotionController _emotionController;

    private void Awake() => _emotionController = character.GetComponent<ConvaiEmotionController>();

    public void OnQuestCompleted()
    {
        // 在 2 秒内平滑进入更快乐的静息心境。
        _emotionController.SetMood("joy", intensity: 0.5f, transitionSeconds: 2f);
    }
}

SetMood(string label, float intensity, float transitionSeconds = 1.5f) 解析为 label 通过角色的活动 EmotionTaxonomyAsset 并在 transitionSeconds。空标签或无法识别的标签，或者一个 强度 的 0 小于或等于 0 的值，都会将角色转换为无心境，而不是抛出异常——无法识别的标签还会额外记录一条带其名称的警告。 TryResolveEmotionLabel 可让你在调用 SetMood之前验证标签，因此调用方可以带着可操作的消息失败，而不是静默地落到无心境。

---

清除心境

// 通过默认的 1.5 秒过渡返回作者设定的基线。
_emotionController.ClearMood();

ClearMood(float transitionSeconds = 1.5f) 会将心境过渡回角色的 撰写的基线 ——不一定是 0。撰写的基线是角色自己的静止心境覆盖值，当它设置在 ConvaiEmotionController 检查器中时如此，否则就是 ConvaiEmotionProfile的 Persona Baseline。调用 ClearMood 以结束一个 SetMood 覆盖；再次调用 SetMood 会无须先清除就直接交叉淡入到新的目标。

会话重置——断开连接或出错——总会丢弃运行时的 SetMood 覆盖，并将心境直接重置回撰写的基线，不受下方所述任何内容影响。

---

Convai 发来的心境命令

Convai 的响应也可以自行改变角色的心境——像心境或反应提示这样的动作会通过 MoodCommandHandlerAdapter路由到该角色，这是 Convai 随着 ConvaiEmotionController 自动添加的基础设施。它会调用同一个 SetMood 你在自己的代码中会调用的 角色动作 ，因此脚本化的心境变更和由 Convai 驱动的变更一旦到达控制器，行为完全相同。参见

---

与锁定和覆盖的交互

LockEmotion/UnlockEmotion 和 SetEmotionOverride/ClearEmotionOverride 都作用于瞬时情绪通道，而不是心境——当锁定或覆盖处于活动状态时，心境仍会独立变化。

• LockEmotion(label, intensity) 会将瞬时情绪锁定在固定值，忽略 Convai 的响应，直到 UnlockEmotion() 将其释放。 SetMood/ClearMood 在情绪被锁定时，它们的工作方式完全相同。
• SetEmotionOverride(label, score) 设置一次性的瞬时值，不同于锁定，它不需要 UnlockEmotion ——调用 ClearEmotionOverride() 即可释放它，并让 Convai 的响应再次驱动瞬时通道。 SetMood/ClearMood 无论哪种方式都不受影响。

因为心境和瞬时情绪是分开的通道，所以用 LockEmotion 锁定一个问候表情，再用 SetMood 在同一脚本中设置心境，二者绝不会冲突——一个决定此刻脸上显示什么，另一个决定它会回落到什么。

---

响应心境变化

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

public class MoodLogger : MonoBehaviour
{
    [SerializeField] private GameObject character;
    private ConvaiEmotionController _emotionController;

    private void Awake() => _emotionController = character.GetComponent<ConvaiEmotionController>();

    private void OnEnable() => _emotionController.MoodChanged += HandleMoodChanged;
    private void OnDisable() => _emotionController.MoodChanged -= HandleMoodChanged;

    private void HandleMoodChanged(string label, float score) =>
        Debug.Log($"角色的静止心境已更改为 {label} @ {score:F2}");
}

MoodChanged 每次标签过渡只触发一次——涵盖撰写的基线首次生效、 SetMood/ClearMood，以及由 Convai 驱动的心境命令——并携带新的标签及其 CurrentMoodScore。在指向同一标签的交叉淡入仍在进行时，它绝不会因为仅数值变化而触发。

---

下一步

情绪系统的工作方式情绪脚本 API