pixelkiln 0.89.6 → 0.91.0

package/docs/CHARACTERS.md

@@ -222,6 +222,75 @@ single direction before a batch.
 "mira.walk": { "animation": { "of": "mira", "template": "walk", "mode": "skeleton-v3", "directions": ["south", "west", "north"] } }
 ```
 
+### Loops from a sentence
+
+`mode: "skeleton-v3"` with **no `template`** animates the asset's `prompt`
+instead: PixelLab writes the sentence into one 3D motion and draws the
+character from it, with no template to pick. `frames` takes PixelLab's own
+3 to 15 for this combination (odd counts included, default 8); a template
+`skeleton-v3` loop still takes none.
+
+```jsonc
+"mira.swing": {
+  "prompt": "swinging a sword in a wide arc",
+  "animation": { "of": "mira", "mode": "skeleton-v3", "frames": 8, "directions": ["south", "west"] }
+}
+```
+
+- **A v3 base is required.** The sentence is written onto the character's
+  stored 3D skeleton, which a `standard` base lacks, so `plan` and `validate`
+  refuse the pairing and name the engine. `pro` and `pro-flash` bases are
+  not refused but are unverified. An `objectPro` has no skeleton at all.
+- **The prompt is the sentence**, sent as written as `action_description`
+  (a loop's prompt never takes the style's prefix or suffix, same as a v3
+  loop). It is required; `startFrame`, `endFrame`, `enhancePrompt`,
+  `subject`, and the template style hints are refused.
+- **The canvas can grow.** The measured 64px loop came back at 96×96. The
+  frames are saved as PixelLab returns them; a mirror flips them locally like
+  any other loop.
+- **Cost**: the plan budgets 4 per direction, the same ceiling as a template
+  `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 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
 
 A v3 loop can start and end where you say. `startFrame` is a
@@ -489,11 +558,12 @@ reference image change alone also makes it stale.
   style (engine, size, directions, body, view, folder) or an existing one,
   the base with an optional sprite of your own (uploaded into `refs/`, so
   only the rotations are billed), any number of loops (each a template
-  posed by `skeleton-v3` by default, or a plain template, v3, or pro loop,
+  posed by `skeleton-v3` by default, a `skeleton-v3` loop described in words
+  with a 3 to 15 frame count, or a plain template, v3, or pro loop,
   in the directions you tick, mirrors added free), and a portrait. A
   `standard` base has no 3D skeleton for `skeleton-v3` to pose, so its loops
-  start on `template` and the skeleton-v3 choice is greyed out; the new-loop
-  form on an existing base does the same. The
+  start on `template` and both skeleton-v3 choices are greyed out; the
+  new-loop form on an existing base does the same. The
   sheet prices the draft live, the way `plan` would. Pro Flash bases are
   priced by PixelLab's own quote (`/pro-flash/cost`, a free call) when the
   project has a key; those rows are marked live, and the offline estimate

package/docs/ENDPOINTS.md

@@ -920,7 +920,18 @@ generations and finished in about two minutes:
   the top-level amount is a dollar zero. PixelLab says the action is written
   into one 3D motion that every direction is drawn from, so later directions
   added with `animation_group_id` move the same way (humanoids). pixelkiln
-  does not send this mode yet.
+  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. 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

@@ -56,7 +56,7 @@ not merely a label edit.
 
 | Field | Type/default | Meaning |
 |---|---|---|
-| `prompt` | string, required unless `mirror`, `portrait`, `outfit`, or a template loop (`animation.template`) | The subject wording wrapped by the selected style's prompt prefix and suffix. A template loop is described by its template; a v3 or pro loop still needs the motion in words. |
+| `prompt` | string, required unless `mirror`, `portrait`, `outfit`, or a template loop (`animation.template`) | The subject wording wrapped by the selected style's prompt prefix and suffix. A template loop is described by its template; a v3, pro, or sentence (`skeleton-v3` with no template) loop still needs the motion in words. |
 | `width` / `height` | integer 16–8192 | Per-asset dimensions for generators that accept rectangular output. Provider limits may be lower. |
 | `size` | integer 16–8192 | Per-asset square size where the generator uses one dimension. |
 | `file` | string | Output path below the style's `outDir`; defaults to `<category>/<assetId>.png`. |
@@ -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). |
+| `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/docs/REVISIONS.md

@@ -492,7 +492,8 @@ a supplied 18-joint skeleton per frame instead of a text motion description:
         "mode": "animate-skeleton",
         "from": "hero-idle",
         "keypointsFile": "poses/hero-swing.json",
-        "direction": "south"
+        "direction": "south",
+        "description": "a knight in steel armour holding a sword"
       }
     }
   }
@@ -522,8 +523,8 @@ over the source image, locally and for free.
 `direction` is **required** for this mode (unlike `animate-pixminimax`,
 where it is optional). `frames`/`fps`/`lastFrame`/`enhancePrompt` are all
 rejected — the frame count comes from the keypoints file itself
-(`frames.length`), never a manifest number. `description` (optional: what the
-character *looks like* — colours, clothing, held items) is a new field
+(`frames.length`), never a manifest number. `description` (**required**: what
+the character *looks like* — colours, clothing, held items) is a new field
 distinct from the asset's own `prompt`, which this mode sends as the motion's
 short label (PixelLab's `action`) — the same `prompt`-as-motion convention
 `animate`/`animate-pixminimax` already use, just under this endpoint's own
@@ -560,8 +561,10 @@ anchor, and returned 8 frames at the sprite's own 64×64 size. The endpoint
 **requires both `description` and `action`**: the asset's `prompt` is sent as
 `action` (a short motion label such as "wave"), and `revision.description`
 (what the character looks like) is sent as `description`. Without a
-`description` PixelLab answers `422` with `description: Field required`,
-and `plan` does not catch that yet.
+`description` PixelLab answers `422` with `description: Field required`, so
+`plan` refuses an `animate-skeleton` revision without a non-empty
+`revision.description` (or an empty `prompt`) and the gallery's form asks for
+one.
 
 ComfyUI does not support this mode either, for the same structural reason as
 `animate`/`animate-pixminimax`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.89.6",
+  "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,9 +1305,13 @@
                     },
                     "minItems": 1
                   },
+                  "motionFrom": {
+                    "type": "string",
+                    "minLength": 1
+                  },
                   "frames": {
                     "type": "integer",
-                    "minimum": 4,
+                    "minimum": 3,
                     "maximum": 16
                   },
                   "fps": {

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

@@ -31,6 +31,21 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
 
 ## Already closed since this catalog's research began
 
+- **Sentence-driven skeleton-v3 loops** — a character loop with
+  `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 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
   (2 to 4 generations and 3 to 5 minutes per direction, beta, Tier 1 and
@@ -299,7 +314,7 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `resolveSpecs`/`estimate()`-time call — so `animate-skeleton`'s submission
   composes exactly one PixelLab endpoint, not two chained together. Both
   endpoints have since run live once (8 frames billed exactly 3), and the
-  run found that `description` is required: `plan` does not check for it yet. **Correcting this catalog's own prior research**: this entry
+  run found that `description` is required, which `plan` now enforces. **Correcting this catalog's own prior research**: this entry
   used to also claim a distinct "animation to animation" endpoint existed,
   for transferring an existing walk cycle's motion onto a different
   character. Checked against the live `animate_with_skeleton_v3` MCP tool
@@ -517,20 +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
-
-PixelLab's October 2026 character-creator update adds custom animation on the
-skeleton v3 model: a sentence becomes one 3D motion that every direction of
-the animation is drawn from, so a direction added later moves the same way.
-It is `POST /characters/animations` with `mode: "skeleton-v3"`, an
-`action_description`, and no `template_animation_id` (3 to 15 frames, humanoid
-v3 characters). **Measured once**: an 8-frame south loop billed exactly 3 and
-came back at 96×96 (docs/ENDPOINTS.md, "Skeleton-driven motion, measured").
-Still a gap: a character loop's `mode: "skeleton-v3"` needs a `template`,
-and the request never sends `action_description` for it. Closing it means a
-loop that names `skeleton-v3` and a `prompt` without a template, a
-`frames` count from 3 to 15, and adding a direction to an existing group.
-
 ## Map Workshop (scene composition)
 
 PixelLab's actual scene-building surface: lay out a tile floor, place

package/skills/pixelkiln/references/pixellab.md

@@ -394,6 +394,17 @@ stored 3D skeleton: a `v3` base has one (measured, 3 generations); a
 refuses the loop at `plan`/`validate`, pointing at `mode: "template"`. `pro`
 and `pro-flash` bases are not refused but are unverified.
 
+`"mode": "skeleton-v3"` with **no** `template` animates the asset's `prompt`
+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: 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
 mostly on characters with empty hands, and reliably struggles once a
 character holds an item — a weapon, a tool, anything gripped. For a