> 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-unreal-engine-plugin/features/emotion/emotion-blueprint-reference.md).

# 情绪 Blueprint 参考

Convai Chatbot 组件上的情绪属性、函数、事件和枚举参考——包括类型、默认值和参数细节。

受支持的基于分数驱动的情绪 Blueprint 节点和属性位于 `UConvaiChatbotComponent` （显示为 `Convai 聊天机器人` 在详情面板和组件列表中）。这些枚举 `EBasicEmotions` 和 `EEmotionIntensity` 在整个 Blueprint 中，只要使用情绪值，就都可用。

### 属性

#### 锁定情绪状态

| 字段   | 值                                    |
| ---- | ------------------------------------ |
| 类型   | `bool`                               |
| 类别   | `Convai \| 情绪`                       |
| 访问权限 | `BlueprintReadWrite`, `EditAnywhere` |
| 已复制  | 是                                    |
| 默认   | `false`                              |

当 `true`，来自服务器的情绪更新会被丢弃。在服务器路径上， `情绪状态已变化` 不会 **不** 在锁定时触发。设置为 `false` 以恢复接收由服务器驱动的情绪更新和事件。

`强制设置情绪` 和 `重置情绪状态` 在锁定时仍会更新状态并触发事件。

#### 情绪偏移

| 字段   | 值                                    |
| ---- | ------------------------------------ |
| 类型   | `float`                              |
| 类别   | `Convai`                             |
| 访问权限 | `BlueprintReadWrite`, `EditAnywhere` |
| 默认   | `0.0`                                |

在服务器驱动的更新到达时，会将所有计算出的情绪分数按此数值平移，然后再将分数钳制到 `0.0`–`1.0`。源代码注释描述了一个有用的范围： `-1.0` 为 `1.0`。正值会增强感知到的强度；负值会减弱它。不会 **不** 应用到通过 `强制设置情绪`.

### 函数

#### 强制设置情绪

```cpp
void ForceSetEmotion(EBasicEmotions BasicEmotion, EEmotionIntensity Intensity, bool ResetOtherEmotions = false)
```

从 Blueprint 覆盖当前情绪状态，而无需等待服务器更新。应用的分数等于所选等级的 `EEmotionIntensity` 乘数（见 [EEmotionIntensity](#eemotionintensity) 表）。 `情绪偏移` 不适用。

| 参数       | 类型                  | 说明                    |
| -------- | ------------------- | --------------------- |
| `基础情绪`   | `EBasicEmotions`    | 要设置的情绪类别              |
| `强度`     | `EEmotionIntensity` | 强度等级——决定应用的分数乘数       |
| `重置其他情绪` | `bool`              | 当 `true`，先将所有其他情绪分数清零 |

`强制设置情绪` 触发 `情绪状态已变化` ，在更新状态后立即触发。

#### 获取情绪分数

```cpp
float GetEmotionScore(EBasicEmotions Emotion)
```

以 `float` 的范围内返回单个情绪类别的当前分数 `0.0`–`1.0`。返回 `0.0` （如果该情绪当前没有分数条目，则返回 0）。

在服务器路径上，分数计算为 `服务器缩放 / 3 + EmotionOffset`，并钳制到 `0.0`–`1.0`。在 `强制设置情绪` 路径上，分数则使用 `EEmotionIntensity` 乘数。

| 参数   | 类型               | 说明       |
| ---- | ---------------- | -------- |
| `情绪` | `EBasicEmotions` | 要查询的情绪类别 |

#### 重置情绪状态

```cpp
void ResetEmotionState()
```

将……中的所有情绪分数清零 `情绪状态`。使用此项可将角色恢复为中性表情——例如在过场动画结束时或切换到新场景时。

`重置情绪状态` 触发 `情绪状态已变化` 在清空状态后。

### 事件

#### 情绪状态已变化

| 字段   | 值                        |
| ---- | ------------------------ |
| 显示名称 | `情绪状态已变化`                |
| 类型   | `BlueprintAssignable` 委托 |
| 类别   | `Convai`                 |

当情绪状态由服务器更新时，会在游戏线程上触发（当 `锁定情绪状态` 是 `false`），由 `强制设置情绪`，或由 `重置情绪状态`。在角色的 Blueprint 中绑定此事件，以响应表情变化。

不会 **不** 在以下情况下触发服务器驱动的更新： `锁定情绪状态` 是 `true`.

**签名：**

| 输出引脚      | 类型                         | 说明                                                                   |
| --------- | -------------------------- | -------------------------------------------------------------------- |
| `聊天机器人组件` | `UConvaiChatbotComponent*` | 情绪状态已更改的聊天机器人组件                                                      |
| `交互玩家组件`  | `UConvaiPlayerComponent*`  | 始终 `null` 在当前插件中的每条路径上（服务器驱动、 `强制设置情绪`，以及 `重置情绪状态`）。在使用前请先检查此引脚是否为空。 |

### 枚举参考

#### EBasicEmotions

{% hint style="info" %}
`期待` 存在于 C++ 枚举中，但被标记为 `隐藏` 且未在 Blueprint 中公开。不要在 Blueprint 图中依赖它。
{% endhint %}

| 枚举值  | Blueprint 显示名称 |
| ---- | -------------- |
| `喜悦` | `开心`           |
| `信任` | `平静`           |
| `恐惧` | `害怕`           |
| `惊讶` | `惊讶`           |
| `悲伤` | `难过`           |
| `厌恶` | `无聊`           |
| `愤怒` | `生气`           |

#### EEmotionIntensity

| 枚举值    | Blueprint 显示名称 | 分数乘数（`强制设置情绪` 仅） |
| ------ | -------------- | ---------------- |
| `较低强度` | `较低强度`         | `0.25`           |
| `基础`   | `基础`           | `0.60`           |
| `较高强度` | `较高强度`         | `1.00`           |

这些乘数仅在 `强制设置情绪` 被调用时适用。服务器驱动的分数使用 `服务器缩放 / 3 + EmotionOffset` 替代。

### 相关页面

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

{% content-ref url="/pages/83566839f3555aa1855858bb1bc0c20ed5a973cc" %}
[情绪示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/emotion-examples.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 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-unreal-engine-plugin/features/emotion/emotion-blueprint-reference.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.