pixelkiln 0.87.0 → 0.89.0

package/schema/manifest.schema.json

@@ -47,7 +47,8 @@
                       "objectPro",
                       "uiAsset",
                       "uiElement",
-                      "imageProFlash"
+                      "imageProFlash",
+                      "vfx"
                     ],
                     "default": "map"
                   },
@@ -233,6 +234,28 @@
                     "minimum": 0,
                     "maximum": 1
                   },
+                  "terrainRoundness": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 2
+                  },
+                  "terrainBoundaryAmplitude": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 0.3
+                  },
+                  "terrainBoundarySeed": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "terrainStepSlope": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 2
+                  },
+                  "terrainConnectDiagonals": {
+                    "type": "boolean"
+                  },
                   "terrainTransitionSize": {
                     "type": "number",
                     "minimum": 0,
@@ -245,6 +268,13 @@
                       "high top-down"
                     ]
                   },
+                  "terrainOrientation": {
+                    "type": "string",
+                    "enum": [
+                      "top-down",
+                      "sidescroller"
+                    ]
+                  },
                   "isometricTileSize": {
                     "type": "number",
                     "enum": [
@@ -382,6 +412,16 @@
                     },
                     "default": []
                   },
+                  "paletteName": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 100
+                  },
+                  "maxColors": {
+                    "type": "integer",
+                    "minimum": 2,
+                    "maximum": 64
+                  },
                   "enforcePalette": {
                     "type": "boolean",
                     "default": false
@@ -505,7 +545,8 @@
                       "objectPro",
                       "uiAsset",
                       "uiElement",
-                      "imageProFlash"
+                      "imageProFlash",
+                      "vfx"
                     ],
                     "default": "map"
                   },
@@ -691,6 +732,28 @@
                     "minimum": 0,
                     "maximum": 1
                   },
+                  "terrainRoundness": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 2
+                  },
+                  "terrainBoundaryAmplitude": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 0.3
+                  },
+                  "terrainBoundarySeed": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "terrainStepSlope": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 2
+                  },
+                  "terrainConnectDiagonals": {
+                    "type": "boolean"
+                  },
                   "terrainTransitionSize": {
                     "type": "number",
                     "minimum": 0,
@@ -703,6 +766,13 @@
                       "high top-down"
                     ]
                   },
+                  "terrainOrientation": {
+                    "type": "string",
+                    "enum": [
+                      "top-down",
+                      "sidescroller"
+                    ]
+                  },
                   "isometricTileSize": {
                     "type": "number",
                     "enum": [
@@ -840,6 +910,16 @@
                     },
                     "default": []
                   },
+                  "paletteName": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 100
+                  },
+                  "maxColors": {
+                    "type": "integer",
+                    "minimum": 2,
+                    "maximum": 64
+                  },
                   "enforcePalette": {
                     "type": "boolean",
                     "default": false
@@ -1015,7 +1095,8 @@
                       "animate-pixminimax",
                       "animate-skeleton",
                       "interpolate",
-                      "edit-animation"
+                      "edit-animation",
+                      "normal-map"
                     ]
                   },
                   "from": {
@@ -1117,6 +1198,13 @@
                       "complex"
                     ]
                   },
+                  "convention": {
+                    "type": "string",
+                    "enum": [
+                      "opengl",
+                      "directx"
+                    ]
+                  },
                   "description": {
                     "type": "string",
                     "minLength": 1
@@ -1544,6 +1632,109 @@
                 ],
                 "additionalProperties": false
               },
+              "vfx": {
+                "type": "object",
+                "properties": {
+                  "preset": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "recipe": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "parts": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "name": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      },
+                      "required": [
+                        "name"
+                      ],
+                      "additionalProperties": {}
+                    }
+                  },
+                  "sprite": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "fps": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 60
+                  },
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "description": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 8000
+                  },
+                  "artist": {
+                    "type": "string",
+                    "enum": [
+                      "lite",
+                      "pro"
+                    ]
+                  }
+                },
+                "additionalProperties": false
+              },
+              "connect": {
+                "type": "object",
+                "properties": {
+                  "lower": {
+                    "type": "object",
+                    "properties": {
+                      "of": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "terrain": {
+                        "type": "string",
+                        "enum": [
+                          "lower",
+                          "upper"
+                        ]
+                      }
+                    },
+                    "required": [
+                      "of",
+                      "terrain"
+                    ],
+                    "additionalProperties": false
+                  },
+                  "upper": {
+                    "type": "object",
+                    "properties": {
+                      "of": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "terrain": {
+                        "type": "string",
+                        "enum": [
+                          "lower",
+                          "upper"
+                        ]
+                      }
+                    },
+                    "required": [
+                      "of",
+                      "terrain"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "additionalProperties": false
+              },
               "proportions": {
                 "anyOf": [
                   {

package/schema/recipe.schema.json

@@ -122,7 +122,8 @@
                 "objectPro",
                 "uiAsset",
                 "uiElement",
-                "imageProFlash"
+                "imageProFlash",
+                "vfx"
               ],
               "default": "map"
             },
@@ -308,6 +309,28 @@
               "minimum": 0,
               "maximum": 1
             },
+            "terrainRoundness": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 2
+            },
+            "terrainBoundaryAmplitude": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 0.3
+            },
+            "terrainBoundarySeed": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "terrainStepSlope": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 2
+            },
+            "terrainConnectDiagonals": {
+              "type": "boolean"
+            },
             "terrainTransitionSize": {
               "type": "number",
               "minimum": 0,
@@ -320,6 +343,13 @@
                 "high top-down"
               ]
             },
+            "terrainOrientation": {
+              "type": "string",
+              "enum": [
+                "top-down",
+                "sidescroller"
+              ]
+            },
             "isometricTileSize": {
               "type": "number",
               "enum": [
@@ -457,6 +487,16 @@
               },
               "default": []
             },
+            "paletteName": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 100
+            },
+            "maxColors": {
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 64
+            },
             "enforcePalette": {
               "type": "boolean",
               "default": false

package/skills/pixelkiln/SKILL.md

@@ -59,7 +59,12 @@ hashes.
   takes a reference, and the unzoomed result is opaque. For outside art that
   was never pixel art (a photo, painting, or render), `pixelkiln pixelate
   --from <file> --out <file>` converts it with PixelLab's Image to Pixel Art
-  Pro Flash for 6 generations and asks first.
+  Pro Flash for 6 generations and asks first. The result is opaque on
+  near-white, so remove its background before using it as a cut-out.
+- For a spell, hit, explosion, aura, or other effect, use `pixelkiln vfx`
+  (PixelLab's VFX workbench, free): start from a `--preset`, add `--part`s,
+  build around a `--sprite`, and keep the `.vfx.json` it writes, since its
+  recipe re-renders the same effect with `--recipe`.
 - 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.
@@ -113,8 +118,8 @@ composition review and, for an isolated asset, background removal.
 Read only the reference needed for the current decision:
 
 - For PixelLab configuration, generators (including `uiElement` for single UI
-  pieces and `imageProFlash` for styled stills), costs, alpha behavior,
-  account operations, or the `unzoom`, `pixelate`, `font`, `estimate-skeleton`, and
+  pieces, `imageProFlash` for styled stills, and `vfx` for animated effects), costs, alpha behavior,
+  account operations, or the `unzoom`, `pixelate`, `normal-map`, `vfx`, `font`, `estimate-skeleton`, and
   `skeleton-preview` utilities, read [references/pixellab.md](references/pixellab.md). For a
   PixelLab style aimed at a specific resolution or fidelity tier (retro,
   high-detail, or matching an existing set's look), read

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

@@ -1,17 +1,26 @@
 # PixelLab coverage and remaining gaps
 
 A catalog of PixelLab capabilities checked against PixelKiln: what this
-adapter now covers, and what is still absent. It was built by reading all 29
+adapter now covers, and what is still absent. It was built by reading all 31
 tutorials on PixelLab's official YouTube channel (the original
 26 — the 12 featured on pixellab.ai plus 14 more from the channel's "PixelLab
-Tutorial" playlist, filtered to ~12 months back from that pass — plus 3 more
+Tutorial" playlist, filtered to ~12 months back from that pass — plus 5 more
 published since: "Level Up Your Game: Custom Sprite Animation Tutorial,"
 "Pixel Art Animation Tutorial: Images Pro Flash, Skeleton V3 & PixMiniMax,"
-and "How to Reduce Colors Like a Pro!") against this adapter's actual source
-— and, for the newest pass, against PixelLab's own MCP tool schemas
-(`create_image_pro_flash`, `edit_image_pro_flash`, `inpaint_image_pro_flash`,
-`get_pro_flash_capabilities`) where a tutorial's framing needed checking
-against the live surface, the same standard the original pass held itself to.
+"How to Reduce Colors Like a Pro!", "How to Make Animated Pixel Art VFX in
+PixelLab" (https://www.youtube.com/watch?v=t8FIMv-8QpI), and "PixelLab Pro
+Tilesets: Full Guide" (https://www.youtube.com/watch?v=MbkqpDUFkEg)) against
+this adapter's actual source — and, for the newer passes, against PixelLab's
+own MCP tool schemas (`create_image_pro_flash`, `edit_image_pro_flash`,
+`inpaint_image_pro_flash`, `get_pro_flash_capabilities`, and for the last two
+`create_topdown_tileset`, `create_sidescroller_tileset`, `create_tiles_pro`,
+`create_map`, `animate_image_pixminimax`, `create_image_pro`, `vfx_workbench`,
+and `search_knowledge`) plus the REST OpenAPI document's `/create-tileset`
+and `/create-tileset-sidescroller` request schemas, where a tutorial's
+framing needed checking against the live surface, the same standard the
+original pass held itself to. The PixelLab 0.4.130 release notes (October 2026: Tileset
+Pro, a target palette for Create Image Pro, VFX in the API, normal maps)
+were checked the same way against the REST OpenAPI document.
 Read this when scoping new PixelLab work, so effort goes toward a
 confirmed gap with real demand rather than a guess. Nothing here is a
 commitment to build it — it is what is missing, with the evidence for why it
@@ -55,10 +64,26 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   — a real gap, not a docs fix: `tiles`'s own `tileFeature: "tileset"` draws
   one terrain's edges, not two named, connected terrain levels with their own
   transition prompt. Closed by the `terrain` generator; see
-  `pixellab.md`. Cost is unmeasured (borrows the same 10/15/25 canvas tiers
-  already confirmed for `tiles` and `1dir`); `/create-tileset-sidescroller`,
-  reference images, `color_image`, and the `pro` pipeline's own tunables
-  beyond `spreadX`/`slopeSize`/`raggedness` remain unmodeled.
+  `pixellab.md`. Reference images and `color_image` remain unmodeled.
+- **Tileset Pro shape controls, connected sets, and sidescrollers**
+  (PixelLab 0.4.130, October 2026). `terrain` styles take
+  `terrainRoundness`, `terrainBoundaryAmplitude`/`terrainBoundarySeed`,
+  `terrainStepSlope`, and `terrainConnectDiagonals`, each refused outside
+  the mode that reads it. `terrainSpreadX`/`terrainSlopeSize` are
+  deprecated, since PixelLab now documents both as "No effect". A Pro set at
+  `terrainTransitionSize` 0.5 counts as 25 tiles. An asset's `connect` shares
+  a terrain with another set in the same style: pixelkiln records each set's
+  `metadata.terrain_ids`, sends the other set's id as `lower_base_tile_id` or
+  `upper_base_tile_id`, blocks until that set is downloaded, and marks the
+  connected set stale when the other is regenerated.
+  `terrainOrientation: "sidescroller"` calls `/create-tileset-sidescroller`
+  (platform body plus top layer). Its response is the top-down shape with
+  `terrain_types` `["central","background"]` but `lower`/`upper` corners,
+  lower being the platform. **Measured once**: a 16px set at transition 0.25
+  billed exactly 3 generations. Estimates now follow PixelLab's quotes: Pro
+  15 up to 32px and 25 at 64px, standard 4 (the top of its quoted 1 to 4),
+  sidescroller 3. What is still open is in
+  [Pro tilesets](#pro-tilesets-what-is-left-after-04130) below.
 - **Pro-tier full-bleed background generation** (`generate-image-v2`, PixelLab's
   Pro image tier) at arbitrary custom aspect ratios (not just square) —
   already measured at 40 generations in `docs/ENDPOINTS.md`, but `pixflux`
@@ -302,9 +327,49 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   PixelLab 0.4.128, October 2026) — converts a photo, painting, or render
   into pixel art, choosing the output size itself. Closed by `pixelkiln
   pixelate`, a standalone command on a loose file like `unzoom`, since its
-  input comes from outside the manifest. Billed a flat 6 generations live,
-  and unlike `image-to-pixelart` it keeps transparency
-  (docs/ENDPOINTS.md, "Image to Pixel Art Pro Flash, measured").
+  input comes from outside the manifest. Billed a flat 6 generations live;
+  the result is opaque on a near-white background (docs/ENDPOINTS.md,
+  "Image to Pixel Art Pro Flash, measured").
+- **Create VFX** (PixelLab 0.4.128, October 2026) — animated pixel-art
+  effects (spells, hits, explosions, auras, weather). Offered only as the
+  `vfx_workbench` MCP tool, with no REST endpoint as of October 2026, and free on a
+  subscription because it renders a recipe rather than generating. Closed by
+  `pixelkiln vfx`, which calls PixelLab's MCP server directly with the same
+  API key. It starts from a preset, a saved effect, or a recipe file, adds
+  parts, downloads the sheet, GIF, atlas, and optional game pack, and saves
+  the recipe so the effect re-renders byte for byte (docs/ENDPOINTS.md, "VFX
+  workbench (MCP only), measured"). Effects are also a manifest generator,
+  `vfx`, planned, locked, and packed like every other asset (see
+  docs/GENERATORS.md). Still open there: a sprite named by asset rather than
+  by file, the game pack's per-piece clips, and the effect's anchor in the
+  sheet formats. PixelLab 0.4.130 then put a second effects path in the
+  REST API: `POST /vfx`, the website's VFX *artist*, which builds an effect
+  from a plain-language description and saves it to My effects. It is paid:
+  1 generation for a lite effect with no sprite or one up to 128px, up to 28
+  for a pro effect around a 512px sprite, charged on delivery and never more
+  than twice the quote. Closed as a `vfx` block's `description` (with
+  `artist: "lite" | "pro"`) and `pixelkiln vfx --description`. Plans count
+  twice the quote. **Measured once**: a lite effect with no sprite billed
+  exactly its 1-generation quote, and its sheet (a 3×3 grid with an
+  Aseprite-style atlas) cut into 8 correct frames (docs/ENDPOINTS.md). A
+  sprite, the pro artist, and changes are unmeasured. Animated sprites (GIF
+  or strips) are not sent yet.
+- **Normal maps** (`POST /normal-map`, PixelLab 0.4.130) — a sprite's normal
+  map for engine lighting, 8 to 512px, up to 32 frames as one strip so the
+  light stays steady, `opengl` or `directx` convention, 0.5 generations.
+  Closed by the `revision` asset shape's `normal-map` mode (a loop goes as
+  one strip and comes back cut into frames; a character's directions are
+  refused, since a strip would shape every direction from the first) and the
+  standalone `pixelkiln normal-map` command. Styles with `enforcePalette` or
+  `quality` refuse it so nothing palette-snaps a normal map. **Measured
+  once**: an 8-frame 1304×26 strip billed exactly 0.5 and came back the same
+  size with matching alpha.
+- **Target palette for Create Image Pro** (`target_palette` on
+  `/generate-image-v2`, PixelLab 0.4.130) — an `imagePro` style's `palette`
+  is now sent as the colors every pixel must use, with `maxColors` (2 to 64
+  per image) and `paletteName`. The beta `smart` mapping is left out because
+  PixelLab documents it as single-image only and `imagePro` returns a grid of
+  candidates below 171px. Cost unchanged and unmeasured with a palette.
 - **October 2026 Pro price cut** — PixelLab 0.4.128 moved every Pro tool from
   20/25/40 to 10/15/25 generations. Cost estimates now use the new prices,
   and `imagePro` (`generate-image-v2`) is tiered instead of a flat 40: a
@@ -363,17 +428,79 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   from an existing 8-direction object's sprites), is not worth a second,
   pricier engine on its own.
 
-## Create VFX (experimental, no API yet)
+## Pro tilesets: what is left after 0.4.130
 
-PixelLab 0.4.128 (October 2026) added Create VFX, an experimental web tool
-for pixel-art visual effects (`pixellab.ai/create-vfx`). As of that release it
-has no endpoint in `/v2/openapi.json` and no MCP tool; PixelLab's release
-notes say it "will be added for MCP". Effects are a real gap for game work
-(hit sparks, spell bursts, dust puffs), and pixelkiln's closest substitutes
-are an `animate` revision or an `objectPro` animation, neither built for it.
-Revisit once an endpoint appears: check its request shape, whether the
-result is a frame set or a sheet, and its cost, then decide between a
-generator (frames into a `pack`able set) and a loose-file command.
+"PixelLab Pro Tilesets: Full Guide" and the 0.4.130 release ("Tileset Pro
+Update... Both top down and sidescroller has been updated! It also supports
+connecting different tilesets") are now mostly covered; see the closed
+`terrain` entries above. Checked against `/create-tileset` and
+`/create-tileset-sidescroller`'s REST schemas, what remains:
+
+- **Pro sidescrollers are web-app only.** The video's sidescroller is the
+  Pro form at 16, 32, and 64px with top-layer height up to 100%.
+  `/create-tileset-sidescroller` has no `mode` field, and its tile size is
+  16 or 32. pixelkiln's sidescroller sets use whatever model that endpoint
+  runs.
+- **Older terrain fields are not identity.** `terrainMode`,
+  `terrainTransitionSize`, `terrainRaggedness`, `terrainShapeStyle`, and
+  `terrainView` never entered `specHash`, so changing one does not mark a set stale. The 0.4.130 fields
+  are hashed (when set). Hashing the older ones would make every existing
+  terrain lock entry stale at once, so it needs a deliberate migration.
+- **Wall-continuation twins export as duplicates.** The 25-tile layout has
+  21 distinct corner combinations. Four tiles share corners with a twin and
+  differ only in `pattern_4x4`, which pixelkiln records but cannot express in
+  a four-bit Tiled/Godot corner mask.
+- **Unexercised live:** `lower_base_tile_id`/`upper_base_tile_id`, every
+  new shape control, and the top-down prices (Pro 15 or 25, standard planned
+  at 4 from PixelLab's quoted 1 to 4). Sidescroller tile counts at transition
+  sizes other than 0.25 are assumed to be 16. The one sidescroller call
+  returned `metadata.transition_size: 0.0` although 0.25 was sent.
+- **Prompting advice** lives in the skill reference: end each terrain on
+  the word "texture", keep prompts short, and lead with color, season, and
+  outline words.
+
+## Generated effects with PixMiniMax
+
+"How to Make Animated Pixel Art VFX in PixelLab" builds effects with
+generation rather than the VFX workbench (`vfx`). It draws a sheet of
+different effects in one Create Image Pro call, then animates each one with
+PixMiniMax. Most of the steps already exist in pixelkiln. An `imagePro`
+asset at 64×64 returns 16 candidates, and a prompt that lists one effect
+per frame ("an orange fireball facing right, a white and cyan crescent
+slash, ...") fills them. `animate-pixminimax` takes the pick as its parent,
+`lastFrame` pins an ending (a full ice crystal grown from a few blue pixels,
+a splash after a water hammer), and a `"engine": "pro-flash"` revision makes
+that ending from the start frame (the video's plain sword, then a "lightning
+enhanced version"). `driftThreshold` and a `reduce-colors` revision across
+the frame set cover its frame-to-frame color flicker, and `correct-pixelart`
+or `pixelkiln edit` covers its stray pixels. The video's frame counts (12,
+16, 20, 24) are all multiples of 4, which PixMiniMax requires. What is
+missing:
+
+- **Several assets from one candidate sheet.** The video animates eight or
+  more effects from two sheets. `pick` gives one `imagePro` asset one
+  candidate, so each effect is either its own paid call or a hand-copied
+  `source` file. `1dir`'s `batch` is the closest shape, but it fans one call
+  out to declared descriptions, not to picks.
+- **Padding the canvas before animating.** The video reframes most effects
+  onto a larger canvas (64 to 80px) so a flame or splash has room to grow.
+  A revision sends its parent at the parent's own size. The workaround is a
+  hand-padded `source` file.
+- **Trimming a loop's repeated frame.** The video deletes the last frame of
+  a fireball loop because it repeats the first. `animate_image_pixminimax`
+  says `get_image` returns `frame_count + 1` images with index 0 the input
+  unchanged. pixelkiln's frame extraction for this mode is unexercised live,
+  so whether the input frame lands in the set is unknown. There is no
+  manifest way to drop a frame either way.
+- **The cost estimate under-reads long clips.** The MCP tool now prices
+  PixMiniMax by generation time: 64×64 at 4, 8, 16, and 40 frames costs 1, 1,
+  2, and 6 generations. pixelkiln's placeholder,
+  `ceil(width × height × frames / 65536)`, gives 1, 1, 1, and 3 for the same
+  clips. Unlike every other unmeasured estimate here, this one under-reads,
+  so `--budget` can be too low.
+- **Joining two clips.** The video joins two orb animations end to end in
+  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.
 
 ## Map Workshop (scene composition)