castle-web-cli 0.4.84 → 0.4.85

package/kits/physics-2d/docs/pxart-format.md

@@ -0,0 +1,377 @@
+# `.pxart` Pixel-Art Format (basic-2d kit)
+
+This documents the `.pxart` sprite format as integrated into the `basic-2d`
+kit. The format and its parser/serializer/renderer live in the kit itself, in
+`engine/pxart.js` (`parseFull`, `serializeFull`, `renderSpriteFrame`, plus
+the compact-form helpers `parseCompact` / `serializeCompact` / `renderToCanvas`).
+`.pxart` is a pure kit-layer concern — the harness (`castle-web-sdk`, the CLI)
+has no knowledge of it.
+
+A sprite is modeled on Aseprite conventions: a `layers × frames` spreadsheet of
+cells, one resolution per sprite, an ordered indexed palette, named animation
+tags, and Aseprite-style linked cells. A `.pxart` file is a single JSON object.
+
+The format has two **coexisting on-disk forms** — capability tiers, *not*
+temporal versions — that the kit treats as one in-memory model:
+
+- **full** — the full layered/animated `Sprite` (`"format": "full"`).
+- **compact** — a flat `{ palette, grid }` object (`"format": "compact"`, or
+  absent). The parser upgrades it into a degenerate one-layer / one-frame
+  Sprite in memory.
+
+> Files in this kit use the extension `.pxart`. They live under `drawings/`
+> and are discovered by `engine/files.js`.
+
+---
+
+## 1. Form discriminator
+
+- Every canonical file carries a top-level string `format`.
+  - `"format": "full"` — the layered/animated sprite.
+  - `"format": "compact"` (or absent) — the flat-grid shorthand (see
+    [§9](#9-compact-shorthand)). The parser upgrades it in memory.
+- `serializeFull` always stamps `"format": "full"`. `serializeCompact` (the
+  compact path the kit's `PxArtEditor` and the `draw` generator use) always
+  stamps `"format": "compact"`.
+- **The two forms are capability tiers, not versions** — `full` is a superset of
+  `compact`. Files of both kinds coexist; a sprite is written in whichever form
+  loses nothing (see [§9](#9-compact-shorthand)).
+- **Detection is by STRUCTURE, not the field.** The parser recognizes the
+  compact form by an object `palette` + a `grid`, and the full form by a
+  `resolution` / array `palette` / `frames` / `layers`. The `format` field is a
+  hint used only to disambiguate genuinely ambiguous shapes; clear structure
+  always wins, so a file with a missing or even mislabeled discriminator still
+  parses (without silent mis-detection). Unknown top-level fields are ignored
+  (forward compatibility).
+
+---
+
+## 2. Resolution
+
+```json
+"resolution": { "width": 16, "height": 16 }
+```
+
+- **Default resolution is 16×16** (`DEFAULT_RESOLUTION`). New/empty sprites and
+  generated art start at 16×16, and the kit's `PxArtEditor` opens a blank canvas
+  at this size.
+- **Power-of-two only**, from **16 to 512**: one of `16, 32, 64, 128, 256, 512`.
+- **One resolution per sprite.** There is no per-layer or per-frame resolution.
+- **Parser policy:**
+  - **Explicit full-form `resolution`:** each dimension is **snapped** to the
+    valid set (clamped to `[16, 512]`, then rounded to the nearest power of two,
+    ties round up). Out-of-range values snap rather than reject, keeping the
+    parser tolerant.
+  - **compact shorthand upgrade:** resolution is inferred from the grid's
+    **native dimensions verbatim** and is **not** snapped, so arbitrary-size
+    compact grids round-trip faithfully.
+
+---
+
+## 3. Palette
+
+```json
+"palette": [
+  { "key": "o", "hex": "#e8b800" },
+  { "key": "y", "hex": "#ffe11a" }
+]
+```
+
+- An **ORDERED array** of `{ key, hex }` entries (indexed-with-hex color mode).
+  - `key`: a **single character** used in packed grid strings.
+  - `hex`: a normalized `#rrggbb` or `#rrggbbaa`.
+- **Ordering is meaningful** — it is the stable index, preserved on parse and
+  serialize.
+- **`.` is reserved for transparent** and is **never** a palette entry. A grid
+  character of `.` (or any char with no matching palette key) renders
+  transparent.
+- Indexed-with-hex only: **not** RGBA-per-pixel, **not** grayscale.
+
+### Two-tier palette system (Endesga-64)
+
+The kit uses a **two-tier** fixed palette, both tiers drawn from Lospec's
+[Endesga 64](https://lospec.com/palette-list/endesga-64). There is no free color
+picking at either tier.
+
+**Full palette — Endesga 64 (`EDG64`, all 64 colors): what USERS paint with.**
+The kit's `PxArtEditor` exposes the **full 64-color swatch** (canonical Lospec
+order). The editor assigns each color a stable single-char key (`KEY_ALPHABET`,
+64 distinct keys) plus `.` for transparent. When an existing sprite is opened for
+editing, each cell's resolved color is **snapped to the nearest Endesga-64
+color** by RGB distance, so editing always stays on the fixed swatch. (Sprites
+still *render* with their own stored palette via `renderSpriteFrame`; the snap
+only affects what the editor writes back.) The swatch UI renders as an 8-column
+grid (8 rows for the 64 colors) that scrolls within the inspector.
+
+**Agent subset — 16 colors (`AGENT_PALETTE_16`): what the LLM generates with.**
+The agent generation path (the `draw` svg-rect → `.pxart` quantizer and the
+prompt the model receives) is constrained to a **fixed 16-color subset of
+Endesga-64**, so generated art stays coherent. Every color below is a member of
+`EDG64`. In order:
+
+```
+#e69c69 #bf6f4a #8a4836 #391f21 #891e2b #ea323c #ffa214 #ffeb57
+#5ac54f #1e6f50 #134c4c #657392 #c7cfdd #ffffff #0cf1ff #0098dc
+```
+
+So: the editor offers all 64 to people; the agent generation path snaps to these
+16. Both constants (`EDG64`, `AGENT_PALETTE_16`) live in the kit's
+`engine/pxart.js`.
+
+---
+
+## 4. Frames & timing
+
+```json
+"frames": [{ "durationMs": 120 }, { "durationMs": 120 }, { "durationMs": 240 }],
+"defaultDurationMs": 120
+```
+
+- `frames`: an array of `{ durationMs }`. Its length is the **frame count**.
+  Frame indices are 0-based.
+- `defaultDurationMs`: applied to any frame missing an explicit `durationMs`
+  (the kit default is 100ms).
+- **No global `fps` field** (matches Aseprite). Holding a frame longer is just a
+  larger `durationMs`.
+
+The kit's `Sprite` behavior advances frames in its `update(dt)` using each
+frame's `durationMs`.
+
+---
+
+## 5. Tags
+
+```json
+"tags": [
+  { "name": "idle",  "from": 0, "to": 1, "direction": "pingpong", "repeat": 0 },
+  { "name": "blink", "from": 2, "to": 2, "direction": "forward",  "repeat": 1 }
+],
+"defaultTag": "idle"
+```
+
+- `tags`: named, inclusive 0-based frame ranges. Each tag has:
+  - `name`: stable handle.
+  - `from`, `to`: inclusive frame indices.
+  - `direction`: `"forward" | "reverse" | "pingpong"`.
+  - `repeat`: play count; **`0` = loop forever**.
+- `defaultTag`: name of the tag that plays by default.
+
+**Animation lives in the file** — ranges and timing are the asset's intrinsic
+property. The placement/runtime layer may override *which* tag plays:
+
+### Actor-side tag override (this kit)
+
+The `Sprite` behavior exposes a `tag` prop. Resolution order:
+
+1. If `tag` is a non-empty string naming a tag in the file, that tag plays.
+2. Otherwise the file's `defaultTag` plays.
+3. Otherwise the whole timeline plays forward, looping.
+
+`direction` and `repeat` come from the tag (a whole-timeline fallback loops
+forever, forward). When `repeat` is exhausted the behavior holds the last frame.
+When the `playing` prop is `false`, the behavior holds frame 0.
+
+---
+
+## 6. Layers
+
+```json
+"layers": [
+  {
+    "id": "body", "name": "Body", "visible": true, "opacity": 1.0,
+    "blendMode": "normal", "kind": "pixel",
+    "cells": [ ... ]
+  }
+]
+```
+
+- `layers`: an **ordered** array, **bottom → top** (`layers[0]` drawn first).
+- Each layer: `id`, `name`, `visible` (skipped when hidden), `opacity`
+  (`0.0`–`1.0`), `blendMode` (**`"normal"` only** for now), `kind`
+  (**`"pixel"` only** for now), and `cells` (its row of the spreadsheet).
+
+`renderSpriteFrame` composites visible layers bottom→top, applying per-layer
+opacity, at 1px/cell with `imageSmoothingEnabled = false`.
+
+---
+
+## 7. Cells
+
+`cells` is **dense-with-`null`**: `layer.cells.length == frames.length`, and
+cell index `f` is the layer's content for frame `f`. A cell is one of:
+
+| Form | Meaning |
+| --- | --- |
+| `{ "grid": ["...", "..."] }` | An image: packed strings using palette keys, one per row. `.` = transparent. |
+| `{ "link": <frameIndex> }` | Aseprite-style **same-layer** reference; shares the image of `cells[frameIndex]`. Edits to the source propagate. |
+| `null` | Empty / fully transparent for this (layer, frame). |
+
+- A `link` must point at a cell index on the **same layer**; the resolver
+  (`resolveCellGrid`) follows the chain to the underlying `{ grid }`, guarding
+  against cycles and invalid indices (resolving to `null` if it can't reach a
+  grid).
+- **Faithful storage:** grids are stored as **packed strings** of palette keys.
+  Generation-only emission shapes (svg-rect, etc.) normalize into this packed
+  form and are never the thing of record.
+
+---
+
+## 8. Coordinates
+
+- **Origin is top-left.** `grid[0]` is the top row; char index 0 is the leftmost
+  column.
+- Units are **pixels** within the sprite's `resolution`. Scaling/placement
+  happen **outside** the file — in this kit, the actor's `Layout` box. The
+  `Sprite` behavior blits the native-resolution frame into the Layout rectangle
+  with smoothing disabled and an optional `tint` multiply.
+
+---
+
+## 9. compact shorthand
+
+A file with a top-level `palette` (an **object** map) + `grid` (no `layers` /
+`frames`) is the **compact flat-grid shorthand**:
+
+```json
+{
+  "format": "compact",
+  "palette": { "y": "#ffe11a", "o": "#e8b800", ".": null },
+  "grid": ["..ooyyoo..", ".oyyyyyyo.", "oyyyyyyyyo"]
+}
+```
+
+It is **sugar for one layer / one frame**, upgraded in memory by `parseFull`
+(via `upgradeCompactToFull`):
+
+- `resolution` ← the grid's native `{ width, height }` (not snapped).
+- `palette` ← the compact record as an ordered array (insertion order), dropping
+  the `.`/null transparent entry.
+- one `frame` using `defaultDurationMs`.
+- one `pixel` layer whose single cell is `{ grid: <the grid> }`.
+
+This keeps cold-start generation tiny: emit just `{ palette, grid }` and the
+system treats it as a full (degenerate) Sprite.
+
+### Single-layer / single-frame generation contract
+
+The **generation contract** for this kit is to emit the **compact shorthand**: a
+single 16×16 (default) `{ palette, grid }` sprite over the agent 16-color subset
+(`AGENT_PALETTE_16`).
+The CLI generation worker and the kit's `PxArtEditor` both produce/store this
+compact form when nothing is lost by it. Multi-layer / multi-frame structure is
+authored by tools later, not hand-generated — and the minimal `PxArtEditor`
+opens such files **read-only** (it only edits the single-layer / single-frame
+case).
+
+### compact ↔ full relationship
+
+- `full` is a **superset** of `compact`; the compact functions keep their exact
+  behavior.
+- A compact file is equivalent to a full sprite with one `pixel` layer and one
+  frame.
+- `parseFull` accepts **both** forms and always yields a full `Sprite`.
+- On save, the kit picks the form **structurally**: it serializes the working
+  sprite to the candidate compact form, re-parses it, and keeps the compact
+  output only when that round-trip reproduces the sprite exactly (`serializeModel`
+  in `editors/pxArtEditorModel.js`). A single fully-opaque visible layer / single
+  inheriting frame / no tags / all on-canvas content round-trips losslessly, so
+  it is stored compact. Anything the compact form can't carry — extra
+  layers/frames/tags, per-layer opacity or visibility, cel offsets, or off-canvas
+  content — forces `serializeFull`. This is a derived fact, not a hand-maintained
+  checklist, so it stays correct as new full-form features are added.
+
+---
+
+## 10. Corner rounding
+
+```json
+"cornerRadius": 0.25
+```
+
+- A top-level **number**: a corner-rounding radius, in native-pixel units.
+  `0` (the default) renders sharp/nearest-neighbor, same as before this field
+  existed. Any value `> 0` renders rounded, by that amount — see "Rendering"
+  below. **File-level** — a property of the sprite asset itself, not a
+  per-actor/per-placement override. There is no equivalent `Sprite` behavior
+  prop.
+- **A value, not a flag**, deliberately: the amount of rounding is itself
+  part of the portable file format, not a fixed code-side constant every
+  smooth sprite would otherwise be stuck with. `MAX_CORNER_RADIUS` (0.5, in
+  `engine/pxart.js`) is the ceiling — two corner cuts on the same
+  1-native-pixel edge must not overlap — and any value is clamped to
+  `[0, MAX_CORNER_RADIUS]` on read. The `PxArtEditor` UI curates this down to
+  a 3-way segmented control (`0` / `¼` / `½`, see `CornerRadiusBar` in
+  `editors/pixelInspector.jsx`) so picking a value never means hunting a
+  slider, but the format itself isn't limited to those three — any in-range
+  number is valid, e.g. from hand-edited JSON or a future finer-grained UI.
+- **`0` is the default** and is never written to disk: `serializeFull` and
+  `serializeCompact` both OMIT the field when it's `0`, so existing (and
+  newly authored, unsmoothed) files stay byte-identical to their
+  pre-`cornerRadius`-field shape.
+- **Present in BOTH on-disk forms.** `parseCompact` reads a top-level
+  `cornerRadius` alongside `palette`/`grid`; `parseFull`'s native-full branch
+  reads it alongside `resolution`/`layers`; `upgradeCompactToFull` carries a
+  compact file's `cornerRadius` through into the upgraded Sprite. This means
+  the kit's save path — which picks compact vs. full by a serialize →
+  re-parse round-trip (`serializeModel` in `editors/pxArtEditorModel.js`, see
+  [§9](#9-compact-shorthand)) — never drops the field: a single-layer/frame
+  rounded sprite still serializes compact, with `cornerRadius: 0.25` alongside
+  `palette`/`grid`.
+- **Parser tolerance:** any non-finite-number value (missing field, `null`, a
+  typo) defaults to `0`. Numbers are clamped to `[0, MAX_CORNER_RADIUS]`.
+  **Legacy back-compat:** this field used to be called `render` — first a
+  `"pixel"` | `"smooth"` string enum, then (briefly) a bare numeric radius
+  under that same key. Both migrate on read: a legacy `render: "smooth"`
+  becomes a fixed radius (`0.25`); a legacy numeric `render` value is read
+  as-is; anything else (including the original `render: "pixel"`) defaults to
+  `0`. This keeps old files rendering rounded rather than silently reverting
+  to sharp. Detection of compact vs. full form ([§1](#1-form-discriminator))
+  is unaffected — neither key is ever used as a structural signal.
+- **Rendering.** `cornerRadius === 0` renders as before: 1px/cell,
+  nearest-neighbor (`renderSpriteFrame`, `imageSmoothingEnabled = false`).
+  `cornerRadius > 0` renders through `engine/pxartSmooth.js`'s
+  `renderSmoothSpriteFrame`, using a LOCAL per-pixel kernel — the same shape
+  of algorithm as Animal Crossing's actual smoothing (xBRZ-style template
+  matching), not a global vectorization pass: it composites the frame
+  normally (so layer visibility/opacity/blend keep working), then for each
+  pixel independently, classifies each of its 4 corners against only the 3
+  pixels touching that corner (its two edge-adjacent neighbors and their
+  shared diagonal neighbor). A corner rounds only when it's a genuine convex
+  corner of that pixel's own color region — a diagonal touch between two
+  same-colored pixels is deliberately left sharp so it doesn't get visually
+  pinched off, and a corner already matched by an adjacent same-color
+  neighbor is left for that neighbor's own (independent) classification to
+  handle. Because the kernel never looks past a pixel's immediate
+  neighborhood, there's no notion of a "run" or "line" to (mis)detect across
+  a whole shape — every pixel supersamples into its own fixed block of the
+  output canvas (by default 8x the sprite's native resolution), so rounding
+  a corner is always a same-block recoloring, never a shape that could leave
+  a gap against its neighbors. This suits small pixel-art sprites, not
+  general raster upscaling.
+- `behaviors/Sprite.jsx` blits a `cornerRadius > 0` sprite's cached canvas
+  with `imageSmoothingEnabled = true` (vs. `false` for `cornerRadius === 0`),
+  passing the sprite's own `cornerRadius` value through as
+  `renderSmoothSpriteFrame`'s `cornerRadius` option; the offscreen canvas
+  cache itself is unaffected (still one WeakMap entry per sprite object —
+  smoothing is a property of the sprite, not an extra cache dimension). The
+  `PxArtEditor` artboard previews rounded sprites live (a display-resolution
+  canvas behind the pixel-grid editing surface) while keeping normal
+  pixel-grid editing/selection interactions on the grid underneath.
+
+---
+
+## 11. Reserved / out of scope
+
+Named so the format can grow without a breaking change, but **not built**:
+tilemap/tileset layers (a future `kind`), slices, layer groups, vector/avatar
+layers, and rich blend modes (beyond `"normal"`). Reserving the `kind` and
+`blendMode` discriminators keeps these additive later, not breaking.
+
+---
+
+## Appendix — sample
+
+`drawings/cauldron.pxart` is a 16×16 multi-layer animated sprite referenced by
+the `pig` actor in `scenes/main.scene` (via `blueprints/cauldron.scene`)
+through the `Sprite` behavior — a working rendered example of the format in
+this kit.

package/kits/physics-2d/drawings/block.pxart

@@ -0,0 +1,25 @@
+{
+  "format": "compact",
+  "palette": {
+    "a": "#c7cfdd",
+    "b": "#657392"
+  },
+  "grid": [
+    "aaaaaaaaaaaaaaaa",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb",
+    "bbbbbbbbbbbbbbbb"
+  ]
+}

package/kits/physics-2d/drawings/cauldron.pxart

@@ -0,0 +1,113 @@
+{
+  "format": "full",
+  "resolution": {
+    "width": 16,
+    "height": 16
+  },
+  "palette": [
+    {
+      "key": "I",
+      "hex": "#5ac54f"
+    },
+    {
+      "key": "1",
+      "hex": "#622461"
+    },
+    {
+      "key": "2",
+      "hex": "#93388f"
+    }
+  ],
+  "frames": [
+    {},
+    {}
+  ],
+  "defaultDurationMs": 500,
+  "tags": [],
+  "cornerRadius": 0.25,
+  "layers": [
+    {
+      "id": "layer-0",
+      "name": "Layer 1",
+      "visible": true,
+      "opacity": 1,
+      "blendMode": "normal",
+      "kind": "pixel",
+      "cells": [
+        {
+          "grid": [
+            "................",
+            "................",
+            "................",
+            "...11111111111..",
+            ".211IIIIIIIII11.",
+            ".22IIIIIIIII221.",
+            "..22222222222...",
+            "...1111111111...",
+            "..222222221111..",
+            ".22222222221111.",
+            ".22222222221111.",
+            ".22222222221111.",
+            ".22222222211111.",
+            "..222222211111..",
+            ".11222211111111.",
+            ".11.11111111.11."
+          ]
+        },
+        {
+          "link": 0
+        }
+      ]
+    },
+    {
+      "id": "layer-1",
+      "name": "Layer 1 copy",
+      "visible": true,
+      "opacity": 1,
+      "blendMode": "normal",
+      "kind": "pixel",
+      "cells": [
+        {
+          "grid": [
+            "...........I....",
+            "....I...........",
+            ".......I........",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................"
+          ]
+        },
+        {
+          "grid": [
+            "...I............",
+            "........I.......",
+            "............I...",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................",
+            "................"
+          ]
+        }
+      ]
+    }
+  ]
+}