@pixel-studio/core 0.0.0-stage → 0.2.0-alpha.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +200 -2
- package/bin/pixel.mjs +313 -0
- package/docs/DESIGN.md +118 -0
- package/docs/README.md +19 -0
- package/docs/SPEC.md +467 -0
- package/docs/api.md +1891 -0
- package/docs/architecture.md +854 -0
- package/docs/cli.md +578 -0
- package/docs/figures.md +476 -0
- package/docs/getting-started.md +85 -0
- package/docs/playground.md +134 -0
- package/docs/runtime.md +664 -0
- package/docs/stage.md +398 -0
- package/examples/fox.json +85 -0
- package/examples/goose-base.json +94 -0
- package/examples/goose-greylag.json +192 -0
- package/examples/goose-kiddie.json +68 -0
- package/examples/goose-phreak.json +69 -0
- package/examples/goose-root.json +136 -0
- package/examples/goose-sudo.json +78 -0
- package/examples/moss.json +1715 -0
- package/examples/pip.json +74 -0
- package/examples/plugins/extras.mjs +53 -0
- package/examples/plugins/starfish.json +21 -0
- package/examples/robot.json +81 -0
- package/examples/slime.json +46 -0
- package/figures/blob.json +19 -0
- package/figures/chibi.json +43 -0
- package/figures/dog.json +60 -0
- package/figures/goose-front.json +56 -0
- package/figures/goose.json +70 -0
- package/figures/human.json +66 -0
- package/package.json +56 -4
- package/references/CREDITS.md +56 -0
- package/references/README.md +92 -0
- package/references/dog.json +167 -0
- package/references/goose-greylag.json +23 -0
- package/references/goose.json +95 -0
- package/references/human.json +281 -0
- package/references/measurements/bird-adjutant-pl774.json +597 -0
- package/references/measurements/bird-cockatoo-pl758.json +746 -0
- package/references/measurements/bird-ostrich-pl772.json +503 -0
- package/references/measurements/bird-pigeon-pl755.json +424 -0
- package/references/measurements/bird-pigeon-pl756.json +433 -0
- package/references/measurements/bird-pigeon-pl757.json +460 -0
- package/references/measurements/bird-vulture-pl765.json +800 -0
- package/references/measurements/bird-vulture-pl768.json +329 -0
- package/references/measurements/dog-pl706.json +196 -0
- package/references/measurements/dog-pl707.json +234 -0
- package/references/measurements/dog-pl708.json +262 -0
- package/references/measurements/dog-pl709.json +347 -0
- package/references/measurements/dog-pl710.json +325 -0
- package/references/measurements/human-pl001.json +1079 -0
- package/references/measurements/human-pl006.json +365 -0
- package/references/measurements/human-pl013.json +283 -0
- package/references/measurements/human-pl060.json +977 -0
- package/references/measurements/human-pl062.json +1183 -0
- package/references/measurements/human-pl064.json +1133 -0
- package/references/measurements/human-pl088.json +887 -0
- package/references/measurements/human-pl109.json +1037 -0
- package/references/measurements/human-pl111.json +365 -0
- package/references/measurements/human-pl152.json +681 -0
- package/references/measurements/human-pl159.json +700 -0
- package/references/measurements/human-pl161.json +660 -0
- package/references/measurements/human-pl162.json +695 -0
- package/references/measurements/human-pl236.json +595 -0
- package/references/measurements/human-pl249.json +556 -0
- package/references/sources.json +794 -0
- package/src/core/animate.js +172 -0
- package/src/core/ascii.js +22 -0
- package/src/core/bundle.js +152 -0
- package/src/core/color.js +112 -0
- package/src/core/export.js +58 -0
- package/src/core/extend.js +161 -0
- package/src/core/figure.js +340 -0
- package/src/core/image.js +61 -0
- package/src/core/index.js +19 -0
- package/src/core/internal.js +10 -0
- package/src/core/lint.js +56 -0
- package/src/core/mix.js +41 -0
- package/src/core/motion.js +521 -0
- package/src/core/plugins.js +96 -0
- package/src/core/png.js +113 -0
- package/src/core/render.js +346 -0
- package/src/core/rig.js +169 -0
- package/src/core/shapes.js +119 -0
- package/src/core/spec.js +457 -0
- package/src/core/textures.js +60 -0
- package/src/node/png.js +9 -0
- package/src/runtime.js +3 -0
- package/src/stage.js +2 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pavel Pascari
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,201 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Pixel Studio
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Agents describe characters; the engine draws them as pixel art at every level of detail; websites play them with one tag.**
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
agent ──JSON rig──▶ engine (SDF raster + pixel-art shader) ──▶ bundle (16/32/64 px sheets) ──▶ <pixel-sprite>
|
|
7
|
+
▲ │
|
|
8
|
+
└──────────── preview PNG / ASCII / validation errors ◀──┘
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Plain ES modules, no build step. Node ≥ 20 for the CLI; any current browser for the runtime. MIT licensed.
|
|
12
|
+
Two packages, always released with the same version:
|
|
13
|
+
|
|
14
|
+
- **`@pixel-studio/core`** (this one): the engine, the `pixel` CLI, the figure library, examples and docs. Its only
|
|
15
|
+
dependency is the runtime.
|
|
16
|
+
- **[`@pixel-studio/runtime`](https://www.npmjs.com/package/@pixel-studio/runtime)**: `<pixel-sprite>` and
|
|
17
|
+
`<pixel-stage>`, the web components that play finished sprites. No dependencies; a site that only shows sprites
|
|
18
|
+
installs just this.
|
|
19
|
+
|
|
20
|
+
Docs and live demos: **[pixel-studio.sh](https://pixel-studio.sh)**.
|
|
21
|
+
|
|
22
|
+
> **Status: alpha.** The engine, CLI and web components work and are tested, and every page of pixel-studio.sh runs
|
|
23
|
+
> on them. The spec and bundle formats may still change before 1.0; each change is listed in the
|
|
24
|
+
> [changelog](../../CHANGELOG.md).
|
|
25
|
+
|
|
26
|
+
## Five minutes to a goose on your page
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm i @pixel-studio/core # brings @pixel-studio/runtime, nothing else
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Make a character by changing an example (`my-goose.json`):
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{ "extends": "./node_modules/@pixel-studio/core/examples/goose-base.json",
|
|
36
|
+
"name": "Marigold",
|
|
37
|
+
"materials": { "feather": { "color": "#e8b04a" }, "beak": { "color": "#d94b32" } } }
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx pixel validate my-goose.json # errors with JSON paths and did-you-mean
|
|
42
|
+
npx pixel preview my-goose.json --out my-goose.png # every animation at 16, 32 and 64 px
|
|
43
|
+
npx pixel bundle my-goose.json --out my-goose.bundle.json
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```html
|
|
47
|
+
<script type="module" src="node_modules/@pixel-studio/runtime/src/pixel-sprite.js"></script>
|
|
48
|
+
<pixel-sprite src="my-goose.bundle.json" anim="idle" size="128" hover-anim="waddle" click-anim="honk"></pixel-sprite>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The full walk-through is [docs/getting-started.md](docs/getting-started.md).
|
|
52
|
+
|
|
53
|
+
Characters can also live on the page itself: walk along cards, jump between them, climb their sides, sit on edges
|
|
54
|
+
and hide behind things ([docs/stage.md](docs/stage.md)):
|
|
55
|
+
|
|
56
|
+
```html
|
|
57
|
+
<script type="module" src="pixel-stage.js"></script>
|
|
58
|
+
<article class="card" data-pixel-surface data-pixel-climbable>…</article>
|
|
59
|
+
<pixel-stage><pixel-actor src="goose.bundle.json" size="64"></pixel-actor></pixel-stage>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## The CLI: the agent's hands and eyes
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npx pixel validate examples/fox.json
|
|
66
|
+
npx pixel preview examples/fox.json --out fox.png # every animation × 16/32/64 px
|
|
67
|
+
npx pixel ascii examples/fox.json --res 24 --anim walk # text view for agents without vision
|
|
68
|
+
npx pixel where examples/goose-root.json --anim honk # world positions of pivots, per frame
|
|
69
|
+
npx pixel resolve examples/goose-sudo.json # a variant merged with its base
|
|
70
|
+
npx pixel bundle examples/fox.json --out fox.bundle.json
|
|
71
|
+
npx pixel export examples/fox.json --res 32 --out game/ # PNG + Aseprite JSON (Phaser, PixiJS)
|
|
72
|
+
npx pixel figures # the skeleton library
|
|
73
|
+
npx pixel brief # the agent brief (system prompt)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
(In a clone of the repository, run `node bin/pixel.mjs` from `packages/pixel-studio/` instead of `npx pixel`, and
|
|
77
|
+
the example paths work as written. Working on Pixel Studio itself: see
|
|
78
|
+
[CONTRIBUTING.md](../../CONTRIBUTING.md).)
|
|
79
|
+
|
|
80
|
+
## Documentation
|
|
81
|
+
|
|
82
|
+
Start with [docs/getting-started.md](docs/getting-started.md), or read everything on
|
|
83
|
+
[pixel-studio.sh](https://pixel-studio.sh/docs/). The reference docs, also in this package's `docs/`:
|
|
84
|
+
|
|
85
|
+
| doc | covers |
|
|
86
|
+
|---|---|
|
|
87
|
+
| [docs/getting-started.md](docs/getting-started.md) | Install, write a character, preview, bundle, put it on a page. |
|
|
88
|
+
| [docs/SPEC.md](docs/SPEC.md) | The character spec. It doubles as the agent brief. |
|
|
89
|
+
| [docs/figures.md](docs/figures.md) | Figures, motion models, follow-through, writing a new figure. |
|
|
90
|
+
| [docs/runtime.md](docs/runtime.md) | `<pixel-sprite>`, the bundle format, events, attachment points, state machines, skins, moving sprites on a page. |
|
|
91
|
+
| [docs/stage.md](docs/stage.md) | `<pixel-stage>`: characters that walk, jump, climb, sit and hide on a real page. |
|
|
92
|
+
| [docs/cli.md](docs/cli.md) | Every CLI command and flag. |
|
|
93
|
+
| [docs/api.md](docs/api.md) | The JavaScript API. |
|
|
94
|
+
| [docs/playground.md](docs/playground.md) | The playground page: a character set up entirely by its URL, for people and browser agents. |
|
|
95
|
+
| [docs/architecture.md](docs/architecture.md) | How the engine works inside, and how to extend it. |
|
|
96
|
+
| [docs/DESIGN.md](docs/DESIGN.md) | Why it is designed this way. |
|
|
97
|
+
|
|
98
|
+
## What's in this package
|
|
99
|
+
|
|
100
|
+
| Path | What |
|
|
101
|
+
|---|---|
|
|
102
|
+
| `src/core/` | The isomorphic engine: spec validation (JSON paths + did-you-mean), figures and motion models, rig maths and IK, variants, SDF shapes, the rasterizer and pixel-art shader (hue-shifted ramps, lighting, textures, dither, outlines, inner lines, contact shadows), sheets, bundles, export, ASCII, plug-ins. |
|
|
103
|
+
| `src/node/png.js` | The Node PNG encoder the CLI uses. |
|
|
104
|
+
| `src/runtime.js`, `src/stage.js` | `@pixel-studio/core/runtime` and `@pixel-studio/core/stage`: re-export [`@pixel-studio/runtime`](https://www.npmjs.com/package/@pixel-studio/runtime), the web components. |
|
|
105
|
+
| `bin/pixel.mjs` | The CLI. `--plugin` loads plug-ins (shapes, textures, motion models; see `examples/plugins/`). |
|
|
106
|
+
| `figures/` | The **figure library**: `goose` (and `goose-front` for its front and back views), `human`, `dog`, `chibi` (front-facing), `blob` (soft body). |
|
|
107
|
+
| `examples/` | Characters: `goose-base` and its variants `goose-root`, `-sudo`, `-phreak`, `-kiddie`, `-greylag`; `pip`; `fox`, `slime`, `robot` (written by a separate agent that only had `SPEC.md` and the CLI); `moss`. |
|
|
108
|
+
| `references/` | Where motion data comes from: every source cited, every measured value and frame logged ([references/README.md](references/README.md), credits in [references/CREDITS.md](references/CREDITS.md)). |
|
|
109
|
+
| `docs/` | The reference docs above. |
|
|
110
|
+
|
|
111
|
+
The studio (live JSON editor, onion skin, all detail levels at once, an **Agent** tab), the figure viewer, the
|
|
112
|
+
playground and the demo pages live in the [repository](https://github.com/pavelpascari/pixel-studio) and run on
|
|
113
|
+
[pixel-studio.sh](https://pixel-studio.sh/gallery/).
|
|
114
|
+
|
|
115
|
+
## Levels of detail and texture
|
|
116
|
+
|
|
117
|
+
The same spec renders at any resolution. The detail tier changes how it is drawn:
|
|
118
|
+
|
|
119
|
+
| tier | default at | tones | texture | dither | outline | extras |
|
|
120
|
+
|---|---|---|---|---|---|---|
|
|
121
|
+
| 1 icon | ≤ 20 px | 2 | off | off | dark | brighter ambient, only `minDetail: 1` shapes |
|
|
122
|
+
| 2 sprite | 21–40 px | 3 | 60% | off | selective | contact shadows |
|
|
123
|
+
| 3 portrait | > 40 px | 5 | 100% | on | selective | inner lines between overlapping parts |
|
|
124
|
+
|
|
125
|
+
Textures: `noise fur scales stripes checker cloth bricks spots metal`. They are evaluated in each part's local space, so they stick to moving limbs. Materials can also carry `shine`, `flat`, and `outline: false`. Every knob can be overridden per spec (`style`) or live in the studio.
|
|
126
|
+
|
|
127
|
+
## The agent loop, tested
|
|
128
|
+
|
|
129
|
+
To check the premise, I gave a fresh agent only `docs/SPEC.md` and the CLI and asked for three characters. It produced `fox`, `slime` and `robot` through about three preview-and-revise rounds each. Its friction report drove these engine fixes:
|
|
130
|
+
|
|
131
|
+
- Eyes and other detail parts cast contact shadows that looked like tears. Fixed: flat and `outline:false` materials no longer cast them.
|
|
132
|
+
- Seams appeared where same-material shapes overlapped. Fixed: they are now lit as one surface (union SDF).
|
|
133
|
+
- Typos like `minDetal` were ignored silently. Fixed: unknown keys produce warnings with did-you-mean.
|
|
134
|
+
- `sx`/`sy` waves centred on 0. Fixed: they now oscillate around 1.
|
|
135
|
+
- The icon tier was too dark. Fixed: it gets an ambient boost.
|
|
136
|
+
- The brief was missing several things: a style-key table, pivot = scale origin, pixel-grid alignment for tiny features, and no small head rotations.
|
|
137
|
+
|
|
138
|
+
Still open: tiny features are at the mercy of the pixel grid (at 16 px the fox's four legs merge), and there is no
|
|
139
|
+
alpha or glow.
|
|
140
|
+
|
|
141
|
+
## Authoring helpers (added while building the goose flock)
|
|
142
|
+
|
|
143
|
+
Each one came from a specific problem building the geese:
|
|
144
|
+
|
|
145
|
+
| problem | feature |
|
|
146
|
+
|---|---|
|
|
147
|
+
| Four geese were four copied 700-line files that drifted apart | **`extends` variants**: a base rig plus about 45 lines of differences per goose (patch/add/remove parts, merge materials and animations, `materialMap`) |
|
|
148
|
+
| Getting the beak onto the keyboard meant guessing three joint angles per frame | **`reach` constraints**: name the chain, the tip point and an animatable target (optionally the head's `aim`); the engine solves the angles each frame |
|
|
149
|
+
| A honk pushed the head off-canvas and I only noticed in previews | **Bounds warnings**: "`head` goes 8.2 units past the right edge in frames 2–7" from `validate`, the CLI and the studio status bar |
|
|
150
|
+
| Unreachable targets fail silently | **Reach warnings**: by how much, which frames, and what to relax |
|
|
151
|
+
| Hard to tell where a joint actually is mid-animation | `pixel where` on the CLI and the **rig** toggle in the studio (pivots, bones, reach targets turning red when missed) |
|
|
152
|
+
|
|
153
|
+
## Figures and motion models
|
|
154
|
+
|
|
155
|
+
Skeletons are dots and lines with realistic motion models. A character picks a figure (`"figure": "goose"`), dresses its bones with shapes, and gets its motions:
|
|
156
|
+
|
|
157
|
+
- **gait** (walk, run, trot, sneak). Feet are planted with IK and swing on real paths. The hips rise and fall with the legs, a four-legged figure's back pitches, and the head keeps its gaze steady. Each gait exports a `speed`, so a page that moves the sprite at that speed gets no foot sliding. The flock uses this.
|
|
158
|
+
- **idle**: breathing and weight shifting over planted feet.
|
|
159
|
+
- **pose**: your keyframes drive the body and the feet stay planted.
|
|
160
|
+
- **hop**: a gravity arc with volume-preserving squash and stretch, a lean into the jump, and a ground shadow that shrinks in the air.
|
|
161
|
+
- **Front view** (`chibi`): walking toward the viewer, the hips shift over the standing foot and lifted legs foreshorten.
|
|
162
|
+
- **Follow-through**: `"follow"` springs make tails, ears, hoods and straps lag, overshoot and settle.
|
|
163
|
+
- **For life on a page**: `jump` (crouch, launch, tuck, land), `climb` (feet holding a wall, with a `speedY`), `fall`,
|
|
164
|
+
`sit` on an edge, and `duck`/`peek` presets. Motions report events (`footstep`, `launch`, `land`), and figures define
|
|
165
|
+
attachment points (`beak`, `head`, hands) and the foot line, all baked into bundles.
|
|
166
|
+
|
|
167
|
+
Author tracks layer on top of the motion. **Every example is dressed on a figure:** the geese on `goose`, Ember on `dog`
|
|
168
|
+
(fitted: shorter neck, bushy tail), Pip and Bolt on `chibi` (Bolt fitted to its boxier proportions, with a springy antenna),
|
|
169
|
+
and Gloop on `blob`. phreak's sneak is the `sneak` preset plus a floppy disk, and honks, headbangs and waves are `pose` motions.
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
npx pixel figures # list the library
|
|
173
|
+
npx pixel preview dog # a bare figure: its skeleton, every motion
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Agent tab (Claude in the browser)
|
|
177
|
+
|
|
178
|
+
In the studio, in the [repository](https://github.com/pavelpascari/pixel-studio) (`npm run studio`).
|
|
179
|
+
|
|
180
|
+
Describe a character, then **Generate**: Claude writes the spec, the studio validates it, and any validation errors go back to Claude for a fix. **Look & refine** renders a contact sheet (16/32/64 × every animation), sends the image back, and asks Claude to critique it like a pixel artist and return a revised spec.
|
|
181
|
+
|
|
182
|
+
- Your API key is stored only in `localStorage`. Requests go directly from the browser to the API (`dangerouslyAllowBrowser`), which is fine for a local prototype but not for a hosted app. A hosted version needs a small server-side proxy.
|
|
183
|
+
- The default model is `claude-opus-5-5`, with adaptive thinking at effort `medium`. The server-side fallback beta is on (`fallbacks: "default"`), so a safety-classifier refusal is routed to a fallback model instead of failing. To turn it off, remove `betas`/`fallbacks` in `studio/agent.js`.
|
|
184
|
+
- The SDK loads from esm.sh on first use, so the rest of the studio works offline.
|
|
185
|
+
- **This path has not been run end-to-end yet; it needs your key.** The extraction and validation-repair logic is exercised; the live API call isn't.
|
|
186
|
+
|
|
187
|
+
## Known limitations and out of scope
|
|
188
|
+
|
|
189
|
+
- The spec and bundle formats are not frozen until 1.0.
|
|
190
|
+
- Parts are rigid: no mesh deformation, no pixel-level touch-up layers, no palette constraints across characters.
|
|
191
|
+
- No GIF/APNG export; PNG sheets, Aseprite JSON and bundles only.
|
|
192
|
+
- The studio's Agent tab is a local prototype (see above).
|
|
193
|
+
|
|
194
|
+
See [docs/DESIGN.md](docs/DESIGN.md) and the research notes in the repository's [docs/research/](../../docs/research/).
|
|
195
|
+
|
|
196
|
+
## Contributing and license
|
|
197
|
+
|
|
198
|
+
See [CONTRIBUTING.md](../../CONTRIBUTING.md). Pixel Studio is released under the [MIT License](LICENSE).
|
|
199
|
+
Motion data comes only from public-domain and openly licensed sources (Muybridge's plates, published measurements);
|
|
200
|
+
each is credited in [references/CREDITS.md](references/CREDITS.md).
|
|
201
|
+
The studio's optional Agent tab loads the Anthropic SDK (MIT) from esm.sh at runtime; nothing third-party is bundled.
|
package/bin/pixel.mjs
ADDED
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Pixel Studio CLI — the agent's hands and eyes.
|
|
3
|
+
//
|
|
4
|
+
// pixel validate <spec.json> check a spec, print errors with JSON paths
|
|
5
|
+
// pixel preview <spec.json> [--out p.png] [--res 16,32,64] [--cell 128] [--anim a,b]
|
|
6
|
+
// contact sheet: every animation (or those named) × every LOD tier
|
|
7
|
+
// pixel ascii <spec.json> [--res 24] [--anim idle] [--frame 0|all]
|
|
8
|
+
// a frame as text (for agents without vision)
|
|
9
|
+
// pixel render <spec.json> [--res 32] [--out dir] [--lod 1|2|3] [--tones n] [--texture 0..1] ...
|
|
10
|
+
// sprite sheet PNG + JSON metadata
|
|
11
|
+
// pixel export <spec.json> [--res 32] [--out dir] [--format aseprite]
|
|
12
|
+
// sheet PNG + Aseprite JSON (Phaser, PixiJS)
|
|
13
|
+
// pixel bundle <spec.json> [--res 16,32,64] [--views front,back|none] [--external] [--out file.bundle.json]
|
|
14
|
+
// self-contained web bundle for <pixel-sprite> (all skins);
|
|
15
|
+
// --external writes the sheets as PNG files beside it
|
|
16
|
+
// pixel resolve <variant.json> [--out full.json] print a variant ("extends") merged with its base
|
|
17
|
+
// pixel where <spec.json> [--anim a] [--frame f] [--part id --point x,y]
|
|
18
|
+
// world positions of part pivots (or of a point on a part)
|
|
19
|
+
// pixel figures list the figure library (skeletons + motions)
|
|
20
|
+
// pixel preview goose any command takes a bare figure name instead of a spec
|
|
21
|
+
//
|
|
22
|
+
// --skin <name> (preview, ascii, render, export, where): use one of the spec's skins
|
|
23
|
+
// style flags (preview, ascii, render, export, bundle): --lod 1|2|3 --tones n --texture 0..1 --dither true|false
|
|
24
|
+
// --outline dark|selective|none --light deg --flip
|
|
25
|
+
// pixel brief print the agent brief (spec format docs)
|
|
26
|
+
// pixel help this text
|
|
27
|
+
//
|
|
28
|
+
// --plugin ./a.mjs,./b.mjs (any command): register plug-in shapes, textures and motion models first
|
|
29
|
+
// errors print as one line and exit 1; PIXEL_DEBUG=1 adds the stack trace
|
|
30
|
+
import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
|
|
31
|
+
import { basename, dirname, join, resolve } from 'node:path';
|
|
32
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
33
|
+
import {
|
|
34
|
+
validate, compile, renderSheet, renderAnimation, renderFrame, resolveStyle,
|
|
35
|
+
contactSheet, frameToAscii, buildBundle, exportSheet, usePlugin, registeredPlugins, DETAIL_NAMES, resolveSpec, checkBounds, MAX_RES,
|
|
36
|
+
} from '../src/core/index.js';
|
|
37
|
+
import { samplePose, worldMatrices } from '../src/core/internal.js';
|
|
38
|
+
import { encodePNG } from '../src/node/png.js';
|
|
39
|
+
|
|
40
|
+
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
41
|
+
|
|
42
|
+
const BOOLEAN_FLAGS = new Set(['flip', 'external']); // never take the next argument as their value
|
|
43
|
+
|
|
44
|
+
function parseArgs(argv) {
|
|
45
|
+
const args = { _: [] };
|
|
46
|
+
for (let i = 0; i < argv.length; i++) {
|
|
47
|
+
const a = argv[i];
|
|
48
|
+
if (a.startsWith('--')) {
|
|
49
|
+
const eq = a.indexOf('='), k = eq < 0 ? a.slice(2) : a.slice(2, eq), v = eq < 0 ? undefined : a.slice(eq + 1);
|
|
50
|
+
args[k] = v ?? (!BOOLEAN_FLAGS.has(k) && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true);
|
|
51
|
+
} else args._.push(a);
|
|
52
|
+
}
|
|
53
|
+
return args;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function readJSON(path) {
|
|
57
|
+
let text;
|
|
58
|
+
try { text = readFileSync(path, 'utf8'); } catch (e) { fail(`cannot read ${path}: ${e.message}`); }
|
|
59
|
+
try { return JSON.parse(text); } catch (e) { fail(`${path} is not valid JSON: ${e.message}`); }
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Load a spec, resolve its "extends" chain (paths relative to the file that names them) and its "figure". */
|
|
63
|
+
async function loadSpec(path) {
|
|
64
|
+
if (!path) fail('missing <spec.json>');
|
|
65
|
+
// A bare figure name ("goose") previews that figure's skeleton.
|
|
66
|
+
const spec = !path.endsWith('.json') && figureNames().includes(path) ? { figure: path } : readJSON(path);
|
|
67
|
+
const absOf = new Map();
|
|
68
|
+
try {
|
|
69
|
+
return await resolveSpec(spec, {
|
|
70
|
+
loadRef: (ref, from) => {
|
|
71
|
+
const abs = resolve(dirname(from ? absOf.get(from) : resolve(path)), ref);
|
|
72
|
+
absOf.set(ref, abs);
|
|
73
|
+
return JSON.parse(readFileSync(abs, 'utf8'));
|
|
74
|
+
},
|
|
75
|
+
loadFigure: (name) => JSON.parse(readFileSync(join(ROOT, 'figures', `${name}.json`), 'utf8')),
|
|
76
|
+
warn: (p, m) => console.error(`warning ${p}: ${m}`),
|
|
77
|
+
});
|
|
78
|
+
} catch (e) { fail(`${path}: ${e.message}`); }
|
|
79
|
+
}
|
|
80
|
+
const figureNames = () => readdirSync(join(ROOT, 'figures')).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5));
|
|
81
|
+
|
|
82
|
+
function printBounds(c, log = console.error) {
|
|
83
|
+
const w = checkBounds(c);
|
|
84
|
+
for (const x of w) log(`warning ${x.path}: ${x.message}`);
|
|
85
|
+
return w;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function fail(msg) { console.error(`error: ${msg}`); process.exit(1); }
|
|
89
|
+
|
|
90
|
+
function compileOrExit(spec) {
|
|
91
|
+
const { errors, warnings } = validate(spec);
|
|
92
|
+
for (const w of warnings) console.error(`warning ${w.path}: ${w.message}`);
|
|
93
|
+
if (errors.length) {
|
|
94
|
+
for (const e of errors) console.error(`error ${e.path}: ${e.message}`);
|
|
95
|
+
process.exit(1);
|
|
96
|
+
}
|
|
97
|
+
let c = compile(spec);
|
|
98
|
+
if (args.skin && cmd !== 'bundle') {
|
|
99
|
+
// Preview, render or inspect one skin (bundle always bakes all of them).
|
|
100
|
+
if (!c.skins?.[args.skin]) { console.error(`error unknown skin "${args.skin}" (skins: ${Object.keys(c.skins ?? {}).join(', ') || 'none'})`); process.exit(1); }
|
|
101
|
+
c = c.skins[args.skin];
|
|
102
|
+
}
|
|
103
|
+
printBounds(c);
|
|
104
|
+
return c;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** A numeric flag, or a clear error naming what was typed. */
|
|
108
|
+
const numFlag = (a, k) => {
|
|
109
|
+
if (a[k] == null) return undefined;
|
|
110
|
+
const n = Number(a[k]);
|
|
111
|
+
if (a[k] === true || !Number.isFinite(n)) fail(`--${k} must be a number (got "${a[k] === true ? '' : a[k]}")`);
|
|
112
|
+
return n;
|
|
113
|
+
};
|
|
114
|
+
const overridesFrom = (a) => ({
|
|
115
|
+
lod: a.lod ? numFlag(a, 'lod') : undefined,
|
|
116
|
+
tones: numFlag(a, 'tones'),
|
|
117
|
+
texture: numFlag(a, 'texture'),
|
|
118
|
+
dither: a.dither != null ? a.dither !== 'false' : undefined,
|
|
119
|
+
outline: a.outline === true ? fail('--outline needs a value: dark, selective or none') : a.outline,
|
|
120
|
+
light: numFlag(a, 'light'),
|
|
121
|
+
flip: a.flip && a.flip !== 'false' ? true : undefined,
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
const resList = (v, d) => {
|
|
125
|
+
const list = String(v ?? d).split(',').map(Number);
|
|
126
|
+
if (!list.length || list.some((n) => !Number.isInteger(n) || n <= 0 || n > MAX_RES)) fail(`--res must be whole numbers 1..${MAX_RES}, e.g. 16,32,64 (got "${v}")`);
|
|
127
|
+
return list;
|
|
128
|
+
};
|
|
129
|
+
const oneRes = (v, d) => {
|
|
130
|
+
if (v != null && String(v).includes(',')) fail(`--res takes one resolution here (got "${v}"); use bundle or preview for several`);
|
|
131
|
+
return resList(v, d)[0];
|
|
132
|
+
};
|
|
133
|
+
/** --frame n, wrapped into 0..frames-1 (so -1 is the last frame). */
|
|
134
|
+
const frameIndex = (v, frames) => { const n = Math.trunc(Number(v) || 0); return ((n % frames) + frames) % frames; };
|
|
135
|
+
function animOrExit(c, name) {
|
|
136
|
+
const key = name ?? Object.keys(c.animations)[0];
|
|
137
|
+
if (!c.animations[key]) fail(`no animation "${name}" (have: ${Object.keys(c.animations).join(', ')})`);
|
|
138
|
+
return key;
|
|
139
|
+
}
|
|
140
|
+
const stem = (p) => basename(p).replace(/\.json$/, '');
|
|
141
|
+
const pngDataURL = (w, h, rgba) => 'data:image/png;base64,' + encodePNG(w, h, rgba).toString('base64');
|
|
142
|
+
|
|
143
|
+
// Anything that throws becomes one line on stderr and exit code 1 (PIXEL_DEBUG=1 shows the stack).
|
|
144
|
+
// A closed pipe (`pixel ascii … | head`) is not an error, and the handler must never run twice: writing the
|
|
145
|
+
// message to a closed stderr would throw again.
|
|
146
|
+
let crashing = false;
|
|
147
|
+
const crash = (e) => {
|
|
148
|
+
if (e?.code === 'EPIPE') process.exit(0);
|
|
149
|
+
if (crashing) process.exit(1);
|
|
150
|
+
crashing = true;
|
|
151
|
+
try { console.error(`error: ${e?.message ?? e}`); if (process.env.PIXEL_DEBUG) console.error(e?.stack); } finally { process.exit(1); }
|
|
152
|
+
};
|
|
153
|
+
process.on('uncaughtException', crash);
|
|
154
|
+
process.on('unhandledRejection', crash);
|
|
155
|
+
|
|
156
|
+
const [cmd, ...rest] = process.argv.slice(2);
|
|
157
|
+
const args = parseArgs(rest);
|
|
158
|
+
// Plug-ins (--plugin ./a.mjs,./b.mjs): register shapes, textures and motion models before anything runs.
|
|
159
|
+
if (args.plugin) {
|
|
160
|
+
for (const p of String(args.plugin).split(',')) {
|
|
161
|
+
try { await usePlugin(await import(pathToFileURL(resolve(p.trim())).href)); }
|
|
162
|
+
catch (e) { fail(`--plugin ${p}: ${e.message}`); }
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
switch (cmd) {
|
|
167
|
+
case 'figures': {
|
|
168
|
+
for (const n of figureNames()) {
|
|
169
|
+
const f = JSON.parse(readFileSync(join(ROOT, 'figures', `${n}.json`), 'utf8'));
|
|
170
|
+
console.log(`${n.padEnd(8)} ${f.bones.length} bones motions: ${Object.entries(f.motions ?? {}).map(([k, m]) => `${k}(${m.model ?? 'gait'})`).join(' ')}`);
|
|
171
|
+
if (f.description) console.log(` ${f.description}`);
|
|
172
|
+
console.log(` bones: ${f.bones.map((b) => b.id).join(' ')}`);
|
|
173
|
+
}
|
|
174
|
+
break;
|
|
175
|
+
}
|
|
176
|
+
case 'validate': {
|
|
177
|
+
const spec = await loadSpec(args._[0]);
|
|
178
|
+
const { errors, warnings } = validate(spec);
|
|
179
|
+
for (const w of warnings) console.log(`warning ${w.path}: ${w.message}`);
|
|
180
|
+
for (const e of errors) console.log(`error ${e.path}: ${e.message}`);
|
|
181
|
+
if (errors.length) process.exit(1);
|
|
182
|
+
const c = compile(spec);
|
|
183
|
+
printBounds(c, console.log);
|
|
184
|
+
const anims = Object.values(c.animations).map((a) => `${a.name}(${a.frames}f@${a.fps}fps)`).join(' ');
|
|
185
|
+
console.log(`ok: "${c.name}" ${c.parts.length} parts, ${Object.keys(c.materials).length} materials, animations: ${anims}`);
|
|
186
|
+
break;
|
|
187
|
+
}
|
|
188
|
+
case 'preview': {
|
|
189
|
+
const c = compileOrExit(await loadSpec(args._[0]));
|
|
190
|
+
const ov = overridesFrom(args);
|
|
191
|
+
const previewAnims = args.anim ? String(args.anim).split(',').map((n) => animOrExit(c, n.trim())) : Object.keys(c.animations);
|
|
192
|
+
const blocks = resList(args.res, '16,32,64').map((res) => ({
|
|
193
|
+
res,
|
|
194
|
+
rows: previewAnims.map((n) => ({ name: n, frames: renderAnimation(c, n, res, ov).frames })),
|
|
195
|
+
}));
|
|
196
|
+
const img = contactSheet(blocks, { cellH: Number(args.cell) || 128 });
|
|
197
|
+
const out = args.out || `${stem(args._[0])}.preview.png`;
|
|
198
|
+
mkdirSync(dirname(resolve(out)), { recursive: true });
|
|
199
|
+
writeFileSync(out, encodePNG(img.w, img.h, img.rgba));
|
|
200
|
+
console.log(`wrote ${out} (${img.w}x${img.h})`);
|
|
201
|
+
console.log(`blocks top→bottom: ${blocks.map((b) => `${b.res}px [${DETAIL_NAMES[resolveStyle(c, b.res, ov).lod]}]`).join(', ')}`);
|
|
202
|
+
console.log(`rows per block: ${previewAnims.join(', ')}`);
|
|
203
|
+
break;
|
|
204
|
+
}
|
|
205
|
+
case 'ascii': {
|
|
206
|
+
const c = compileOrExit(await loadSpec(args._[0]));
|
|
207
|
+
const res = oneRes(args.res, 24);
|
|
208
|
+
const anim = animOrExit(c, args.anim);
|
|
209
|
+
const frames = args.frame === 'all'
|
|
210
|
+
? [...Array(c.animations[anim].frames).keys()]
|
|
211
|
+
: [frameIndex(args.frame, c.animations[anim].frames)];
|
|
212
|
+
const style = resolveStyle(c, res, overridesFrom(args));
|
|
213
|
+
for (const f of frames) {
|
|
214
|
+
const fr = renderFrame(c, { res, anim, frame: f, style });
|
|
215
|
+
const { text, legend } = frameToAscii(fr);
|
|
216
|
+
console.log(`${anim} frame ${f} @${res}px legend: ${Object.entries(legend).map(([k, v]) => `${v}=${k}`).join(' ')} #=outline .=empty`);
|
|
217
|
+
console.log(text + '\n');
|
|
218
|
+
}
|
|
219
|
+
break;
|
|
220
|
+
}
|
|
221
|
+
case 'render': {
|
|
222
|
+
const c = compileOrExit(await loadSpec(args._[0]));
|
|
223
|
+
const res = oneRes(args.res, 32);
|
|
224
|
+
const sheet = renderSheet(c, res, overridesFrom(args));
|
|
225
|
+
const dir = args.out || '.';
|
|
226
|
+
mkdirSync(dir, { recursive: true });
|
|
227
|
+
const base = `${stem(args._[0])}.${res}`;
|
|
228
|
+
writeFileSync(join(dir, `${base}.png`), encodePNG(sheet.width, sheet.height, sheet.rgba));
|
|
229
|
+
writeFileSync(join(dir, `${base}.json`), JSON.stringify({ name: c.name, image: `${base}.png`, ...sheet.meta }, null, 2));
|
|
230
|
+
console.log(`wrote ${join(dir, base)}.png (${sheet.width}x${sheet.height}) + .json`);
|
|
231
|
+
break;
|
|
232
|
+
}
|
|
233
|
+
case 'export': {
|
|
234
|
+
// Aseprite-format JSON (Phaser) with a PixiJS animations map, plus the PNG sheet.
|
|
235
|
+
const c = compileOrExit(await loadSpec(args._[0]));
|
|
236
|
+
const res = oneRes(args.res, 32);
|
|
237
|
+
if ((args.format ?? 'aseprite') !== 'aseprite') { console.error('error --format: only "aseprite" (also read by Phaser and PixiJS)'); process.exit(1); }
|
|
238
|
+
const dir = args.out || '.';
|
|
239
|
+
mkdirSync(dir, { recursive: true });
|
|
240
|
+
const base = `${stem(args._[0])}${args.skin ? `.${args.skin}` : ''}.${res}`;
|
|
241
|
+
const ex = exportSheet(c, res, { image: `${base}.png`, overrides: overridesFrom(args) });
|
|
242
|
+
writeFileSync(join(dir, `${base}.png`), encodePNG(ex.width, ex.height, ex.rgba));
|
|
243
|
+
writeFileSync(join(dir, `${base}.json`), JSON.stringify(ex.json, null, 2));
|
|
244
|
+
console.log(`wrote ${join(dir, base)}.png (${ex.width}x${ex.height}) + .json (${Object.keys(ex.json.frames).length} frames, ${ex.json.meta.frameTags.length} tags, ${ex.json.meta.slices.length} slices)`);
|
|
245
|
+
break;
|
|
246
|
+
}
|
|
247
|
+
case 'bundle': {
|
|
248
|
+
const c = compileOrExit(await loadSpec(args._[0]));
|
|
249
|
+
// --views front | front,back | none: which extra views (front, back, …) to ship; default all.
|
|
250
|
+
const views = args.views == null ? undefined : String(args.views) === 'none' ? [] : String(args.views).split(',').map((s) => s.trim()).filter(Boolean);
|
|
251
|
+
const bundle = await buildBundle(c, { resolutions: resList(args.res, '16,32,64'), overrides: overridesFrom(args), encode: pngDataURL, views });
|
|
252
|
+
const out = args.out || `${stem(args._[0])}.bundle.json`;
|
|
253
|
+
mkdirSync(dirname(resolve(out)), { recursive: true });
|
|
254
|
+
// --external: sheets as PNG files next to the bundle, so a page downloads only the one it shows.
|
|
255
|
+
if (args.external) {
|
|
256
|
+
const name = basename(out).replace(/\.bundle\.json$|\.json$/, '');
|
|
257
|
+
for (const v of bundle.variants) for (const key of ['image', 'overlay']) {
|
|
258
|
+
if (typeof v[key] !== 'string' || !v[key].startsWith('data:image/png;base64,')) continue;
|
|
259
|
+
// Skin names come from the spec: keep them to a safe slug so the file stays beside the bundle.
|
|
260
|
+
const slug = (x) => String(x).replace(/[^A-Za-z0-9_-]+/g, '_');
|
|
261
|
+
const file = `${slug(name)}.${Number(v.res)}${v.skin ? `.${slug(v.skin)}` : ''}${key === 'overlay' ? '.overlay' : ''}.png`;
|
|
262
|
+
const dir = dirname(resolve(out)), target = resolve(dir, file);
|
|
263
|
+
if (basename(file) !== file || dirname(target) !== dir) fail(`--external: refusing to write ${file} outside ${dir}`);
|
|
264
|
+
writeFileSync(target, Buffer.from(v[key].slice(22), 'base64'));
|
|
265
|
+
v[key] = file;
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
const json = JSON.stringify(bundle);
|
|
269
|
+
writeFileSync(out, json);
|
|
270
|
+
console.log(`wrote ${out} (${(json.length / 1024).toFixed(1)} KB, variants: ${bundle.variants.map((v) => v.skin ? `${v.res} (${v.skin})` : v.res).join(', ')})`);
|
|
271
|
+
break;
|
|
272
|
+
}
|
|
273
|
+
case 'resolve': {
|
|
274
|
+
const json = JSON.stringify(await loadSpec(args._[0]), null, 2);
|
|
275
|
+
if (args.out) { writeFileSync(args.out, json + '\n'); console.log(`wrote ${args.out}`); } else console.log(json);
|
|
276
|
+
break;
|
|
277
|
+
}
|
|
278
|
+
case 'where': {
|
|
279
|
+
const c = compileOrExit(await loadSpec(args._[0]));
|
|
280
|
+
const anim = c.animations[animOrExit(c, args.anim)];
|
|
281
|
+
const frame = frameIndex(args.frame, anim.frames);
|
|
282
|
+
const pose = samplePose(c, anim, frame);
|
|
283
|
+
const { world, visible } = worldMatrices(c.parts, pose);
|
|
284
|
+
const at = (m, [x, y]) => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]].map((v) => +v.toFixed(1));
|
|
285
|
+
console.log(`${anim.name} frame ${frame} (canvas ${c.size.join('x')} units)`);
|
|
286
|
+
if (args.part) {
|
|
287
|
+
const p = c.parts.find((q) => q.id === args.part);
|
|
288
|
+
if (!p) fail(`no part "${args.part}"`);
|
|
289
|
+
const pt = args.point ? String(args.point).split(',').map(Number) : p.pivot;
|
|
290
|
+
console.log(`${p.id} [${pt}] (rest) → [${at(world.get(p.id), pt)}] rot ${pose.get(p.id).rot.toFixed(1)}°`);
|
|
291
|
+
} else {
|
|
292
|
+
for (const p of c.parts) {
|
|
293
|
+
const t = pose.get(p.id);
|
|
294
|
+
console.log(`${p.id.padEnd(12)} pivot [${p.pivot}] → [${at(world.get(p.id), p.pivot)}] rot ${t.rot.toFixed(1)}°${visible.get(p.id) ? '' : ' (hidden)'}`);
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
break;
|
|
298
|
+
}
|
|
299
|
+
case 'brief': {
|
|
300
|
+
process.stdout.write(readFileSync(join(ROOT, 'docs/SPEC.md'), 'utf8'));
|
|
301
|
+
const extra = registeredPlugins();
|
|
302
|
+
if (extra.length) process.stdout.write(`\n## Plug-ins loaded for this project\n\n${extra.map((p) => `- ${p.kind} \`${p.name}\`${p.describe ? `: ${p.describe}` : ''}`).join('\n')}\n`);
|
|
303
|
+
break;
|
|
304
|
+
}
|
|
305
|
+
case 'help': case '--help': case '-h': case undefined:
|
|
306
|
+
default:
|
|
307
|
+
{
|
|
308
|
+
const lines = readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(1); // skip the #! line
|
|
309
|
+
const header = lines.slice(0, lines.findIndex((l) => !l.startsWith('//')));
|
|
310
|
+
console.log(header.map((l) => l.slice(3)).join('\n'));
|
|
311
|
+
}
|
|
312
|
+
process.exit(!cmd || ['help', '--help', '-h'].includes(cmd) ? 0 : 1);
|
|
313
|
+
}
|
package/docs/DESIGN.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Pixel Studio — PoC design (working backwards)
|
|
2
|
+
|
|
3
|
+
## 1. Start from the end: what does a website need?
|
|
4
|
+
|
|
5
|
+
A character animation that lives on a web page has to be:
|
|
6
|
+
|
|
7
|
+
| Need on the page | Consequence for the system |
|
|
8
|
+
|---|---|
|
|
9
|
+
| Crisp at any CSS size, no blur | Integer-scaled pixels, `image-rendering: pixelated`, canvas sized to the sprite's native resolution |
|
|
10
|
+
| Tiny and fast (hero, buttons, 404 pages, docs) | Bake to a sprite sheet (PNG) + a few hundred bytes of metadata; one small runtime file (`pixel-sprite.js`, about 15 KB gzipped); no framework |
|
|
11
|
+
| Drop-in embed | One custom element: `<pixel-sprite src="fox.bundle.json" anim="idle">` |
|
|
12
|
+
| Interactive | Named animations + `hover-anim` / `click-anim`, a `play()` API, `pixel-end` events |
|
|
13
|
+
| Responsive | Several resolutions per character (like `srcset`): the runtime picks the one that fits the rendered size |
|
|
14
|
+
| Polite | Honours `prefers-reduced-motion`, pauses off-screen |
|
|
15
|
+
|
|
16
|
+
So the **output artifact** is a *bundle*: `{ animations, variants: [{res, image(PNG)}, ...] }`.
|
|
17
|
+
|
|
18
|
+
## 2. One step back: what produces a bundle?
|
|
19
|
+
|
|
20
|
+
A renderer that takes a **character description** and a **render setting** (resolution, detail level,
|
|
21
|
+
texture, outline, light) and emits frames. The key question is: *what is the character description?*
|
|
22
|
+
|
|
23
|
+
### Why not "agents paint pixels"?
|
|
24
|
+
|
|
25
|
+
LLM agents are bad at long 2D pixel grids: coordinates drift, symmetry breaks, a 64×64 frame is 4096
|
|
26
|
+
cells, and every animation frame has to be repainted consistently. Hand-painted grids also don't give
|
|
27
|
+
you levels of detail for free: a 16px and a 64px version are two separate drawings.
|
|
28
|
+
|
|
29
|
+
### What agents *are* good at
|
|
30
|
+
|
|
31
|
+
Structured, semantic, compositional descriptions: "a head is an ellipse here, the arm is a capsule from
|
|
32
|
+
the shoulder to the hand, it swings ±25° over the walk cycle". That is a scene graph, and it is
|
|
33
|
+
resolution-independent.
|
|
34
|
+
|
|
35
|
+
### Decision: agents author a semantic rig, the engine rasterizes it into pixel art
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
Agent ──writes──▶ Character spec (JSON)
|
|
39
|
+
materials · parts (shapes, pivots, z, parent) · animations (tracks per part)
|
|
40
|
+
│
|
|
41
|
+
▼
|
|
42
|
+
Rasterizer (per frame, per resolution)
|
|
43
|
+
SDF shapes → coverage at pixel centres → material/part/normal per pixel
|
|
44
|
+
│
|
|
45
|
+
▼
|
|
46
|
+
Pixel-art shader (the "detail & texture" knobs)
|
|
47
|
+
tone ramps with hue shifting · lighting quantized to ramp ·
|
|
48
|
+
procedural textures in part space · ordered dither · outlines/selout ·
|
|
49
|
+
inner lines
|
|
50
|
+
│
|
|
51
|
+
▼
|
|
52
|
+
Frames → sprite sheet → bundle ──▶ <pixel-sprite> on a website
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Because geometry is rasterized fresh for every frame and every resolution:
|
|
56
|
+
|
|
57
|
+
- **LOD is free**: the same spec renders at 16, 32, 64 px. Shapes can opt in/out per detail tier
|
|
58
|
+
(`minDetail`) so a 16px icon drops eyebrows and buttons instead of turning them into noise.
|
|
59
|
+
- **Animation is cheap to author**: tracks move/rotate/scale parts; rotation doesn't smear pixels
|
|
60
|
+
(we never rotate a bitmap).
|
|
61
|
+
- **Texture moves with the body**: procedural textures are evaluated in each part's local space, so
|
|
62
|
+
fur/scales/cloth stick to the limb instead of swimming.
|
|
63
|
+
|
|
64
|
+
## 3. What "levels of detail and texture" means concretely
|
|
65
|
+
|
|
66
|
+
Three detail tiers, each a preset of shader knobs (all overridable):
|
|
67
|
+
|
|
68
|
+
| Tier | Typical res | Tones per material | Texture | Dither | Outline | Inner lines | Shapes |
|
|
69
|
+
|---|---|---|---|---|---|---|---|
|
|
70
|
+
| 1 · icon | ≤ 20 px | 2 | off | off | dark | off | `minDetail ≤ 1 ≤ maxDetail` |
|
|
71
|
+
| 2 · sprite | 21–40 px | 3 | 60% | off | selective | off | `minDetail ≤ 2 ≤ maxDetail` |
|
|
72
|
+
| 3 · portrait | > 40 px | 5 | 100% | on | selective | on | `minDetail ≤ 3 ≤ maxDetail` |
|
|
73
|
+
|
|
74
|
+
Texture vocabulary (per material): `noise, fur, scales, stripes, checker, cloth, bricks, spots, metal`.
|
|
75
|
+
Materials also carry `shine` (specular), `flat` (no shading — eyes, emissive bits) and `outline: false`.
|
|
76
|
+
|
|
77
|
+
Pixel-art craft baked in, so agents don't need to know it:
|
|
78
|
+
- **hue-shifted ramps** (shadows drift cool, highlights drift warm) instead of plain darken/lighten
|
|
79
|
+
- **selective outline** (outline tinted by the neighbouring material) instead of pure black
|
|
80
|
+
- **thin-feature preservation**: a shape thinner than a pixel still gets 1 px instead of vanishing
|
|
81
|
+
- **pixel-snapped motion**: part offsets snap to whole pixels at each resolution
|
|
82
|
+
- **far-side shading**: `part.shade: -0.3` for the far arm/leg (figures set it automatically) (classic depth cue)
|
|
83
|
+
|
|
84
|
+
## 4. The agent loop (the "studio for agents" part)
|
|
85
|
+
|
|
86
|
+
An agent needs to *see* what it drew. The PoC gives three loops:
|
|
87
|
+
|
|
88
|
+
1. **CLI (any coding agent, e.g. Claude Code)** — `node bin/pixel.mjs validate|preview|ascii|render|export|bundle|resolve|where|figures|brief`
|
|
89
|
+
(see [cli.md](cli.md)).
|
|
90
|
+
`preview` writes a contact sheet PNG (all animations × LOD tiers) the agent can look at;
|
|
91
|
+
`ascii` prints a frame as text for agents without vision. Validation errors carry JSON paths.
|
|
92
|
+
2. **Studio UI (human + agent)** — live JSON editor, animated preview, LOD strip, sprite sheet,
|
|
93
|
+
shader knobs, export.
|
|
94
|
+
3. **In-studio Claude loop** — describe a character → Claude writes the spec → the studio renders a
|
|
95
|
+
contact sheet → sends the image back to Claude to critique and revise. (Needs your API key.)
|
|
96
|
+
|
|
97
|
+
`docs/SPEC.md` is the single source of truth for the format and doubles as the agent system prompt.
|
|
98
|
+
|
|
99
|
+
## 5. Non-goals for the PoC
|
|
100
|
+
|
|
101
|
+
- Frame-by-frame hand editing / pixel painting tools (a later "touch-up layer" could store per-frame
|
|
102
|
+
pixel overrides on top of the rig).
|
|
103
|
+
- Mesh deformation, tweened easing curves editor. (Skeletal IK and palette-swap skins were on this list; IK now exists
|
|
104
|
+
as `reach` constraints and the figure motion models, see [figures.md](figures.md), and skins as patches of
|
|
105
|
+
materials and parts stored as recolours in the bundle, see [SPEC.md](SPEC.md#skins).)
|
|
106
|
+
- Server, accounts, storage. Everything is static files + Node with zero dependencies.
|
|
107
|
+
|
|
108
|
+
## 6. Open questions for after the PoC
|
|
109
|
+
|
|
110
|
+
- ~~Is the rig expressive enough for non-humanoids (wings, tails, tentacles) — add chains/bones?~~ Resolved: figures
|
|
111
|
+
are bone chains with `wings`, `tail` and four-legged roles, `follow` springs for trailing parts, and plug-in motion
|
|
112
|
+
models ([figures.md](figures.md)).
|
|
113
|
+
- Should agents get a **touch-up pass** (pixel overrides per LOD tier) for faces, where geometry
|
|
114
|
+
rasterization is weakest at 16px?
|
|
115
|
+
- Palette constraints per site (brand palettes, limited global palette across characters)?
|
|
116
|
+
- ~~Export targets beyond the web component~~ Partly resolved: `pixel export` writes a sheet PNG with Aseprite JSON
|
|
117
|
+
(Phaser, PixiJS) and `pixel render` a plain sheet with metadata. GIF/APNG, a CSS `steps()` sprite and Lottie-like JSON
|
|
118
|
+
remain open.
|