> 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-unity-sdk/features/emotion/quick-start.md).

# Emotion quick start

We will attach the Emotion Controller to an NPC, assign the bundled sample profile, and see the character's face react to live AI emotion signals in Play Mode. No custom assets are required for the initial setup.

### Prerequisites

Before starting, verify:

* [ ] A `ConvaiCharacter` is in the scene and responds to speech in Play Mode

### Set up the Emotion Controller

{% stepper %}
{% step %}

#### Add the Emotion Controller

Select your NPC's root GameObject in the Hierarchy. In the Inspector, click **Add Component** and search for **Emotion Controller**, or navigate to **Convai → Embodiment → Emotion Controller**.

The component appears with a **Profile** field that is currently empty.

<figure><img src="/files/3YTosc0pKCqlj1dPBsk9" alt="Unity Inspector showing ConvaiEmotionController added to the NPC root GameObject with the Profile field empty, ready for a profile asset to be assigned"><figcaption><p>ConvaiEmotionController added to the NPC root — the Profile field is empty until an EmotionProfile asset is assigned in step 3. No blendshape mapping is active yet.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Locate the bundled sample profile

In the Project window, navigate to:

{% code overflow="wrap" %}

```
Packages / Convai SDK for Unity / SamplesShared / Resources / Embodiment / Modules / Emotion
```

{% endcode %}

You will find two assets:

| Asset                                 | Purpose                                                                                                                        |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `ConvaiSamplesShared_EmotionProfile`  | Pre-configured expression slots for Reallusion characters, with smoothing, micro-burst, and neutral alternation already tuned. |
| `ConvaiSamplesShared_EmotionTaxonomy` | The default emotion vocabulary, already referenced by the profile above.                                                       |
| {% endstep %}                         |                                                                                                                                |

{% step %}

#### Assign the profile

Drag `ConvaiSamplesShared_EmotionProfile` from the Project window into the **Profile** field on the `ConvaiEmotionController` component.

<figure><img src="/files/zqKwH6BqlZUxurttsc8X" alt="Unity Inspector showing ConvaiEmotionController with ConvaiSamplesShared_EmotionProfile assigned to the Profile field"><figcaption><p>ConvaiSamplesShared_EmotionProfile assigned — the controller is now configured with pre-tuned expression slots for Reallusion characters and will begin driving blendshapes as soon as Play Mode starts.</p></figcaption></figure>

{% hint style="warning" %}
The bundled asset is **read-only** — it lives inside the package. To adjust any settings, duplicate it first (**Ctrl+D** on Windows / **Cmd+D** on macOS), move the copy into your own `Assets/` folder, and assign the copy instead.
{% endhint %}
{% endstep %}

{% step %}

#### Enter Play Mode and speak

Press **Play**. Talk to the character using your configured microphone. As the AI responds, watch the `ConvaiEmotionController` in the Inspector — the **Current** reading updates live.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**Expected result:** The NPC's facial expression changes as the conversation develops. The **Current → Dominant Label** field shows the active emotion and **Current → Dominant Score** shows its smoothed intensity. If you are using a Reallusion character with the default rig, blendshapes activate on the character's face immediately.
{% endhint %}

### How it works

When you spoke to the character, `ConvaiEmotionController` received the backend's emotion signal, resolved it through the taxonomy (mapping `"happy"` to `"joy"`), smoothed the intensity score over time, and wrote the score to the character's facial blendshapes every frame. For a full explanation of every stage, see [How the emotion system works](/api-docs/plugins-and-integrations/convai-unity-sdk/features/emotion/how-the-emotion-system-works.md).

The bundled profile is configured for Reallusion characters. For other rigs, duplicate the profile and update the blendshape names in each slot to match your character's shapes. See [Emotion profile](/api-docs/plugins-and-integrations/convai-unity-sdk/features/emotion/emotion-profile.md) and [Emotion output bindings](/api-docs/plugins-and-integrations/convai-unity-sdk/features/emotion/output-bindings.md) for how to configure slots for any rig.

### Next steps

The quick start runs end-to-end with the bundled profile. These pages cover tuning and extending the setup.

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

{% content-ref url="/pages/4kPK7vkbjtuDa9qfc75O" %}
[Emotion profile](/api-docs/plugins-and-integrations/convai-unity-sdk/features/emotion/emotion-profile.md)
{% endcontent-ref %}

{% content-ref url="/pages/mqwNGzveKocvvR9sOhts" %}
[Emotion output bindings](/api-docs/plugins-and-integrations/convai-unity-sdk/features/emotion/output-bindings.md)
{% endcontent-ref %}

{% content-ref url="/pages/OM0Nzbb46ldsnhmYvu6a" %}
[Emotion scripting API](/api-docs/plugins-and-integrations/convai-unity-sdk/features/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/plugins-and-integrations/convai-unity-sdk/features/emotion/quick-start.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.