pixelkiln 0.90.0 → 0.91.0

package/dist/index.cjs

@@ -284,6 +284,7 @@ __export(index_exports, {
   readVfxConversation: () => readVfxConversation,
   readVfxRecipe: () => readVfxRecipe,
   recipeDigest: () => recipeDigest,
+  recordedAnimationGroup: () => recordedAnimationGroup,
   referencedHashes: () => referencedHashes,
   refineAsset: () => refineAsset,
   refineFrameSet: () => refineFrameSet,
@@ -692,6 +693,15 @@ var CharacterAnimationSchema = import_zod.z.object({
    * `src/loop-directions.ts`.
    */
   directions: import_zod.z.array(CharacterDirectionSchema).min(1).optional(),
+  /**
+   * A sentence loop (`mode: "skeleton-v3"`, no `template`) of another
+   * direction whose motion this one shares: the asset id of the loop that
+   * leads. This loop is then submitted after it, into its animation group,
+   * so PixelLab draws it from the same 3D motion. Written for you when
+   * `directions` expands (the first direction leads); set by hand only when
+   * declaring the loops explicitly.
+   */
+  motionFrom: import_zod.z.string().min(1).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.
@@ -779,6 +789,9 @@ var CharacterAnimationSchema = import_zod.z.object({
   if (!animation.template && animation.mode === "template") {
     context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "template mode needs a template", path: ["template"] });
   }
+  if (animation.motionFrom !== void 0 && !sentence) {
+    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "motionFrom applies to a skeleton-v3 loop from a sentence (no template)", path: ["motionFrom"] });
+  }
   if (sentence && animation.subject !== void 0) {
     context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "subject does not apply to a skeleton-v3 loop from a sentence; describe the motion in the prompt", path: ["subject"] });
   }
@@ -1711,6 +1724,7 @@ var LockTerrainConnectSchema = import_zod.z.record(
   TerrainSideSchema,
   import_zod.z.object({ sourceAssetId: import_zod.z.string().min(1), sourceObjectId: import_zod.z.string().min(1) }).strict()
 );
+var LockMotionShareSchema = import_zod.z.object({ sourceAssetId: import_zod.z.string().min(1), animationGroupId: import_zod.z.string().min(1).nullable() }).strict();
 var LockTerrainSettingsSchema = import_zod.z.object({
   terrainMode: import_zod.z.string().optional(),
   terrainShapeStyle: import_zod.z.string().optional(),
@@ -1747,6 +1761,8 @@ var LockHistoryEntrySchema = import_zod.z.object({
   postprocess: PostprocessSchema.optional(),
   /** A connected terrain set's other sets; see LockEntrySchema.terrainConnect. */
   terrainConnect: LockTerrainConnectSchema.optional(),
+  /** A sentence loop that shares another direction's motion; see LockEntrySchema.motionShare. */
+  motionShare: LockMotionShareSchema.optional(),
   /** A terrain set's settings outside specHash; see LockEntrySchema.terrainSettings. */
   terrainSettings: LockTerrainSettingsSchema.optional(),
   /** When the replacement was submitted. */
@@ -1823,6 +1839,16 @@ var LockEntrySchema = import_zod.z.object({
    * Absent (not null) otherwise, so other entries do not grow the key.
    */
   terrainConnect: LockTerrainConnectSchema.optional(),
+  /**
+   * For a sentence loop of a later direction: the loop whose motion it
+   * shares and the animation group of that loop's generation this was
+   * drawn into when submitted. Tracked the way `terrainConnect` is, not
+   * through `specHash`: the group lives in the lockfile. A regenerated leader
+   * has a new group, so the plan marks this stale. `animationGroupId` is
+   * null when the leader had no group recorded and this was drawn on its own.
+   * Absent otherwise.
+   */
+  motionShare: LockMotionShareSchema.optional(),
   /**
    * For a terrain set: the settings it was submitted with that `specHash`
    * leaves out (see LockTerrainSettingsSchema). The plan marks the entry
@@ -2288,6 +2314,8 @@ var CharacterSubmitSchema = import_zod3.z.object({
 var AnimateSubmitSchema = import_zod3.z.object({
   background_job_ids: import_zod3.z.array(import_zod3.z.string()),
   directions: import_zod3.z.array(import_zod3.z.string()),
+  /** skeleton-v3 only: the group the directions were drawn into. */
+  animation_group_id: import_zod3.z.string().nullable().optional(),
   status: import_zod3.z.string().default("processing"),
   usage: UsageSchema
 }).passthrough();
@@ -3011,7 +3039,10 @@ var PixelLabClient = class {
    * 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).
+   * 3 generations, frames back at 96x96). `animationGroupId` (skeleton-v3
+   * only) adds the directions to an existing animation of the character,
+   * drawn from its motion; the group's own name must be sent again as
+   * `animationName`, or the group appears renamed.
    */
   async animateCharacter(args) {
     const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
@@ -3023,6 +3054,7 @@ var PixelLabClient = class {
         animation_name: args.animationName,
         mode: args.mode,
         directions: args.directions,
+        ...args.mode === "skeleton-v3" && args.animationGroupId ? { animation_group_id: args.animationGroupId } : {},
         ...args.template ? { template_animation_id: args.template } : {},
         ...args.actionDescription ? { action_description: args.actionDescription } : {},
         ...args.description ? { description: args.description } : {},
@@ -4395,6 +4427,10 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         template: spec.character.template,
         parent: spec.character.parentAssetId,
         parentSha256: spec.character.parentSha256 ?? null,
+        // Which loop leads, not its group: the group is in the lockfile,
+        // and the plan compares it there. Absent for every loop that
+        // shares nothing, so no existing hash moves.
+        motionFrom: spec.character.motionLeader?.assetId,
         state: spec.character.state,
         // Pose images enter as their hashes, never their paths.
         animation: spec.character.animation ? {
@@ -5439,7 +5475,13 @@ function decodeAnimationJob(jobId) {
   try {
     const value = JSON.parse(Buffer.from(jobId.slice("character-animation:".length), "base64url").toString("utf8"));
     if (typeof value?.characterId === "string" && typeof value.name === "string" && typeof value.direction === "string") {
-      return { characterId: value.characterId, name: value.name, direction: value.direction, jobIds: Array.isArray(value.jobIds) ? value.jobIds : [] };
+      return {
+        characterId: value.characterId,
+        name: value.name,
+        direction: value.direction,
+        jobIds: Array.isArray(value.jobIds) ? value.jobIds : [],
+        ...typeof value.groupId === "string" && value.groupId ? { groupId: value.groupId } : {}
+      };
     }
   } catch {
   }
@@ -6277,11 +6319,18 @@ var PixelLabProvider = class _PixelLabProvider {
       };
     }
     const animation = character.animation;
-    const name = characterAnimationName(spec);
+    const ownName = characterAnimationName(spec);
+    const shared = context?.motionGroup;
+    const name = shared?.animationName ?? ownName;
     const replaced = context?.replacedMetadata?.character ?? {};
     const existing = await this.client.getCharacter(parentId);
+    if (shared && !existing.animations.some((group) => group.animation_group_id === shared.animationGroupId && group.directions.some((d) => d.direction !== animation.direction))) {
+      throw new Error(
+        `${spec.styleId}/${spec.assetId} shares the motion of an animation group (${shared.animationGroupId}) that is no longer on the character; regenerate the leading direction first`
+      );
+    }
     for (const group of existing.animations) {
-      const ours = group.animation_group_id && (group.animation_group_id === replaced.animationGroupId || group.display_name === name || replaced.animationId && group.directions.some((d) => d.frames.some((url) => url.includes(`/animations/${replaced.animationId}/`))));
+      const ours = group.animation_group_id && (group.animation_group_id === replaced.animationGroupId || group.display_name === name || group.display_name === ownName || replaced.animationId && group.directions.some((d) => d.frames.some((url) => url.includes(`/animations/${replaced.animationId}/`))));
       if (!ours || !group.animation_group_id) continue;
       if (group.directions.some((d) => d.direction === animation.direction)) {
         await this.client.deleteCharacterAnimations(parentId, { animationGroupId: group.animation_group_id }, animation.direction);
@@ -6296,6 +6345,7 @@ var PixelLabProvider = class _PixelLabProvider {
       frameCount: animation.frames,
       keepFirstFrame: animation.keepFirstFrame,
       directions: [animation.direction],
+      ...shared ? { animationGroupId: shared.animationGroupId } : {},
       seed: spec.seed,
       textGuidanceScale: character.textGuidanceScale,
       isometric: character.isometric,
@@ -6308,10 +6358,11 @@ var PixelLabProvider = class _PixelLabProvider {
       enhancePrompt: animation.enhancePrompt,
       paletteSwatchBase64: spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0
     });
-    const job = { characterId: parentId, name, direction: animation.direction, jobIds: res.background_job_ids };
+    const groupId = res.animation_group_id ?? shared?.animationGroupId;
+    const job = { characterId: parentId, name, direction: animation.direction, jobIds: res.background_job_ids, ...groupId ? { groupId } : {} };
     return {
       jobId: encodeAnimationJob(job),
-      metadata: { character: { kind: "animation", characterId: parentId, animationName: name, direction: animation.direction, mode: animation.mode, backgroundJobIds: res.background_job_ids } }
+      metadata: { character: { kind: "animation", characterId: parentId, animationName: name, direction: animation.direction, mode: animation.mode, backgroundJobIds: res.background_job_ids, ...groupId ? { animationGroupId: groupId } : {} } }
     };
   }
   /**
@@ -6526,13 +6577,13 @@ var PixelLabProvider = class _PixelLabProvider {
       const animationId = typeof done.animation_id === "string" ? done.animation_id : null;
       if (Array.isArray(frames) && frames.length && frames.every((f) => typeof f === "string")) {
         const character2 = await this.client.getCharacter(job.characterId);
-        const group = findAnimation(character2, job.name, job.direction, animationId);
-        return review(frames, animationId, group?.groupId ?? null, billedFromUsage(status.usage));
+        const group = findAnimation(character2, job.name, job.direction, animationId, job.groupId);
+        return review(frames, animationId, group?.groupId ?? job.groupId ?? null, billedFromUsage(status.usage));
       }
     }
     const recorded = context?.metadata?.character?.animationId ?? null;
     const character = await this.client.getCharacter(job.characterId);
-    const found = findAnimation(character, job.name, job.direction, recorded);
+    const found = findAnimation(character, job.name, job.direction, recorded, job.groupId);
     if (found) return review(found.frames, found.animationId, found.groupId, null);
     return cleanedUp ? { status: "failed", error: `animation job is gone upstream and no "${job.name}" ${job.direction} animation exists on the character` } : { status: "processing" };
   }
@@ -7966,10 +8017,11 @@ function rotationSources(character) {
   }
   return sources;
 }
-function findAnimation(character, name, direction, animationId) {
+function findAnimation(character, name, direction, animationId, groupId) {
   for (const group of character.animations) {
     const match = group.directions.find((d) => d.direction === direction && d.frames.length > 0);
     if (!match) continue;
+    if (groupId && group.animation_group_id !== groupId) continue;
     const byName = group.display_name === name || group.animation_type === name;
     const byId = animationId !== null && match.frames.some((url) => url.includes(`/animations/${animationId}/`));
     if (!byName && !byId) continue;
@@ -10203,8 +10255,16 @@ function expandLoopDirections(raw) {
       continue;
     }
     for (const expandedId of ids) claimed.add(expandedId);
-    for (const loop of loops) {
-      expanded[loop.id] = { ...asset, animation: { ...animation, direction: loop.direction } };
+    const sentence = animation.mode === "skeleton-v3" && !animation.template;
+    for (const [index, loop] of loops.entries()) {
+      expanded[loop.id] = {
+        ...asset,
+        animation: {
+          ...animation,
+          direction: loop.direction,
+          ...sentence && index > 0 ? { motionFrom: loops[0].id } : {}
+        }
+      };
     }
     for (const mirror of mirrors) {
       const inherited = {};
@@ -11139,7 +11199,8 @@ async function resolveSpecs(loaded, filter) {
               `assets.${assetId}: mirroring ${asset.mirror} gives another ${facing}-facing loop; mirror a loop facing east, west, or a diagonal`
             );
           }
-          resolved.character = { ...sourceSpec.character, animation: { ...sourceSpec.character.animation, direction: mirrored } };
+          const { motionLeader: _motionLeader, ...flipped } = sourceSpec.character;
+          resolved.character = { ...flipped, animation: { ...sourceSpec.character.animation, direction: mirrored } };
         } else if (sourceSpec.character) {
           resolved.character = { ...sourceSpec.character };
         }
@@ -11196,6 +11257,26 @@ async function resolveSpecs(loaded, filter) {
           directions: resolved.character.kind === "base" ? resolved.character.directions : parentSpec.character?.directions ?? resolved.character.directions
         };
       }
+      if (resolved.character?.animation && asset.animation?.motionFrom) {
+        const leaderId = asset.animation.motionFrom;
+        const where = `assets.${assetId}.animation.motionFrom`;
+        if (leaderId === assetId) throw new Error(`${where}: an asset cannot share its own motion`);
+        const leader = await finalize(leaderId);
+        const led = leader.character?.animation;
+        if (leader.character?.kind !== "animation" || leader.mirror || !led || led.mode !== "skeleton-v3" || led.template) {
+          throw new Error(`${where}: ${leaderId} is not a skeleton-v3 loop from a sentence`);
+        }
+        if (leader.character.parentAssetId !== resolved.character.parentAssetId) {
+          throw new Error(`${where}: ${leaderId} animates ${leader.character.parentAssetId}, not ${resolved.character.parentAssetId}`);
+        }
+        if (leader.character.motionLeader) {
+          throw new Error(`${where}: ${leaderId} itself shares ${leader.character.motionLeader.assetId}'s motion; point at the loop that leads`);
+        }
+        if (led.direction === resolved.character.animation.direction) {
+          throw new Error(`${where}: ${leaderId} is drawn in the same direction; sharing a motion needs another direction`);
+        }
+        resolved.character = { ...resolved.character, motionLeader: { assetId: leaderId, spec: leader } };
+      }
       if (resolved.objectPro && characterParent) {
         const parentSpec = await finalize(characterParent);
         if (!parentSpec.objectPro) {
@@ -13190,7 +13271,10 @@ var import_node_path14 = __toESM(require("path"), 1);
 async function inspectRevisionReadiness(spec, lock) {
   if (spec.mirror) return inspectMirror(spec, lock, /* @__PURE__ */ new Set());
   if (spec.character?.kind === "outfit") return inspectOutfit(spec, lock, /* @__PURE__ */ new Set());
-  if (spec.character?.parentSpec) return inspectCharacterParent(spec, lock, /* @__PURE__ */ new Set());
+  if (spec.character?.parentSpec) {
+    const parent = await inspectCharacterParent(spec, lock, /* @__PURE__ */ new Set());
+    return parent.ready && spec.character.motionLeader ? inspectMotionLeader(spec, lock, /* @__PURE__ */ new Set()) : parent;
+  }
   if (spec.character?.styleAnchor) return inspectStyleAnchor(spec, lock, /* @__PURE__ */ new Set());
   if (spec.objectPro?.parentSpec) return inspectObjectProParent(spec, lock, /* @__PURE__ */ new Set());
   if (spec.scene) return inspectScene(spec);
@@ -13225,6 +13309,17 @@ async function inspectTerrainConnect(spec, lock, seen) {
   }
   return { ready: true, reason: "connected sets are current" };
 }
+function recordedAnimationGroup(entry) {
+  const character = entry?.providerMetadata?.[entry.provider]?.character;
+  const text = (value) => typeof value === "string" && value ? value : null;
+  return { animationGroupId: text(character?.animationGroupId), animationName: text(character?.animationName) };
+}
+async function inspectMotionLeader(spec, lock, seen) {
+  const leader = spec.character.motionLeader;
+  const label = `motion leader ${spec.styleId}/${leader.assetId}`;
+  const dependency = await inspectParent(leader.spec, lock, seen);
+  return dependency.ready ? { ready: true, reason: `${label} is current` } : { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
+}
 async function inspectScene(spec) {
   const scene = spec.scene;
   const files = [{ label: "scene image", file: scene.file, sha256: scene.sha256 }];
@@ -13383,6 +13478,10 @@ async function inspectParent(spec, lock, seen) {
     const inputs = await inspectCharacterParent(spec, lock, nextSeen);
     if (!inputs.ready) return inputs;
   }
+  if (spec.character?.motionLeader) {
+    const inputs = await inspectMotionLeader(spec, lock, nextSeen);
+    if (!inputs.ready) return inputs;
+  }
   if (spec.character?.styleAnchor) {
     const inputs = await inspectStyleAnchor(spec, lock, nextSeen);
     if (!inputs.ready) return inputs;
@@ -13439,6 +13538,7 @@ function dependencies(spec) {
     spec.mirror?.sourceSpec,
     spec.revision?.sourceSpec,
     spec.character?.parentSpec,
+    spec.character?.motionLeader?.spec,
     spec.character?.styleAnchor?.spec,
     spec.objectPro?.parentSpec,
     spec.terrainConnect?.lower?.spec,
@@ -13455,6 +13555,12 @@ function changedTerrainConnection(spec, entry, lock) {
   }
   return null;
 }
+function changedMotionLeader(spec, entry, lock) {
+  const leader = spec.character?.motionLeader;
+  if (!leader) return null;
+  const current = recordedAnimationGroup(lock.entries[lockKey(leader.spec.styleId, leader.spec.assetId)]).animationGroupId;
+  return (entry.motionShare?.animationGroupId ?? null) === current ? null : leader.assetId;
+}
 function changedTerrainSettings(spec, entry) {
   const recorded = entry.terrainSettings;
   const current = terrainSettings(spec);
@@ -13496,6 +13602,7 @@ async function buildPlan(specs, lock, opts = {}) {
     let state;
     let reason;
     const changedConnection = entry ? changedTerrainConnection(spec, entry, lock) : null;
+    const changedMotion = entry ? changedMotionLeader(spec, entry, lock) : null;
     const changedSettings = entry ? changedTerrainSettings(spec, entry) : null;
     const revision = await inspectRevisionReadiness(spec, lock);
     if (revision && !revision.ready) {
@@ -13535,6 +13642,9 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (changedConnection) {
       state = "stale";
       reason = `connected set ${changedConnection} was regenerated; draw this set from its new terrain`;
+    } else if (changedMotion) {
+      state = "stale";
+      reason = `shares motion with ${changedMotion}, which was regenerated; draw this direction into its new motion`;
     } else if (changedSettings) {
       state = "stale";
       reason = changedSettings;
@@ -13598,6 +13708,14 @@ async function buildPlan(specs, lock, opts = {}) {
       }
     }
   }
+  for (const item of items) {
+    const leader = item.spec.character?.motionLeader;
+    if (!leader || !isActionable(item)) continue;
+    const leaderEntry = lock.entries[lockKey(leader.spec.styleId, leader.spec.assetId)];
+    if (leaderEntry?.status === "downloaded" && !recordedAnimationGroup(leaderEntry).animationGroupId) {
+      item.reason += `; ${leader.assetId} has no animation group recorded, so this is drawn on its own and its motion will differ`;
+    }
+  }
   const actionable = items.filter(isActionable);
   const groupsByProvider = /* @__PURE__ */ new Map();
   for (const item of actionable) {
@@ -15007,6 +15125,7 @@ function retireGeneration(entry, retiredAt) {
     provider: entry.provider,
     postprocess: entry.postprocess,
     ...entry.terrainConnect ? { terrainConnect: entry.terrainConnect } : {},
+    ...entry.motionShare ? { motionShare: entry.motionShare } : {},
     ...entry.terrainSettings ? { terrainSettings: entry.terrainSettings } : {},
     retiredAt
   };
@@ -15102,6 +15221,8 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     // A connected set comes back with the connection it was drawn from, so
     // the plan compares the restored generation, not the one it replaced.
     terrainConnect: generation.terrainConnect,
+    // Likewise a loop that shared another direction's motion.
+    motionShare: generation.motionShare,
     // Likewise its settings; a generation from before they were recorded
     // comes back with none and is taken as current.
     terrainSettings: generation.terrainSettings,
@@ -16141,6 +16262,12 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       };
       terrainConnect[side] = { sourceAssetId: link.assetId, sourceObjectId: objectId };
     }
+    const motionLeader = spec.character?.motionLeader;
+    const leaderGroup = motionLeader ? recordedAnimationGroup(lock.entries[lockKey(motionLeader.spec.styleId, motionLeader.spec.assetId)]) : void 0;
+    const motionGroup = leaderGroup?.animationGroupId && leaderGroup.animationName ? { animationGroupId: leaderGroup.animationGroupId, animationName: leaderGroup.animationName } : void 0;
+    if (motionLeader && !motionGroup) {
+      log(`  ${key}: ${motionLeader.assetId} has no animation group recorded; drawing this direction on its own`);
+    }
     upsert(lock, key, {
       styleId: spec.styleId,
       assetId: spec.assetId,
@@ -16182,6 +16309,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         referenceSha256: spec.character.outfit.reference.sha256
       } : null,
       terrainConnect: spec.terrainConnect ? terrainConnect : void 0,
+      motionShare: motionLeader ? { sourceAssetId: motionLeader.assetId, animationGroupId: motionGroup?.animationGroupId ?? null } : void 0,
       // The terrain knobs specHash leaves out, so the plan can tell a
       // changed one; undefined (no key) for every other generator.
       terrainSettings: terrainSettings(spec),
@@ -16232,6 +16360,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         ...anchorEntry?.objectId ? { styleObjectId: anchorEntry.objectId } : {},
         ...parentOutputs ? { parentOutputs } : {},
         ...spec.terrainConnect ? { terrainLinks } : {},
+        ...motionGroup ? { motionGroup } : {},
         ...replacedMetadata ? { replacedMetadata } : {},
         ...lastGenerationMetadata ? { lastGenerationMetadata } : {},
         ...previousMetadata ? { previousMetadata } : {},
@@ -21424,6 +21553,7 @@ async function workspaceStatus(ws, dir) {
   readVfxConversation,
   readVfxRecipe,
   recipeDigest,
+  recordedAnimationGroup,
   referencedHashes,
   refineAsset,
   refineFrameSet,