Events
Section titled “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.
Footsteps as they happen
<pixel-sprite id="ev-goose" src="goose-root.bundle.json" anim="waddle" size="128" states="off"></pixel-sprite><pixel-sprite id="ev-fox" src="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
Section titled “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.
A speech bubble that follows the beak
<div id="pt-box" style="position:relative"><pixel-sprite id="pt-goose" src="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 '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
Section titled “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.
Standing on a line, at three sizes
<div id="gl-row" style="position:relative;height:150px;width:100%"><div class="ground-line" style="top:130px"></div><pixel-sprite class="stand" src="goose-root.bundle.json" size="48" style="position:absolute;left:10px" states="off"></pixel-sprite><pixel-sprite class="stand" src="pip.bundle.json" size="96" style="position:absolute;left:90px"></pixel-sprite><pixel-sprite class="stand" src="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
Section titled “Clicking the character, not its box”el.hitTest(x, y) is true only over the character’s opaque pixels in the current frame.
Click around the goose
<div id="ht-box" style="position:relative;cursor:crosshair"><pixel-sprite id="ht-goose" src="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
Section titled “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.
Click Pip fast
<pixel-sprite id="rc-pip" src="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, {"on": "burst", "set": {"fury": "$rate"}} turns bursts into an input; the goose on that page honks faster and then panics.
Holding a frame
Section titled “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.
"honk": {"motion": "pose", "frames": 10, "fps": 10, "loop": false, "events": [{"frame": 3, "name": "honk"}], "holds": {"3": 2}, "tracks": { … }}