pixelkiln 0.37.0 → 0.38.0

package/README.md

@@ -59,7 +59,7 @@ provenance and no long-lived npm token.
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
 | Quality control | Palette snapping on download, native grid recovery, named approval, regression baselines, and fail-closed packaging. |
 | Sprite packaging | Deterministic RGBA packing, stable-cell mounting, explicit external input lists, structural output roles. |
-| Engine export | Lossless generic tile contract, Tiled Wang sets, and Godot 4 terrain sets. |
+| Engine export | Aseprite sheet JSON and Godot SpriteFrames from `pack`; Tiled Wang sets and Godot terrain sets from `export`. |
 | Artifact integrity | Portable source/output hashes, canonical fingerprints, manual-edit protection, transactional promotion, crash journal recovery. |
 | Library/extension | Public TypeScript primitives, provider capability interface, and deterministic `FakeProvider`. |
 

package/dist/cli.js

@@ -336,8 +336,9 @@ function parseArgs(argv) {
   }
   const manifest = get("--manifest") ?? "pixelkiln.manifest.json";
   const rawFormat = get("--format");
-  if (rawFormat && rawFormat !== "generic" && rawFormat !== "tiled" && rawFormat !== "godot") {
-    throw new UsageError(`--format must be generic, tiled, or godot, got "${rawFormat}"`);
+  const formats = command === "export" ? ["generic", "tiled", "godot"] : ["generic", "aseprite", "godot"];
+  if (rawFormat && !formats.includes(rawFormat)) {
+    throw new UsageError(`--format must be ${formats.slice(0, -1).join(", ")}, or ${formats.at(-1)}, got "${rawFormat}"`);
   }
   const numberOption = (flag, opts) => {
     const raw = get(flag);
@@ -465,7 +466,8 @@ Options
   --columns <n>       pack/export: sprites or tiles per row (default: near-square)
   --port <n>          Local review/gallery server port (default: choose a free port)
   --inputs <path>     pack/quality snapshot: JSON input list; needs --out
-  --format <format>   export: generic (default), tiled, or godot
+  --format <format>   export: generic (default), tiled, or godot (TileSet)
+                      pack/mount: generic (default), aseprite, or godot (SpriteFrames)
   --output-role <r>   pack: include only this output role (repeatable)
   --primary-only      pack: include only unambiguous primary/single outputs
   --max-distance <n>  audit: maximum palette distance
@@ -522,6 +524,7 @@ Examples
   pixelkiln adopt --tag
   pixelkiln pack --style heybud-premium
   pixelkiln pack --inputs sprites.json --out dist/sheet   # no manifest needed
+  pixelkiln pack --style hero --format aseprite         # sheet JSON engines load
   pixelkiln mount --style ground
   pixelkiln export --style ground --only terrain --format tiled
   pixelkiln refine --style environment
@@ -1903,6 +1906,15 @@ function resolveSpecOutputs(spec, lock, manifestDir) {
     sha256: ""
   }];
 }
+function frameSetFps(entry) {
+  const namespace = entry.providerMetadata?.[entry.provider];
+  const frameSet = namespace?.frameSet;
+  if (frameSet && typeof frameSet === "object" && "fps" in frameSet) {
+    const fps = frameSet.fps;
+    if (typeof fps === "number" && Number.isFinite(fps) && fps > 0) return fps;
+  }
+  return null;
+}
 
 // src/pipeline/quality-profile.ts
 import { existsSync as existsSync3 } from "fs";
@@ -9174,16 +9186,7 @@ async function samePixels(a, b) {
     return false;
   }
 }
-function metadataFps(entry) {
-  if (!entry) return null;
-  const namespace = entry.providerMetadata?.[entry.provider];
-  const frameSet = namespace?.frameSet;
-  if (frameSet && typeof frameSet === "object" && "fps" in frameSet) {
-    const fps = frameSet.fps;
-    if (typeof fps === "number" && Number.isFinite(fps) && fps > 0) return fps;
-  }
-  return null;
-}
+var metadataFps = (entry) => entry ? frameSetFps(entry) : null;
 async function fileInfo(absolutePath) {
   try {
     const info = await stat2(absolutePath);
@@ -12716,6 +12719,7 @@ import { readFile as readFile23 } from "fs/promises";
 // src/pipeline/pack.ts
 import { readFileSync as readFileSync5 } from "fs";
 import path35 from "path";
+var DEFAULT_FRAME_SET_FPS = 12;
 function resolvePackInputs(raw, inputsFilePath) {
   if (!Array.isArray(raw) || !raw.length) {
     throw new Error("--inputs must be a non-empty JSON array of { id, path }");
@@ -12815,6 +12819,7 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
   const inputs = [];
   const noOutput = [];
   const locked = /* @__PURE__ */ new Set();
+  const sets = [];
   for (const [key, entry] of entries) {
     const id = key.slice(prefix.length);
     locked.add(id);
@@ -12842,6 +12847,15 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
       continue;
     }
     for (const output of selected) inputs.push({ id: output.id, path: output.absolutePath });
+    if (entry.outputs.length > 1) {
+      const fps = entry.generator === "frames" ? frameSetFps(entry) ?? DEFAULT_FRAME_SET_FPS : null;
+      sets.push({
+        id,
+        kind: entry.generator === "frames" ? "frames" : "members",
+        ...fps ? { fps } : {},
+        frames: selected.map((output) => output.id)
+      });
+    }
   }
   for (const [id, source] of Object.entries(sources)) {
     if (!locked.has(id)) inputs.push({ id, path: path35.resolve(manifestDir, source) });
@@ -12850,9 +12864,11 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
     throw new Error(`No readable sprites for style "${styleId}" \u2014 ${noOutput.length} skipped.`);
   }
   const packed = packSprites(inputs, options);
+  const packedIds = new Set(packed.atlas.frames.map((frame) => frame.id));
+  const placed = sets.map((set) => ({ ...set, frames: set.frames.filter((frameId) => packedIds.has(frameId)) })).filter((set) => set.frames.length).sort((a, b) => a.id.localeCompare(b.id));
   return {
     ...packed,
-    atlas: { ...packed.atlas, style: styleId },
+    atlas: { ...packed.atlas, style: styleId, ...placed.length ? { sets: placed } : {} },
     skipped: [...noOutput, ...packed.skipped]
   };
 }
@@ -13261,6 +13277,98 @@ function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/pipeline/sheet-formats.ts
+var SHEET_FORMATS = ["generic", "aseprite", "godot"];
+var ASEPRITE_DEFAULT_DURATION_MS = 100;
+var GODOT_DEFAULT_SPEED = 5;
+function renderAsepriteSheet(atlas, opts) {
+  const index = new Map(atlas.frames.map((frame, i) => [frame.id, i]));
+  const durations = /* @__PURE__ */ new Map();
+  const frameTags = [];
+  for (const set of atlas.sets ?? []) {
+    const positions = set.frames.map((id) => index.get(id)).filter((i) => i !== void 0);
+    if (!positions.length) continue;
+    if (set.kind === "frames" && set.fps) {
+      for (const id of set.frames) durations.set(id, Math.max(1, Math.round(1e3 / set.fps)));
+    }
+    frameTags.push({ name: set.id, from: Math.min(...positions), to: Math.max(...positions), direction: "forward" });
+  }
+  const frames = {};
+  for (const frame of atlas.frames) {
+    frames[frame.id] = {
+      frame: { x: frame.x, y: frame.y, w: frame.width, h: frame.height },
+      rotated: false,
+      trimmed: false,
+      spriteSourceSize: { x: 0, y: 0, w: frame.width, h: frame.height },
+      sourceSize: { w: frame.width, h: frame.height },
+      duration: durations.get(frame.id) ?? ASEPRITE_DEFAULT_DURATION_MS
+    };
+  }
+  const document = {
+    frames,
+    meta: {
+      app: "https://pixelkiln.griffen.codes",
+      version: opts.version ?? "pixelkiln",
+      image: opts.imageName,
+      format: "RGBA8888",
+      size: { w: atlas.sheet.width, h: atlas.sheet.height },
+      scale: "1",
+      frameTags,
+      layers: [{ name: atlas.style, opacity: 255, blendMode: "normal" }],
+      slices: []
+    }
+  };
+  return JSON.stringify(document, null, 2) + "\n";
+}
+function renderGodotSpriteFrames(atlas, opts) {
+  const textureIds = /* @__PURE__ */ new Map();
+  atlas.frames.forEach((frame, i) => textureIds.set(frame.id, `AtlasTexture_${i + 1}`));
+  const inSet = new Set((atlas.sets ?? []).flatMap((set) => set.frames));
+  const lines = [
+    `[gd_resource type="SpriteFrames" load_steps=${atlas.frames.length + 2} format=3]`,
+    "",
+    `[ext_resource type="Texture2D" path=${JSON.stringify(`./${opts.imageName}`)} id="1_texture"]`
+  ];
+  for (const frame of atlas.frames) {
+    lines.push(
+      "",
+      `[sub_resource type="AtlasTexture" id="${textureIds.get(frame.id)}"]`,
+      `atlas = ExtResource("1_texture")`,
+      `region = Rect2(${frame.x}, ${frame.y}, ${frame.width}, ${frame.height})`
+    );
+  }
+  const animations = [];
+  const animation = (name, ids, speed, loop) => {
+    const frames = ids.filter((id) => textureIds.has(id)).map((id) => `{
+"duration": 1.0,
+"texture": SubResource("${textureIds.get(id)}")
+}`);
+    if (!frames.length) return;
+    animations.push(
+      `{
+"frames": [${frames.join(", ")}],
+"loop": ${loop},
+"name": &${JSON.stringify(name)},
+"speed": ${speed.toFixed(1)}
+}`
+    );
+  };
+  for (const set of atlas.sets ?? []) {
+    if (set.kind === "frames") animation(set.id, set.frames, set.fps ?? GODOT_DEFAULT_SPEED, true);
+    else for (const id of set.frames) animation(id, [id], GODOT_DEFAULT_SPEED, false);
+  }
+  for (const frame of atlas.frames) {
+    if (!inSet.has(frame.id)) animation(frame.id, [frame.id], GODOT_DEFAULT_SPEED, false);
+  }
+  lines.push("", "[resource]", `animations = [${animations.join(", ")}]`, "");
+  return lines.join("\n");
+}
+function renderSheetDocument(format, atlas, opts) {
+  if (format === "aseprite") return { extension: ".json", document: renderAsepriteSheet(atlas, opts) };
+  if (format === "godot") return { extension: ".tres", document: renderGodotSpriteFrames(atlas, opts) };
+  return { extension: ".json", document: JSON.stringify(atlas, null, 2) + "\n" };
+}
+
 // src/cli/commands/pack.ts
 async function runPack(args) {
   if (args.inputs) {
@@ -13271,20 +13379,22 @@ async function runPack(args) {
     const raw = JSON.parse(await readFile23(path36.resolve(args.inputs), "utf8"));
     const inputs = resolvePackInputs(raw, args.inputs);
     const { png, atlas, skipped, sources } = packSprites(inputs, { columns: args.columns });
-    const base = path36.resolve(args.out.replace(/\.png$/, ""));
+    const format = sheetFormat(args);
+    const base = path36.resolve(args.out.replace(/\.(?:png|json|tres)$/i, ""));
+    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path36.basename(`${base}.png`) });
     const outputs = [
       { path: `${base}.png`, data: png },
-      { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
+      { path: `${base}${extension}`, data: document }
     ];
     await writeManagedArtifactBundle(`${base}.pixelkiln.json`, outputs, {
       kind: "pack",
       sources: [await provenanceFile("$inputs", args.inputs), ...sources],
-      options: { columns: args.columns ?? null, order: "id", style: null }
+      options: { columns: args.columns ?? null, format, order: "id", style: null }
     }, { force: args.force });
     log(
-      `  ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s) \u2014 ${(png.length / 1024).toFixed(1)} KB`
+      `  ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s) \u2014 ${(png.length / 1024).toFixed(1)} KB (${format})`
     );
-    log(`    ${path36.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+    log(`    ${path36.relative(process.cwd(), base)}.png + ${extension} + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     return;
   }
@@ -13305,10 +13415,12 @@ async function runPack(args) {
       sources: manifestSources(loaded.manifest, styleId)
     });
     const style = loaded.manifest.styles[styleId];
-    const base = args.out ? path36.resolve(args.out.replace(/\.png$/, "")) : path36.resolve(manifestDir, style.outDir, `${styleId}-sheet`);
+    const base = args.out ? path36.resolve(args.out.replace(/\.(?:png|json|tres)$/i, "")) : path36.resolve(manifestDir, style.outDir, `${styleId}-sheet`);
+    const format = sheetFormat(args);
+    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path36.basename(`${base}.png`) });
     const outputs = [
       { path: `${base}.png`, data: png },
-      { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
+      { path: `${base}${extension}`, data: document }
     ];
     const qualityRecords = qualitySources ? await Promise.all(
       packagingSpecs.filter((spec) => spec.quality).map((spec) => provenanceFile(
@@ -13326,6 +13438,7 @@ async function runPack(args) {
       ],
       options: {
         columns: args.columns ?? null,
+        format,
         order: "id",
         outputRoles: [...args.outputRoles].sort(),
         primaryOnly: args.primaryOnly,
@@ -13333,9 +13446,9 @@ async function runPack(args) {
       }
     }, { force: args.force });
     log(
-      `  ${styleId} \u2014 ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s)`
+      `  ${styleId} \u2014 ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s)` + (atlas.sets?.length ? `, ${atlas.sets.length} set(s)` : "") + ` (${format})`
     );
-    log(`    ${path36.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+    log(`    ${path36.relative(process.cwd(), base)}.png + ${extension} + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
   }
 }
@@ -13381,11 +13494,13 @@ async function runMount(args) {
       outputRoles
     );
     const out = path36.resolve(manifestDir, style.mount.out);
-    const metadata = out.replace(/\.png$/, "") + ".json";
+    const format = sheetFormat(args);
+    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path36.basename(out) });
+    const metadata = out.replace(/\.png$/, "") + extension;
     const companion = out.replace(/\.png$/, "") + ".pixelkiln.json";
     const outputs = [
       { path: out, data: png },
-      { path: metadata, data: JSON.stringify(atlas, null, 2) + "\n" }
+      { path: metadata, data: document }
     ];
     const qualityRecords = qualitySources ? await Promise.all(
       packagingSpecs.filter((spec) => spec.quality && Object.hasOwn(cells, spec.assetId)).map((spec) => provenanceFile(
@@ -13407,6 +13522,7 @@ async function runMount(args) {
         cellHeight: style.mount.cellHeight,
         cellWidth: style.mount.cellWidth,
         cells: Object.entries(cells).sort(([a], [b]) => a.localeCompare(b)),
+        format,
         style: styleId
       }
     }, { force: args.force });
@@ -13473,6 +13589,13 @@ async function runExport(args) {
     );
   }
 }
+function sheetFormat(args) {
+  const format = args.format ?? "generic";
+  if (!SHEET_FORMATS.includes(format)) {
+    throw new Error(`--format ${format} is for export; sheets take ${SHEET_FORMATS.join(", ")}`);
+  }
+  return format;
+}
 
 // src/cli/commands/quality.ts
 import path38 from "path";