From nothing to your own pixel-art goose walking on a web page, in five steps. You need Node 20 or newer and a browser. Every command below was run as written.
1. Install
Section titled “1. Install”mkdir my-site && cd my-site && npm init -ynpm i @pixel-studio/coreThis installs two packages: @pixel-studio/core and the web components it depends on, @pixel-studio/runtime (always the
same version), and nothing else. A site that only plays finished sprites needs just npm i @pixel-studio/runtime.
The package brings the engine, the pixel command, the web components, the figure
library and the example characters in node_modules/@pixel-studio/core/examples/.
2. Describe a character
Section titled “2. Describe a character”A character is a JSON spec: shapes on a skeleton, materials, animations. The quickest start is a variant of an
example: it extends one and changes only what differs. Save this as my-goose.json:
{ "extends": "./node_modules/@pixel-studio/core/examples/goose-base.json", "name": "Marigold", "materials": { "feather": { "color": "#e8b04a" }, "beak": { "color": "#d94b32" } }}The path in extends is relative to the spec file. The base goose stands on the goose figure, so the variant
gets every motion of it: idle, waddle, run, rush, honk, jump, fall, sit, duck, peek, climb, flap and fly.
3. Check it and look at it
Section titled “3. Check it and look at it”npx pixel validate my-goose.json # errors carry a JSON path and a did-you-meannpx pixel preview my-goose.json --anim idle,waddle --out my-goose.pngnpx pixel ascii my-goose.json --res 16 --anim idle # the same as text, for agents without visionpreview draws every animation (or those named) at 16, 32 and 64 px, so you see each level of detail. Change the
spec, run it again. That loop is the whole authoring workflow; SPEC.md lists everything a spec can say.
4. Build a bundle
Section titled “4. Build a bundle”npx pixel bundle my-goose.json --out my-goose.bundle.jsonA bundle is one JSON file with the sprite sheets at every resolution, frame timings, events (footsteps), attachment points (the beak) and the foot line. It is the only thing the page needs.
5. Put it on a page
Section titled “5. Put it on a page”index.html:
<!doctype html><meta charset="utf-8"><script type="module" src="node_modules/@pixel-studio/runtime/src/pixel-sprite.js"></script><pixel-sprite src="my-goose.bundle.json" anim="idle" size="128" hover-anim="waddle" click-anim="honk" alt="Marigold, a yellow goose"></pixel-sprite>Serve the folder (modules and fetch need http, not file://), for example python3 -m http.server, and open it.
The goose idles, waddles while the mouse is over it, and honks when clicked. The runtime picks the sharpest sheet
for the size and the screen, scales in whole device pixels, pauses off-screen and respects reduced motion.
In production, copy pixel-sprite.js and the bundle next to your page; the runtime is one file with no imports.
Where next
Section titled “Where next”| to… | read |
|---|---|
| design a character from scratch, or brief an agent to | SPEC.md (it is also the agent brief: npx pixel brief) |
| choose a skeleton, tune how it walks | figures.md (npx pixel figures lists them) |
| move a sprite across the page with its feet planted, react to events, use skins and state machines | runtime.md |
| let characters walk, climb and hide on your page’s own elements | stage.md |
| use the sprites in Phaser or PixiJS | cli.md (npx pixel export) |
| call the engine from JavaScript | api.md |
| see it all live, with editable examples | the guide on pixel-studio.sh |