Skip to content

Thanks for helping. Pixel Studio is small on purpose: plain ES modules, no dependencies, no build step.

Terminal window
node --version # 20 or newer
npm install # links the two packages to each other; there are no third-party dependencies
npm test # both packages: engine, rig, figure, plug-in, reference and runtime tests (node:test)
npm run build:demo # the demo's bundles and posters (generated, not committed)
npm run studio # http://localhost:5173/studio/ , /studio/figures.html , /demo/

npm run studio serves the repository on 127.0.0.1 only (set HOST/PORT to change).

Path What
packages/pixel-studio/ The @pixel-studio/core package: the engine (src/core, src/node), the pixel CLI (bin/), figures, examples, motion references, the user docs (docs/) and their tests (test/).
packages/runtime/ The @pixel-studio/runtime package: <pixel-sprite> and <pixel-stage> (src/), no imports from the engine, and their tests.
studio/, demo/ The studio and playground, and the demo pages. Served from the repository root by npm run studio.
website/ pixel-studio.sh, including the guide (src/content/docs/docs/guide/: live examples and editable characters) (Astro, astro-project-site). Its own npm install; npm run deploy there.
docs/research/ Research notes behind the design. Not shipped in the packages.
scripts/ The dev server, the demo build, version and browser checks.

Read docs/architecture.md first: it maps every module and walks the pipeline from JSON spec to pixels. The other references:

doc for
docs/SPEC.md the character spec (also the brief given to agents)
docs/figures.md figures, motion models, follow-through, writing a new figure
docs/api.md the JavaScript API
docs/cli.md the pixel CLI
docs/runtime.md the <pixel-sprite> element and the bundle format
docs/stage.md <pixel-stage>: characters living on a page
docs/playground.md the URL-driven playground page
docs/DESIGN.md why the format looks the way it does
  • No dependencies. Not at runtime, not for tests, not for building. (@pixel-studio/core depends on @pixel-studio/runtime, its sibling in this repository, and nothing else.)
  • src/core is isomorphic. No DOM, no Node APIs. Node-only code goes in src/node, bin, scripts; browser-only code in packages/runtime and studio.
  • The runtime never imports the engine. It plays finished bundles, so a site can install it alone.
  • Two packages, one version. @pixel-studio/core and @pixel-studio/runtime are always released together with the same version, and @pixel-studio/core depends on exactly that runtime version. npm run version:set -- <version> sets all three; a test fails if they drift.
  • Deterministic. The same spec renders the same pixels on every machine. No Math.random, no clocks.
  • Everything reduces to a plain spec. extends, figures and motions expand into ordinary parts and tracks before validation, so every tool (validator, linter, renderer, studio) understands the result.
  • Errors point at the problem. Validation messages carry a JSON path and, for typos, a suggestion. Prefer a helpful error or warning to silently doing something odd.
  • Agents are users. Anything an agent must learn to use a feature goes into packages/pixel-studio/docs/SPEC.md (it is the brief), short and with an example.
  1. Add or change a test in the package’s test/ (node:test, assert/strict). Rendering tests compare pixels or pixel-derived facts; motion tests check physical facts (planted feet do not move, volume is preserved).
  2. Make the change. Keep functions small and comments about why.
  3. npm test passes. For anything visual, also look at it: node packages/pixel-studio/bin/pixel.mjs preview packages/pixel-studio/examples/<name>.json --out /tmp/x.png.
  4. If you changed a format or behaviour, update packages/pixel-studio/docs/ (and docs/SPEC.md there if agents need to know). If example output changed, run npm run build:demo (and npm run previews).
  5. Add a line to CHANGELOG.md under Unreleased.

New figures, examples and motion presets are very welcome: see “Writing a new figure” in docs/figures.md. Characters you contribute must be your own designs, not recreations of existing characters or games.

Both packages are released together, from one signed tag, with the same version.

  1. npm run version:set -- <version> (for example 0.2.0-alpha.2): sets both versions, pins @pixel-studio/core’s dependency on exactly that runtime, moves the changelog’s Unreleased notes under the version, and refreshes the lockfile. It commits nothing.
  2. Review git diff; commit it signed: git commit -S -am "Release <version>".
  3. Tag it signed and push both: git tag -s v<version> -m "Pixel Studio <version>", then git push origin main v<version>.
  4. The tag runs .github/workflows/release.yml: it checks the tag against both versions, runs the tests, packs both packages, creates the GitHub release (with both tarballs, their SHA-256 and the changelog section) and stages both on npm (pre-releases under their label, alpha, beta, rc).
  5. Approve them with your npm 2FA, @pixel-studio/runtime first (@pixel-studio/core depends on exactly that version): npm stage list, then npm stage approve <stage-id> --otp=<code> for each (npm 11.15.0+), or from the packages’ pages on npmjs.com. The workflow cannot publish on its own: its trusted publisher may only stage.

By contributing you agree that your contributions are licensed under the MIT License.

test/browser/runtime.html checks the runtime in a real browser (open it on any device while npm run studio runs). To run it, and every page of the website’s guide, in Firefox and WebKit, serve both (npm run studio here, and npm run build && npm run preview in website/), install Playwright anywhere outside the project and run the script from there:

Terminal window
mkdir /tmp/pw && cd /tmp/pw && npm i playwright && npx playwright install firefox webkit
node /path/to/pixel-studio/scripts/browser-check.mjs # --browsers firefox,webkit,chromium --base http://localhost:5173 --site http://localhost:4321
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.