Emotion

How the Emotion system works, what each component does, and where to go next — the starting point for adding facial emotion to any Convai character.

Giving Convai Characters Emotionally Responsive Faces

The Emotion system translates the Convai AI's internal emotional state into live facial animation — driving blendshapes, Animator parameters, or both simultaneously. Every time the backend decides the character feels joy, anger, surprise, or any other state, the Emotion system receives that signal, smooths it into a natural arc, and writes the result to your character's face in real time. The result is a character that reads as emotionally present rather than expressionless.

How It Works

The backend sends a short emotion label (for example "happy") and an intensity on a 1–3 scale. The taxonomy resolves that label to its canonical form ("joy"), normalises the intensity to a 0–1 score, and hands it to the score accumulator, which applies exponential smoothing and an optional micro-expression burst. The neutral alternator then periodically blends the expression back toward neutral to prevent a frozen face. Finally, the smoothed scores are written to blendshapes and Animator parameters through configurable output bindings.

Prerequisites

Before adding the Emotion system to a character, ensure:

• Your character mesh has facial blendshapes, or your Animator Controller has float parameters you want to drive from emotion. The pipeline runs without these, but no visual output occurs until at least one output binding is configured.

What Goes Where

Component	Where to place it	Notes
ConvaiEmotionController	On the NPC's root GameObject, alongside the Embodiment component	One per character
ConvaiEmotionProfile	Anywhere in your Assets/ folder as a ScriptableObject asset	Shared across multiple NPC prefabs if needed
EmotionTaxonomyAsset	Anywhere in your Assets/ folder	Optional — omit to use the built-in Plutchik set
ConvaiCharacterEventRelay	On any GameObject in the scene	Auto-resolves ConvaiCharacter on the same GameObject; drag a different character if needed

Key Concepts

Concept	What It Is
ConvaiEmotionController	The MonoBehaviour that owns the entire pipeline for one NPC. Add one per character.
ConvaiEmotionProfile	A ScriptableObject asset that holds every tunable parameter: smoothing, micro-burst, neutral alternation, and output slot definitions.
EmotionTaxonomyAsset	A ScriptableObject that defines the emotion vocabulary — canonical labels, server aliases, and mouth influence hints. The built-in default is Plutchik's eight primary emotions plus neutral.
Output bindings	BlendshapeEmotionBinding and AnimatorParameterEmotionBinding map each canonical emotion label to mesh blendshape names or Animator float parameters.
EmotionReading	An immutable snapshot of the current emotional state: dominant label, dominant score, all scores, and mouth influence hint for LipSync. Available every frame via ConvaiEmotionController.Current.
Micro-burst	A short overshoot applied when a new emotion arrives, giving expressions a punchy entry before settling to their sustained level.
Neutral alternation	A timer that periodically fades the active expression toward neutral and back, preventing the character's face from locking into a single pose during long turns.
ConvaiCharacterEventRelay	An Inspector-friendly component that exposes emotion change callbacks as Unity Events — no code required.

In This Section

Quick Start

Attach the Emotion Controller, assign the bundled profile, and get your NPC reacting emotionally to conversation — no custom assets required.

Emotion Profile

Configure smoothing speed, micro-expression bursts, neutral alternation, and output bindings in one portable asset.

Output Bindings

Map smoothed emotion scores to facial blendshapes and Animator float parameters, with per-slot weight and LipSync control.

Emotion Taxonomy

Understand the built-in Plutchik vocabulary, how server aliases are resolved, and how to author a custom taxonomy.

Scripting API

Read live emotion state, inject overrides, lock expressions, and react to emotion events — from Inspector relays to typed C# subscriptions.

Usage Examples

Complete scenarios covering hazard triggers, locked greetings, distress branching, analytics logging, and Editor debugging.

Troubleshooting & Diagnostics

Step-by-step fixes for the most common problems — from expressions that will not move to LipSync conflicts and production build gotchas.

Conclusion

The Emotion system gives Convai characters a believable emotional presence — server-driven, smoothed, and fully configurable without writing code for the common case. Start with Quick Start to get a character reacting live, then use the deeper configuration pages to tune the behaviour for your specific rig and scenario.