> 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/embodiment/emotion/emotion-taxonomy.md). # Emotion taxonomy Explains the built-in emotion set, how server labels map to it, and how to author a custom emotion taxonomy for a character. The taxonomy translates Convai's raw emotion strings into the canonical labels the rest of the Emotion module uses. When Convai sends `"happy"`, the taxonomy resolves that alias to `"joy"` so that the accumulator and expression pipeline — which are keyed on canonical labels — know exactly which score to update. The SDK ships with a nine-emotion Plutchik-inspired default; author a custom `EmotionTaxonomyAsset` when you need a different vocabulary or additional server aliases. ### Built-in taxonomy When the `taxonomy` field on a `ConvaiEmotionProfile` is left empty, the system synthesizes the following set at runtime. This default covers every emotion Convai currently produces and requires no asset to be created. | Canonical label | Server aliases | Default mouth influence | | --------------- | ------------------------------------------------------------------------------ | ----------------------- | | `neutral` | `calm`, `idle` | 0.0 | | `joy` | `happy`, `happiness`, `ecstasy`, `serenity`, `excited`, `enthusiastic` | 0.6 | | `trust` | `acceptance`, `admiration`, `confident`, `reassured` | 0.3 | | `fear` | `afraid`, `apprehension`, `terror`, `fearful`, `worried`, `anxious`, `nervous` | 0.4 | | `surprise` | `amazement`, `distraction`, `surprised` | 0.5 | | `sadness` | `sad`, `pensiveness`, `grief` | 0.3 | | `disgust` | `disgusted`, `loathing`, `boredom`, `bored` | 0.4 | | `anger` | `angry`, `annoyance`, `rage` | 0.55 | | `anticipation` | `interest`, `vigilance`, `curious`, `curiosity`, `eager`, `hopeful` | 0.45 | **Default mouth influence** is a per-emotion hint (0–1) that tells the facial compositor how much an emotion-driven mouth shape should contribute when the character is not speaking. During active speech, LipSync owns the mouth blendshapes; outside of speech, this value controls how strongly the emotional pose shapes the mouth region. Every non-neutral entry in the built-in set also carries a **complement** — a related emotion that comes along at reduced strength when [emotion blending](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/emotion/emotion-profile.md#emotion-blending) is on. `joy` and `trust` are mutual complements; `fear` and `surprise` are mutual; `sadness` complements `disgust`; `disgust` complements `anger`; `anger` complements `disgust`; `anticipation` complements `joy`. ### How alias resolution works Every time Convai sends an emotion, the controller calls `IEmotionTaxonomy.TryResolve(serverLabel, out EmotionDescriptor descriptor)`. The resolver checks canonical labels first, then the full alias list across all entries. * If the label resolves successfully, the corresponding canonical label and descriptor are used throughout the pipeline. * If the label does **not** resolve, the controller falls back to the neutral descriptor. **No console warning is produced.** The pipeline continues running normally, writing neutral scores every frame. **Example:** Convai sends `"happy"` → `TryResolve` finds `"happy"` in the aliases list of the `joy` entry → the accumulator sets the target score for `"joy"`. {% hint style="warning" %} When Convai sends a label that is not in the taxonomy, the failure is silent — no console warning appears and no error is logged. The character returns to neutral as if no emotion signal arrived. If a specific emotion never appears on your character, the server label is likely not covered by the active taxonomy. See [Troubleshoot emotion](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/emotion/troubleshooting-and-diagnostics.md#unknown-server-labels-silent-neutral-fallback) for how to detect and fix this. {% endhint %} ### Creating a custom taxonomy asset In the Project window, right-click inside your `Assets/` folder and choose: **Create → Convai → Embodiment → Emotion Taxonomy** A new asset named `EmotionTaxonomy` appears. Select it to edit the entries list in the Inspector. #### EmotionTaxonomyEntry fields | Field | Type | Description | | ------------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | `string` | The canonical, lowercase label used throughout the pipeline (e.g. `"joy"`). Must be unique within the taxonomy. | | `aliases` | `List` | All server-side strings that should resolve to this entry (e.g. `"happy"`, `"happiness"`). | | `complements` | `List` | Canonical labels of emotions that read naturally alongside this one and come along at reduced strength when [emotion blending](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/emotion/emotion-profile.md#emotion-blending) is on — for example `joy` with a trace of `trust`. Only consulted when the character's profile has blending enabled. | | `defaultMouthInfluence` | `float` (0–1) | Mouth influence hint for LipSync blending. See the built-in table above for reference values. | | `isNeutral` | `bool` | Marks this entry as the taxonomy's neutral baseline — what the face relaxes to between feelings, and the accumulator's decay anchor. | | `useCustomDimensions` | `bool` | When enabled, this entry's `valence`/`arousal`/`agency`/`approach` fields override the built-in dimension defaults for the label. When disabled, the values are resolved from `EmotionDimensionDefaults` for known labels. | | `valence`, `arousal`, `agency`, `approach` | `float` (-1 – 1) | The `EmotionDimensions` this emotion carries: how pleasant, how worked up, how in control, and whether it moves the character toward or away from what caused it. Consumed by Gaze, Body Language, and locomotion as one shared modulation signal alongside the categorical label. Only used when `useCustomDimensions` is `true`. | {% hint style="warning" %} **Exactly one entry must have `isNeutral = true`.** The accumulator uses the neutral entry as its decay anchor. If no entry is marked neutral, or if more than one is marked neutral, the system logs a warning and synthesizes a fallback — but expressions will not settle correctly at runtime. The console warning messages are: * `[EmotionTaxonomyAsset] This emotion vocabulary marks no emotion as the neutral one, so a stand-in is being used. Tick 'Is Neutral' on exactly one emotion — it is what the face relaxes to between feelings.` — no neutral entry found * `[EmotionTaxonomyAsset] N emotions in this vocabulary are ticked 'Is Neutral' and only the first is used. Untick the others, so it is clear which one the face relaxes to.` — multiple neutral entries found {% endhint %} #### Assigning a custom taxonomy to a profile {% stepper %} {% step %} #### Open the profile asset Open your `ConvaiEmotionProfile` asset. {% endstep %} {% step %} #### Assign the taxonomy Drag the custom `EmotionTaxonomyAsset` into the **Taxonomy** field. {% endstep %} {% step %} #### Confirm the controller picks it up The controller picks up the new taxonomy the next time the profile is applied — immediately in Play Mode, and immediately in Edit Mode because `ConvaiEmotionController` carries `[ExecuteAlways]` from its base class. {% endstep %} {% endstepper %} ### When to create a custom taxonomy The built-in Plutchik set covers all emotions Convai currently sends. A custom taxonomy is worth creating when: * Your Convai configuration uses custom emotion labels that differ from the built-in aliases. * You want to use a different conceptual model — for example, Ekman's six basic emotions — and map multiple server aliases onto fewer canonical buckets. * You want to adjust `defaultMouthInfluence` values for specific emotions to better suit your character's rig. * You need to define `complements` relationships for emotion blending, or author `valence`/`arousal`/`agency`/`approach` dimensions that differ from the built-in defaults. ### Next steps {% content-ref url="/pages/OM0Nzbb46ldsnhmYvu6a" %} [Emotion scripting API](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/emotion/scripting-api.md) {% endcontent-ref %} {% content-ref url="/pages/N6zov1sJHXMKI44gRL56" %} [Troubleshoot emotion](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/emotion/troubleshooting-and-diagnostics.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/embodiment/emotion/emotion-taxonomy.md?ask=&goal= ``` `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.