pixelkiln 0.53.4 → 0.55.0

package/docs/CHARACTERS.md

@@ -8,6 +8,12 @@ runs it in waves, and `pack` writes every direction and loop for the engine.
 This page is the reference for the manifest shapes; the [manifest
 reference](./MANIFEST.md) covers the fields every asset shares.
 
+A prop, creature, or vehicle with no skeleton to fit — a floating rune, a
+treasure chest, a turret — wants `objectPro` instead: the same base/state/
+animation shapes and `asset.state`/`asset.animation` authoring described
+here, minus everything template/skeleton-specific. See
+[GENERATORS.md](./GENERATORS.md#objectpro).
+
 ## The three shapes
 
 A cast in full, with a base, a state, and two loops. This is the robot on

package/docs/ENDPOINTS.md

@@ -237,6 +237,49 @@ Given that `color_image` is honoured on `pixflux` but silently ignored on
 `resize`, **verify the palette actually holds on a single tileset before
 committing to a set**.
 
+## Standalone isometric tile: schema documented, cost measured once
+
+`POST /create-isometric-tile` (+ `GET`/`DELETE /isometric-tiles/{tile_id}`) is
+a *third*, separate path to isometric content, distinct from both
+`create-tiles-pro`'s `tile_type: "isometric"` (a full Wang/connectable set)
+and the tileset family above (confirmed square-only, no isometric option at
+all). This one generates a single standalone tile — no candidates, no
+connectable set — and is wrapped by pixelkiln's `isometricTile` generator
+(docs/GENERATORS.md).
+
+`isometric_tile_shape` (`"thin tile"` ~15% canvas height, `"thick tile"`
+~25%, `"block"` ~50%, the default) is a direct thickness/elevation control,
+more granular than anything in `tiles`/`terrain`. `isometric_tile_size` (16
+or 32, default 16) is the API's own tile grid, a separate concept from
+`image_size` (the generation canvas, 16-64px each side; the endpoint's own
+description states "sizes above 24x24 often produce better quality
+results"). `outline` defaults to `"lineless"` here specifically — unlike
+`create-tiles-pro`'s `"outline"` default — with its own three-value enum
+(`"single color outline"`, `"selective outline"`, `"lineless"`); `shading`
+and `detail` reuse the same enums as the tileset family above.
+
+`GET /isometric-tiles/{tile_id}` carries no `status` field either: it answers
+**423 while still processing** and 200 with the image once done, matching the
+tileset family's own polling contract. Unlike every other job resource here,
+its response shape is `{ image: Base64Image, usage }` — the finished tile
+comes back embedded as base64, not a `storage_urls` link.
+
+**Its own OpenAPI response schema example is misleading on cost.** It shows
+`{ type: "usd", usd: 0.02 }`, which reads as billing in real dollars rather
+than subscription generations, unlike everything else in this file. A real
+call against a live subscription account (Tier 2, "generations" balance)
+billed exactly `{ type: "generations", generations: 1 }` instead — the
+documented shape never actually appeared. Measured at one size/shape
+combination only (32px canvas, `"block"`); the endpoint's own docs give no
+size-tiering formula the way `1dir`/`tiles` do, so pixelkiln's
+`isometricTileCost()` assumes flat 1-generation pricing across the whole
+16-64px range rather than guessing a tier.
+
+`init_image`/`init_image_strength` (image-to-image) and `color_image`
+(native forced-palette) both exist on this endpoint and are not modeled by
+pixelkiln yet — no `style_images` concept exists here at all, unlike
+`create-tiles-pro`.
+
 ---
 
 ## Recipes
@@ -402,8 +445,10 @@ Listed so the gaps are known rather than assumed away:
 - `image-to-pixelart-pro` takes only `image` + `description`, no size fields.
   The non-Pro version is characterised above.
 - the tileset family, with schema documented above and costs unmeasured
-- `create-isometric-tile`, `create-ui-asset`, `generate-font-pro`, all job-based,
-  with response shapes not in the simple `{usage, image}` form
+  (the standalone isometric tile endpoint alongside it now has one real
+  measured data point — see above)
+- `create-ui-asset`, `generate-font-pro`, both job-based, with response
+  shapes not in the simple `{usage, image}` form
 - the character family beyond what the `character` generator uses: portraits
   (`portrait-character-pro` both ways, `/characters/{id}/portrait`), outfit
   transfer (`transfer-outfit-v2`), lip-sync, skeleton animation, and

package/docs/GENERATORS.md

@@ -12,6 +12,7 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | Exact fixed palette | `pixflux` | 1 generation | 1 inline image |
 | Candidate variety, richer rendering, future rotation/animation | `1dir` | 20–40 generations | 4–64 by size |
 | Ground tiles or connectable structural sets | `tiles` | 20–40 generations | variations or complete set |
+| A single elevation tile — a raised mesa, a cliff block | `isometricTile` | 1 generation | 1 |
 | Controlled pose/expression sequence in ComfyUI | `frames` | 0 `free` provider units | one atomic ordered set |
 | A character facing 4 or 8 directions, its poses, and its animations | `character` | 1 per base (standard), 20–40 per pose, 1 per template loop | one set of directions, or one ordered loop |
 
@@ -201,6 +202,94 @@ bot.dented, east"), links parent and children in the record, and counts the
 family in the style header ("3 characters, 4 states, 6 loops"). See
 [Characters](./CHARACTERS.md).
 
+## `objectPro`
+
+`objectPro` wraps PixelLab's `/create-object-pro-flash` — the same base
+→ state → animation family as `character`, for PixelLab's separate,
+skeleton-free "object" entity. Use it for a prop, creature, or vehicle that
+needs a pose (`state`) or a directional loop (`animation`) but has no
+humanoid/quadruped rig to fit: a floating rune, a treasure chest, a turret,
+anything `character`'s template concept does not describe.
+
+It reuses `character`'s own authoring shapes — `asset.state`/`asset.animation`
+are the identical fields, and a `mirror` flips an animation's direction the
+same way. Everything `character`'s templates/proportions/skeleton bring is
+simply absent: no `mode`, `template`, `proportions`, `isometric`, `concept`,
+or `styleCharacter` — `/create-object-pro-flash` is the only base-creation
+path, and setting `animation.template`/`subject`/`outline`/`shading`/`detail`
+on an `objectPro` animation is rejected at resolve time rather than silently
+ignored, since none of them reach the API for an object.
+
+- `objectDirections` (1 or 8, default 8, style-level) is the rotation count —
+  a real choice `character` does not offer (character pro-flash is always 8).
+  A 1-direction object's `animation.direction` must be `south`; anything else
+  is rejected, since the endpoint 400s if `directions` is even sent for a
+  1-direction object.
+- `reference` (asset-level, base only) rotates the author's own south-facing
+  sprite instead of drawing from the prompt, same as `character`'s reference
+  — but only ever reads the south image, since one frame is all
+  `/create-object-pro-flash` takes.
+- A style image anchors the look the same way `character` pro-flash's does,
+  including `styleTraits` (which of the image's palette/outline/detail/shading
+  to carry over).
+- Regenerating an already-animated direction is simpler than `character`'s:
+  the object endpoint has its own `replace_existing` flag, so PixelKiln
+  always passes it rather than fetching the object first to find and delete
+  a prior take (`character`'s own workaround for not having one).
+
+**Cost is not independently measured.** `objectProCost()` assumes
+`/create-object-pro-flash`/its state/its animation price identically to
+`character`'s own measured pro-flash formula (`proFlashCharacterCost`),
+since the request bodies are near-identical minus `template_id` — treat it
+as a working assumption, not a confirmed number, until checked against a
+live account.
+
+Adoption (`pixelkiln adopt`) has not been extended for `objectPro`'s own
+`<object id>#<animation group id>` remote-id scheme yet, unlike `character`'s
+dedicated adoption path — a base may already be adoptable through the
+generic object-matching pixelkiln already does for `1dir`/`map`, since a
+pro-flash object shares that same `/objects` identity space, but this is
+untested.
+
+## `isometricTile`
+
+`isometricTile` wraps PixelLab's `/create-isometric-tile` — a different
+endpoint from both `tiles` (which also has its own `isometric` `tileType`
+for full connectable Wang/road/building sets) and `terrain` (`/create-tileset`,
+confirmed square-only, no isometric option at all). This one generates a
+single standalone isometric tile, no candidates, no connectable set.
+
+Use it when a per-tile height/elevation primitive is what's needed — a raised
+mesa, a cliff block, a standalone rock outcrop — rather than a connected
+ground set.
+
+- `isometricTileShape` controls vertical thickness: `"thin tile"` (~15% of
+  canvas height), `"thick tile"` (~25%), or `"block"` (~50%, the API
+  default). This is a more direct elevation control than anything in `tiles`
+  or `terrain`.
+- `isometricTileSize` is the API's own tile grid size, 16 or 32 (default 16)
+  — a separate concept from `size`, the generation canvas (16–64px; the
+  endpoint's own guidance is that sizes above 24px "often produce better
+  quality results").
+- `outline` defaults to `"lineless"` on this endpoint specifically, unlike
+  `tiles-pro`'s `"outline"` default — its own valid values are `"single
+  color outline"`, `"selective outline"`, or `"lineless"`.
+
+**Cost: 1 generation flat, measured.** PixelLab's own OpenAPI response schema
+example shows `{ type: "usd", usd: 0.02 }`, which reads as billing in real
+dollars — but a real call against a live subscription account billed exactly
+1 generation instead (`usage: { type: "generations", generations: 1 }`), and
+`costUnit` here is `"generations"` like every other generator. Only one
+size/tile-shape combination (32px canvas, `"block"`) has actually been
+measured; the endpoint's own docs give no size-tiering formula the way
+`1dir`/`tiles` do, so this assumes flat pricing across the 16–64px range
+rather than guessing a tier.
+
+Style images, `init_image`/`init_image_strength` (image-to-image), and
+`color_image` (native forced-palette) are not modeled yet — PixelKiln's own
+`palette`/`enforcePalette` post-processing works generically on the
+downloaded tile regardless, if a closed palette is what's actually needed.
+
 ## Style variants
 
 Styles are namespaces. Add another style to re-derive the same asset ids into a

package/docs/MANIFEST.md

@@ -113,7 +113,7 @@ One asset using the fields most projects reach for:
 |---|---|---|
 | `extends` | style id | Optional parent style. The child inherits resolved settings but must declare its own `outDir`. |
 | `provider` | top-level default | Provider registry id for this style. Assets cannot override it. |
-| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `character`, or provider-specific `animation`/`frames`. |
+| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
 | `outDir` | string, required | Output directory relative to the manifest. |
 | `promptPrefix` | `""` | Prepended to every participating asset prompt. |
 | `promptSuffix` | `""` | Appended to every participating asset prompt. |

package/package.json

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

package/schema/manifest.schema.json

@@ -42,7 +42,9 @@
                       "frames",
                       "character",
                       "terrain",
-                      "imagePro"
+                      "imagePro",
+                      "isometricTile",
+                      "objectPro"
                     ],
                     "default": "map"
                   },
@@ -236,6 +238,28 @@
                       "high top-down"
                     ]
                   },
+                  "isometricTileSize": {
+                    "type": "number",
+                    "enum": [
+                      16,
+                      32
+                    ]
+                  },
+                  "isometricTileShape": {
+                    "type": "string",
+                    "enum": [
+                      "thin tile",
+                      "thick tile",
+                      "block"
+                    ]
+                  },
+                  "objectDirections": {
+                    "type": "number",
+                    "enum": [
+                      1,
+                      8
+                    ]
+                  },
                   "noBackground": {
                     "type": "boolean",
                     "default": true
@@ -469,7 +493,9 @@
                       "frames",
                       "character",
                       "terrain",
-                      "imagePro"
+                      "imagePro",
+                      "isometricTile",
+                      "objectPro"
                     ],
                     "default": "map"
                   },
@@ -663,6 +689,28 @@
                       "high top-down"
                     ]
                   },
+                  "isometricTileSize": {
+                    "type": "number",
+                    "enum": [
+                      16,
+                      32
+                    ]
+                  },
+                  "isometricTileShape": {
+                    "type": "string",
+                    "enum": [
+                      "thin tile",
+                      "thick tile",
+                      "block"
+                    ]
+                  },
+                  "objectDirections": {
+                    "type": "number",
+                    "enum": [
+                      1,
+                      8
+                    ]
+                  },
                   "noBackground": {
                     "type": "boolean",
                     "default": true

package/schema/recipe.schema.json

@@ -117,7 +117,9 @@
                 "frames",
                 "character",
                 "terrain",
-                "imagePro"
+                "imagePro",
+                "isometricTile",
+                "objectPro"
               ],
               "default": "map"
             },
@@ -311,6 +313,28 @@
                 "high top-down"
               ]
             },
+            "isometricTileSize": {
+              "type": "number",
+              "enum": [
+                16,
+                32
+              ]
+            },
+            "isometricTileShape": {
+              "type": "string",
+              "enum": [
+                "thin tile",
+                "thick tile",
+                "block"
+              ]
+            },
+            "objectDirections": {
+              "type": "number",
+              "enum": [
+                1,
+                8
+              ]
+            },
             "noBackground": {
               "type": "boolean",
               "default": true

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

@@ -54,6 +54,39 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `pixellab.md`. Reference images and a style image
   (`reference_images`/`style_image`) remain unmodeled, and the completed
   job's response shape has not itself been exercised live yet.
+- **A standalone single isometric tile** (`/create-isometric-tile`, a third,
+  separate path to isometric content distinct from both `tiles`'
+  `tileType: "isometric"` and `terrain`'s `/create-tileset`, which is
+  confirmed square-only with no isometric option at all) — a real gap: no
+  per-tile elevation primitive existed for a raised mesa or a cliff block
+  outside a connected ground set. Found via direct API/schema investigation,
+  not a tutorial (real downstream demand: a Godot game's terrain-verticality
+  work). Closed by the `isometricTile` generator; see `pixellab.md`. Its
+  `isometricTileShape` (thin/thick/block) is a direct thickness control
+  `tiles`/`terrain` do not have. **Cost measured once, and it corrected a
+  wrong assumption**: the endpoint's own OpenAPI response schema example is
+  `{ type: "usd", usd: 0.02 }`, which reads as real-dollar billing, but a
+  live call against a subscription account billed exactly 1 generation
+  instead — `costUnit` is `"generations"` here, not `"usd"`. Only one
+  size/shape combination (32px, `"block"`) has actually been measured; no
+  size-tiering formula is documented the way `1dir`/`tiles` have one. Style
+  images, `init_image`/`init_image_strength`, and `color_image` remain
+  unmodeled.
+- **Object Creator's rotation/state/animation family** (`/create-object-pro-flash`,
+  a skeleton-free entity distinct from both `character` and the generic
+  `/objects` polling resource `1dir`/`map` already use) — demonstrated in
+  "Object Creator" and used throughout "GBA-Style Sprites" and "Build a Game
+  with AI"; `map` (one generation, no direction/state concept) and `1dir`
+  (one direction only) were the closest analogs, and neither modeled
+  rotation, states, or animation for a plain object. Closed by the
+  `objectPro` generator; see `pixellab.md`. It reuses `character`'s own
+  `asset.state`/`asset.animation` authoring shapes and mirror handling
+  rather than inventing parallel ones. **Cost is not independently
+  measured**: assumed identical to `character` pro-flash's own measured
+  formula, since the request bodies are near-identical minus `template_id` —
+  a real assumption pending a live check, not a confirmed number the way
+  `isometricTile`'s now is. Batch "pack" generation (N distinct objects from
+  one call) remains unmodeled — see above.
 
 ## Generic (non-character) animation and interpolation
 
@@ -69,17 +102,13 @@ PixelLab"). Pixelkiln's only interpolation concept is the `character` v3
 loop's `startFrame`/`endFrame`, scoped strictly inside a `character` asset —
 there is no way to animate a `map`, `pixflux`, or `tiles` output at all.
 
-## Object Creator
-
-Generic 8-direction object rotation, object "states" (prompted variations of
-an existing object), object animation (with a pro-vs-V3 model choice), and
-batch "pack" generation (one prompt or style reference → N distinct objects,
-each with an optional per-item text override) — all scoped to a standalone
-object, not a `character`. Demonstrated in "Object Creator" and used
-throughout "GBA-Style Sprites" and "Build a Game with AI." Pixelkiln's
-closest generator is `map` (single prop, one generation, no direction or
-state concept at all) and `1dir` (implies one direction). Neither models
-rotation, states, or animation for a plain object.
+## Object Creator: batch generation only
+
+Object Creator's "pack" generation — one prompt or style reference → N
+distinct objects in one call, each with an optional per-item text override —
+remains unmodeled. Demonstrated in "Object Creator" and used throughout
+"GBA-Style Sprites" and "Build a Game with AI." The rest of Object Creator
+(8-direction rotation, states, pro/v3 animation) is closed; see below.
 
 ## UI elements and RPG UI kits
 

package/skills/pixelkiln/references/pixellab.md

@@ -125,6 +125,63 @@ response shape has not been exercised against a live account — see
 `pollImagePro` in `src/providers/pixellab.ts` if a real call ever
 contradicts what it assumes.
 
+`objectPro` wraps `/create-object-pro-flash` — the same base → state →
+animation family `character` uses (`docs/CHARACTERS.md`), for PixelLab's
+separate, skeleton-free "object" entity, distinct from the generic
+`/objects` polling resource `1dir`/`map` already share. It reuses
+`character`'s own `asset.state`/`asset.animation` authoring fields and
+mirror handling verbatim rather than inventing parallel ones — an
+`objectPro` asset's `state`/`animation` are validated identically, since an
+object's state is a strict subset of a character's (no `paletteFromReference`/
+`canvas` equivalent on the API, always inherits the parent's exact canvas)
+and its animation is the same minus the template/skeleton concept objects
+have none of: `template`, `subject`, `outline`, `shading`, `detail` on an
+`objectPro` animation are rejected at resolve time rather than silently
+dropped. `objectDirections` (1 or 8, default 8) is a real choice `character`
+pro-flash does not offer (always 8); a 1-direction object's animation must
+target `south` — passing any other direction, or `directions` at all to the
+API for a 1-direction object, is what the endpoint itself 400s on.
+Regenerating an already-animated direction is simpler than `character`'s
+own "find and delete the prior take" dance: `/objects/{id}/animations` has
+its own `replace_existing` flag, which PixelKiln always passes. **Cost is
+not independently measured** — `objectProCost()` assumes it prices
+identically to `character` pro-flash's own measured formula
+(`proFlashCharacterCost`), since the request bodies are near-identical minus
+`template_id`; treat it as a working assumption pending a live check.
+Batch "pack" generation (PixelLab's Object Creator can make N distinct
+objects from one call) and `objectPro`'s own place in `pixelkiln adopt` are
+not modeled yet.
+
+`isometricTile` wraps a *third*, separate path to isometric content:
+`/create-isometric-tile`, distinct from both `tiles`' own `tileType:
+"isometric"` (a full connectable set) and `terrain`'s `/create-tileset`
+(confirmed square-only — no isometric option exists there at all). It
+generates one standalone tile, no candidates, no connectable set — the
+shape for a per-tile elevation primitive (a raised mesa, a cliff block) when
+a connected ground set is not what's needed. `isometricTileShape` controls
+vertical thickness — `"thin tile"` (~15% canvas height), `"thick tile"`
+(~25%), or `"block"` (~50%, the API default) — the most direct
+height/elevation knob of any generator here. `isometricTileSize` is the
+API's own tile grid (16 or 32, default 16), separate from `size` (the 16–64px
+generation canvas; the endpoint's own guidance is that sizes above 24px
+"often produce better quality results"). `outline` defaults to `"lineless"`
+on this endpoint specifically (`tiles-pro`'s own default is `"outline"`),
+with its own three-value enum (`"single color outline"`, `"selective
+outline"`, `"lineless"`); `shading`/`detail` reuse the same enums `terrain`
+does. **Cost: 1 generation flat, measured** — PixelLab's own OpenAPI response
+example shows `{ type: "usd", usd: 0.02 }`, which reads as real-dollar
+billing, but a real call against a live subscription account billed exactly
+1 generation instead (`usage: { type: "generations", generations: 1 }`);
+`costUnit` here is `"generations"` like every other generator, not `"usd"`.
+Only one size/shape combination (32px, `"block"`) has actually been
+measured, and the endpoint documents no size-tiering formula, so
+`isometricTileCost()` assumes flat pricing across the 16–64px range rather
+than guessing a tier. Style images, `init_image`/`init_image_strength`
+(image-to-image), and `color_image` (native forced-palette) exist on this
+endpoint and are not modeled yet; pixelkiln's own `palette`/`enforcePalette`
+post-processing already works generically on the downloaded tile if a
+closed palette is what's actually needed.
+
 Do not confuse pixelkiln's `map` generator with PixelLab's own "Map
 Workshop": `map` returns one static prop, icon, or building in a single
 generation with no scene, canvas, or placement concept. Map Workshop (scene