# Events, points and the foot line

> Bundles carry more than pictures. The engine bakes in when feet touch down, where the beak is in every frame, and where the character stands, so a page can react to what the character is doing.

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

## Events

Motion models mark moments automatically: `footstep` (with the leg) in walks, runs and climbs, `launch` and `land` in jumps, `takeoff` and `land` in hops. Authors add their own, like the goose's `honk`. The element fires a bubbling `pixel-event` on the frame where it happens.

<LiveExample
  title="Footsteps as they happen"
  code={`<pixel-sprite id="ev-goose" src="../demo/assets/goose-root.bundle.json" anim="waddle" size="128" states="off"></pixel-sprite>
<pixel-sprite id="ev-fox" src="../demo/assets/fox.bundle.json" anim="walk" size="128"></pixel-sprite>
<div class="controls"><span class="readout" id="ev-out">listening…</span></div>
<script type="module">
  const out = document.getElementById('ev-out');
  const counts = {};
  document.addEventListener('pixel-event', (e) => {
    if (e.detail.name !== 'footstep') return;
    const who = e.target.id.replace('ev-', '');
    counts[who] = (counts[who] ?? 0) + 1;
    out.textContent = \`\${who}: \${e.detail.data.leg} down on frame \${e.detail.frame} · \` +
      Object.entries(counts).map(([k, n]) => \`\${k} \${n} steps\`).join(', ');
  });
</script>`}
/>

Use them for footstep sounds, dust puffs, a camera nudge on landing, or to start something exactly when the character acts. In a spec: `"events": [{"frame": 3, "name": "honk"}]`; `"events": false` turns a motion's own off.

## Attachment points

Figures name useful points (the goose's `beak`, `head` and `tail`; human hands; …) and specs add their own. `el.point('beak')` says where that point is in the frame showing now, mirrored when the sprite is flipped.

<LiveExample
  title="A speech bubble that follows the beak"
  height={200}
  code={`<div id="pt-box" style="position:relative">
  <pixel-sprite id="pt-goose" src="../demo/assets/goose-root.bundle.json" anim="honk" size="160" states="off"></pixel-sprite>
  <div class="bubble" id="pt-bubble">HONK</div>
</div>
<div class="controls"><button id="pt-flip">flip</button><span class="readout" id="pt-out"></span></div>
<script type="module">
  import { clock } from '../packages/runtime/src/pixel-sprite.js';
  const goose = document.getElementById('pt-goose'), bubble = document.getElementById('pt-bubble');
  document.getElementById('pt-flip').onclick = () => goose.toggleAttribute('flip');
  clock.add(() => {
    const p = goose.point('beak', { relative: true });
    if (!p) return;
    bubble.style.left = \`\${p.x}px\`;
    bubble.style.top = \`\${p.y - 6}px\`;
    document.getElementById('pt-out').textContent = \`beak at \${p.x.toFixed(0)}, \${p.y.toFixed(0)} px (frame \${goose.frame})\`;
  });
</script>`}
/>

## The foot line

`el.groundOffset` is how far below the top of the sprite's box its feet are, at the displayed size. Subtract it from a line's position and the character stands exactly on it, whatever its size.

<LiveExample
  title="Standing on a line, at three sizes"
  height={170}
  code={`<div id="gl-row" style="position:relative;height:150px;width:100%">
  <div class="ground-line" style="top:130px"></div>
  <pixel-sprite class="stand" src="../demo/assets/goose-root.bundle.json" size="48" style="position:absolute;left:10px" states="off"></pixel-sprite>
  <pixel-sprite class="stand" src="../demo/assets/pip.bundle.json" size="96" style="position:absolute;left:90px"></pixel-sprite>
  <pixel-sprite class="stand" src="../demo/assets/fox.bundle.json" size="128" style="position:absolute;left:200px"></pixel-sprite>
</div>
<script type="module">
  for (const s of document.querySelectorAll('#gl-row .stand')) {
    const place = () => (s.style.top = \`\${130 - s.groundOffset}px\`);
    s.addEventListener('pixel-ready', place);
    if (s.status === 'ready') place();
  }
</script>`}
/>

## Clicking the character, not its box

`el.hitTest(x, y)` is true only over the character's opaque pixels in the current frame.

<LiveExample
  title="Click around the goose"
  height={190}
  code={`<div id="ht-box" style="position:relative;cursor:crosshair">
  <pixel-sprite id="ht-goose" src="../demo/assets/goose-root.bundle.json" size="160" states="off" style="outline:1px dashed #ccc"></pixel-sprite>
</div>
<span class="readout" id="ht-out">click on and around it</span>
<script type="module">
  const box = document.getElementById('ht-box'), goose = document.getElementById('ht-goose');
  box.addEventListener('pointerdown', (e) => {
    const hit = goose.hitTest(e.clientX, e.clientY);
    const r = box.getBoundingClientRect();
    const dot = Object.assign(document.createElement('div'), { className: 'dot' });
    dot.style.cssText = \`left:\${e.clientX - r.left}px;top:\${e.clientY - r.top}px;background:\${hit ? '#1a7f37' : '#cf222e'}\`;
    box.append(dot);
    document.getElementById('ht-out').textContent = hit ? 'hit the goose' : 'missed (empty pixel)';
  });
</script>`}
/>

## Rage clicks

Click a sprite three or more times in quick succession and it fires `spriteburst` with the count and a suggested speed-up, then `spritecalm` when you stop. A playing click animation speeds up instead of restarting. Hook your own reactions on it: an easter egg, a "calm down" message, a faster animation.

<LiveExample
  title="Click Pip fast"
  code={`<pixel-sprite id="rc-pip" src="../demo/assets/pip.bundle.json" anim="idle" size="128" click-anim="wave" alt="Pip"></pixel-sprite>
<div class="controls"><span class="readout" id="rc-out">click Pip several times quickly</span></div>
<script type="module">
  const pip = document.getElementById('rc-pip'), out = document.getElementById('rc-out');
  pip.addEventListener('pixel-burst', (e) => (out.textContent = \`burst ×\${e.detail.count}: waving at \${pip.effectiveRate.toFixed(2)}× speed\`));
  pip.addEventListener('pixel-calm', (e) => (out.textContent = \`calm again after \${e.detail.count} clicks\`));
</script>`}
/>

With a [state machine](/docs/guide/states/), `{"on": "burst", "set": {"fury": "$rate"}}` turns bursts into an input; the goose on that page honks faster and then panics.

## Holding a frame

A spec's `"holds": {"3": 2}` shows frame 3 twice as long, for timing a key pose. Bundles carry per-frame `durations`; the goose's honk holds its loudest frame.

```json
"honk": {"motion": "pose", "frames": 10, "fps": 10, "loop": false,
         "events": [{"frame": 3, "name": "honk"}], "holds": {"3": 2}, "tracks": { … }}
```
