Character

A character is a face for your voice assistant. The gaze knows whose turn it is: it looks at you while you talk, looks up and away while it thinks, and blinks when your turn ends. The mouth follows only how loud the agent's voice is. Give it a voice source or an agent state, like every other object.

Want your own? A character is a recipe, and you can make your own from one of these in a single file.

When to use which pattern

How it behaves

• The eyes are shapes. No pupils and no brows: the eye's shape is the expression, so it still reads at 20 px.
• It knows whose turn it is. It looks at you while listening, looks up and away while thinking, and blinks once as your turn ends.
• The mouth follows the voice's loudness. Nothing more: no lip-sync, so any voice source works.
• Effects are expressions. success is ^ ^ eyes with a grin, error is x x eyes with a short shake, celebrate is star eyes with a burst.
• Muted, it squints and fades. Its colours stay.
• State changes are smooth. The eyes slide up as thinking starts; they don't jump.

Head turn

The head turns like a solid, not a flat sticker: the face slides round its surface and the body shows the turn. At rest it looks from corner to corner, listening it turns to you, thinking it looks up and away, and speaking it nods with the voice.

turn sets how far: the default is about ±25°, 1 is ±35° and 0 draws it flat. At 20 px the head doesn't turn, and with reduced motion only the facing of each state stays. It stays in the light cost class.

Expressions

expression gives the character a mood your app picks. It stays until you change it, and a change eases over 0.6 s.

• It sits on top of the voice state. The expression owns the eyes' shape; the state keeps the gaze, the head turn, the blinks and the talking mouth. A sad Bean still turns to you while you talk.
• Chirp and Hum have no resting mouth to change (a beak, a grille), so theirs is in the eyes only.
• Effects still play on top, and an expression is never announced.
• In an FX Spec, expression can go in the file and in each state. The view's prop wins over the file's.

Tap reaction

A tap or a click on a character plays hop: it crouches, hops and lands with a little squash, smiles, and glances toward where you tapped. The voice state carries on underneath.

• It's on by default on SinuaCharacter and <sinua-character>; the plain SinuaView leaves it off.
• A tap never cuts a running success, error or celebrate, and there are at most two hops a second.
• With reduced motion it only smiles.
• Inside a tappable button or list row, set tap: false, so the tap goes to your control and the character doesn't hop as well.

Palette

palette repaints some of a character's colours and leaves the rest as drawn: { body: "#E63946" }. To change only colours, this is all you need; no recipe.

• Slots are named by the part they paint, never by colour: body is every character's main colour, and outline, cheeks and shine mean the same everywhere. The eyes are eyes on a body face and glow on a screen face. An unknown slot is an error that suggests the closest name.
• Tones follow. Given body, its bodyLight and bodyDark move with it. A tone you give yourself wins.
• After hue. hue still turns the slots it turns; a colour you give is never turned.
• The eyes stay readable. When a new colour comes too close to the ink of the eyes and mouth, the ink moves to the far side, unless you set the ink too.
• Labels for a colour picker: every slot has a label and a one-line description in spec/character-slot-labels.json, with the localization key sinua.slot.<character>.<slot>.
• A change applies at once. In an FX Spec, palette can go in the file and in each state.

Roles and the dark variant

A palette can also be written over roles, so one palette fits every character: each character maps primary, secondary and accent to its own slots.

• { primary: "#E63946" } paints by role, without knowing the slot names. Slots you write win over roles.
• A role a character doesn't have is read as a slot name, so writing it is an error (Buzzy and Bean have no secondary).
• Dark theme: { primary: "#2E87C2", dark: { primary: "#2E6A9E" } } gives your own dark variant. The view picks it when the theme is dark.

A character keeps its own colours otherwise: color and gradient don't apply, and in an FX Spec they are an error.

The richer look

Airbrushed shading, rim light and film grain, with no blur: a character's soft shade masses and rim light give it depth, and grain lays a still, fine noise inside its body. The face stays crisp. shading turns the soft layers off and grain sets the amount; under low power both turn off.

The built-in characters are unchanged; a recipe adds the layers.

Options

import { SinuaCharacter } from "@sinua/web/components";
import type { VoiceSource } from "@sinua/core";

// A character for your assistant: it looks at you while you talk, looks away while it
// thinks, and its mouth follows the agent's voice.
export function Assistant({ voice }: { voice: VoiceSource }) {
  return (
    <SinuaCharacter
      pattern="buzzy"
      voice={voice}
      hue={190} // turns the body; the eyes and accents keep their colours
      palette={{ accent: "#FFFFFF" }} // repaint a slot outright
      expression="happy" // a mood your app picks; the voice state still moves it
      label="Buzzy"
      labels={{ listening: "Buzzy is listening", speaking: "Buzzy is speaking" }}
      style={{ width: 160, height: 160 }}
    />
  );
}

On the web it's also a tag: <sinua-character pattern="buzzy" hue="190">, with palette as a property.

Props

Every prop, per pattern. Besides the options above, the pose values the states set (gazeX, lid, eyeSmile, …) are props too, so you can tune how a state looks. Defaults can differ per size (20 · 32 · 64).

The character component is SinuaCharacter. Pick a look with pattern; each pattern reads the props below. Sizes are engine sizes (20, 32, 64): defaults can differ per size.

Buzzy

pattern: "buzzy" · mode buzzy · speed 1× · sizes 20, 32, 64

Hum

pattern: "hum" · mode hum · speed 1× · sizes 20, 32, 64

Wisp

pattern: "wisp" · mode wisp · speed 1× · sizes 20, 32, 64

Chirp

pattern: "chirp" · mode chirp · speed 1× · sizes 20, 32, 64

Cuppa

pattern: "cuppa" · mode cuppa · speed 1× · sizes 20, 32, 64

Bean

pattern: "bean" · mode bean · speed 1× · sizes 20, 32, 64

Beep

pattern: "beep" · mode beep · speed 1× · sizes 20, 32, 64