Thanks for helping. Pixel Studio is small on purpose: plain ES modules, no dependencies, no build step.
node --version # 20 or newernpm install # links the two packages to each other; there are no third-party dependenciesnpm 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).
Where things are
Section titled “Where things are”| 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 |
Rules the code keeps
Section titled “Rules the code keeps”- No dependencies. Not at runtime, not for tests, not for building. (
@pixel-studio/coredepends on@pixel-studio/runtime, its sibling in this repository, and nothing else.) src/coreis isomorphic. No DOM, no Node APIs. Node-only code goes insrc/node,bin,scripts; browser-only code inpackages/runtimeandstudio.- The runtime never imports the engine. It plays finished bundles, so a site can install it alone.
- Two packages, one version.
@pixel-studio/coreand@pixel-studio/runtimeare always released together with the same version, and@pixel-studio/coredepends 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.
Making a change
Section titled “Making a change”- 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). - Make the change. Keep functions small and comments about why.
npm testpasses. 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.- If you changed a format or behaviour, update
packages/pixel-studio/docs/(anddocs/SPEC.mdthere if agents need to know). If example output changed, runnpm run build:demo(andnpm run previews). - Add a line to
CHANGELOG.mdunder 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.
Releasing
Section titled “Releasing”Both packages are released together, from one signed tag, with the same version.
npm run version:set -- <version>(for example0.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.- Review
git diff; commit it signed:git commit -S -am "Release <version>". - Tag it signed and push both:
git tag -s v<version> -m "Pixel Studio <version>", thengit push origin main v<version>. - 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). - Approve them with your npm 2FA,
@pixel-studio/runtimefirst (@pixel-studio/coredepends on exactly that version):npm stage list, thennpm 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.
License
Section titled “License”By contributing you agree that your contributions are licensed under the MIT License.
Browser checks
Section titled “Browser checks”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:
mkdir /tmp/pw && cd /tmp/pw && npm i playwright && npx playwright install firefox webkitnode /path/to/pixel-studio/scripts/browser-check.mjs # --browsers firefox,webkit,chromium --base http://localhost:5173 --site http://localhost:4321