Character Studio help

The same SVGMotion editor — canvas, timeline, inspector, Connect graph, AI dock, exports — wearing a character hat. Three extra things on top: rig roles, a micro-action verb kit, and a Stage floor where many entities act together under an AI director. This page mirrors the main editor guide — everything in it still applies here. Two guided tours run live inside the studio — the quick tour (rig → micro → macro → world, ~2 min) and the full tour (everything incl. keyframing, links and the director) — plus a How it's made walkthrough on every gallery item.

Quickstart

npm run dev                         # → http://localhost:4173/characterstudio
ollama serve && ollama pull qwen3:8b  # optional — same providers as the editor

Character Studio shares the editor's ☰ Menu → Settings… → AI provider — Ollama, OpenRouter, or OpenAI, BYOK, keys stay in this browser. Settings → Advanced can also enable a local browser AI engine (WebLLM, runs on this device) that handles tool work — commands, edits, and world-director beats — before any provider is needed. With neither, everything works offline; the world director falls back to a deterministic built-in brain so the choreography pipeline never dead-ends.

Core concepts

The three modes

The mode rail sits where the editor's view switcher lives; every panel, shortcut (B/I/M/G/F), the AI dock, autosave, undo and export behave exactly as in the main editor. Canvas gestures too — click a part to select it, drag to move it, or use the arrow keys to nudge the selected layer or shape (⇧ = 10×); with nothing selected ←/→ step the playhead.

The sidebar is contextual: instead of every studio section open at once, it keeps the relevant one expanded — select a rigged part → Parts, select something unrigged or nothing → Rig, pose a non-idle action → Micro actions. In Stage mode the sidebar and inspector hide entirely — stage chrome (cast tray, autopilot, console drawer) takes over. You can always ▾-open another section by hand; the next selection change re-tidies.

Rigging a character

New character… (top bar) opens the picker:

Assigning roles

The Rig sidebar lists the archetype's roles as a checklist. Pick a role row → click a layer on the canvas → assigned. Shape-level roles (eyes, mouth, ears) tag an element inside a layer. Presets a creature can't perform — Wag tail on a blob — are greyed out automatically.

Parts library

The Parts sidebar panel restyles a character by swapping rig slots — eyes, mouths, ears, snouts, heads, torsos, limbs, tails — plus attachable accessories (hats, glasses, scarves, headphones…). It only shows slots your current rig actually resolves, and swaps keep the rig keys, transforms and pivots, so every micro-action and macro keeps working after a restyle. The library has ~90 authored parts plus everything below.

Parts arrive style-locked: snippets paint with palette tokens ($ink, $body, $skin, $soft, $accent) sampled from your character's colors — a swapped eye inherits the face ink, a swapped arm inherits the body tone.

Micro-actions

The Micro actions panel offers presets — Nod, Tilt head, Wave, Blink, Smile, Bark/speak, Wag tail, Prick ears, Sit, Bounce, Hop, Shiver. Click ＋ to add one; it lands in the Actions list like any action and plays so you can refine it on the canvas/timeline. Right-click a preset to add it with tuned params ({"degrees":20,"duration":500,"side":"l"}).

＋ Custom micro… scopes a sparse action to a role (or the whole body); ＋ From selected layer scopes one to the selection. Then pose and keyframe exactly like the main editor — unposed layers simply hold.

Micro-verb API

Every preset is a call into js/char/microapi.js — functions that build a transient sparse action from clamped args. The command bar and the AI call the same verbs directly:

partId is a rig role; numbers clamp to safe ranges; an unresolvable verb is a no-op, never a crash. hold:true keeps the pose until the next call — that's how sleep-style behaviors are built.

Macros

A macro is a named chain of micros — "greet" = nod → wave → bow. In the Macro composer: tap action chips in play order, name it, pick an entry trigger (click/hover/press), hit ⌁ Wire. The composer writes ordinary idle → steps → idle transitions — fully visible and editable in Connect.

Parameterized macros: steps may be verb calls — {call:'walkTo', params:{entity:'$target'}} — where $target, $self, $user, $x, $y bind at trigger time. So eat can be walkTo($target) → consume($target), triggered by the AI as triggerMacro('eat', {targetEntityId:'prop_apple'}). Verb-step macros run through the entity's queue (each step waits for the previous) and only play in Stage mode.

Connect

The shared state-machine graph, unchanged: action nodes, transition edges, triggers (click/hover/press/layer-targeted), guards, inputs. Macro chains appear as readable rows of nodes. No world entities here — it's deliberately the same manual canvas as the editor's Connect mode.

Stage floor

Switch to Stage to stage many entities on one floor — the sidebar and inspector hide so the stage gets the whole canvas:

• Add entities — the ＋ Cast tray (left edge) holds bundled characters & props, your recent scenes, and import — click a tile or drag it onto the floor. ⇪ Send to stage pushes the character you're editing; dropping any .svg file on the floor works too. Project files keep their actions and click triggers — a lamp that toggles still toggles.
• Direct them — drag any cast member to move it (a tap still fires its own click triggers); with one selected, click the floor and it goes there — characters walk, props arc. Hover shows action/macro chips plus a floating ⋯/✕ (menu / remove — ⌦ works too); Esc deselects; double-click a character to edit it in Rig. Or type in the command bar: blobby wave, dog go to bone, cat pick up apple.
• Edit back — a chip's Edit in rig editor (or double-click the cast member) loads the entity into Rig; ↺ Update entity writes it back.
• Tags — entity menu → Tags… gives the AI affordances: edible props get eaten, toy props get played with.
• The user — with nothing selected, click the floor and a ◈ marker moves there; face(user) / walkTo(user) work, drops/clicks emit director events. With a cast member selected, a floor click directs it instead.
• ⌄ Console — a bottom drawer (bar button) holds the plumbing: Director log, Links form, Events feed, and the State JSON the AI sees.

Entity methods — what AI and you can call

walkTo(x,y | entity)   goto(entity)    face(entity)    tellAt(entity, action)
pickUp(prop)           drop()          consume(prop)   interact(entity, act, targetAct)
nudge(prop)            say(text)       seq(steps[])     launch/throw(x|entity|vx,vy)
micro(verb, args)      triggerMacro(name, bindings)    macro name  → runs the macro

pickUp makes the prop ride with its carrier; consume plays the prop's own eaten/vanish action (or shrinks it away). Movement is a real walk, not a glide: the entity advances stride-by-stride in sync with its own gait cycle — eased sub-move + a footfall pause per stride, the loco-tagged action re-firing each step — and it faces travel direction (left-authored art sets rig.facing:-1 so it never moonwalks). Positions track live as it walks, so near/moves links fire mid-journey. Positions clamp to the floor. seq queues ordered steps — walkTo blocks until arrival. launch/throw arcs a prop (or any entity) on a real ballistic path — the same solver as the editor's projectile recipe, run in stage space.

Everything funnels through one dispatch:

invoke(entity, { type: 'micro'|'macro'|'verb'|'say'|'seq', action, params })

Chips, the command bar, links and the director all use it — malformed actions drop with a visible ✗, never a crash.

Links — entity → entity rules

In the console drawer's Links tab pick source → when → target → action. Conditions:

"When Nova finishes wave → Orbit plays greet." "When the dog is near the bone → bone plays pickup." Links fire once when the condition begins and re-arm when it ends — that's how the gallery's Buddy duo world runs its call-and-response greeting with zero code.

AI director & the autopilot

With a provider configured or the local engine enabled, ▶ Autopilot (stage bar) hands the director the full state — every entity's kind, position, tags, callable methods and micro-verb signatures, plus links and recent events — and it returns a structured beat:

{ "thought": "The user placed an apple next to Blobby…",
  "actions": [
    { "target": "char_blobby", "type": "micro",
      "action": "setPartRotation", "params": { "partId": "head", "degrees": 12, "duration": 200 } },
    { "target": "char_blobby", "type": "macro",
      "action": "eat", "params": { "targetEntityId": "prop_apple" } } ] }

thought shows as a 💭 bubble over the entity it's about to move (the full log lives in the console's Director tab); actions run through invoke(). Beats are periodic and reactive — drops, clicks, arrivals and landings wake the director in under a second; user-caused events react fastest (~0.5s). While the model thinks, a light ambient micro keeps the cast alive so nobody freezes. Quiet world → ambient micros (blink, breathe, wagTail) or an empty list.

Offline: a deterministic built-in director and a parser handle "X does A", "X go to Y", "X pick up / eat Y", "X throw Y", "X say …" — so the pipeline still runs end-to-end. The gallery's scripted beats are canned presets in the same {thought, actions[]} shape — the AI director buttons and the "tell the cast" box ask the real model (local browser AI first, provider fallback). In the editor the same local-first path powers the ⚡ command box — it also edits: "make it red", "add a spin action", "move head up".

Gallery & deep links

World bundles are JSON: {name, floor, entities:[{name, file, x, y, w, tags}], links:[…], presets:{note, beats:[{thought, label, actions}]}} — entities reference ordinary gallery/studio .svg files by path. Deep links merge into the current stage rather than wiping it.

Files & persistence

Physics-lite: proximity uses bounding boxes polled per frame — enough for near/touch/pick-up. Real motion physics reuse the editor's solvers (launch, physMove).

Worked example — Biscuit fetches a bone

Troubleshooting