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

# Emotion Blueprint reference

The supported score-driven emotion Blueprint nodes and properties live on `UConvaiChatbotComponent` (displayed as `Convai Chatbot` in the Details panel and Components list). The enums `EBasicEmotions` and `EEmotionIntensity` are available throughout Blueprint wherever emotion values are used.

### Properties

#### LockEmotionState

| Field      | Value                                |
| ---------- | ------------------------------------ |
| Type       | `bool`                               |
| Category   | `Convai \| Emotion`                  |
| Access     | `BlueprintReadWrite`, `EditAnywhere` |
| Replicated | Yes                                  |
| Default    | `false`                              |

When `true`, incoming emotion updates from the server are discarded. On the server path, `On Emotion State Changed` does **not** fire while locked. Set to `false` to resume receiving server-driven emotion updates and events.

`Force Set Emotion` and `Reset Emotion State` still update state and fire the event while locked.

#### EmotionOffset

| Field    | Value                                |
| -------- | ------------------------------------ |
| Type     | `float`                              |
| Category | `Convai`                             |
| Access   | `BlueprintReadWrite`, `EditAnywhere` |
| Default  | `0.0`                                |

Shifts all computed emotion scores by this amount when a server-driven update arrives, before scores are clamped to `0.0`–`1.0`. The source comment describes a useful range of `-1.0` to `1.0`. A positive value amplifies perceived intensity; a negative value diminishes it. Does **not** apply to scores set via `Force Set Emotion`.

### Functions

#### Force Set Emotion

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

Overrides the current emotion state from Blueprint without waiting for a server update. The score applied equals the `EEmotionIntensity` multiplier for the chosen level (see the [EEmotionIntensity](#eemotionintensity) table). `EmotionOffset` is not applied.

| Parameter            | Type                | Description                                               |
| -------------------- | ------------------- | --------------------------------------------------------- |
| `BasicEmotion`       | `EBasicEmotions`    | The emotion category to set                               |
| `Intensity`          | `EEmotionIntensity` | Intensity level — determines the score multiplier applied |
| `ResetOtherEmotions` | `bool`              | When `true`, zeros all other emotion scores first         |

`Force Set Emotion` fires `On Emotion State Changed` immediately after updating the state.

#### Get Emotion Score

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

Returns the current score for a single emotion category as a `float` in the range `0.0`–`1.0`. Returns `0.0` if the emotion has no current score entry.

On the server path, scores are computed as `server scale / 3 + EmotionOffset`, clamped to `0.0`–`1.0`. On the `Force Set Emotion` path, scores use the `EEmotionIntensity` multiplier instead.

| Parameter | Type             | Description                   |
| --------- | ---------------- | ----------------------------- |
| `Emotion` | `EBasicEmotions` | The emotion category to query |

#### Reset Emotion State

```cpp
void ResetEmotionState()
```

Zeros all emotion scores in `EmotionState`. Use this to return the character to a neutral expression — for example, at the end of a cutscene or when transitioning to a new scene.

`Reset Emotion State` fires `On Emotion State Changed` after zeroing the state.

### Events

#### On Emotion State Changed

| Field        | Value                          |
| ------------ | ------------------------------ |
| Display name | `On Emotion State Changed`     |
| Type         | `BlueprintAssignable` delegate |
| Category     | `Convai`                       |

Fires on the game thread when the emotion state is updated by the server (when `LockEmotionState` is `false`), by `Force Set Emotion`, or by `Reset Emotion State`. Bind to this event in the character's Blueprint to react to expression changes.

Does **not** fire for server-driven updates while `LockEmotionState` is `true`.

**Signature:**

| Output pin                     | Type                       | Description                                                                                                                                             |
| ------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Chatbot Component`            | `UConvaiChatbotComponent*` | The chatbot component whose emotion state changed                                                                                                       |
| `Interacting Player Component` | `UConvaiPlayerComponent*`  | Always `null` in the current plugin on every path (server-driven, `Force Set Emotion`, and `Reset Emotion State`). Null-check this pin before using it. |

### Enum reference

#### EBasicEmotions

{% hint style="info" %}
`Anticipation` exists in the C++ enum but is marked `Hidden` and is not exposed in Blueprint. Do not rely on it in Blueprint graphs.
{% endhint %}

| Enum value | Blueprint display name |
| ---------- | ---------------------- |
| `Joy`      | `Happy`                |
| `Trust`    | `Calm`                 |
| `Fear`     | `Afraid`               |
| `Surprise` | `Surprise`             |
| `Sadness`  | `Sad`                  |
| `Disgust`  | `Bored`                |
| `Anger`    | `Angry`                |

#### EEmotionIntensity

| Enum value    | Blueprint display name | Score multiplier (`Force Set Emotion` only) |
| ------------- | ---------------------- | ------------------------------------------- |
| `LessIntense` | `Less Intense`         | `0.25`                                      |
| `Basic`       | `Basic`                | `0.60`                                      |
| `MoreIntense` | `More Intense`         | `1.00`                                      |

These multipliers apply only when `Force Set Emotion` is called. Server-driven scores use `server scale / 3 + EmotionOffset` instead.

### Related pages

{% content-ref url="/pages/rhrJSUDsxJtlVoC5RBxt" %}
[How the emotion system works](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/emotion/how-the-emotion-system-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/b9ztYs8XT0CsQtGnPjeC" %}
[Emotion examples](/api-docs/plugins-and-integrations/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 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/plugins-and-integrations/convai-unreal-engine-plugin/features/emotion/emotion-blueprint-reference.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.