pixelkiln 0.88.0 → 0.89.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,17 +1,26 @@
1
1
  # PixelLab coverage and remaining gaps
2
2
 
3
3
  A catalog of PixelLab capabilities checked against PixelKiln: what this
4
- adapter now covers, and what is still absent. It was built by reading all 29
4
+ adapter now covers, and what is still absent. It was built by reading all 31
5
5
  tutorials on PixelLab's official YouTube channel (the original
6
6
  26 — the 12 featured on pixellab.ai plus 14 more from the channel's "PixelLab
7
- Tutorial" playlist, filtered to ~12 months back from that pass — plus 3 more
7
+ Tutorial" playlist, filtered to ~12 months back from that pass — plus 5 more
8
8
  published since: "Level Up Your Game: Custom Sprite Animation Tutorial,"
9
9
  "Pixel Art Animation Tutorial: Images Pro Flash, Skeleton V3 & PixMiniMax,"
10
- and "How to Reduce Colors Like a Pro!") against this adapter's actual source
11
- — and, for the newest pass, against PixelLab's own MCP tool schemas
12
- (`create_image_pro_flash`, `edit_image_pro_flash`, `inpaint_image_pro_flash`,
13
- `get_pro_flash_capabilities`) where a tutorial's framing needed checking
14
- against the live surface, the same standard the original pass held itself to.
10
+ "How to Reduce Colors Like a Pro!", "How to Make Animated Pixel Art VFX in
11
+ PixelLab" (https://www.youtube.com/watch?v=t8FIMv-8QpI), and "PixelLab Pro
12
+ Tilesets: Full Guide" (https://www.youtube.com/watch?v=MbkqpDUFkEg)) against
13
+ this adapter's actual source — and, for the newer passes, against PixelLab's
14
+ own MCP tool schemas (`create_image_pro_flash`, `edit_image_pro_flash`,
15
+ `inpaint_image_pro_flash`, `get_pro_flash_capabilities`, and for the last two
16
+ `create_topdown_tileset`, `create_sidescroller_tileset`, `create_tiles_pro`,
17
+ `create_map`, `animate_image_pixminimax`, `create_image_pro`, `vfx_workbench`,
18
+ and `search_knowledge`) plus the REST OpenAPI document's `/create-tileset`
19
+ and `/create-tileset-sidescroller` request schemas, where a tutorial's
20
+ framing needed checking against the live surface, the same standard the
21
+ original pass held itself to. The PixelLab 0.4.130 release notes (October 2026: Tileset
22
+ Pro, a target palette for Create Image Pro, VFX in the API, normal maps)
23
+ were checked the same way against the REST OpenAPI document.
15
24
  Read this when scoping new PixelLab work, so effort goes toward a
16
25
  confirmed gap with real demand rather than a guess. Nothing here is a
17
26
  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.
55
64
  — a real gap, not a docs fix: `tiles`'s own `tileFeature: "tileset"` draws
56
65
  one terrain's edges, not two named, connected terrain levels with their own
57
66
  transition prompt. Closed by the `terrain` generator; see
58
- `pixellab.md`. Cost is unmeasured (borrows the same 10/15/25 canvas tiers
59
- already confirmed for `tiles` and `1dir`); `/create-tileset-sidescroller`,
60
- reference images, `color_image`, and the `pro` pipeline's own tunables
61
- beyond `spreadX`/`slopeSize`/`raggedness` remain unmodeled.
67
+ `pixellab.md`. Reference images and `color_image` remain unmodeled.
68
+ - **Tileset Pro shape controls, connected sets, and sidescrollers**
69
+ (PixelLab 0.4.130, October 2026). `terrain` styles take
70
+ `terrainRoundness`, `terrainBoundaryAmplitude`/`terrainBoundarySeed`,
71
+ `terrainStepSlope`, and `terrainConnectDiagonals`, each refused outside
72
+ the mode that reads it. `terrainSpreadX`/`terrainSlopeSize` are
73
+ deprecated, since PixelLab now documents both as "No effect". A Pro set at
74
+ `terrainTransitionSize` 0.5 counts as 25 tiles. An asset's `connect` shares
75
+ a terrain with another set in the same style: pixelkiln records each set's
76
+ `metadata.terrain_ids`, sends the other set's id as `lower_base_tile_id` or
77
+ `upper_base_tile_id`, blocks until that set is downloaded, and marks the
78
+ connected set stale when the other is regenerated.
79
+ `terrainOrientation: "sidescroller"` calls `/create-tileset-sidescroller`
80
+ (platform body plus top layer). Its response is the top-down shape with
81
+ `terrain_types` `["central","background"]` but `lower`/`upper` corners,
82
+ lower being the platform. **Measured once**: a 16px set at transition 0.25
83
+ billed exactly 3 generations. Estimates now follow PixelLab's quotes: Pro
84
+ 15 up to 32px and 25 at 64px, standard 4 (the top of its quoted 1 to 4),
85
+ sidescroller 3. What is still open is in
86
+ [Pro tilesets](#pro-tilesets-what-is-left-after-04130) below.
62
87
  - **Pro-tier full-bleed background generation** (`generate-image-v2`, PixelLab's
63
88
  Pro image tier) at arbitrary custom aspect ratios (not just square) —
64
89
  already measured at 40 generations in `docs/ENDPOINTS.md`, but `pixflux`
@@ -317,7 +342,34 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
317
342
  `vfx`, planned, locked, and packed like every other asset (see
318
343
  docs/GENERATORS.md). Still open there: a sprite named by asset rather than
319
344
  by file, the game pack's per-piece clips, and the effect's anchor in the
320
- sheet formats.
345
+ sheet formats. PixelLab 0.4.130 then put a second effects path in the
346
+ REST API: `POST /vfx`, the website's VFX *artist*, which builds an effect
347
+ from a plain-language description and saves it to My effects. It is paid:
348
+ 1 generation for a lite effect with no sprite or one up to 128px, up to 28
349
+ for a pro effect around a 512px sprite, charged on delivery and never more
350
+ than twice the quote. Closed as a `vfx` block's `description` (with
351
+ `artist: "lite" | "pro"`) and `pixelkiln vfx --description`. Plans count
352
+ twice the quote. **Measured once**: a lite effect with no sprite billed
353
+ exactly its 1-generation quote, and its sheet (a 3×3 grid with an
354
+ Aseprite-style atlas) cut into 8 correct frames (docs/ENDPOINTS.md). A
355
+ sprite, the pro artist, and changes are unmeasured. Animated sprites (GIF
356
+ or strips) are not sent yet.
357
+ - **Normal maps** (`POST /normal-map`, PixelLab 0.4.130) — a sprite's normal
358
+ map for engine lighting, 8 to 512px, up to 32 frames as one strip so the
359
+ light stays steady, `opengl` or `directx` convention, 0.5 generations.
360
+ Closed by the `revision` asset shape's `normal-map` mode (a loop goes as
361
+ one strip and comes back cut into frames; a character's directions are
362
+ refused, since a strip would shape every direction from the first) and the
363
+ standalone `pixelkiln normal-map` command. Styles with `enforcePalette` or
364
+ `quality` refuse it so nothing palette-snaps a normal map. **Measured
365
+ once**: an 8-frame 1304×26 strip billed exactly 0.5 and came back the same
366
+ size with matching alpha.
367
+ - **Target palette for Create Image Pro** (`target_palette` on
368
+ `/generate-image-v2`, PixelLab 0.4.130) — an `imagePro` style's `palette`
369
+ is now sent as the colors every pixel must use, with `maxColors` (2 to 64
370
+ per image) and `paletteName`. The beta `smart` mapping is left out because
371
+ PixelLab documents it as single-image only and `imagePro` returns a grid of
372
+ candidates below 171px. Cost unchanged and unmeasured with a palette.
321
373
  - **October 2026 Pro price cut** — PixelLab 0.4.128 moved every Pro tool from
322
374
  20/25/40 to 10/15/25 generations. Cost estimates now use the new prices,
323
375
  and `imagePro` (`generate-image-v2`) is tiered instead of a flat 40: a
@@ -376,6 +428,80 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
376
428
  from an existing 8-direction object's sprites), is not worth a second,
377
429
  pricier engine on its own.
378
430
 
431
+ ## Pro tilesets: what is left after 0.4.130
432
+
433
+ "PixelLab Pro Tilesets: Full Guide" and the 0.4.130 release ("Tileset Pro
434
+ Update... Both top down and sidescroller has been updated! It also supports
435
+ connecting different tilesets") are now mostly covered; see the closed
436
+ `terrain` entries above. Checked against `/create-tileset` and
437
+ `/create-tileset-sidescroller`'s REST schemas, what remains:
438
+
439
+ - **Pro sidescrollers are web-app only.** The video's sidescroller is the
440
+ Pro form at 16, 32, and 64px with top-layer height up to 100%.
441
+ `/create-tileset-sidescroller` has no `mode` field, and its tile size is
442
+ 16 or 32. pixelkiln's sidescroller sets use whatever model that endpoint
443
+ runs.
444
+ - **Older terrain fields are not identity.** `terrainMode`,
445
+ `terrainTransitionSize`, `terrainRaggedness`, `terrainShapeStyle`, and
446
+ `terrainView` never entered `specHash`, so changing one does not mark a set stale. The 0.4.130 fields
447
+ are hashed (when set). Hashing the older ones would make every existing
448
+ terrain lock entry stale at once, so it needs a deliberate migration.
449
+ - **Wall-continuation twins export as duplicates.** The 25-tile layout has
450
+ 21 distinct corner combinations. Four tiles share corners with a twin and
451
+ differ only in `pattern_4x4`, which pixelkiln records but cannot express in
452
+ a four-bit Tiled/Godot corner mask.
453
+ - **Unexercised live:** `lower_base_tile_id`/`upper_base_tile_id`, every
454
+ new shape control, and the top-down prices (Pro 15 or 25, standard planned
455
+ at 4 from PixelLab's quoted 1 to 4). Sidescroller tile counts at transition
456
+ sizes other than 0.25 are assumed to be 16. The one sidescroller call
457
+ returned `metadata.transition_size: 0.0` although 0.25 was sent.
458
+ - **Prompting advice** lives in the skill reference: end each terrain on
459
+ the word "texture", keep prompts short, and lead with color, season, and
460
+ outline words.
461
+
462
+ ## Generated effects with PixMiniMax
463
+
464
+ "How to Make Animated Pixel Art VFX in PixelLab" builds effects with
465
+ generation rather than the VFX workbench (`vfx`). It draws a sheet of
466
+ different effects in one Create Image Pro call, then animates each one with
467
+ PixMiniMax. Most of the steps already exist in pixelkiln. An `imagePro`
468
+ asset at 64×64 returns 16 candidates, and a prompt that lists one effect
469
+ per frame ("an orange fireball facing right, a white and cyan crescent
470
+ slash, ...") fills them. `animate-pixminimax` takes the pick as its parent,
471
+ `lastFrame` pins an ending (a full ice crystal grown from a few blue pixels,
472
+ a splash after a water hammer), and a `"engine": "pro-flash"` revision makes
473
+ that ending from the start frame (the video's plain sword, then a "lightning
474
+ enhanced version"). `driftThreshold` and a `reduce-colors` revision across
475
+ the frame set cover its frame-to-frame color flicker, and `correct-pixelart`
476
+ or `pixelkiln edit` covers its stray pixels. The video's frame counts (12,
477
+ 16, 20, 24) are all multiples of 4, which PixMiniMax requires. What is
478
+ missing:
479
+
480
+ - **Several assets from one candidate sheet.** The video animates eight or
481
+ more effects from two sheets. `pick` gives one `imagePro` asset one
482
+ candidate, so each effect is either its own paid call or a hand-copied
483
+ `source` file. `1dir`'s `batch` is the closest shape, but it fans one call
484
+ out to declared descriptions, not to picks.
485
+ - **Padding the canvas before animating.** The video reframes most effects
486
+ onto a larger canvas (64 to 80px) so a flame or splash has room to grow.
487
+ A revision sends its parent at the parent's own size. The workaround is a
488
+ hand-padded `source` file.
489
+ - **Trimming a loop's repeated frame.** The video deletes the last frame of
490
+ a fireball loop because it repeats the first. `animate_image_pixminimax`
491
+ says `get_image` returns `frame_count + 1` images with index 0 the input
492
+ unchanged. pixelkiln's frame extraction for this mode is unexercised live,
493
+ so whether the input frame lands in the set is unknown. There is no
494
+ manifest way to drop a frame either way.
495
+ - **The cost estimate under-reads long clips.** The MCP tool now prices
496
+ PixMiniMax by generation time: 64×64 at 4, 8, 16, and 40 frames costs 1, 1,
497
+ 2, and 6 generations. pixelkiln's placeholder,
498
+ `ceil(width × height × frames / 65536)`, gives 1, 1, 1, and 3 for the same
499
+ clips. Unlike every other unmeasured estimate here, this one under-reads,
500
+ so `--budget` can be too low.
501
+ - **Joining two clips.** The video joins two orb animations end to end in
502
+ Aseprite. pixelkiln has no frame-set concatenation; `lastFrame` can pin a
503
+ clip's ending to another clip's frame file, but the two sets stay separate.
504
+
379
505
  ## Map Workshop (scene composition)
380
506
 
381
507
  PixelLab's actual scene-building surface: lay out a tile floor, place
@@ -24,14 +24,14 @@ providers, or before any PixelLab account operation.
24
24
  | `pixflux` | Closed palettes or full-bleed backgrounds up to 400×400 | 1 generation |
25
25
  | `1dir` | Reference-guided work or several candidates | 10–25 generations |
26
26
  | `tiles` | Ground variations or connected structures | 10–25 generations |
27
- | `terrain` | A two-terrain Wang tileset for elevation (grass-to-water, floor-to-cliff) | Unmeasured; borrows the same 10–25 canvas tiers |
28
- | `imagePro` | A larger or non-square background/scene, or real style transfer | **10–25 generations** by canvas (64px billed 10; a flat 40 before October 2026) |
27
+ | `terrain` | A two-terrain Wang tileset for elevation (grass-to-water, floor-to-cliff), or a sidescroller platform set | Sidescroller **3**, measured. Top-down plans at PixelLab's quote: Pro 15 (up to 32px) or 25 (64px), standard 4 (quoted 1–4) |
28
+ | `imagePro` | A larger or non-square background/scene, or real style transfer; takes the style `palette` as a hard constraint | **10–25 generations** by canvas (64px billed 10; a flat 40 before October 2026) |
29
29
  | `character` | A character in 4 or 8 directions, its poses (`state`), its loops (`animation`), bust `portrait`s, and `outfit` transfers onto a loop | 1 per standard base, 6 per pro-flash base at 64px (1 from a `reference`), 20–40 per pose or portrait, 1 per template loop per direction (2–4 as `skeleton-v3`), 20 per outfit (measured once) |
30
30
  | `objectPro` | A prop, creature, or vehicle that needs rotations, states, or loops but has no character rig | 6 per base at 64px (1 from a `reference`), **unmeasured**; assumed to match `character` pro-flash |
31
31
  | `isometricTile` | One standalone isometric tile (a raised mesa, a cliff block), 16–64px | **1 generation, measured once** (32px `block`) |
32
32
  | `uiAsset` | A UI panel, button, health bar, or other chrome, from precise `pieces` and/or named `elements` | **20 generations, measured once** (256×192); the borrowed canvas-tier estimate still predicts 40 |
33
33
  | `uiElement` | One UI element (button, slot, bar, dialogue box) from the prompt, 16px and up, with an optional concept image | 10–25 generations, **unmeasured** |
34
- | `vfx` | An animated effect (explosion, aura, lightning, status icons) from a `vfx` block: a `preset` or `recipe`, `parts`, an optional `sprite` to build around; cut into an ordered frame set | **free** (a renderer, not a model) |
34
+ | `vfx` | An animated effect (explosion, aura, lightning, status icons) from a `vfx` block: a `preset` or `recipe`, `parts`, an optional `sprite` to build around; cut into an ordered frame set. Or a `description` (+ `artist`: `lite`/`pro`, a local PNG `sprite`) for PixelLab's paid VFX artist | workbench **free** (a renderer, not a model); `description`: lite 1–5, pro 6–28 by sprite size, billed up to 2× the quote, which is what plan counts (a lite effect with no sprite billed its quote of 1, measured once) |
35
35
  | `imageProFlash` | A styled still on the Pro Flash model (style image + `styleTraits`), 16–256px in multiples of 4; also the natural source for a Pro Flash character's south sprite | 5–9 generations, PixelLab's provisional quote |
36
36
 
37
37
  `tiles` is not limited to top-down ground: `tileType` selects the projection
@@ -92,26 +92,72 @@ into the three fields before the call, with the style's `promptPrefix`/
92
92
  `promptSuffix` wrapped around each one individually rather than the whole
93
93
  string once.
94
94
 
95
- A set is always 16 tiles, or 25 when `terrainTransitionSize` is exactly 1
96
- (the "cliff" layout, where the visual step between levels is tallest and
97
- corners take a third "transition" value); it always resolves straight to a
98
- finished asset with one output file per tile, never a candidate sheet to
99
- pick from, the same as a connectable `tiles` set. `terrainTileSize` sets the
100
- tile edge (16 or 32 in both modes, 64 needs `terrainMode: "pro"`, default
101
- 16). `terrainMode: "standard"` (the default) is the classic Wang pipeline,
95
+ A set is 16 tiles, or 25 in the tall layout: `terrainTransitionSize` 1 on
96
+ standard, or anything above 0.4 on Pro (so 0.5 is already 25 tiles). There
97
+ the step between levels is a wall and corners take a third "transition"
98
+ value. A set always resolves straight to a finished asset with one output
99
+ file per tile, never a candidate sheet to pick from, the same as a
100
+ connectable `tiles` set. `terrainTileSize` sets the tile edge (16 or 32 in
101
+ both modes, 64 needs `terrainMode: "pro"`, default 16).
102
+ `terrainTransitionSize` is 0, 0.25, 0.5, or 1 without `terrainShapeStyle`
103
+ (any value 0–1 with it, though above 0.5 switches to an extended 32-tile
104
+ layout pixelkiln does not model). Pro reads it as wall height: 0 flat, 0.25
105
+ a low bank, 0.5 or 1 a proper wall. `terrainView` picks `low top-down` or
106
+ `high top-down` (API default). The style's `outline`/`shading`/`detail`
107
+ apply here too.
108
+
109
+ `terrainMode: "standard"` (the default) is the classic Wang pipeline,
102
110
  optionally with `terrainShapeStyle` (`square` or `round`) for a fixed
103
- procedural boundary; `terrainMode: "pro"` swaps that for its own shape
104
- controls — `terrainSpreadX` (0 = steep, 1 = gradual boundary), `terrainSlopeSize`
105
- (slope on three sides as a fraction of wall height), and `terrainRaggedness`
106
- (0 = smooth, 1 = rough boundary noise) — and rejects `terrainShapeStyle`
107
- outright. `terrainTransitionSize` (0, 0.25, 0.5, or 1 without `terrainShapeStyle`;
108
- any value 0–1 with it, though above 0.5 switches to an extended 32-tile
109
- layout pixelkiln does not yet model) controls how pronounced the elevation
110
- step looks. `terrainView` picks `low top-down` or `high top-down` (API
111
- default). The style's existing `outline`/`shading`/`detail` apply here too.
112
- Reference images, a forced palette, and the `pro` pipeline's own tunables
113
- beyond the three above (`tileStrength`, `tilesetAdherence`, and the rest)
114
- are not modeled yet; open an issue if a real project needs one of them.
111
+ procedural boundary. `terrainMode: "pro"` rejects `terrainShapeStyle` and
112
+ shapes the border with its own controls, each refused outside the mode that
113
+ reads it:
114
+
115
+ - `terrainRaggedness` (0–1): boundary noise, half strength on tall sets.
116
+ - `terrainRoundness` (0–2): 0 square corners, 1 round, 2 cut at 45°. Pro or
117
+ a shape style; above 1 needs Pro. Defaults 0.85 (Pro), 0.6 (shape style).
118
+ - `terrainBoundaryAmplitude` (0–0.3) and `terrainBoundarySeed` (integer):
119
+ how far the border meanders, and which meander. Pro, or a shape style.
120
+ - `terrainStepSlope` (0–2): 0 a cliff to 2 a gentle slope. Pro at
121
+ `terrainTransitionSize` 0.25 only.
122
+ - `terrainConnectDiagonals` (boolean): joins the two diagonal tiles'
123
+ upper corners into one area. Pro only. With `terrainRoundness: 2` it is
124
+ the fix for 45° paths and coastlines that break into one island per step.
125
+
126
+ `terrainSpreadX` and `terrainSlopeSize` are deprecated: PixelLab ignores
127
+ both now, so leave them out. Reference images, a forced palette, and the
128
+ remaining tunables (`tileStrength`, `tilesetAdherence`) are not modeled.
129
+
130
+ **Connected sets.** An asset's `connect` makes one of its terrains the very
131
+ terrain of another set in the same style, so ocean, sand, and grass paint on
132
+ one map: `"connect": { "lower": { "of": "coast", "terrain": "upper" } }` is
133
+ "this set's lower terrain is `coast`'s upper". The other set generates
134
+ first (the connected one is blocked until it is downloaded, and follows in
135
+ the next wave), PixelLab draws the shared terrain from its base tile, and
136
+ regenerating the other set makes this one stale. Sharing a terrain makes it
137
+ available, not blendable: two terrains with no set of their own between
138
+ them still meet with a hard (in PixelLab's map tool, black) edge, so plan a
139
+ set for every pair that touches.
140
+
141
+ **Sidescroller sets.** `terrainOrientation: "sidescroller"` switches to
142
+ `/create-tileset-sidescroller`: a platform seen from the side. The prompt is
143
+ `"1). mossy stone bricks texture 2). green grass texture"`, the platform
144
+ body and the layer on top of it; the other side of every edge is empty air.
145
+ 16 or 32px tiles, `terrainTransitionSize` (the top layer's height) 0, 0.25,
146
+ 0.5, or 1, and none of the mode, view, or shape controls. It billed 3
147
+ generations for 16 tiles. A sidescroller set connects only its platform
148
+ (`lower`) terrain. PixelLab's Pro sidescroller (64px, taller top layers) is
149
+ web-app only.
150
+
151
+ Prompt each terrain as a short material ending on the word "texture" ("deep
152
+ ocean water texture", "plain smooth sand texture"). PixelLab's "Pro
153
+ Tilesets: Full Guide" shows that without it, Pro sometimes scatters rocks,
154
+ shells, or plants over the surface. Pro needs no long prompts. Put style
155
+ words in the style's `promptPrefix`/`promptSuffix` so they wrap each
156
+ terrain: color, season, and outline words ("autumn", "frosty", "bold black
157
+ outlines with cel shading", "four-color green palette") change the set the
158
+ most, so try two or three at a time. With `terrainTransitionSize` above 0.4
159
+ on Pro, the third numbered description is the wall itself ("crumbling
160
+ dungeon brick wall").
115
161
 
116
162
  `1dir`'s own candidate mechanic (the size-tiered table above) normally
117
163
  returns N variations of one prompt. `/create-1-direction-object` also takes
@@ -147,7 +193,13 @@ and a 64×64 call billed exactly 10 (`docs/ENDPOINTS.md`, "October 2026 Pro
147
193
  price cut"). One call still returns
148
194
  several candidates to pick from by the same size tiering as `1dir` (up to
149
195
  42px: 64, 43–85px: 16, 86–170px: 4, above 170px: 1), reached through the
150
- generic background-job endpoint the same way a `revision` is. Reference
196
+ generic background-job endpoint the same way a `revision` is. The style's
197
+ `palette` goes out as the beta `target_palette` (PixelLab 0.4.130): every
198
+ pixel of every candidate lands on those 2–256 colours, at no extra cost.
199
+ `paletteName` (needs `palette`) names it, and `maxColors` (2–64) caps each
200
+ candidate's colours, with or without a palette. PixelLab's `smart` palette
201
+ mapping is not wrapped: it is "single images only", and this endpoint
202
+ returns a grid of candidates below 171px. Reference
151
203
  images and a style image (`reference_images`, `style_image` +
152
204
  `style_options`, up to 4 subject references plus one style reference) exist
153
205
  on this endpoint but are not modeled yet, and the completed job's exact
@@ -412,6 +464,9 @@ An asset that declares `revision` against a PixelLab style calls `inpaint`
412
464
  (palette quantize, `/reduce-colors`), `correct-pixelart` (edge/noise
413
465
  cleanup, `/correct-pixelart`), `remove-background` (transparent cutout,
414
466
  `/remove-background`, one image up to 400x400, 1 generation measured),
467
+ `normal-map` (`/normal-map`, lighting normals for a sprite or a loop sent as
468
+ one strip, 0.5 generation per call from the docs, a background job; refused
469
+ on a set of directions and in a style with `enforcePalette` or `quality`),
415
470
  `animate` (`/animate-with-text-v3`),
416
471
  `animate-pixminimax` (`/animate-pixminimax`, beta, tier 1 subscription or
417
472
  higher), `animate-skeleton` (`/animate-with-skeleton-v3`, also beta/tier
@@ -463,12 +518,42 @@ the `direction` value. The same tutorial states outright that PixMiniMax
463
518
  "allows up to 40 frames," a second, independent (though still not
464
519
  live-billed) confirmation of the ceiling above.
465
520
 
521
+ Try `vfx` first for an effect: the workbench is free and re-renders the same
522
+ pixels. When presets and parts do not get there and the person would rather
523
+ describe the effect, a `vfx` `description` asks PixelLab's paid VFX artist
524
+ (`POST /vfx`) instead: it cannot be mixed with `preset`/`recipe`/`parts`/`fps`,
525
+ its `sprite` must be a local PNG up to 512px (no `character:` references), and
526
+ every regeneration is a new, re-billed effect. Tell the person the price
527
+ before running it.
528
+ Generate one instead when the effect is a drawn object or a character's own
529
+ motion, such as a water hammer that bursts into a splash, a sword turning
530
+ into lightning, or a mage casting. PixelLab's "How to Make Animated Pixel
531
+ Art VFX" tutorial gives a pattern for that which maps onto what exists. Draw a sheet of different effects in
532
+ one `imagePro` call by listing one effect per frame in the prompt (64×64
533
+ returns 16 candidates), pick one, and animate it with `animate-pixminimax`.
534
+ Pin the ending with `lastFrame` when the motion should arrive somewhere: a
535
+ crystal cluster grown from a few hand-placed blue pixels, a splash after a
536
+ hammer strike, or the same sprite edited by a `"engine": "pro-flash"`
537
+ revision ("make it a lightning-enhanced version") so the clip transforms one
538
+ into the other. Describe motion, not appearance, and ask a loop to "return to
539
+ its original state at the end." Give a growing effect room: the tutorial
540
+ pads most sources onto a larger canvas first, which here means a hand-padded
541
+ `source` file, since a revision sends its parent at its own size. Then clean
542
+ up: `driftThreshold` or a `reduce-colors` revision over the frame set for
543
+ color flicker, `correct-pixelart` or `pixelkiln edit` for stray pixels, and
544
+ check a loop's last frame against its first for a duplicate.
545
+
546
+ Budget `animate-pixminimax` above what `plan` prints for long clips. The MCP
547
+ tool prices it by generation time (64×64 at 16 frames is 2, at 40 frames is
548
+ 6), while pixelkiln's placeholder estimate gives 1 and 3. Tell the person the
549
+ plan may under-read before a long PixMiniMax run.
550
+
466
551
  Parts of Pro Flash image editing are still outside this adapter: `edit`'s
467
552
  reference-image method, palette correction, inpaint's output-method choice,
468
553
  and inpainting with surrounding `context_image`. See
469
554
  [pixellab-roadmap.md](./pixellab-roadmap.md) for the confirmed shape.
470
555
 
471
- Five commands call PixelLab on loose files, outside the manifest and
556
+ Six commands call PixelLab on loose files, outside the manifest and
472
557
  lockfile. `pixelkiln unzoom --from <file> --out <file>` returns upscaled
473
558
  pixel art to its native grid; run it before outside art becomes a
474
559
  `reference` or `styleImages` entry (input at least 256×256, result opaque,
@@ -476,14 +561,20 @@ cost unmeasured). `pixelkiln pixelate --from <file> --out <file>` converts a
476
561
  photo, painting, or render into pixel art with Image to Pixel Art Pro Flash:
477
562
  PixelLab picks the output size, the result is opaque on near-white, an optional
478
563
  `--description` steers the style, and it costs a flat 6 generations
479
- (measured) after asking first. `pixelkiln vfx --preset <name> --out <base>`
564
+ (measured) after asking first. `pixelkiln normal-map --from <png> [--frames
565
+ N] [--convention opengl|directx]` writes a sprite's normal map, or a strip's
566
+ (N equal frames side by side, up to 32), for 0.5 generation after asking
567
+ first. `pixelkiln vfx --preset <name> --out <base>`
480
568
  builds an animated effect (explosion, heal pillar, lightning strike, aura,
481
569
  and more; `pixelkiln vfx presets` and `vfx parts` list them) with PixelLab's
482
570
  VFX workbench, which is free and reached through PixelLab's MCP server. Add
483
571
  `--part <name>` to layer parts, `--sprite <file|character:<id>:<dir>>` to
484
572
  build around a character, and `--game-pack` for per-piece clips. It writes a
485
573
  spritesheet, GIF, atlas JSON, and a `.vfx.json` record whose recipe
486
- re-renders the same effect with `--recipe`. `pixelkiln font --description <text> --out <base>` writes a
574
+ re-renders the same effect with `--recipe`. `pixelkiln vfx --description
575
+ <text> [--artist pro] --out <base>` asks the paid VFX artist instead, prints
576
+ the quote and its 2× ceiling, and asks first; with `--effect <id>` it changes
577
+ that saved effect in place. `pixelkiln font --description <text> --out <base>` writes a
487
578
  `.ttf` and an 80-glyph atlas for PixelLab's documented 15 generations, and
488
579
  asks first. `pixelkiln estimate-skeleton <image> --out <file>` starts an
489
580
  `animate-skeleton` keypoints file, and `pixelkiln skeleton-preview <asset>`
@@ -23,6 +23,16 @@ Read this reference when an asset declares `revision`.
23
23
  `simple` or `complex`, optional `description` hint) cuts the background out
24
24
  to transparency and leaves a locked palette intact; 1 generation measured.
25
25
  It refuses a set parent.
26
+ - `normal-map` (PixelLab `/normal-map`, 8–512px per side, PNG only,
27
+ optional `convention` `opengl` or `directx`) makes lighting data, not art:
28
+ 0.5 generation per call, unmeasured. A loop's frames go as one strip
29
+ (`frames: N`, up to 32) so the light stays steady, and come back cut into
30
+ the parent's `-frame-NN` files; a character's directions are refused (one
31
+ revision per direction instead). It is refused in a style with
32
+ `enforcePalette` or `quality`, since snapping or grid repair would wreck
33
+ the normals: put it in a plain style and point at the parent with
34
+ `fromStyle`. A mirror of a normal map is refused too. For a loose file,
35
+ `pixelkiln normal-map --from <png> [--frames N]` asks before spending.
26
36
  - `reduce-colors` and `correct-pixelart` send no prompt to the provider — the
27
37
  asset's `prompt` stays a manifest-only label. `numColors`/`paletteImage`
28
38
  are mutually exclusive; a `paletteImage` has no size relationship to the
@@ -93,8 +103,10 @@ Read this reference when an asset declares `revision`.
93
103
  paint-over-the-sprite mask editor that writes the mask PNG into the project),
94
104
  `animate`, `animate-pixminimax`, `interpolate` (another same-size sprite as
95
105
  the ending keyframe), `reduce-colors`, `correct-pixelart`, or
96
- `remove-background`; on a PixelLab frame set (or a character's directions)
97
- `edit-animation`, `reduce-colors`, or `correct-pixelart`; on ComfyUI
106
+ `remove-background`, or `normal-map`; on a PixelLab frame set (or a
107
+ character's directions) `edit-animation`, `reduce-colors`, or
108
+ `correct-pixelart`, plus `normal-map` on a loop (never in a style with
109
+ `enforcePalette` or `quality`); on ComfyUI
98
110
  `image-to-image` or `inpaint`; on other providers `image-to-image`. On a
99
111
  single PixelLab sprite, "+ Skeleton animation" creates an `animate-skeleton`
100
112
  revision: poses from a project file, pasted JSON, or "Estimate poses" (one