pixelkiln 0.90.0 → 0.91.0

package/docs/CHARACTERS.md

@@ -252,14 +252,44 @@ character from it, with no template to pick. `frames` takes PixelLab's own
   `skeleton-v3` loop. Measured live on a v3 character: 8 frames at 64px billed
   exactly 3 generations for one direction, about 15 seconds before the jobs
   start. `billed` in the lock records the real amount.
-- **Directions do not share one motion yet.** PixelLab draws every direction
-  of a request from one 3D motion, and `animation_group_id` appends a
-  direction to an existing animation so it moves the same way. pixelkiln
-  makes one request per direction asset (including each direction of
-  `directions`), so each direction's motion is written from the sentence
-  separately and may differ a little. Appending to a recorded group is not
-  wired up; the lock keeps each direction's `animationGroupId` for when it is.
-  Verified live is a single south direction only.
+- **Directions share the first direction's motion.** PixelLab draws every
+  direction of an animation from one 3D motion, and `animation_group_id`
+  adds a direction to an existing animation so it moves the same way. The
+  first direction listed in `directions` leads and is submitted as a new
+  animation; every later direction follows in the next wave and is sent into
+  the leader's group (with the group's own name as `animation_name`, since
+  PixelLab does not inherit it). Each direction is still its own asset and
+  request, billed separately; mirrors flip a direction and join nothing. The
+  expansion writes `animation.motionFrom: "<leader id>"` on each later
+  direction, and you can write it yourself when declaring the loops
+  explicitly. It is part of the asset's identity; the leader's hash, a single
+  direction's, and every template or other loop's are unchanged.
+  - **Adding a direction later**: append it to `directions` (new directions
+    at the end, so the leader stays the same). The leader is already
+    downloaded and current, so the new direction goes straight into its
+    recorded group, with no regeneration of the others. Putting a new
+    direction first makes it the leader and the old one a follower, which
+    regenerates both.
+  - **Regenerating**: a regenerated leader is a new animation with a new group,
+    so followers drawn into the old group show `stale` ("shares motion with
+    `<leader>`, which was regenerated") and are redrawn into the new one.
+    Restoring an older generation brings back the group it was drawn into.
+    The lock keeps it as `motionShare: { sourceAssetId, animationGroupId }`.
+  - **Replacing**: only an asset's own direction is ever deleted, from the
+    group it is in, so redrawing a follower never removes the leader's
+    animation or the reverse. This relies on PixelLab keeping a group alive
+    while any direction remains, and on a follower keeping its motion after
+    the leader's direction is deleted; neither is verified.
+  - **Fallback**: a leader with no recorded `animationGroupId` (generated
+    before groups were recorded, or adopted without one) does not block its
+    followers. Each is drawn as its own request and animation, as before, and
+    `plan` says so; its `motionShare.animationGroupId` is `null`. If the
+    leader's recorded group is gone from the character, the follower fails
+    before spending and asks you to regenerate the leader.
+  - Verified against mocked HTTP only; not yet run live. A single south
+    direction was verified live through PixelKiln on an adopted v3 character:
+    "jumping with joy and pumping both fists", 8 frames at 96×96, billed 3,
+    with `animationId` and `animationGroupId` saved in the lock.
 
 ### Pose frames and other loop controls
 

package/docs/ENDPOINTS.md

@@ -922,9 +922,16 @@ generations and finished in about two minutes:
   added with `animation_group_id` move the same way (humanoids). pixelkiln
   sends this mode for a character loop with `mode: "skeleton-v3"`, a prompt,
   and no template (docs/CHARACTERS.md, "Loops from a sentence"), one request
-  per direction asset and without `animation_group_id`. Verified live with
-  one south direction on a v3 character; a standard-engine character is
-  refused (`has no stored 3D skeleton`).
+  per direction asset. The first direction of a `directions` loop is sent
+  without `animation_group_id`; each later one is sent after it with the
+  leader's recorded `animation_group_id` and the group's own `animation_name`
+  (not inherited, so omitting it would rename the group). That append is
+  **mock-verified only**: the request shape follows the tool's documentation
+  and a live append has not been run. Verified live twice
+  with one south direction on a v3 character, once by a direct call and once
+  through `pixelkiln gen` (a manifest loop on an `adopt`ed character, 8
+  frames at 96×96, billed 3, then `pick` and `fetch`); a standard-engine
+  character is refused (`has no stored 3D skeleton`).
 
 ## Characters, measured
 

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 dependency on another asset: `image-to-image`, `inpaint`, or `outpaint`; on PixelLab also `reduce-colors`, `correct-pixelart`, `remove-background`, `normal-map`, the animate modes (`animate`, `animate-pixminimax`, `animate-skeleton`), `interpolate`, and `edit-animation`. `engine: "pro-flash"` selects PixelLab's Pro Flash tier for `image-to-image`/`inpaint`. 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. `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). `mode: "skeleton-v3"` with no `template` animates the asset's `prompt` as a sentence (3–15 `frames`, default 8; a v3 base); see [Loops from a sentence](./CHARACTERS.md#loops-from-a-sentence). |
+| `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). `mode: "skeleton-v3"` with no `template` animates the asset's `prompt` as a sentence (3–15 `frames`, default 8; a v3 base); see [Loops from a sentence](./CHARACTERS.md#loops-from-a-sentence). `motionFrom` (an asset id) makes a sentence loop follow another direction's loop and share its motion; `directions` writes it for you. |
 | `portrait` | object | `character` styles: a bust of a base or state's south sprite, `{ "of": "<asset>", "size": 64 }`; `size` is 16, 32, 48, 64 (default), 128, or 160. See [Portraits](./CHARACTERS.md#portraits). |
 | `outfit` | object | `character` styles: an existing loop's frames re-clothed from an outfit image, `{ "of": "<loop asset>", "reference": "<image>" }`, with optional `additionalInstructions`. See [Outfit transfer](./CHARACTERS.md#outfit-transfer). |
 | `mirror` | string | Another asset of the same style flipped left to right, made locally at no cost. See [Mirrors](./CHARACTERS.md#mirrors). |

package/docs/PIXELLAB.md

@@ -100,6 +100,52 @@ beside the submit-time `cost` estimate a wave budget spends against;
 `pixelkiln history`, `plan --json`, and the gallery show both when they
 differ (docs/ENDPOINTS.md, "Limits and billing").
 
+## Custom animation on skeleton v3
+
+PixelLab's character creator can now animate a character on its skeleton v3
+model from a sentence or from skeletons you pose, and the same two paths are
+in the API. PixelKiln sends both from a manifest.
+
+A loop with `mode: "skeleton-v3"` and no `template` animates its `prompt`:
+
+```jsonc
+"hero.cheer": {
+  "prompt": "cheerfully waving both arms overhead",
+  "animation": { "of": "hero", "mode": "skeleton-v3", "frames": 8, "directions": ["south"] }
+}
+```
+
+An `animate-skeleton` revision poses the sprite along skeletons you give it.
+`pixelkiln estimate-skeleton` writes the file from an image, you edit the
+joints, and `skeleton-preview` draws them over the sprite before you spend:
+
+```jsonc
+"hero-wave": {
+  "prompt": "wave",
+  "styles": ["rig"],
+  "revision": {
+    "mode": "animate-skeleton", "from": "hero",
+    "keypointsFile": "poses/wave.json", "direction": "south",
+    "description": "cheerful adventurer with short auburn hair, blue tunic"
+  }
+}
+```
+
+- Both need a v3 character. A `standard` base has no 3D skeleton for the model
+  to pose, so `plan` refuses the loop and names the engine.
+- The revision's `prompt` is the motion ("wave") and its `description` is how
+  the character looks. PixelLab requires both, and `plan` refuses a revision
+  without a description.
+- Each billed exactly 3 generations for 8 frames, measured live. The sentence
+  loop came back at 96×96 from a 64px character; the posed one stayed 64×64.
+  [The home page](https://pixelkiln.griffen.codes/#updates) shows both.
+- Each direction of a sentence loop is its own request for now, so a loop with
+  several directions can move a little differently in each. PixelLab can draw
+  every direction from one motion, but PixelKiln does not send that yet.
+
+See [Loops from a sentence](./CHARACTERS.md#loops-from-a-sentence) and
+[Skeleton-driven animation](./REVISIONS.md#skeleton-driven-animation).
+
 ## What changed in PixelLab 0.4.130
 
 PixelLab 0.4.130 (October 2026) added four things. PixelKiln covers each:

package/package.json

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

package/schema/manifest.schema.json

@@ -1305,6 +1305,10 @@
                     },
                     "minItems": 1
                   },
+                  "motionFrom": {
+                    "type": "string",
+                    "minLength": 1
+                  },
                   "frames": {
                     "type": "integer",
                     "minimum": 3,

package/skills/pixelkiln/references/pixellab-roadmap.md

@@ -35,8 +35,16 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `mode: "skeleton-v3"`, no `template`, and a `prompt` animates the sentence
   on `/characters/animations` (`action_description`, 3 to 15 `frames`). Billed
   exactly 3 generations for 8 frames at 64px, frames back at 96×96; the plan
-  budgets 4. See `docs/CHARACTERS.md`, "Loops from a sentence". Shared motion
-  across directions is not wired up (one request per direction asset).
+  budgets 4. See `docs/CHARACTERS.md`, "Loops from a sentence".
+- **Shared motion across the directions of a sentence loop** — the first
+  direction of `directions` is submitted as a new animation; each later one
+  follows in the next wave with the leader's recorded `animation_group_id` and
+  the group's `animation_name`, so every direction is drawn from one 3D motion
+  (`animation.motionFrom`, lock `motionShare`). Adding a direction to a
+  generated loop appends into its group, a regenerated leader marks followers
+  stale, and a leader with no recorded group falls back to one request per
+  direction. **Mock-verified only; live proof pending** (a live append, and that
+  deleting one direction leaves the group and the others' motion intact).
 
 - **Skeleton-v3 template loops** — `/characters/animations`'
   `mode: "skeleton-v3"` poses a template with the skeleton video model
@@ -524,17 +532,6 @@ missing:
   Aseprite. pixelkiln has no frame-set concatenation; `lastFrame` can pin a
   clip's ending to another clip's frame file, but the two sets stay separate.
 
-## Sentence-driven skeleton-v3 loops, shared motion across directions
-
-PixelLab's sentence loops (`mode: "skeleton-v3"`, no template) are supported;
-see "Already closed". What is still open: every direction of one request is
-drawn from one 3D motion, and `animation_group_id` appends a direction to an
-existing animation so it moves the same way. pixelkiln makes one request per
-direction asset and never sends the group id, so each direction's motion is
-written separately. Closing it means linking the direction assets of a
-`directions` loop to one group (a batch like `1dir`'s, or the recorded
-`animationGroupId` of a sibling) and passing it on the later requests.
-
 ## Map Workshop (scene composition)
 
 PixelLab's actual scene-building surface: lay out a tile floor, place

package/skills/pixelkiln/references/pixellab.md

@@ -398,8 +398,11 @@ and `pro-flash` bases are not refused but are unverified.
 as a sentence (`frames` 3 to 15, default 8; a v3 base): PixelLab writes it
 into one 3D motion. Measured: 8 frames at 64px billed exactly 3 generations
 and came back at 96×96, so the canvas can grow. The plan still budgets 4. One
-request goes out per direction asset, so directions are not drawn from one
-shared motion yet (docs/CHARACTERS.md, "Loops from a sentence"). The
+request goes out per direction asset: the first direction of `directions`
+leads, and each later one follows in the next wave, sent into the leader's
+`animation_group_id` so every direction moves the same way (`animation.motionFrom`,
+lock `motionShare`; mock-verified only, docs/CHARACTERS.md, "Loops from a
+sentence"). The
 `prompt` is required and gets no style prefix or suffix.
 
 A named `template` loop (`walk`, `breathing-idle`, and similar) is trained