pixelkiln 0.62.0 → 0.63.0

package/docs/CHARACTERS.md

@@ -296,6 +296,45 @@ who holds a sword in the right hand holds it in the left when facing the
 mirrored way. Most games accept that; if yours does not, generate both
 sides. `adopt` skips mirrors, since there is nothing upstream to adopt.
 
+### One loop, several directions
+
+Writing each direction out is five near-identical loops and three mirrors
+for a full walk. `directions` on an animation says the same thing once:
+
+```json
+"bot.walk": {
+  "prompt": "walking forward in place, short legs stepping, body bobbing slightly",
+  "animation": { "of": "bot", "frames": 12, "fps": 12, "directions": ["south", "west", "north", "south-west", "north-west"] }
+}
+```
+
+When the manifest loads, this becomes exactly the assets it stands for: one
+loop per named direction (`bot.walk.south`, `bot.walk.west`, ...), each with
+every field of the shorthand and its own `direction`, plus a mirror for each
+direction whose flip is not named (`bot.walk.east` mirrors `bot.walk.west`,
+`bot.walk.south-east` mirrors `bot.walk.south-west`, `bot.walk.north-east`
+mirrors `bot.walk.north-west`). Eight directions for five generations. Name
+both sides of a pair (`["west", "east"]`) to generate both instead of
+mirroring, which is the fix for a character whose handedness matters. The
+mirrors carry the shorthand's `category`, `tags`, and `styles`.
+
+- The expanded ids are ordinary assets: `plan`, the gallery, the lockfile,
+  and `pack` all see `bot.walk.west` and `bot.walk.east`, never `bot.walk`.
+  Rewriting the shorthand into explicit assets by hand changes no identity
+  and regenerates nothing.
+- `--only bot.walk` selects the whole family; `--only bot.walk.west` one
+  member of it.
+- `direction` and `directions` are mutually exclusive, and fields that name
+  one output (`file`, `cell`, `remoteId`, `source`, `sourceByStyle`,
+  `outputRole`) are refused on a shorthand, since every direction would
+  claim them. An expanded id that is already declared is an error, not an
+  override.
+- The gallery's `--edit` changes the shorthand, not one direction: editing
+  `bot.walk.west` there is refused with a pointer to `bot.walk`. A revision,
+  state, or new loop can still name an expanded asset as its parent. To
+  change one direction alone, write it out as its own asset and drop it
+  from `directions`.
+
 Engines that flip sprites at draw time (Godot's `flip_h`, Unity's
 `flipX`) do not need mirrored files at all. Declare only the directions
 you generate and flip in the engine; mirrors are for pipelines that want

package/docs/MANIFEST.md

@@ -66,7 +66,7 @@ not merely a label edit.
 | `remoteId` | string | The provider's own id for art that already exists on the account, so `adopt` maps it without matching bytes: an object id, a character id, or `<character id>#<animation group id>`. Not part of the spec's identity. |
 | `revision` | object | Controlled image-to-image or inpaint dependency. See [controlled revisions](REVISIONS.md). |
 | `state` | object | `character` styles: a pose or outfit of another character asset. See [Characters](./CHARACTERS.md). |
-| `animation` | object | `character` styles: a loop of another character asset in one direction. See [Characters](./CHARACTERS.md). |
+| `animation` | object | `character` styles: a loop of another character asset in one direction. `directions` (a list, instead of `direction`) declares the loop for several directions at once and fills the unnamed flips with mirrors; see [One loop, several directions](./CHARACTERS.md#one-loop-several-directions). |
 | `mirror` | string | Another asset of the same style flipped left to right, made locally at no cost. See [Mirrors](./CHARACTERS.md#mirrors). |
 | `batch` | object | `1dir` styles: rides along on another `1dir` asset's `item_descriptions` submission instead of generating on its own — `{ "of": "<leader asset id>", "index": <1-based slot> }`. See [`1dir`](./GENERATORS.md#1dir). |
 | `pieces` | array | `uiAsset` styles: exact shape regions (`rounded_rect`/`circle`/`polygon`) the panel is composited from, each with a unique `id`. See [`uiAsset`](./GENERATORS.md#uiasset). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/schema/manifest.schema.json

@@ -1153,6 +1153,23 @@
                     ],
                     "default": "south"
                   },
+                  "directions": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "south",
+                        "south-east",
+                        "east",
+                        "north-east",
+                        "north",
+                        "north-west",
+                        "west",
+                        "south-west"
+                      ]
+                    },
+                    "minItems": 1
+                  },
                   "frames": {
                     "type": "integer",
                     "minimum": 4,

package/skills/pixelkiln/SKILL.md

@@ -48,7 +48,9 @@ hashes.
   dependent asset the same way: one `pixelkiln gen` runs the waves in order
   and stops when the budget cannot cover the next one. Before declaring the
   east-facing loop of a character, check whether a `mirror` of the west one
-  does the job for nothing; before drawing a base from text, ask whether the
+  does the job for nothing (an animation's `directions` list declares the
+  generated sides once and mirrors the rest; `--only <shorthand id>`
+  selects the whole family); before drawing a base from text, ask whether the
   user has a south-facing sprite to `reference` instead (1 generation on
   `pro-flash` at 64px). Mirrors swap handedness.
 - Treat every ComfyUI output as source material until it passes the native-grid,