Skip to content

Cards, a crate and two characters

Ridge loop
Lakeside
Old forest
<script type="module" src="pixel-stage.js"></script>
<div class="stage-demo">
<div class="row">
<article id="st-tall" class="tcard" style="min-height:170px" data-pixel-surface data-pixel-climbable><b>Ridge loop</b></article>
<div id="st-crate" class="crate" data-pixel-hide></div>
<article id="st-low" class="tcard" style="min-height:70px" data-pixel-surface data-pixel-perch><b>Lakeside</b></article>
<article id="st-mid" class="tcard" style="min-height:110px" data-pixel-surface data-pixel-climbable><b>Old forest</b></article>
</div>
<div class="shelf" data-pixel-surface></div>
</div>
<div class="controls">
<button id="st-hide">goose.hideBehind(crate)</button>
<button id="st-sit">goose.goTo(Lakeside, {then: 'sit'})</button>
<button id="st-climb">goose.goTo(Ridge loop)</button>
<button id="st-say">goose.say('honk?')</button>
<button id="st-scene">stage.playScene('#race')</button>
<span class="readout" id="st-out"></span>
</div>
<script type="application/json" id="race">
{"cast": {"goose": "#st-goose", "pip": "#st-pip"}, "steps": [
{"together": [{"actor": "goose", "goTo": "#st-low", "at": 0.2}, {"actor": "pip", "goTo": "#st-low", "at": 0.8}]},
{"together": [{"actor": "goose", "face": "pip"}, {"actor": "pip", "face": "goose"}]},
{"actor": "pip", "say": "Race you to the top?", "ms": 1600},
{"actor": "goose", "say": "HONK", "ms": 900},
{"together": [{"actor": "goose", "goTo": "#st-tall"}, {"actor": "pip", "goTo": "#st-mid"}]},
{"actor": "goose", "say": "first!", "ms": 1400, "async": true},
{"actor": "pip", "perform": "wave"},
{"actor": "pip", "goTo": "#st-mid", "then": "sit"}
]}
</script>
<pixel-stage controls="none" floor="none">
<pixel-actor id="st-goose" src="goose-root.bundle.json" size="72" start="#st-low" alt="a goose"></pixel-actor>
<pixel-actor id="st-pip" src="pip.bundle.json" size="64" start="#st-mid" alt="Pip"></pixel-actor>
</pixel-stage>
<script type="module">
await customElements.whenDefined('pixel-actor');
const goose = document.getElementById('st-goose'), out = document.getElementById('st-out');
const say = (ok, what) => (out.textContent = ok ? what : 'no way there right now');
goose.addEventListener('pixel-activity', (e) => (out.textContent = `goose: ${e.detail.to}`));
document.getElementById('st-hide').onclick = () => say(goose.hideBehind(document.getElementById('st-crate')), 'heading for the crate');
document.getElementById('st-sit').onclick = () => say(goose.goTo(document.getElementById('st-low'), { then: 'sit' }), 'going to sit');
document.getElementById('st-climb').onclick = () => say(goose.goTo(document.getElementById('st-tall')), 'off to Ridge loop');
document.getElementById('st-say').onclick = () => goose.say('honk?');
const stage = document.querySelector('pixel-stage'), sceneBtn = document.getElementById('st-scene');
sceneBtn.onclick = () => (stage.scene ? stage.scene.stop() : stage.playScene('#race'));
stage.addEventListener('pixel-scenestep', (e) => (out.textContent = `scene: ${e.detail.path}`));
stage.addEventListener('pixel-sceneend', (e) => (out.textContent = e.detail.completed ? 'scene: the end' : 'scene: stopped'));
</script>

Tap or click a character to shoo it; with a mouse, drag one to pick it up and throw it. This page hides the stage’s own pause button (controls="none") and its floor; the full demo page has both.

Give a character keep-in-view and it follows the reader: after a scroll settles, it runs back if it is close (at 2.5× speed, feet still planted), or drops in from the top of the screen onto a visible surface. The stage also reports scroll speed, so a page can react to fast scrolling. Try it on the demo page, which is long enough to scroll.

<pixel-actor src="goose.bundle.json" size="64" keep-in-view></pixel-actor>
stage.addEventListener('pixel-fastscroll', (e) => goose.say('wait for me!')); // e.detail.speed in px/s
goose.addEventListener('pixel-catchup', () => console.log('coming back'));
goose.addEventListener('pixel-burst', (e) => console.log('rage taps', e.detail.count)); // tapping fast makes it panic

A scene is a scripted moment written as data: who goes where, says what, and when. Steps run in order; together runs several at once, "async": true starts one without waiting, and waitFor pauses until something happens (a tap on a character, a click on a button). The cast is directed while it plays: characters wait for their next line instead of wandering off. Steps that cannot happen (no route, a tap that startles a character) are skipped, so readers poking at the characters never jam it. Press stage.playScene(‘#race’) in the example above to play this one.

{"cast": {"goose": "#st-goose", "pip": "#st-pip"}, "steps": [
{"together": [{"actor": "goose", "goTo": "#st-low", "at": 0.2}, {"actor": "pip", "goTo": "#st-low", "at": 0.8}]},
{"together": [{"actor": "goose", "face": "pip"}, {"actor": "pip", "face": "goose"}]},
{"actor": "pip", "say": "Race you to the top?", "ms": 1600},
{"actor": "goose", "say": "HONK", "ms": 900},
{"together": [{"actor": "goose", "goTo": "#st-tall"}, {"actor": "pip", "goTo": "#st-mid"}]},
{"actor": "goose", "say": "first!", "ms": 1400, "async": true},
{"actor": "pip", "perform": "wave"},
{"actor": "pip", "goTo": "#st-mid", "then": "sit"}
]}
const run = stage.playScene('#race'); // an object, JSON text, or a <script type="application/json">
await run.finished; // true at the end, false if run.stop() was called
stage.addEventListener('pixel-sceneevent', (e) => console.log(e.detail.name)); // from {"emit": "…"} steps
// The same orders, awaitable from code: true when done, false if impossible or interrupted.
if (await goose.run('goTo', summit, { then: 'sit' })) await goose.say('made it');

Steps: goTo (a selector, a cast name, or a point; then, at), hideBehind, perform, say, face, shoo, wait, together, waitFor, emit. <pixel-stage scene="#intro"> plays one when the page loads. The full table is in docs/stage.md.

Give a scene a trigger and mark its script data-pixel-scene: it plays by itself when that happens: a form submitted, a button clicked, a section scrolled into view ("visible"), a character tapped. Characters can pickUp any element (a copy rides at the beak or hand), drop it, exit by the side of the screen (delivering what they carry) and enter again. A character with front and back views can turn to the reader: {"face": "viewer"}, "away", "side". The demo page’s newsletter form hands the goose a letter to post.

{"cast": {"goose": "#goose"},
"trigger": {"event": "submit", "on": "#signup", "preventDefault": true},
"steps": [
{"actor": "goose", "pickUp": "$trigger .letter"},
{"actor": "goose", "exit": "right"},
{"wait": 1800}, {"emit": "delivered"},
{"actor": "goose", "enter": "right"},
{"actor": "goose", "say": "delivered. HONK"}
]}
attribute meaning
data-pixel-surface its top edge is a platform
data-pixel-climbable its sides are walls (its foot must rest on a platform)
data-pixel-perch a favourite place to sit
data-pixel-hide a hiding spot (standing on a platform)
data-pixel-occluder characters always pass behind it
data-pixel-avoid never stand on or hide behind it
const goose = document.querySelector('pixel-actor');
goose.goTo(document.querySelector('#summit'), { then: 'sit' }); // route: walk, drop, jump, climb
goose.hideBehind(document.querySelector('.crate')); // duck and peek
goose.say('honk?'); // bubble at the beak
goose.shoo(); // startle and run
moss.perform('think'); // any animation of its own, in place
goose.addEventListener('pixel-activity', (e) => console.log(e.detail.to));
const stage = document.querySelector('pixel-stage');
stage.pause(); // what the built-in button does; remembered
stage.world.invalidate(); // after you move elements with CSS transforms

Characters need a few animations to do all this: a walk with a speed, jump, fall, climb, sit, duck and peek. Every figure has presets for them; see Figures and motions. The full reference is docs/stage.md.

Pixel Studio

Agents describe characters; the engine draws them as pixel art at every level of detail; websites play them with one tag.

© 2026 Pixel Studio · v0.2.0-alpha.2 · Released under the MIT licence.