pixelkiln 0.87.0 → 0.89.0

package/docs/CLI.md

@@ -54,6 +54,8 @@ Which command:
 | see the account balance | `pixelkiln balance` |
 | shrink upscaled outside art to its native grid before using it as a reference | `pixelkiln unzoom --from refs/knight-512.png --out refs/knight.png` |
 | turn a photo, painting, or render into pixel art | `pixelkiln pixelate --from renders/lodge.png --out art/lodge.png` |
+| make a normal map so an engine can light a sprite or a loop strip | `pixelkiln normal-map --from art/hero-walk.png --frames 6` |
+| make a pixel-art effect (spell, hit, explosion, aura), free | `pixelkiln vfx --preset explosion --out fx/explosion` |
 | generate a pixel font (`.ttf` plus glyph atlas) | `pixelkiln font --description "warm orange arcade font" --out fonts/arcade` |
 | start an `animate-skeleton` keypoints file from an image | `pixelkiln estimate-skeleton poses/hero.png --out poses/hero-swing.json` |
 | see a keypoints file's poses over the source before paying | `pixelkiln skeleton-preview hero-swing` |
@@ -1007,8 +1009,9 @@ which recovers the grid instead of redrawing it.
 - PixelLab picks the output size from the source's detected pixel scale; there
   is no size option. A 256x256 render came back 108x109 and a 384x384 render
   84x110. Sources over 2048px on the longer side are scaled down upstream.
-- The result keeps transparency: both opaque renders measured came back with
-  the subject cut out.
+- **The result is opaque**, on a near-white background (transparent source
+  areas become white too), like `unzoom`. Remove the background afterwards
+  when you need a cut-out sprite.
 - `--description` optionally steers the style, e.g. `"retro vibes with light
   dithering"`.
 - A flat **6 generations**, confirmed against a live bill. The command prints
@@ -1023,6 +1026,130 @@ Like `unzoom`, it writes a loose file and leaves the lockfile alone. Declare
 the result as an asset's `source`, or use it as a `styleImages` or
 `reference` path, to bring it into a manifest.
 
+### `normal-map`
+
+```bash
+pixelkiln normal-map --from art/hero-walk.png --frames 6 --convention opengl --out art/hero-walk-normal.png
+```
+
+Makes the normal map of a sprite with PixelLab's `/normal-map`, so a game
+engine can light it. The map is the input's size: RGB is the way each pixel
+faces, and alpha is 255 where the sprite shows and 0 elsewhere.
+
+- `--from` must be a PNG: its alpha marks where the sprite is. For an
+  animation, pass a horizontal strip of equal frames and `--frames <n>` (1–32,
+  default 1). PixelLab shapes the first frame and carries that to the others,
+  so the light stays steady, and returns the map as a strip of the same
+  layout.
+- Each frame must be 8 to 512 pixels per side, and the strip's width must
+  divide evenly by `--frames`. Both are checked before anything is sent.
+- `--convention opengl` (the default) is green up, for Godot, Unity, and
+  Phaser; `--convention directx` is green down, for Unreal.
+- **0.5 generation** per call, a whole strip included, charged only when the
+  map is delivered (PixelLab's documented price; not yet measured here). The
+  command prints that and asks first; `--yes` skips the question,
+  `--budget <n>` refuses when `n` is below it, and `--dry-run` sends nothing.
+- `--out` defaults to `<input>.normal.png` beside the input, and the input is
+  never overwritten. An existing `--out` is replaced only with `--force`.
+- `--json` prints the job id, the map's size, the frame count, the convention,
+  and the billed usage.
+
+It writes a loose file and leaves the lockfile alone. For a manifest asset or
+a loop, declare a [`normal-map` revision](./REVISIONS.md#normal-maps) instead:
+it tracks the parent and cuts a loop's map back into per-frame files.
+
+### `vfx`
+
+```bash
+pixelkiln vfx presets
+pixelkiln vfx parts
+pixelkiln vfx --preset explosion --part scorch_mark --out fx/explosion --game-pack
+pixelkiln vfx --preset heal_pillar --sprite sprites/hero.png --out fx/hero-heal
+pixelkiln vfx --recipe fx/explosion.vfx.json --out fx/explosion-v2
+pixelkiln vfx --effect <saved effect id> --out fx/explosion --force
+```
+
+Builds an animated pixel-art effect with PixelLab's VFX workbench (Create
+VFX), exports it, and downloads it. PixelLab only offers the workbench as an
+MCP tool, with no REST endpoint, so this command talks to PixelLab's MCP
+server with the same `PIXELLAB_API_KEY`. The workbench is a renderer, not a
+model: it is **free** on a subscription and the same recipe renders the
+same pixels every time.
+
+- `vfx presets` and `vfx parts` print PixelLab's current lists: whole-effect
+  presets (explosion, lightning_strike, heal_pillar, portal, aura, and more)
+  and parts to layer on (scorch_mark, spark_burst, stun_stars, rain_streaks,
+  and about 90 others).
+- Start from exactly one of `--preset <name>`, `--recipe <file>`, or
+  `--effect <id>`, or from `--part` alone. `--part <name>` is repeatable and
+  adds parts on top, in order.
+- `--sprite` builds the effect around a character: a local PNG or JPEG, a
+  URL, or a PixelLab reference such as `character:<id>:south`.
+- `--fps <n>` sets the frame rate (1–60). `--name` sets the name saved to
+  your PixelLab "My effects"; it defaults to the preset or the output's file
+  name.
+- `--out <base>` writes `<base>.png` (spritesheet), `<base>.gif`,
+  `<base>.json` (an Aseprite-style frame atlas pointing at the sheet, with the
+  effect's anchor in `meta.anchor`), and `<base>.vfx.json`. `--game-pack`
+  adds `<base>-game.zip`: every piece as its own clip (the whole effect, the
+  layers behind and in front of the sprite, each part) plus a
+  `manifest.json` saying where each plays. Existing files are replaced only
+  with `--force`.
+- `<base>.vfx.json` records the saved effect's id, its edit link on
+  pixellab.ai, the frame facts, the sprite it was built around, and the
+  effect's full **recipe**. Pass it back as `--recipe` to render the same
+  effect again; it reuses the recorded sprite unless you pass `--sprite`.
+- Every run saves the effect to your My effects, where its sliders can be
+  moved on pixellab.ai. Pick the changes up with `--effect <id> --force`,
+  which exports over the saved effect and keeps its name.
+- `--json` prints the export facts and paths; `--dry-run` sends nothing.
+
+For effects that need more than presets and parts (your own layers, exact
+timing, a projectile you drew), use the `vfx_workbench` tool from an MCP
+client such as Claude Code. Then pull the result into the project with
+`pixelkiln vfx --effect <id>`.
+
+#### Described effects (paid)
+
+```bash
+pixelkiln vfx --description "a blue lightning strike that leaves sparks" --out fx/zap
+pixelkiln vfx --description "a green healing aura" --artist pro --sprite sprites/hero.png --out fx/heal
+pixelkiln vfx --description "make it red and faster" --effect <effect id> --out fx/zap --force
+```
+
+`--description` asks PixelLab's VFX artist (`POST /vfx`) to build the
+effect from words instead of the free workbench: it picks the parts, renders
+the effect, checks it, and saves it to My effects. It goes over the REST API
+and needs no MCP.
+
+- `--artist lite` (the default) or `--artist pro`, the stronger artist for
+  detailed effects.
+- `--sprite` must be a local PNG up to 512×512; the artist takes pixels, not
+  a URL or a `character:` reference. `--preset`, `--recipe`, `--part`, and
+  `--fps` are refused with `--description`.
+- `--effect <id>` changes that saved effect in place, with `--description`
+  saying what to change. When `<base>.vfx.json` is that effect's record from
+  an earlier run, its `conversation` is sent too, which PixelLab prices as a
+  change. Without one, PixelLab prices it as a new effect.
+- **Cost.** PixelLab quotes each job and bills on delivery, up to twice the
+  quote when the effect runs long. Its table: lite 1 generation (3 with a
+  sprite over 128 px, 5 over 256 px; a change 1–2), pro 6 (8 with a sprite,
+  14 over 128 px, 28 over 256 px; a change 4–8). The command prints the quote
+  and the twice-the-quote ceiling and asks first. `--budget <n>` refuses when
+  `n` is below the ceiling, `--yes` skips the question, and `--dry-run` sends
+  nothing. A change prices the saved effect's sprite at the top tier unless
+  you pass `--sprite`, since its size is not known here.
+- It writes the same `<base>.png`, `.gif`, `.json`, and `-game.zip` (with
+  `--game-pack`) as the workbench, plus `<base>-normals.png` when a light in
+  the effect made the sprite's normal map. `<base>.vfx.json` records the
+  effect id, edit link, the artist's message, the frame facts, the quote, the
+  bill, and the `conversation`. It holds no recipe; to get a free, repeatable
+  one, run `pixelkiln vfx --effect <id> --out <another base>` afterwards.
+
+To plan, lock, and pack effects with the rest of a project's art, declare
+them in the manifest instead, with the [`vfx` generator](./GENERATORS.md#vfx).
+A `.vfx.json` record from this command works there as a `recipe`.
+
 ### `font`
 
 ```bash
@@ -1106,14 +1233,15 @@ Print the package version. `-v` is an alias.
 | Option | Applies to | Meaning |
 |---|---|---|
 | `--manifest <path>` | manifest commands | Manifest path; defaults to `pixelkiln.manifest.json`. |
-| `--frames <n>` | `estimate-skeleton` | Frames to scaffold after the estimated pose, 3–15; default 4. |
+| `--frames <n>` | `estimate-skeleton`/normal-map | Frames to scaffold after the estimated pose, 3–15; default 4. For normal-map, the equal frames in the `--from` strip, 1–32; default 1. |
+| `--convention <c>` | normal-map | `opengl` (green up, the default) or `directx` (green down, for Unreal). |
 | `--lock <path>` | manifest commands | Lock path; defaults beside the manifest. |
 | `--style a,b` | most workflows | Restrict styles; repeatable. |
 | `--only id1,id2` | most workflows | Restrict asset ids; repeatable. An `animation.directions` shorthand id selects every loop and mirror it expands into. |
 | `--budget <n\|provider=n>` | submit/gen/gallery | Refuse work above this cost. Repeat `provider=n` for every provider in a mixed run; do not mix keyed and unkeyed forms. For `gallery`, the session ceiling that enables generation from the page. |
 | `--force` | gen/fetch/derived commands/recipe install/quality snapshot | Regenerate current work, replace a changed or untracked fetch destination, rebuild current quality-profile output, take ownership of modified/unowned derived output, replace changed recipe files, or replace a changed quality baseline. A refinement rebuild resets approval. |
 | `--dry-run` | supported mutating commands | Inspect without spending or mutating provider state. |
-| `--json` | plan/doctor/audit/cache/status/gallery/salvage/refine/recipe/quality | Machine-readable stdout where supported. For `gallery`, prints the snapshot instead of serving it. |
+| `--json` | plan/doctor/audit/cache/status/gallery/salvage/refine/recipe/quality/unzoom/pixelate/normal-map/vfx/font | Machine-readable stdout where supported. For `gallery`, prints the snapshot instead of serving it. |
 | `--check` | plan/audit/cache | Exit nonzero when selected state is unsafe. |
 | `--yes`, `-y` | confirmed operations | Skip an interactive confirmation. For `refine approve`, it records an already-completed human review; it does not replace one. |
 | `--no-open` | pick/salvage/gallery/edit | Do not automatically open the browser (`open`, `xdg-open`, or `start`, by platform), or the editor for `edit`. |
@@ -1126,13 +1254,13 @@ Print the package version. `-v` is an alias.
 | `--provider <id>` | balance/adopt/salvage/purge/workspace add | Select the account provider for a mixed manifest, or set the workspace catalog's default provider hint. |
 | `--account <label>` | workspace add | Free-form account label, e.g. distinguishing sandboxes. |
 | `--all` | salvage dry run | List every unclaimed object rather than the first 30. |
-| `--from <path>` | init/refine/quality check/unzoom | Existing source tree for init; source PNG or quality record for one-file refine mode; baseline for quality check; the upscaled image for unzoom; the photo or render for pixelate. Omit it to use manifest `style.quality`. |
+| `--from <path>` | init/refine/quality check/unzoom/pixelate/normal-map | Existing source tree for init; source PNG or quality record for one-file refine mode; baseline for quality check; the upscaled image for unzoom; the photo or render for pixelate; the sprite or strip for normal-map. Omit it to use manifest `style.quality`. |
 | `--exclude <names>` | init | Directory/name fragments to exclude; repeatable. |
 | `--generator <name>` | init | Generator assigned to the scaffolded style. |
-| `--name <name>` | init/font | Project name for the scaffolded manifest, or the generated font's family name. |
+| `--name <name>` | init/font/vfx | Project name for the scaffolded manifest, the generated font's family name, or the effect's name in My effects. |
 | `--write-prompts` | adopt | Recover provider prompts into the manifest. |
 | `--port <n>` | pick/salvage/gallery | Local review or gallery server port; otherwise chooses a free port. |
-| `--out <path>` | pack/export/refine/recipe install/quality snapshot/unzoom/pixelate/font | Output base override, final native PNG for path-mode refine, exact recipe destination, quality baseline path, the unzoomed or pixelated PNG, or the font's `<base>.ttf`/`<base>.png`. Export requires one selected tileset. |
+| `--out <path>` | pack/export/refine/recipe install/quality snapshot/unzoom/pixelate/normal-map/vfx/font | Output base override, final native PNG for path-mode refine, exact recipe destination, quality baseline path, the unzoomed, pixelated, or normal-map PNG, the effect's `<base>.png`/`.gif`/`.json`/`.vfx.json`, or the font's `<base>.ttf`/`<base>.png`. Export requires one selected tileset. |
 | `--inputs <path>` | pack/quality snapshot | JSON input array; requires `--out`. Quality cases use `{ id, path, record?, tolerances? }`. |
 | `--columns <n>` | pack/export | Grid columns, 1–1024; default is near-square. |
 | `--format <name>` | export, pack, mount | `export`: `generic` (default), `tiled`, or `godot` (TileSet). `pack` and `mount`: `generic` (default), `aseprite` (sheet JSON), or `godot` (SpriteFrames). |
@@ -1151,9 +1279,17 @@ Print the package version. `-v` is an alias.
 | `--note <text>` | refine approve | Optional review note stored in the quality companion. |
 | `--model-root <path>` | recipe verify | ComfyUI `models` directory. Enables streamed hash checks for every external model declared by the recipe. |
 | `--quantize <n>` | unzoom | `0` auto-detects a palette (default), `-1` keeps every color, `2`-`256` quantizes to exactly that many. |
-| `--description <text>` | font/pixelate | The font's style, e.g. `"warm orange arcade font"`, or an optional style steer for pixelate. |
+| `--description <text>` | font/pixelate/vfx | The font's style, e.g. `"warm orange arcade font"`, an optional style steer for pixelate, or the effect for PixelLab's paid VFX artist (with `--effect`, what to change). |
+| `--artist <a>` | vfx | With `--description`: `lite` (default) or `pro`. |
 | `--weight <w>` | font | `Bold` or `Regular` (default). |
 | `--glyph-px <n>` | font | Native glyph size: `8`, `16` (default), `32`, or `64`. |
+| `--preset <name>` | vfx | Start from one of PixelLab's whole-effect presets; `pixelkiln vfx presets` lists them. |
+| `--recipe <file>` | vfx | Render a recipe: a bare recipe JSON or a `.vfx.json` record from an earlier run. |
+| `--effect <id>` | vfx | Start from an effect saved in your PixelLab My effects, and export over it. |
+| `--part <name>` | vfx | Add a part; repeatable, applied in order. `pixelkiln vfx parts` lists them. |
+| `--sprite <ref>` | vfx | Build the effect around a sprite: a local PNG/JPEG, a URL, or `character:<id>:<direction>`. |
+| `--fps <n>` | vfx | Frame rate, 1–60. |
+| `--game-pack` | vfx | Also download the game-pack ZIP (one clip per piece plus a manifest). |
 | `--generation <n\|hash>` | restore | Bring a replaced generation back: `1` is the most recently replaced, or a prefix of one of its output hashes. One asset at a time. |
 
 ## Exit and output contract

package/docs/ENDPOINTS.md

@@ -206,8 +206,8 @@ Measured live, October 2026:
 
 | Source | Description | Output | Billed |
 |---|---|---|---|
-| 256×256 opaque render (a knight) | none | 108×109, transparent background | **6** |
-| 384×384 opaque render (a mountain keep) | "light dithering" | 84×110, transparent background | **6** |
+| 256×256 opaque render (a knight) | none | 108×109, opaque, near-white background | **6** |
+| 384×384 opaque render (a mountain keep) | "light dithering" | 84×110, opaque, near-white background | **6** |
 
 - It is a background job. The submit response carries `estimated_generations:
   6`, `pricing_provisional: true`, and `image_id`/`source_image_id` (the result
@@ -216,8 +216,10 @@ Measured live, October 2026:
   image at `last_response.images[0]` as `{type, base64, width, height}`.
   `last_response.original_images[0]` is the same size, before PixelLab's
   final "touching up pixels" pass. pixelkiln reads `images[0]`.
-- Unlike `image-to-pixelart`, it keeps alpha: both opaque renders came back
-  with the subject cut out on transparency.
+- **The result is opaque.** Both outputs have every pixel at alpha 255, the
+  subject on a near-white field (`#fefefe`). PixelLab's MCP tool for the same
+  conversion says transparent source areas become white too. Run
+  `remove-background` (1 generation) on the result when you need a cut-out.
 
 Wired up as `pixelkiln pixelate`, a standalone command on a loose file like
 `unzoom`; see [the CLI reference](./CLI.md#pixelate). Use `unzoom` instead
@@ -255,24 +257,164 @@ Re-measured after the cut:
 `proTierCost` (≤65536px² is 10, ≤102400px² is 15, larger is 25), the same
 function `inpaint-v3` and `edit-images-v2` revisions use.
 
-**Create VFX** shipped in the same release as an experimental web tool
-(`pixellab.ai/create-vfx`). As of October 2026 it has no REST endpoint in
-`/v2/openapi.json` and no MCP tool; PixelLab says the MCP tool is coming.
-pixelkiln cannot wrap it until one of those exists; see the
-[roadmap](../skills/pixelkiln/references/pixellab-roadmap.md).
+---
+
+## VFX workbench (MCP only), measured
+
+Create VFX shipped in PixelLab 0.4.128 as a web tool
+(`pixellab.ai/create-vfx`). Since October 2026 it is also the
+`vfx_workbench` tool on PixelLab's MCP server. The workbench still has **no
+REST endpoint**. 0.4.130 added only the paid artist to REST, as `POST /vfx`
+([below](#vfx-artist-post-vfx-measured-once)).
+
+**It is a renderer, not a model.** An effect is a JSON recipe of layers
+(glows, rings, rays, particles, noise, and more), most of them dropped in as
+tuned "parts" with their own sliders. PixelLab renders the recipe to
+pixel-art frames, generates nothing, and bills nothing on a subscription.
+Rendering is deterministic: the same recipe re-rendered gave a byte-identical
+sheet and GIF.
+
+**Calling it.** `POST https://api.pixellab.ai/mcp` with the REST API's own key
+as a bearer token, one JSON-RPC `tools/call` per request. No `initialize`
+handshake or session id is needed (the server issues none). The reply is a
+short server-sent-event stream whose `data:` line holds the JSON-RPC
+response; its `content` is plain text plus PNG contact sheets of the frames.
+
+The tool takes one `argv` list per call:
+
+- `start [--preset <name> | --effect <saved id>] [--sprite <image>] [--fps N]`
+  returns a step id. `--preset` and `--effect` also print the working recipe
+  as one JSON line. `--sprite` accepts base64, a `data:` URL, a URL, or
+  `character:<id>:<direction>` / `object:<id>` / `gallery:<id>`.
+- `<step> add_part '{"parts": [...]}'`, `set_part`, `remove_part`, `throw`, and
+  `render '{"recipe": {...}}'` or `'{"patch": [...]}'` each return a **new**
+  step id. Steps are immutable, so an older id is a way back.
+- `<step> export --name <n> [--replace <saved id>] [--game-pack]` saves to
+  the account's My effects and replies with the effect id, an edit link,
+  `<w>x<h>, <n> frames @ <fps> fps, plays once|loops`, the anchor, and a
+  download folder listing `<slug>.gif`, `<slug>.png` (sheet), `<slug>.json`
+  (an Aseprite/TexturePacker-style atlas with `meta.anchor`), and with
+  `--game-pack`, `<slug>-game.zip` (`whole.png`, one sheet per part,
+  `manifest.json` with each clip's depth, frames, and offset). The download
+  URLs need no auth.
+- `describe presets|parts|recipe|edits|...` documents the rest: 17 presets
+  and about 90 parts as of October 2026.
+
+**Two gaps a wrapper has to cover:**
+
+- No reply after a part is added prints the recipe, and the exported JSON
+  does not carry it. `start --effect <saved id>` does, including slider
+  changes made on pixellab.ai, so pixelkiln reads it back from there after
+  each export.
+- A recipe stores only where the sprite stands (`subject: {x, y, align}`),
+  not its pixels, so re-rendering an effect built around a sprite needs the
+  sprite sent again.
+
+Wired up as `pixelkiln vfx` for loose files ([the CLI reference](./CLI.md#vfx))
+and as the `vfx` manifest generator ([GENERATORS.md](./GENERATORS.md#vfx)),
+which cuts the exported sheet into an ordered frame set. The workbench
+answers "the pixel tools are busy. retry in a few seconds." while another
+render on the account is running; pixelkiln retries that with backoff.
+
+---
+
+## VFX artist (`POST /vfx`), measured once
+
+PixelLab 0.4.130 added "Create VFX" to the REST API: an effects artist (the
+website's VFX creator) that builds an effect from a plain-language
+description, renders it, checks its own work, and saves it to My effects.
+The request and price table come from the OpenAPI document.
+
+**Measured once** (October 2026, Tier 3 account): `pixelkiln vfx
+--description "a small orange fireball flying right, flickering flames,
+short looping trail" --artist lite`, no sprite. The submit quoted 1
+generation and the finished job's `usage` billed exactly 1 (balance 5104
+to 5103).
+The job finished in about 20 s. `files` held the GIF, the sheet, and the
+atlas. The result was a 163×26 canvas, 8 frames at 12 fps, looping, anchor
+`origin` at (80, 13), parts `fireball` and `trail`. The sheet is 489×78, a
+3×3 grid holding 8 frames, and the atlas is an Aseprite-style `frames` list
+with per-frame `frame` rects and 83 ms durations. pixelkiln's slicer cut 8
+correct frames from it. A sprite, the pro artist, a change, and the game
+pack remain unmeasured.
+
+**Request** (`VfxRequest`): `description` (required, up to 8000 characters;
+with `effect_id`, what to change), `sprite` (optional base64 PNG or GIF, up
+to 512×512 per frame; an animation is a GIF or a horizontal strip of
+`sprite_frames`, 1–32), `sprite_fps` (1–60), `artist` (`lite`, the default,
+or `pro`), `effect_id` (change a saved effect in place; it keeps its own
+sprite), `conversation` (from a previous result, with its `effect_id`:
+priced as a change), `name` (up to 80 characters), and `game_pack`.
+
+**Response.** A 202 with `background_job_id`, `status`, `quoted_generations`,
+and `usage`. Poll `GET /background-jobs/{id}` every 5–10 s (PixelLab says
+30–90 s usually). A completed job's `last_response` has `files` (no-auth
+links: `<name>.gif`, `<name>.png` sheet, `<name>.json` with frames,
+durations, `pivot`, and `meta.anchor`, `<name>-game.zip` with `game_pack`,
+`<name>-normals.png` when a light made the sprite's normal map), `effect_id`,
+`name`, `edit_url`, `message`, `canvas` `{w, h}`, `frames`, `fps`, `loop`,
+`anchor` `{kind, x, y}`, `parts`, and `conversation`. The shape of `files`
+(a list or a map) is not documented; pixelkiln reads a URL list, a list of
+`{name, url}` records, or a name-to-URL map, and fails naming the keys it got
+otherwise.
+
+**Errors.** 400 is a request to change (the detail says what), 402 means
+insufficient credits, 429 too many concurrent jobs, and 503 the renderer is
+busy. The shared HTTP policy retries 429 and 503 with backoff.
+
+**Cost** (generations), quoted at submit and charged on delivery: the quote,
+or more when the effect took much longer (the overrun past 25% of the
+quote), never more than twice the quote.
+
+| | lite | pro |
+|---|---|---|
+| new effect, no sprite or up to 128 px | 1 | 6 (8 with a sprite) |
+| change (with `conversation`) | 1 | 4 |
+| sprite up to 256 px | 3 (change 2) | 14 (change 5) |
+| sprite up to 512 px | 5 (change 2) | 28 (change 8) |
+
+An animated sprite adds "a little per frame", unpriced; pixelkiln sends
+still PNG sprites only. Plans and `--budget` count twice the quote, the most
+a job can bill, and the lock records `quotedGenerations` beside the bill read
+from the finished job's `usage`.
+
+Wired up as `pixelkiln vfx --description` ([CLI](./CLI.md#described-effects-paid))
+and as a `vfx` block's `description` ([GENERATORS.md](./GENERATORS.md#described-effects-the-paid-vfx-artist)).
+
+---
+
+## Normal map (`POST /normal-map`), measured once
+
+PixelLab 0.4.130. The body is `image` (base64 PNG, 8 to 512px per frame
+side; an animation is a horizontal strip), `frames` (1 to 32), and
+`convention` (`opengl`, green up, the default; or `directx`). It returns a
+background job, and the finished job's `last_response.image` is the map as
+a PNG the input's size. PixelLab documents 0.5 generations, charged on
+delivery.
+
+**Measured once** (October 2026): `pixelkiln normal-map --frames 8` on a
+1304×26 strip of eight 163×26 effect frames billed exactly 0.5 generations
+(balance 5103 to 5102.5) and returned a 1304×26 RGBA strip. Its alpha
+matched the source's pixel for pixel, so the strip cuts back into the same
+8 frames. Wired up as the `normal-map` revision mode and `pixelkiln
+normal-map` ([REVISIONS.md](./REVISIONS.md#normal-maps)).
 
 ---
 
-## Tilesets: schema only, not yet measured
+## Tilesets: mostly schema, one sidescroller measured
 
 Called out separately because these are the most capable endpoints for level art
-and they are relevant to the disc-golf game. **Costs below are unmeasured.**
+and they are relevant to the disc-golf game. **Top-down costs are unmeasured**:
+pixelkiln plans a top-down set at PixelLab's own quote (Pro 15 for tiles up to
+32px, 25 at 64px; standard 4, the top of its quoted 1 to 4). The sidescroller
+cost below is measured.
 
 `POST /tilesets` (top-down) and `/tilesets-sidescroller` are the current
 versions; `/create-tileset*` are the older aliases with identical schemas.
-The top-down family is wrapped by pixelkiln's `terrain` generator
-(skills/pixelkiln/references/pixellab.md); `/create-tileset-sidescroller` and
-the reference-image/`color_image` knobs below are not.
+Both are wrapped by pixelkiln's `terrain` generator
+(skills/pixelkiln/references/pixellab.md), the sidescroller one with
+`terrainOrientation: "sidescroller"`; the reference-image/`color_image`
+knobs below are not.
 
 They take `lower_description` + `upper_description` (+ optional
 `transition_description`). You describe two terrains and the transition between
@@ -282,8 +424,43 @@ them, and get a tileset that blends them. Distinctively, they accept **both**
 family that combines palette forcing with style anchoring.
 
 Useful knobs: `tile_size`, `tileset_adherence` / `tileset_adherence_freedom`
-(how strictly tiles must fit together), `raggedness` and `slope_size` for edge
-character, plus the usual `outline` / `shading` / `detail`.
+(how strictly tiles must fit together), and the usual `outline` / `shading` /
+`detail`. Pro's border controls are `raggedness`, `roundness`,
+`boundary_amplitude` with `boundary_seed`, `step_slope`, and
+`connect_diagonals`; `spread_x` and `slope_size` are documented as "No
+effect" now and kept only so existing calls work.
+
+`lower_base_tile_id` / `upper_base_tile_id` connect a new set to another
+set's terrain. `GET /tilesets/{id}` (observed live) has a top-level
+`metadata.terrain_ids` of `{ "lower": "<uuid>", "upper": "<uuid>" }`: those
+are the base tile ids, so set A's `upper` id sent as set B's
+`lower_base_tile_id` makes the two share that terrain. pixelkiln records them
+as `terrainIds` when it polls a set.
+
+### Sidescroller, measured
+
+One `POST /create-tileset-sidescroller` call, 16px tiles,
+`transition_size: 0.25`, `lower_description` "mossy stone bricks texture",
+`transition_description` "green grass texture", billed **exactly 3
+generations** (balance 5107 to 5104). PixelLab's MCP tool quotes 2 or 3.
+
+- The body has no `mode`, `view`, `upper_description`, or shape controls.
+  `tile_size` is 16 or 32 only, `transition_size` one of 0, 0.25, 0.5, 1.
+  `lower_base_tile_id` is the only connection field.
+- Submit answers `{ tileset_id, background_job_id, status: "processing" }`,
+  with `usage: null`.
+- `GET /tilesets/{id}` (and `/tilesets-sidescroller/{id}`) returns the
+  top-down shape: 16 tiles named `wang_0` to `wang_15`, each with `corners`
+  and `pattern_4x4`, images base64 inline. But `tileset.terrain_types` is
+  `["central", "background"]` while every corner still says `"lower"` (the
+  platform) or `"upper"` (empty, transparent air; the all-upper tile is
+  blank). pixelkiln records `["lower", "upper"]` so its corner masks work.
+- `metadata.terrain_ids` has `lower` only, and `metadata.view` is `"side"`.
+  `metadata.transition_size` came back `0.0` although 0.25 was sent.
+- `usage` is null on the GET, so the billed amount comes from
+  `GET /background-jobs/{background_job_id}` (`usage.generations: 3.0`).
+
+A trimmed copy of that response is `test/fixtures/tileset/sidescroller-get.json`.
 
 `create-tiles-pro` is a different shape, a single `description` plus
 `style_images`, `tile_view`, `building_*` fields for structures.

package/docs/GENERATORS.md

@@ -9,10 +9,11 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | You need | Generator | Measured cost | Candidates/output |
 |---|---|---:|---|
 | Standalone prop or icon with arbitrary dimensions | `map` (default) | 1 generation | 1 |
-| Exact fixed palette | `pixflux` | 1 generation | 1 inline image |
+| Exact fixed palette | `pixflux`, or `imagePro` for a larger or non-square canvas | 1 generation (`imagePro`: 10–25) | 1 inline image (`imagePro`: 1–64 by size) |
 | Candidate variety, richer rendering, future rotation/animation | `1dir` | 10–25 generations | 4–64 by size |
 | Ground tiles or connectable structural sets | `tiles` | 10–25 generations | variations or complete set |
-| Two-terrain Wang tileset for elevation (grass to water, floor to cliff) | `terrain` | 10–25 generations (unmeasured) | 16 or 25 tiles |
+| Two-terrain Wang tileset for elevation (grass to water, floor to cliff), or a sidescroller platform set | `terrain` | Pro 15, or 25 at 64px; standard plans at 4 (PixelLab's quotes); sidescroller 3 (measured) | 16 or 25 tiles |
+| Platform tileset for a sidescroller (stone body, grass top) | `terrain`, `terrainOrientation: "sidescroller"` | 3 generations | 16 tiles |
 | A single elevation tile — a raised mesa, a cliff block | `isometricTile` | 1 generation | 1 |
 | Larger or non-square scene or background, up to 792 wide and 688 tall | `imagePro` | 10–25 generations by canvas | 1–64 by size |
 | Controlled pose/expression sequence in ComfyUI | `frames` | 0 `free` provider units | one atomic ordered set |
@@ -22,13 +23,16 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | UI chrome — panels, buttons, health bars, toolbars | `uiAsset` | 20 generations (measured once, at 256x192) | 1 composited image |
 | One UI element from a description, 16px and up, optionally guided by a concept image | `uiElement` | 10–25 generations (unmeasured) | 1 image |
 | A styled still on the Pro Flash model, or the south sprite a Pro Flash character will rotate | `imageProFlash` | 5–9 generations (PixelLab's provisional quote) | 1 image |
+| An animated effect (spell, hit, explosion, aura), on its own or around a sprite | `vfx` | free from presets and parts; 1–28 when described to PixelLab's artist (lite measured at 1; plans at twice the quote) | one ordered frame set |
 
-Start with `map` unless a required capability points elsewhere. Forty `map`
-re-rolls cost the same as one 64×64 `1dir` call.
+Start with `map` unless a required capability points elsewhere. Twenty-five
+`map` re-rolls cost the same as one 64×64 `1dir` call.
 
 `terrain` and `imagePro` have no section below: their fields and limits are in
-the [PixelLab skill reference](../skills/pixelkiln/references/pixellab.md), and
-a `terrain` set's export shape is in [Tiles](./TILES.md). Retro Diffusion
+the [PixelLab skill reference](../skills/pixelkiln/references/pixellab.md),
+including Pro's border controls, sidescroller sets, and connecting sets that
+share a terrain (an asset's `connect`), and a `terrain` set's export shape is
+in [Tiles](./TILES.md). Retro Diffusion
 `animation` styles are in [Set up Retro Diffusion](./RETRO_DIFFUSION.md).
 
 ## `map`
@@ -535,6 +539,154 @@ billed yet. The plan prices it on the same 10/15/25 canvas tiers as
 job's shape is read defensively (`pollUiElement` names the keys it got if
 the shape is not the documented `images` list).
 
+## `vfx`
+
+`vfx` renders animated pixel-art effects with PixelLab's VFX workbench:
+spells, hits, explosions, auras, shields, status icons, weather. The workbench
+is a renderer, not a model. An effect is a recipe of layers, most of them
+dropped in as tuned parts, and it renders the same pixels every time. It is
+free on a PixelLab subscription, and PixelLab offers it only over MCP, which
+pixelkiln calls with the same `PIXELLAB_API_KEY`. An effect can also be
+described in words for PixelLab's paid VFX artist; see
+[Described effects](#described-effects-the-paid-vfx-artist).
+
+```jsonc
+{
+  "styles": {
+    "fx": { "generator": "vfx", "outDir": "art/fx" }
+  },
+  "assets": {
+    "robot.zap": {
+      "prompt": "lightning on the robot",
+      "vfx": { "preset": "lightning_strike", "sprite": "art/chars/robot-south.png" }
+    },
+    "boom": {
+      "vfx": { "preset": "explosion", "parts": [{ "name": "scorch_mark" }], "fps": 12 }
+    },
+    "zap.tuned": {
+      "vfx": { "recipe": "fx/zap.vfx.json" }
+    }
+  }
+}
+```
+
+- Start from one `preset` (`pixelkiln vfx presets` lists them) or one
+  `recipe`, and add `parts` (`pixelkiln vfx parts`) on top. `parts` alone also
+  start an effect. Each part is `{ "name": … }` plus any of the workbench's
+  own options, sent as given: `size`, `colour`, `amount`, `speed`, `start`,
+  `end`, `anchor`, `at`, `offset`, `travel`, `role`, `params`.
+- `recipe` is a bare recipe JSON or a `.vfx.json` record written by
+  `pixelkiln vfx`. That is how an effect tuned by hand, in the workbench or
+  with the sliders on pixellab.ai, enters a manifest: export it with
+  `pixelkiln vfx --effect <id> --out fx/zap`, then point `recipe` at the
+  record.
+- `sprite` builds the effect around a character: a manifest-relative PNG or
+  JPEG, or a `character:<id>:<direction>`, `object:<id>`, or `gallery:<id>`
+  reference. A path may be another asset's output. Until that file exists
+  the effect is blocked, and `gen` renders it in a later wave once it does.
+  The exported frames include the sprite.
+- `fps` overrides the preset's or recipe's own rate. `name` is the effect's
+  name in your PixelLab My effects; it defaults to `pixelkiln:<style>/<asset>`.
+  `prompt` is optional and only a label.
+- An asset that lists no `styles` joins every style of its own kind: a `vfx`
+  style takes the assets with a `vfx` block, and every other style the
+  assets without one. A mirror or revision of an effect names its style.
+
+The workbench builds an effect from tuned parts. An effect that is a drawn
+object or a character's own motion, like a sword turning into lightning or a
+mage casting a fireball, is a job for generation instead: an `imagePro`
+sheet of candidates, then an `animate-pixminimax` revision with an optional
+`lastFrame`. PixelLab's
+[VFX tutorial](https://www.youtube.com/watch?v=t8FIMv-8QpI) shows that
+workflow, and [Set up PixelLab](./PIXELLAB.md#animated-effects) maps it onto
+PixelKiln.
+
+**Outputs.** The exported spritesheet is cut into frames,
+`<asset>-frame-00.png` onward, recorded as an ordered frame set with the
+effect's fps and whether it loops. `pack` lays them out like any loop, and
+`pack --format godot` writes a one-shot effect with `loop: false`. The
+gallery plays them, shows the rendered size, and links each generation to
+its effect on pixellab.ai.
+
+**Identity.** An effect goes stale when its preset, parts, fps, recipe
+content, or sprite content changes. It does not go stale for a renamed or
+moved file, a new `name` or `prompt`, or a style's prompt, size, or palette
+settings, none of which reach the workbench. Plan cannot see slider changes
+made on pixellab.ai or changes to PixelLab's own presets.
+
+**Regenerating.** A regeneration exports over the effect the asset rendered
+last time, so My effects keeps one entry per asset. If that effect was
+changed on pixellab.ai since, or deleted, a new effect is saved instead and
+the edited one is left alone; the lock records why.
+
+### Described effects: the paid VFX artist
+
+A `description` in place of a preset, recipe, or parts asks PixelLab's VFX
+artist (`POST /vfx`, added in 0.4.130) to build the effect. The artist is the
+same one behind the website's VFX creator: it picks and tunes parts from your
+words, renders the effect, checks its own work, and saves it to My effects.
+
+```jsonc
+"zap.described": {
+  "vfx": {
+    "description": "a blue lightning strike that hits the ground and leaves sparks",
+    "artist": "pro",
+    "sprite": "art/chars/robot-south.png"
+  }
+}
+```
+
+Use the free workbench when a preset or a few parts get you there, or when
+you want to tune the effect by hand; it renders the same pixels every time.
+Use the artist when you would rather describe the effect than assemble it.
+It costs generations, and the same description draws a different effect
+each time.
+
+- `description` is the effect in plain words: what it is, its colours, how
+  it moves, how long. It cannot be combined with `preset`, `recipe`,
+  `parts`, or `fps`; the artist picks those itself.
+- `artist` is `lite` (the default, quick and cheap) or `pro` (the stronger
+  artist, for detailed effects).
+- `sprite` must be a local PNG up to 512×512, another asset's output
+  included. The endpoint takes the sprite's pixels, so `character:`,
+  `object:`, and `gallery:` references are refused; point at the
+  character's own output file instead. JPEG is refused too.
+- `name` is capped at 80 characters, and the default is cut to fit.
+
+**Cost.** PixelLab quotes each job when it is submitted and bills on
+delivery: the quote, or more when the effect ran long, never more than twice
+the quote. The quote comes from this table (generations):
+
+| | lite | pro |
+|---|---|---|
+| no sprite, or a sprite up to 128 px | 1 | 6 (8 with a sprite) |
+| sprite up to 256 px | 3 | 14 |
+| sprite up to 512 px | 5 | 28 |
+
+`plan` and `--budget` count **twice the quote**, the most a job can bill, so
+a budget is never overrun. A sprite that is another asset's output not drawn
+yet is priced at the 512 px tier until it exists. The lock records PixelLab's
+own quote (`quotedGenerations`) and the bill read from the finished job.
+These prices are PixelLab's published table; no artist bill has been
+measured here yet.
+
+**Outputs and identity.** The artist's spritesheet is cut into the same
+ordered frame set as the workbench's, with its fps and loop flag. The lock
+records the effect id, its edit link, the artist's message, the anchor, the
+parts it used, and the file names. The asset goes stale when its
+`description`, `artist`, or sprite content changes, and not for `name` or
+`prompt`. Adding these fields left every workbench effect's identity as it
+was.
+
+**Regenerating.** Every regeneration is a new effect, billed again. The
+manifest's description is the whole effect, not a change to the last one,
+so it is never sent as one. The previous effect stays in My effects, and the
+lock names it (`previousEffect`). To change one saved effect in place at the
+change price, use `pixelkiln vfx --description "<what to change>" --effect
+<id>` ([CLI](./CLI.md#vfx)). To turn a described effect into a free,
+repeatable recipe, export it with `pixelkiln vfx --effect <id> --out
+fx/zap` and point a workbench `recipe` at the record.
+
 ## Style variants
 
 Styles are namespaces. Add another style to re-derive the same asset ids into a