castle-web-cli 0.4.115 → 0.4.117

package/kits/physics-2d/scripts/svg-emission-guide.md

@@ -0,0 +1,92 @@
+## Path-layer sprites (SVG paths → stacked path-layer `.sprite`)
+
+Emit a tiny vector SVG — silhouette-first shapes on a design grid — and pipe it
+to `node scripts/import-svg.mjs <name>`. The importer turns each SVG element into
+one **shape** in document order (painter's order). Coordinates are stored as
+floats in cubic segment form (`{ closed, start, segs: [{ to, c1?, c2? }] }`).
+The layer's `grid` is always baked from the shape stack on write — pixels remain
+truth.
+
+> The legacy extension `.pxart` names the same format and remains readable; emit
+> and create new art as `.sprite`.
+
+- **Resolution is 16×16.** Use `viewBox="0 0 16 16"`. Coordinates are in that
+  design grid (pixel corners at integers, centers at `n+0.5`). Prefer a modest
+  anchor count; curves are cheap (a `C` segment is still just its two endpoint
+  anchors) — what to avoid is tracing detail with many tiny segments.
+- **Palette is the agent 16-color subset** — every `fill` / `stroke` should be
+  one of:
+
+  `#e69c69` `#bf6f4a` `#8a4836` `#391f21` `#891e2b` `#ea323c` `#ffa214` `#ffeb57`
+  `#5ac54f` `#1e6f50` `#134c4c` `#657392` `#c7cfdd` `#ffffff` `#0cf1ff` `#0098dc`
+
+  (Off-palette colors snap to the nearest of these. Prefer staying on-palette.)
+- **Curves are encouraged — use them for anything organic.** Bodies, leaves,
+  canopies, bellies, petals: use `C`/`Q`/`A` path segments (or a `circle`/`ellipse`).
+  A curve segment costs only its two anchors. Reserve straight-line polygons for
+  genuinely hard-edged subjects (blades, boxes, buildings). Curves import as cubic
+  segments with relative handles; S-curves split at inflections automatically.
+  Circles and ellipses materialize as four kappa cubics.
+- **Supported elements:** `<path d>`, `<polygon points>`, `<polyline points>`,
+  `<rect>` (rx/ry ignored), `<circle>`, `<ellipse>`, plain `<g>` (grouping only).
+- **Supported path commands:** `M L H V Q C A Z` (absolute and relative). Smooth
+  `S`/`T` are accepted (normalized to `C`/`Q`). Arcs (`A`/`a`) split into ≤90°
+  cubic segments.
+- **Presentation:** `fill` and `stroke` as attributes or in `style` — when both
+  are present, inline `style` wins (SVG spec). Use `fill="none"` for unfilled
+  outlines. Strokes are always 1px after import — ignore `stroke-width` / opacity
+  / filters. Stroke is per-shape (whole outline or none) — not per segment.
+- **Fill rule:** Castle renders multi-subpath fills with **even-odd** winding.
+  SVG defaults to nonzero. For holes and compound silhouettes, emit
+  `fill-rule="evenodd"` (or structure art so even-odd matches your intent).
+  Importer notes warn when multiple closed subpaths arrive without an explicit
+  even-odd rule.
+- **Optional dark outline:** a 1px stroke in `#391f21` (or another dark agent
+  color) around a filled silhouette reads well at 16×16.
+- **Overlap and occlusion are native.** Later shapes paint over earlier ones
+  (fill then stroke within each shape). Same-color stacks union visually; later
+  fills correctly hide earlier strokes. You do **not** need to merge same-color
+  blobs or avoid stroking stretches that will be covered.
+- **Underlap idiom.** Build art as a ground shape plus overlays that extend
+  generously underneath. A shared boundary should be owned by the **top** shape.
+  Avoid stroking both of two abutting shapes along a shared seam — that
+  double-strokes the seam and looks thicker than intended. Prefer: bottom shape
+  fill (optional stroke on its outer silhouette only); top shape fill that
+  overlaps the seam; stroke only the top shape's visible outline when needed.
+- **Fill vs stroke phase.** Storage accepts floats — no lattice snap at import.
+  Fill-only shapes may use integer corners freely. Stroked shapes with any
+  integer-phase coordinate get a uniform +0.05 cell nudge so 1px strokes avoid
+  bad rasterization at pixel corners; fill-only shapes are not nudged. The
+  half-cell magnetic lattice is an **editor-only** guide (§6.1.2), not enforced
+  on import.
+- **Minimum feature size is one cell at 16×16.** Draw eyes and dots as a
+  1×1 `<rect>` on a whole cell (or a circle with `r ≥ 0.8` centered on a
+  pixel center — coordinates like `5.5`), never tiny sub-cell circles. A
+  two-tone detail (eye + pupil) needs at least 2 cells or it cannot survive.
+  Keep enclosed shapes at least ~2 cells across their narrow axis.
+- **Do not emit:** `transform` attributes, transformed `<g>`, gradients,
+  `<text>`, `<image>`, or anything outside the subset above.
+
+**Run it** (sprite name as the arg; stdin is the svg):
+
+```bash
+printf '<svg viewBox="0 0 16 16"><circle cx="8" cy="8" r="5" fill="#5ac54f" stroke="#391f21"/></svg>' \
+  | node scripts/import-svg.mjs blob
+```
+
+writes `drawings/blob.sprite`. You can also pass `--from file.svg` instead of
+stdin. Use `--size 32` only when you intentionally author a 32×32 viewBox.
+Use `--pixel` to bake to a compact pixel-only `.sprite` (no path source).
+
+A curvy silhouette with an overlay accent (later shape covers earlier stroke):
+
+```xml
+<svg viewBox="0 0 16 16">
+  <path d="M 3 13 C 3 7 6 3 13 3 C 13 9 10 13 3 13 Z"
+        fill="#5ac54f" stroke="#1e6f50"/>
+  <circle cx="6" cy="7" r="1.2" fill="#391f21"/>
+</svg>
+```
+
+**After writing new sprites referenced by the scene, `npm run restart`** so the
+deck's file glob picks them up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.115",
+  "version": "0.4.117",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"