kids.kapish.characters

unity

Procedural facial animation, expressions, and lipsync for Unity characters.

Architecture

The package provides a shader-driven procedural face system. Instead of blend shapes or bone rigs, facial features are rendered entirely via shader uniforms -- eyelids use bezier curves, pupils are positioned in UV space, and mouth shapes are selected from a sprite sheet. This keeps the mesh simple (a single MeshRenderer with multiple material slots) while allowing smooth, data-driven animation.

Core Flow

FaceController is the root MonoBehaviour. It owns references to left/right EyeController components, a mouth material, and eyelid rest poses.
Each frame, FaceController.Update() processes active transitions (eyelid and pupil), updates both eyes, and pushes mouth shape/color to the mouth material.
EyeController.ManagedUpdate() writes sclera, iris, pupil, and eyelid parameters to the eye shader material each frame. Pupil position is clamped to prevent overflow past the iris edge.
Eyelid shape is defined by EyelidData -- four bezier control heights with handle vectors. The shader evaluates bezier curves per-pixel for smooth eyelid edges.

Expression System

Expressions are ScriptableObject assets (FaceExpression) that store target eyelid shapes. FaceControlMode determines symmetry:

Mode	Left Eye	Right Eye
`LeftOnly`	Uses `eyelidLeft`	Unchanged
`RightOnly`	Unchanged	Uses `eyelidRight`
`BothLeft`	Uses `eyelidLeft`	Mirrors `eyelidLeft`
`BothSeparate`	Uses `eyelidLeft`	Uses `eyelidRight`

Transitions are driven by EyelidTransition, which interpolates from current to target EyelidData over a configurable duration with optional delay. The interpolation respects the target's AnimationCurve for easing.

Lipsync

MouthShape maps Preston-Blair phonemes to integer indices that select columns in the mouth sprite sheet texture. Call FaceController.ChangeMouth(MouthShape.A) to set a viseme -- the mouth shader updates immediately.

Blinking

FaceController runs a coroutine that automatically blinks both eyes at random intervals (4.5--5.5 seconds). The blink is a fast 0.14-second close/open cycle using AnimationCurve.EaseInOut for natural motion.

Pupil Gaze

PupilTransition smoothly moves pupil position over time using an AnimationCurve. Pupil overflow is clamped so the pupil never clips the iris edge, and left-eye positions are automatically mirrored.

Assembly

Assembly name: Carrot.Characters
Root namespace: Carrot.Characters
References: Carrot (base package)

Key Design Decisions

Shader-driven rendering. No blend shapes or skeletal animation. All facial features are controlled via material uniforms, keeping the mesh topology trivial.
Material slots, not submeshes. The MeshRenderer material array is indexed by configurable slot numbers (body, mouth, eye left, eye right), so the system adapts to different character mesh layouts.
ExecuteInEditMode. FaceController updates in the editor so you get live preview of expressions and eyelid shapes without entering Play mode.
Managed lifecycle. EyeController and FaceController use ManagedEnable() / ManagedUpdate() rather than Unity's OnEnable() / Update() to keep initialization order explicit.
ScriptableObject expressions. Expressions are assets, not inline data. This encourages reuse across characters and enables expression libraries.

Using kids.kapish.characters

Procedural facial animation, expressions, and lipsync for Unity characters.

Setup

Add kids.kapish.characters to your Unity project via the Package Manager.
Your character mesh needs a MeshRenderer with at least four material slots (body, mouth, eye right, eye left). The slot indices are configurable on the FaceController.

Common Patterns

1. Wire up a face

Add FaceController to your character's face GameObject. Assign:

Mesh Renderer -- the renderer with your character's face submeshes.
Material Body -- the body/skin material.
Shader Mouth / Texture Mouth -- the mouth shader and phoneme sprite sheet.
Eye Left / Eye Right -- child GameObjects with EyeController components.
Material Slots -- indices matching your mesh's submesh order.

csharp

using Carrot.Characters.Faces;

// FaceController is typically configured in the Inspector.
// Access it at runtime:
FaceController face = GetComponent<FaceController>();

2. Create and apply expressions

Create expression assets via Create > Carrot > Characters > Face Expression in the Project window. Configure eyelid shapes and control mode in the Inspector.

csharp

using Carrot.Characters.Faces;

// Transition to an expression over 0.3 seconds
[SerializeField] private FaceExpression angryExpression;

face.ChangeExpression(angryExpression, 0.3f);

// Return to the rest expression over 0.5 seconds
face.ChangeExpressionToRest(0.5f);

// Change the rest pose itself (e.g. for a new character state)
[SerializeField] private FaceExpression sleepyRest;
face.SetRestExpression(sleepyRest);

3. Expression control modes

When authoring a FaceExpression, the FaceControlMode determines symmetry:

BothLeft (default) -- author the left eye only; the right eye mirrors it.
BothSeparate -- author left and right independently for asymmetric expressions (winks, smirks).
LeftOnly / RightOnly -- only affect one eye, leaving the other at its current state.

4. Lipsync with mouth shapes

Drive mouth visemes from your audio/lipsync system:

csharp

using Carrot.Characters.Faces;

// Set a Preston-Blair phoneme shape
face.ChangeMouth(MouthShape.A); // MBP (lips together)
face.ChangeMouth(MouthShape.D); // AI (wide open)
face.ChangeMouth(MouthShape.X); // Rest (neutral)

The MouthShape enum maps to standard Preston-Blair phoneme positions:

Shape	Phoneme	Description
`A`	MBP	Lips together
`B`	etc	Relaxed consonant
`C`	E	Wide smile
`D`	AI	Open mouth
`E`	O	Round lips
`F`	U	Tight round
`G`	FV	Teeth on lip
`H`	L	Tongue up
`X`	Rest	Neutral

5. Pupil gaze

Animate where the character is looking:

csharp

using Carrot.Characters.Faces;

// Smoothly shift gaze over 0.2 seconds
face.ChangePupilPosition(new Vector2(0.3f, 0.1f), 0.2f);

// Set pupil size and iris size directly
face.EyesPupilSize = 0.9f;
face.EyesIrisSize = 0.25f;

Pupil position is normalized: (0, 0) is center, positive X is right, positive Y is up. Left-eye mirroring is handled automatically.

6. Configuring eye appearance

Eye colors and sizes are set on the FaceController and applied to both eyes:

csharp

using Carrot.Characters.Faces;
using UnityEngine;

FaceController face = GetComponent<FaceController>();
// These are typically set in the Inspector, but can be changed at runtime.

Inspector fields include sclera color, pupil color, iris color, iris size, eyelid color, and pupil focus animation curve.

Tips

Blinking is automatic. FaceController runs a blink coroutine in Play mode with randomized intervals. No setup needed.
Live preview works in Edit mode. FaceController is [ExecuteInEditMode], so expression and eyelid changes are visible without entering Play mode.
Expressions are assets. Create a library of FaceExpression ScriptableObjects and reference them from dialogue systems, animation events, or state machines.

Package Contents