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

# Quick Start

## Get Your First Emotionally Reactive NPC Working

This guide walks you through the fastest path to a working emotion setup. You will attach the controller, assign the bundled sample profile, and see your character's face respond to live AI emotion signals in Play Mode — with no configuration required upfront.

{% hint style="info" %}
**Prerequisites**

* A Unity scene with a `ConvaiCharacter` component already set up and working (the character should respond to speech).
* Your Convai API key is configured in **Tools → Convai → Configuration**.
  {% endhint %}

## Step-by-Step Setup

{% 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=""><figcaption></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).                                                      |

{% hint style="info" %}
The bundled profile is configured for **Reallusion** characters out of the box. If your character uses a different rig, the pipeline will still run — but you will need to update the blendshape names in the profile slots to match your character. See Emotion Profile for how to do this.
{% endhint %}
{% 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=""><figcaption></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.

{% hint style="success" %}
**Expected result:** The NPC's facial expression changes as the conversation develops — a subtle smile during warm exchanges, a more serious expression during difficult topics. If you are using a Reallusion character with the default rig, you will see the shapes activate on the character's face immediately.
{% endhint %}
{% endstep %}
{% endstepper %}

## What Just Happened

When you spoke to the character, the following occurred automatically:

1. The Convai backend processed your speech and decided on an emotional state for the character.
2. It sent a short message containing a label such as `"happy"` and an intensity value from 1 to 3.
3. `ConvaiEmotionController` received this, resolved `"happy"` to the canonical label `"joy"` via the taxonomy, and smoothed the intensity score over time.
4. The profile's pre-configured blendshape slots wrote the smoothed score to the character's facial blendshapes every frame.
5. `EmotionReading.Current` on the controller reflected the live state throughout.

All of this runs automatically for the lifetime of the session.

## Using a Non-Reallusion Character

If your character has different blendshape names, open the duplicated profile and update the **Blendshape Names** field in each slot to match your character's shapes. The slot structure and all other settings remain valid — only the shape names need to change.

For a walkthrough of how slots work and how to configure them for any rig, see Emotion Profile and Output Bindings.

{% hint style="info" %}
Mapping blendshapes for a new character can be done quickly with the help of an AI coding assistant. Share your character's blendshape list and ask it to generate the slot configuration — the slot format is straightforward and maps directly to the Inspector fields.
{% endhint %}

## Next Steps

* **Adapt the profile to your own rig** → [Emotion Profile](/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/emotion/emotion-profile.md)
* **Understand how slot mappings work** → [Output Bindings](/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/emotion/output-bindings.md)
* **Customise the emotion vocabulary** → [Emotion Taxonomy](/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/emotion/emotion-taxonomy.md)
* **Read emotion state or trigger overrides from script** → [Scripting API](/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/emotion/scripting-api-reference.md)
* **Something not working?** → [Troubleshooting & Diagnostics](/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/emotion/troubleshooting-and-diagnostics.md)

## Conclusion

You now have a complete emotion pipeline running on your character — server-driven, smoothed, and reacting to live AI decisions. If your character is Reallusion-based, expressions are already active. If not, update the blendshape names in the profile and the rest of the configuration carries over unchanged.


---

# 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/unity-plugin-beta-overview/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.