pixelkiln 0.67.0 → 0.68.0

package/docs/GENERATORS.md

@@ -43,6 +43,37 @@ attempts in the [environment provider benchmark](./PROVIDER_BENCHMARK.md) were
 opaque. `map` has no `noBackground` control in PixelKiln. Check alpha before
 assuming the file can be placed directly over a map.
 
+### Drawing into a scene
+
+A `map` asset can declare a `scene`: an existing picture of the place the
+object belongs in (a floor, a room, a level). PixelLab draws the object into
+that scene and in its style, which is the one way to match a specific map's
+look without a style image. The price is still one generation.
+
+```jsonc
+"barrel": {
+  "prompt": "a small wooden barrel",
+  "width": 64, "height": 64,
+  "scene": { "image": "maps/tavern-floor.png", "placement": { "oval": 0.3 } }
+}
+```
+
+- `scene.image` is a manifest-relative PNG. It can be another asset's output;
+  until that file exists, `plan` shows this asset as blocked. Its bytes are
+  part of the spec's identity, so a redrawn scene makes the object stale.
+- `scene.placement` is where the object goes: `{ "oval": f }` or
+  `{ "rectangle": f }`, a region PixelLab generates covering `f` (0.05–0.95)
+  of the scene, or `{ "mask": "path.png" }`, a PNG the size of the scene,
+  white where the object goes and black for context. The default is
+  `{ "oval": 0.3 }`, PixelLab's own.
+- PixelLab only. Other providers refuse `scene` when the manifest is resolved.
+
+Unverified until a real call is billed: whether the scene has to match the
+object's `width`/`height` or can be a larger picture; where an oval or a
+rectangle sits, since the API takes no position (presumably centered); and
+whether the result is the object alone or the object composited into the
+scene. Check the first result before drawing a batch.
+
 ## `1dir`
 
 `1dir` is the single-facing sibling of PixelLab's rotatable/animated object

package/docs/MANIFEST.md

@@ -68,6 +68,7 @@ not merely a label edit.
 | `state` | object | `character` styles: a pose or outfit of another character asset. See [Characters](./CHARACTERS.md). |
 | `animation` | object | `character` styles: a loop of another character asset in one direction. `directions` (a list, instead of `direction`) declares the loop for several directions at once and fills the unnamed flips with mirrors; see [One loop, several directions](./CHARACTERS.md#one-loop-several-directions). |
 | `mirror` | string | Another asset of the same style flipped left to right, made locally at no cost. See [Mirrors](./CHARACTERS.md#mirrors). |
+| `scene` | object | `map` styles, PixelLab only: draw this object into a scene image, in its style. `{ "image": "scene.png", "placement": { "oval": 0.3 } }`; `placement` is `oval` or `rectangle` (a fraction, 0.05–0.95) or `mask` (a PNG the size of the scene). See [Drawing into a scene](./GENERATORS.md#drawing-into-a-scene). |
 | `batch` | object | `1dir` styles: rides along on another `1dir` asset's `item_descriptions` submission instead of generating on its own — `{ "of": "<leader asset id>", "index": <1-based slot> }`. See [`1dir`](./GENERATORS.md#1dir). |
 | `pieces` | array | `uiAsset` styles: exact shape regions (`rounded_rect`/`circle`/`polygon`) the panel is composited from, each with a unique `id`. See [`uiAsset`](./GENERATORS.md#uiasset). |
 | `elements` | string array | `uiAsset` styles: named, auto-positioned UI scaffolds (`button`, `health_bar`, `window`, ...). Combine with `pieces`; omit both for a plain full-canvas panel. See [`uiAsset`](./GENERATORS.md#uiasset). |

package/docs/PIXELLAB.md

@@ -175,5 +175,8 @@ scene composition (placing objects and characters into a map, in-scene
 inpainting, export) is a separate PixelLab product surface this adapter does
 not model at all — including PixelKiln's own `map` generator, which is
 unrelated to PixelLab's "Map Workshop" despite the shared name: `map` returns
-one static prop in one generation, with no scene or canvas concept. Use the
+one static prop in one generation. The one piece of style matching the public
+`/map-objects` endpoint takes, drawing an object into an existing scene image,
+is a `map` asset's `scene` field; see
+[Drawing into a scene](./GENERATORS.md#drawing-into-a-scene). Use the
 [manifest reference](./MANIFEST.md) for the fields PixelKiln supports today.

package/package.json

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

package/schema/manifest.schema.json

@@ -1456,6 +1456,67 @@
                 ],
                 "additionalProperties": false
               },
+              "scene": {
+                "type": "object",
+                "properties": {
+                  "image": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "placement": {
+                    "anyOf": [
+                      {
+                        "type": "object",
+                        "properties": {
+                          "oval": {
+                            "type": "number",
+                            "minimum": 0.05,
+                            "maximum": 0.95
+                          }
+                        },
+                        "required": [
+                          "oval"
+                        ],
+                        "additionalProperties": false
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "rectangle": {
+                            "type": "number",
+                            "minimum": 0.05,
+                            "maximum": 0.95
+                          }
+                        },
+                        "required": [
+                          "rectangle"
+                        ],
+                        "additionalProperties": false
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "mask": {
+                            "type": "string",
+                            "minLength": 1
+                          }
+                        },
+                        "required": [
+                          "mask"
+                        ],
+                        "additionalProperties": false
+                      }
+                    ],
+                    "default": {
+                      "oval": 0.3
+                    }
+                  }
+                },
+                "required": [
+                  "image"
+                ],
+                "additionalProperties": false
+              },
               "proportions": {
                 "anyOf": [
                   {

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

@@ -372,8 +372,11 @@ describing only the new terrain, and export the whole map (tilesets, full
 composite, and every object as separate files). Demonstrated at length in
 "Create Interior Maps," "PixelLab Map Workshop Tutorial," "How to Create
 Destructible Environments in Seconds," and "Create a Full Side Scroller
-Level." Zero pixelkiln analogue — and see pixellab.md for the naming
-collision with pixelkiln's own unrelated `map` generator.
+Level." Zero pixelkiln analogue for the scene editor itself — and see
+pixellab.md for the naming collision with pixelkiln's own unrelated `map`
+generator. The one part the public API exposes, `/map-objects` style matching
+(`background_image` + `inpainting`), is closed: a `map` asset's `scene` field
+(issue #216).
 
 One concrete, recurring gotcha worth carrying into any future implementation:
 default/generic object prompts in Map Workshop reliably come out oversized

package/skills/pixelkiln/references/pixellab.md

@@ -270,7 +270,13 @@ of 4, no `strength`), at the Pro Flash tier instead of the Pro endpoints' 20–4
 
 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
+generation. Its one scene concept is optional: a `map` asset's `scene` (`{
+"image": "floor.png", "placement": { "oval": 0.3 } }`, or `rectangle`, or a
+`mask` PNG the scene's size) draws the object into that picture, in its style,
+still for one generation. The scene can be another asset's output; the object
+is blocked until it exists and goes stale when it is redrawn. Whether the
+result is the object alone or composited, and where an oval sits, are
+unverified; look at the first result before a batch. Map Workshop (scene
 composition — laying out a tile floor, placing characters and movable
 objects, inpainting sections in place, exporting the result) is a distinct
 PixelLab product surface this adapter does not model at all.