pixelkiln 0.89.6 → 0.90.0

package/docs/CHARACTERS.md

@@ -222,6 +222,45 @@ 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 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.
+
 ### Pose frames and other loop controls
 
 A v3 loop can start and end where you say. `startFrame` is a
@@ -489,11 +528,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,11 @@ 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 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`).
 
 ## 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). |
 | `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/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.90.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/schema/manifest.schema.json

@@ -1307,7 +1307,7 @@
                   },
                   "frames": {
                     "type": "integer",
-                    "minimum": 4,
+                    "minimum": 3,
                     "maximum": 16
                   },
                   "fps": {

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

@@ -31,6 +31,13 @@ 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 directions is not wired up (one request per direction asset).
+
 - **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 +306,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,19 +524,16 @@ 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
+## Sentence-driven skeleton-v3 loops, shared motion across directions
 
-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.
+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)
 

package/skills/pixelkiln/references/pixellab.md

@@ -394,6 +394,14 @@ 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, so directions are not drawn from one
+shared motion yet (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