> 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/embodiment/emotion/moods.md).

# 心情

通过代码设置和清除 Convai 角色的常驻心情，并了解心情与短暂的情绪反应有何不同。

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

***

### 心境与情绪

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

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

角色可以在 `惊讶` 时主动反应，同时底下保持一个 `喜悦` 心境——瞬时状态永远不会覆盖心境，而心境也永远不会显示为活动情绪。参见 [情绪系统的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/how-the-emotion-system-works.md) 以查看这两个通道所在的完整流程。

***

### 设置心境

```csharp
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`之前验证标签，因此调用方可以带着可操作的消息失败，而不是静默地落到无心境。

***

### 清除心境

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

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

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

***

### Convai 发来的心境命令

Convai 的响应也可以自行改变角色的心境——像心境或反应提示这样的动作会通过 `MoodCommandHandlerAdapter`路由到该角色，这是 Convai 随着 `ConvaiEmotionController` 自动添加的基础设施。它会调用同一个 `SetMood` 你在自己的代码中会调用的 [角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions.md) ，因此脚本化的心境变更和由 Convai 驱动的变更一旦到达控制器，行为完全相同。参见

***

### 与锁定和覆盖的交互

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

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

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

***

### 响应心境变化

```csharp
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`。在指向同一标签的交叉淡入仍在进行时，它绝不会因为仅数值变化而触发。

***

### 下一步

{% content-ref url="/pages/a169ddd3c944e6f42f2701922ad7b55a03ac789a" %}
[情绪系统的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/how-the-emotion-system-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/39d161d99d04e6ca98725c740d134ccb5eac9e73" %}
[Emotion 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/scripting-api.md)
{% endcontent-ref %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/moods.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.