pixelkiln 0.89.6 → 0.90.0

package/dist/cli.js

@@ -1238,16 +1238,21 @@ var CharacterAnimationSchema = z.object({
    * `src/loop-directions.ts`.
    */
   directions: z.array(CharacterDirectionSchema).min(1).optional(),
-  /** Frames to generate without a template (v3). Even, 4 to 16. */
-  frames: z.number().int().min(4).max(16).optional(),
+  /**
+   * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+   * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+   */
+  frames: z.number().int().min(3).max(16).optional(),
   /** Playback rate recorded with the frames; PixelLab does not store one. */
   fps: z.number().int().min(1).max(60).default(8),
   /** v3 only: keep the resting pose as frame 0, so `frames` generated frames land as `frames + 1` files. */
   keepFirstFrame: z.boolean().default(true),
   /**
    * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-   * poses a template with PixelLab's skeleton model instead; `pro` for the
-   * sequential high-quality engine.
+   * poses a template with PixelLab's skeleton model instead, or, with no
+   * template, animates the asset's prompt as a sentence written into one 3D
+   * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+   * high-quality engine.
    */
   mode: CharacterAnimationModeSchema.optional(),
   /**
@@ -1277,15 +1282,23 @@ var CharacterAnimationSchema = z.object({
       path: ["directions"]
     });
   }
-  if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
-    context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+  const sentence = animation.mode === "skeleton-v3" && !animation.template;
+  if (animation.frames !== void 0 && !sentence) {
+    if (animation.frames % 2 !== 0) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+    } else if (animation.frames < 4) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be 4 to 16", path: ["frames"] });
+    }
+  }
+  if (animation.frames !== void 0 && sentence && animation.frames > 15) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "a skeleton-v3 loop from a sentence takes 3 to 15 frames", path: ["frames"] });
   }
   const mode2 = animation.mode ?? (animation.template ? "template" : "v3");
   for (const key of ["startFrame", "endFrame", "enhancePrompt"]) {
     if (animation[key] !== void 0 && mode2 !== "v3") {
       context.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `${key} is for v3 loops; a ${mode2} loop ${mode2 === "template" || mode2 === "skeleton-v3" ? "starts from the character's rotation and follows its template" : "takes neither"}`,
+        message: `${key} is for v3 loops; a ${mode2} loop ${mode2 === "template" || mode2 === "skeleton-v3" ? `starts from the character's rotation and ${animation.template ? "follows its template" : "animates its sentence"}` : "takes neither"}`,
         path: [key]
       });
     }
@@ -1309,8 +1322,11 @@ var CharacterAnimationSchema = z.object({
       path: ["frames"]
     });
   }
-  if (!animation.template && (animation.mode === "template" || animation.mode === "skeleton-v3")) {
-    context.addIssue({ code: z.ZodIssueCode.custom, message: `${animation.mode} mode needs a template`, path: ["template"] });
+  if (!animation.template && animation.mode === "template") {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "template mode needs a template", path: ["template"] });
+  }
+  if (sentence && animation.subject !== void 0) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "subject does not apply to a skeleton-v3 loop from a sentence; describe the motion in the prompt", path: ["subject"] });
   }
 });
 var RevisionDitheringSchema = z.enum(["none", "2x2", "4x4", "8x8"]);
@@ -7258,7 +7274,10 @@ var PixelLabClient = class {
    * Every mode but skeleton-v3 goes to `/animate-character`, the path whose
    * shapes were measured live. skeleton-v3 is documented only on
    * `/characters/animations`, which takes the same request and answers with
-   * the same job list (plus an `animation_group_id`).
+   * the same job list (plus an `animation_group_id`). With no `template` it
+   * animates `actionDescription` as a sentence, 3 to 15 `frameCount` frames
+   * written into one 3D motion; measured on a v3 character (8 frames, 64px:
+   * 3 generations, frames back at 96x96).
    */
   async animateCharacter(args) {
     const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
@@ -7273,7 +7292,8 @@ var PixelLabClient = class {
         ...args.template ? { template_animation_id: args.template } : {},
         ...args.actionDescription ? { action_description: args.actionDescription } : {},
         ...args.description ? { description: args.description } : {},
-        ...args.mode === "v3" && args.frameCount ? { frame_count: args.frameCount } : {},
+        // A template fixes its own frame count; v3 and a skeleton-v3 sentence take one.
+        ...(args.mode === "v3" || args.mode === "skeleton-v3" && !args.template) && args.frameCount ? { frame_count: args.frameCount } : {},
         ...args.mode === "v3" && args.keepFirstFrame === false ? { keep_first_frame: false } : {},
         ...args.mode === "v3" && args.startFrame ? { custom_start_frame: encode(args.startFrame) } : {},
         ...args.mode === "v3" && args.endFrame ? { end_frame: encode(args.endFrame) } : {},
@@ -9193,6 +9213,16 @@ var PixelLabProvider = class _PixelLabProvider {
       if (skeletonTemplate && !CHARACTER_TEMPLATES.includes(skeletonTemplate)) {
         throw new Error(`PixelLab animate-skeleton template "${skeletonTemplate}" is not one of ${CHARACTER_TEMPLATES.join(", ")}`);
       }
+      if (!spec.revision.description?.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId}: an animate-skeleton revision needs revision.description, what the character looks like (for example "a knight in steel armour holding a sword"); PixelLab refuses the request without it`
+        );
+      }
+      if (!spec.prompt.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId}: an animate-skeleton revision needs a prompt, a short motion label (for example "swinging the sword")`
+        );
+      }
     }
     if (spec.revision?.mode === "animate" || spec.revision?.mode === "animate-pixminimax") {
       const { sourceWidth: width, sourceHeight: height, mode: mode2, frames, lastFrameWidth, lastFrameHeight } = spec.revision;
@@ -9596,12 +9626,18 @@ var PixelLabProvider = class _PixelLabProvider {
           `${spec.styleId}/${spec.assetId} animates "${character.animation.direction}", but its character has ${character.directions} directions: ${allowed.join(", ")}`
         );
       }
-      if (character.animation.mode !== "template" && character.animation.mode !== "skeleton-v3" && !spec.prompt.trim()) {
-        throw new Error(`${spec.styleId}/${spec.assetId} needs a prompt describing the motion, or a template`);
+      const sentence = character.animation.mode === "skeleton-v3" && !character.animation.template;
+      if (character.animation.mode !== "template" && (character.animation.mode !== "skeleton-v3" || sentence) && !spec.prompt.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId} needs a prompt describing the motion, or a template` + (sentence ? ' (a skeleton-v3 loop with no template animates its prompt, e.g. "swinging a sword in a wide arc")' : "")
+        );
+      }
+      if (sentence && (character.animation.frames < 3 || character.animation.frames > 15)) {
+        throw new Error(`${spec.styleId}/${spec.assetId}: a skeleton-v3 loop from a sentence takes 3 to 15 frames; ${character.animation.frames} is out of range`);
       }
       if (character.animation.mode === "skeleton-v3" && character.mode === "standard") {
         throw new Error(
-          `${spec.styleId}/${spec.assetId}: skeleton-v3 poses a template onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" for this loop`
+          sentence ? `${spec.styleId}/${spec.assetId}: a skeleton-v3 loop from a sentence writes the motion onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" with a template for this loop` : `${spec.styleId}/${spec.assetId}: skeleton-v3 poses a template onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" for this loop`
         );
       }
     }
@@ -17029,7 +17065,8 @@ var SkeletonAnimationRequestSchema = z10.object({
   /** The motion, sent as PixelLab's `action`. */
   prompt: z10.string().min(1),
   direction: CharacterDirectionSchema,
-  description: z10.string().min(1).optional(),
+  /** What the character looks like; PixelLab refuses the request without it. */
+  description: z10.string().min(1),
   skeletonTemplate: z10.string().min(1).optional(),
   /** Manifest-relative JSON path inside the project. */
   keypointsFile: z10.string().min(1),
@@ -17136,7 +17173,7 @@ async function createSkeletonAnimation(manifestPath, request) {
           from: request.from,
           keypointsFile: relative.split(path31.sep).join("/"),
           direction: request.direction,
-          ...request.description ? { description: request.description } : {},
+          description: request.description,
           ...request.skeletonTemplate ? { skeletonTemplate: request.skeletonTemplate } : {}
         }
       }