pixelkiln 0.46.0 → 0.47.0

package/docs/PIXELLAB.md

@@ -31,7 +31,7 @@ makes the choice clear:
     "props": {
       "generator": "map",
       "outDir": "assets/generated/props",
-      "promptSuffix": ", isolated pixel-art game asset"
+      "promptSuffix": "isolated pixel-art game asset"
     }
   },
   "assets": {
@@ -124,7 +124,10 @@ packaging.
 ## What is outside this adapter
 
 PixelLab offers more than PixelKiln currently exposes. Portraits, outfit
-transfer, lip-sync, skeleton-driven animation, and Pro Flash are not part of
-this adapter. Characters, their states, and their animations are the
-`character` generator; see [Characters](./MANIFEST.md#characters). Use the
-[manifest reference](./MANIFEST.md) for the fields PixelKiln supports today.
+transfer, lip-sync, and skeleton-driven animation are not part of this
+adapter. Characters, their states, and their animations are the `character`
+generator, with all four creation engines (standard, v3, pro, pro-flash),
+reference sprites, concept images, style anchors, mirrors, and every
+`animate-character` control; see [Characters](./CHARACTERS.md). Use
+the [manifest reference](./MANIFEST.md) for the fields PixelKiln supports
+today.

package/docs/README.md

@@ -14,7 +14,7 @@ provider you are using. These Markdown files also render at
 | [Set up ComfyUI](./COMFYUI.md) | Bind local still, revision, and atomic frame-set workflows with an explicit quality boundary. |
 | [Set up Scenario](./SCENARIO.md) | Configure hosted models, two-part credentials, CU ceilings, and durable downloads. |
 | [CLI reference](./CLI.md) | Every command and flag, including `gallery`, `edit`, and `tools`; offline and provider requirements; JSON output; exit codes. |
-| [Manifest reference](./MANIFEST.md) | Every style and asset field, quality profiles, generator constraints, mounting, and schema validation. |
+| [Manifest reference](./MANIFEST.md) | Every shared style and asset field, palette enforcement, quality profiles, revisions, mounting, and schema validation. |
 | [Mixed-provider projects](./MIXED_PROVIDERS.md) | Route styles to different providers, set separate budget ceilings, and resume safely from one lockfile. |
 | [Agent workflows](./AGENTS.md) | Install the official skill and pair agent guidance with the deterministic CLI. |
 
@@ -22,7 +22,8 @@ provider you are using. These Markdown files also render at
 
 | Guide | Use it for |
 |---|---|
-| [Generators](./GENERATORS.md) | Choose between still, tile, hosted animation, and ComfyUI frame-set workflows. |
+| [Characters](./CHARACTERS.md) | A base in 4 or 8 directions from a prompt or your own sprite, states, loops, mirrors, the four PixelLab engines, and what each costs. |
+| [Generators](./GENERATORS.md) | Choose between still, tile, character, hosted animation, and ComfyUI frame-set workflows. |
 | [Environment provider benchmark](./PROVIDER_BENCHMARK.md) | Compare PixelLab, Retro Diffusion, and ComfyUI on buildings, backgrounds, cleanup, and native-grid recovery. |
 | [Controlled asset revisions](./REVISIONS.md) | Use image-to-image/inpaint parents, masks, approval gates, side-by-side review, and ComfyUI bindings. |
 | [Derived artifacts](./ARTIFACTS.md) | Refine, pack, mount, and export; provenance, approval gates, ownership, and crash recovery. |

package/docs/RETRO_DIFFUSION.md

@@ -93,8 +93,102 @@ Useful options under `providerOptions.retrodiffusion` include:
 
 RD Pro and user still styles accept up to nine reference images. Advanced
 animation and tile modes have narrower input rules. PixelKiln validates those
-rules during planning. See the [manifest reference](./MANIFEST.md#experimental-retro-diffusion)
-for complete examples.
+rules during planning. See [Manifest fields](#manifest-fields) below for complete
+examples.
+
+## Manifest fields
+
+Retro Diffusion maps `map` and `pixflux` to still generation, `tiles` to its
+tileset family, and `animation` to GIF or PNG-spritesheet generation. Durable
+sources and lock outputs record `image/png` or `image/gif`, so recovery retains
+the correct extension and validates the correct structure.
+
+```jsonc
+{
+  "name": "my-game",
+  "provider": "retrodiffusion",
+  "styles": {
+    "base": {
+      "generator": "map",
+      "outDir": "assets/generated/base",
+      "providerOptions": {
+        "retrodiffusion": {
+          "promptStyle": "rd_plus__default",
+          "numImages": 4,
+          "removeBg": true
+        }
+      }
+    }
+  },
+  "assets": {
+    "anvil": { "prompt": "a compact blacksmith anvil" }
+  }
+}
+```
+
+`promptStyle` accepts a live Retro Diffusion still-style selector,
+`numImages` accepts 1–16 candidates, and `removeBg` overrides
+`noBackground`. The Retro Diffusion API accepts 16–512px output. Selected
+styles can impose smaller limits. RD Pro and user styles accept up to nine
+reference images. Costs are
+planned in USD and checked again with Retro Diffusion's free authoritative
+quote endpoint before the paid request is sent. Authenticated single-candidate
+RD Fast and RD Plus paths have passed from quote through validated output and
+recovery.
+Multi-candidate, tileset, GIF, and spritesheet paths remain mock-tested, so the
+adapter is still experimental.
+
+Additional Retro Diffusion options are:
+
+| Option | Meaning |
+|---|---|
+| `framesDuration` | Animation duration: `4`, `6`, `8`, `10`, `12`, or `16`. |
+| `returnSpritesheet` | Return a PNG spritesheet instead of an animated GIF. |
+| `extraPrompt` | Outside texture description for `rd_tile__tileset_advanced`. |
+| `tileX` / `tileY` | Make supported still styles seamless on either axis. |
+
+An animation style is declared explicitly:
+
+```jsonc
+{
+  "generator": "animation",
+  "size": 64,
+  "outDir": "assets/generated/animations",
+  "providerOptions": {
+    "retrodiffusion": {
+      "promptStyle": "rd_animation__any_animation",
+      "numImages": 1,
+      "framesDuration": 8,
+      "returnSpritesheet": false
+    }
+  }
+}
+```
+
+The default output is `<assetId>.gif`; `returnSpritesheet: true` produces
+`<assetId>.png`. Advanced animation styles require exactly one `styleImages`
+input. PixelKiln currently limits animation batches to one so selection never
+loses the output media type.
+
+For a Wang-style tileset sheet:
+
+```jsonc
+{
+  "generator": "tiles",
+  "tileSize": 32,
+  "outDir": "assets/generated/tiles",
+  "providerOptions": {
+    "retrodiffusion": {
+      "promptStyle": "rd_tile__tileset",
+      "numImages": 1
+    }
+  }
+}
+```
+
+`rd_tile__tileset_advanced` accepts `extraPrompt` and up to two style images;
+`rd_tile__tile_variation` requires one style image. Provider-specific size and
+input constraints are checked during the free planning phase.
 
 ## Current operational limits
 

package/docs/SCENARIO.md

@@ -144,6 +144,52 @@ its own selected `candidateIndex` alongside the chosen durable asset ID.
 The committed [Scenario live smoke](../benchmarks/provider-scenario-smoke/README.md)
 contains the manifest, lockfile, measured costs, and selected outputs.
 
+## Manifest fields
+
+Scenario uses hosted model IDs and requires a conservative Compute Unit ceiling
+for every style:
+
+```jsonc
+{
+  "provider": "scenario",
+  "styles": {
+    "environment": {
+      "generator": "map",
+      "size": 512,
+      "outDir": "assets/generated/environment",
+      "providerOptions": {
+        "scenario": {
+          "modelId": "model_bfl-flux-2-dev",
+          "projectId": "project_example",
+          "numOutputs": 4,
+          "maxComputeUnits": 60,
+          "parameters": {
+            "guidance": 4,
+            "numInferenceSteps": 28
+          }
+        }
+      }
+    }
+  },
+  "assets": {
+    "mountain-town": { "prompt": "a fortified mountain town" }
+  }
+}
+```
+
+| Option | Meaning |
+|---|---|
+| `modelId` | Required Scenario endpoint model ID. |
+| `maxComputeUnits` | Required positive per-asset offline ceiling and maximum accepted live quote. |
+| `numOutputs` | One to four PNG candidates; defaults to one. |
+| `projectId` | Optional Scenario ownership/routing project. |
+| `parameters` | Additional model-specific JSON inputs. PixelKiln-owned request fields cannot be overridden. |
+
+The current adapter supports `map`, dimensions from 128–2048px in multiples of
+16, optional seed, and no style-image uploads. Every paid request is preceded
+by an identical `dryRun=true` request. See [Set up Scenario](SCENARIO.md) for
+credentials, cost semantics, recovery, and the paid live-test boundary.
+
 ## Review and recovery
 
 One output moves directly to download. Two to four outputs enter the normal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/skills/pixelkiln/SKILL.md

@@ -40,6 +40,13 @@ hashes.
 - When an asset declares `revision`, read the revision reference, require its
   parent gate to pass, and never bypass a `blocked` plan. Generate or approve
   the parent explicitly before re-planning the child.
+- A character `state`, `animation`, `mirror`, or pro `styleCharacter` is a
+  dependent asset the same way: one `pixelkiln gen` runs the waves in order
+  and stops when the budget cannot cover the next one. Before declaring the
+  east-facing loop of a character, check whether a `mirror` of the west one
+  does the job for nothing; before drawing a base from text, ask whether the
+  user has a south-facing sprite to `reference` instead (1 generation on
+  `pro-flash` at 64px). Mirrors swap handedness.
 - Treat every ComfyUI output as source material until it passes the native-grid,
   final-palette, prompt-coverage, and human 1× checks in the ComfyUI reference.
   A successful PNG or high-confidence grid result is not quality approval.

package/skills/pixelkiln/references/pixellab.md

@@ -39,7 +39,7 @@ mislead, and ask PixelLab to `enhancePrompt`; a template loop takes
 
 A loop costs per direction, and a sprite facing east is the sprite facing
 west flipped. Declare the west loop and make the east one `{ "mirror":
-"hero.walk.west" }`: PixelKiln flips it locally for nothing, in the wave
+"bot.walk.west" }`: PixelKiln flips it locally for nothing, in the wave
 after the source lands. South and north cannot be mirrored. Eight directions
 of one loop are then 5 generations, not 8.