> 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 组件上的情绪属性、函数、事件和枚举参考——包括类型、默认值和参数细节。

受支持的、由分数驱动的情绪蓝图节点和属性位于 `UConvaiChatbotComponent` （在「细节」面板和「组件」列表中显示为 `Convai Chatbot` ）。枚举 `EBasicEmotions` 和 `EEmotionIntensity` 可在蓝图中所有使用情绪值的地方使用。

### 属性

#### LockEmotionState

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

当 `true`时，会丢弃来自服务器的情绪更新。在服务器路径上， `On Emotion State Changed` 不会 **触发** 锁定期间。将其设为 `false` 即可恢复接收由服务器驱动的情绪更新和事件。

`Force Set Emotion` 和 `Reset Emotion State` 在锁定期间仍会更新状态并触发事件。

#### EmotionOffset

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

收到由服务器驱动的更新时，会在分数被限制到 `0.0`–`1.0`之前，将此数值加到所有计算出的情绪分数上。源代码注释说明了一个实用范围： `-1.0` 到 `1.0`。正值会增强感知到的强度；负值会减弱强度。此属性 **不** 适用于通过 `Force Set Emotion`.

### 设置的分数。

#### 函数

```cpp
Force Set Emotion
```

void ForceSetEmotion(EBasicEmotions BasicEmotion, EEmotionIntensity Intensity, bool ResetOtherEmotions = false) `无需等待服务器更新，即可在蓝图中覆盖当前情绪状态。应用的分数等于所选级别的` EEmotionIntensity [EEmotionIntensity](#eemotionintensity) 表中的乘数）。 `EmotionOffset` 不会应用。

| 参数                   | 类型                  | 说明                      |
| -------------------- | ------------------- | ----------------------- |
| `BasicEmotion`       | `EBasicEmotions`    | 要设置的情绪类别                |
| `Intensity`          | `EEmotionIntensity` | 强度级别——决定所应用的分数乘数        |
| `ResetOtherEmotions` | `bool`              | 当 `true`时，会先将其他所有情绪分数归零 |

`Force Set Emotion` 会触发 `On Emotion State Changed` ，触发时机紧接在状态更新之后。

#### 获取情绪分数

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

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

在服务器路径中，分数的计算方式为 `server scale / 3 + EmotionOffset`，并限制在 `0.0`–`1.0`范围内。在 `Force Set Emotion` 路径中，分数则使用 `EEmotionIntensity` 乘数。

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

#### 重置情绪状态

```cpp
void ResetEmotionState()
```

将 `EmotionState`中的所有情绪分数归零。使用此方法可使角色恢复中性表情，例如在过场动画结束时或切换到新场景时。

`Reset Emotion State` 会在状态归零后触发 `On Emotion State Changed` 。

### 事件

#### 情绪状态更改时

| 字段   | 值                          |
| ---- | -------------------------- |
| 显示名称 | `On Emotion State Changed` |
| 类型   | `BlueprintAssignable` 委托   |
| 类别   | `Convai`                   |

当服务器更新情绪状态时（即 `LockEmotionState` 为 `false`时），或通过 `Force Set Emotion`或 `Reset Emotion State`更新情绪状态时，会在游戏线程上触发。在角色的蓝图中绑定此事件，即可响应表情变化。

在 **不** 会因服务器驱动的更新而触发，前提是 `LockEmotionState` 是 `true`.

**签名：**

| 输出引脚      | 类型                         | 说明                                                                 |
| --------- | -------------------------- | ------------------------------------------------------------------ |
| `聊天机器人组件` | `UConvaiChatbotComponent*` | 情绪状态发生变化的聊天机器人组件                                                   |
| `交互玩家组件`  | `UConvaiPlayerComponent*`  | 始终 `null` 在当前插件的所有路径中（服务器驱动、 `强制设置情绪`，以及 `重置情绪状态`）。使用前请对该引脚进行空值检查。 |

### 枚举引用

#### EBasicEmotions

{% hint style="info" %}
`期待` 在 C++ 枚举中存在，但标记为 `隐藏` 且未在蓝图中公开。请勿在蓝图图表中依赖它。
{% endhint %}

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

#### EEmotionIntensity

| 枚举值           | 蓝图显示名称 | 分数乘数（`强制设置情绪` 专用） |
| ------------- | ------ | ----------------- |
| `LessIntense` | `较弱`   | `0.25`            |
| `基础`          | `基础`   | `0.60`            |
| `MoreIntense` | `较强`   | `1.00`            |

这些乘数仅在调用 `强制设置情绪` 时应用。服务器驱动的分数使用 `server scale / 3 + EmotionOffset` 而是。

### 相关页面

{% content-ref url="/pages/c3081281b873e1a1b00439a147d3db6877743003" %}
[情绪系统的工作原理](https://docs.convai.com/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" %}
[情绪示例](https://docs.convai.com/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.
