# State machines and skins

> A bundle can carry a little brain. The page says what it wants (a speed, a honk) and the character works out the choreography: when to switch gait, when it may stop, what to fidget with while waiting.

import LiveExample from '../../../../components/LiveExample.astro';

## Drive it with inputs

<LiveExample
  title="set() and fire()"
  code={`<pixel-sprite id="sm-goose" src="../demo/assets/goose-root.bundle.json" size="160" alt="root, a goose"></pixel-sprite>
<div class="controls">
  <label>speed <input id="sm-speed" type="range" min="0" max="100" value="0"></label>
  <button id="sm-honk">fire('honk')</button>
  <span class="readout">node: <b id="sm-node">idle</b> · <span id="sm-log"></span></span>
</div>
<script type="module">
  const goose = document.getElementById('sm-goose');
  document.getElementById('sm-speed').oninput = (e) => goose.set('speed', Number(e.target.value));
  document.getElementById('sm-honk').onclick = () => goose.fire('honk');
  goose.addEventListener('pixel-statechange', (e) => {
    document.getElementById('sm-node').textContent = e.detail.to;
    document.getElementById('sm-log').textContent = \`\${e.detail.from} → \${e.detail.to}\`;
  });
</script>`}
/>

Drag the speed up: the goose walks, then runs without restarting its stride. Drag it to zero: it stops on the next footstep, feet together. Hover it: it hacks. Leave it alone: it fidgets now and then. Click it fast, again and again: each quick click speeds up its honk, and from the fifth it panics; stop and it calms down.

### The machine, as written in the spec

```json
"states": {
  "initial": "idle",
  "inputs": {"speed": 0, "honk": "trigger", "hovered": false, "fury": 1},
  "nodes": {
    "idle": {"anim": "idle", "random": [{"anim": "hack", "every": [6, 12]}]},
    "walk": {"anim": "waddle"},
    "run":  {"anim": "run"},
    "honk": {"anim": "honk", "then": "previous", "rate": "fury"},
    "panic": {"anim": "run", "rate": "fury"},
    "hack": {"anim": "hack"}
  },
  "transitions": [
    {"from": ["idle", "walk", "run", "hack", "honk"], "to": "panic", "when": "fury >= 2"},
    {"from": "panic", "to": "idle", "when": "fury < 2", "at": "footstep"},
    {"from": ["idle", "walk", "run", "hack"], "to": "honk", "when": "honk"},
    {"from": ["idle", "hack"], "to": "walk", "when": "speed > 0 && speed <= 60"},
    {"from": ["idle", "hack", "walk"], "to": "run", "when": "speed > 60", "at": "sync"},
    {"from": "run", "to": "walk", "when": "speed > 0 && speed <= 60", "at": "sync"},
    {"from": ["walk", "run"], "to": "idle", "when": "speed == 0", "at": "footstep"},
    {"from": "idle", "to": "hack", "when": "hovered"},
    {"from": "hack", "to": "idle", "when": "!hovered"}
  ],
  "interactions": [
    {"on": "click", "fire": "honk"}, {"on": "burst", "set": {"fury": "$rate"}}, {"on": "calm", "set": {"fury": 1}},
    {"on": "enter", "set": {"hovered": true}}, {"on": "leave", "set": {"hovered": false}}
  ]
}
```

| `at` | switches… |
| --- | --- |
| `now` | immediately (the default) |
| `end` | when the current animation finishes or loops |
| `sync` | immediately, keeping the cycle's phase: walk → run mid-stride |
| an event name | on the next such event: `footstep` stops with the feet together |

## Transition clips

Switching animations swaps pictures, which can pop. A spec's `mixes` bake a few in-between frames (blended poses, not faded pixels), and the element plays them when the switch happens where the old animation ends.

<LiveExample
  title="Stopping: without and with a clip"
  code={`<figure><pixel-sprite id="mx-a" src="../demo/assets/goose-root.bundle.json" anim="waddle" size="128" states="off"></pixel-sprite><figcaption>mix: false</figcaption></figure>
<figure><pixel-sprite id="mx-b" src="../demo/assets/goose-root.bundle.json" anim="waddle" size="128" states="off"></pixel-sprite><figcaption>with "waddle&gt;idle"</figcaption></figure>
<div class="controls"><button id="mx-go">stop both at the end of the stride</button><span class="readout" id="mx-out"></span></div>
<script type="module">
  const a = document.getElementById('mx-a'), b = document.getElementById('mx-b');
  document.getElementById('mx-go').onclick = () => {
    for (const el of [a, b]) el.play('waddle', { restart: true });
    // wait for the stride to come round to its first frame, then stop
    const stop = () => {
      if (a.frame !== 0 || performance.now() - t0 < 300) return requestAnimationFrame(stop);
      a.play('idle', { mix: false });
      b.play('idle');
      document.getElementById('mx-out').textContent = \`right: \${b.currentAnim}\`;
      setTimeout(() => { for (const el of [a, b]) el.play('waddle'); }, 1500);
    };
    const t0 = performance.now();
    stop();
  };
</script>`}
/>

```json
"mixes": { "waddle>idle": {"frames": 3}, "run>idle": {"frames": 3}, "idle>waddle": {"frames": 2} }
```

## Skins

A skin is a patch (extra parts, other colours) that every animation shares. All skins are baked into the bundle; the `skin` attribute switches live, without restarting the animation.

<LiveExample
  title="One bundle, three looks"
  code={`<figure><pixel-sprite src="../demo/assets/goose-root.bundle.json" size="128" states="off" anim="waddle"></pixel-sprite><figcaption>default</figcaption></figure>
<figure><pixel-sprite src="../demo/assets/goose-root.bundle.json" size="128" states="off" anim="waddle" skin="party"></pixel-sprite><figcaption>skin="party"</figcaption></figure>
<figure><pixel-sprite src="../demo/assets/goose-root.bundle.json" size="128" states="off" anim="waddle" skin="redteam"></pixel-sprite><figcaption>skin="redteam"</figcaption></figure>`}
/>

```json
"skins": {
  "party": {
    "materials": {"partyHat": {"color": "#ff5fa2", "texture": "stripes"}, "pompom": {"color": "#ffd84a"}},
    "parts": [{"id": "hat", "parent": "head", "pivot": [68, 19], "z": 8, "shapes": [
      {"type": "polygon", "points": [[62.5, 20], [73.5, 20], [69, 6]], "material": "partyHat"},
      {"type": "circle", "cx": 69, "cy": 6, "r": 2.4, "material": "pompom"}
    ]}]
  },
  "redteam": {"materials": {"hoodie": {"color": "#8e2b3a"}, "lens": {"color": "#ff4d5e"}}}
}
```

Each skin adds about as much to the bundle as the default look. Turn a bundle's machine off with `states="off"` when your page picks the animations itself, as the skins example above does.
