@pixelvibing/cli 0.52.0 → 0.53.0

package/dist/pixel-vibing-cli.js

@@ -4967,7 +4967,7 @@ const GENERATED = {
   "ui-sketch": { references: 3, words: "a UI" }
 };
 const KIND_NAMES = { ui: "ui-sketch", [OLD_CONCEPT_ART]: CONCEPT_ART };
-const WORDS_ONLY = ["size", "transparent", "pixel-art", "no-pixel-art", "tag", "names", "purpose", "tiles", "sketch"];
+const WORDS_ONLY = ["size", "transparent", "pixel-art", "no-pixel-art", "tag", "mask", "names", "purpose", "tiles", "sketch"];
 const MORE_REFERENCES = 3;
 const ENRICHED = /* @__PURE__ */ new Set(["animate", "pose", "rotate", "terrain-animation"]);
 function listOf(given2, what) {
@@ -5075,17 +5075,17 @@ function sizeOf(given2, what) {
   if (match === null) throw new CliError(`${what} is <cols>x<rows>, such as 2x1, not ${given2}`);
   return { cols: Number(match[1]), rows: Number(match[2]) };
 }
-async function referenceOf(context, path) {
+async function referenceOf(context, path, what = "reference") {
   const file = resolve(context.io.cwd, path);
   let size;
   try {
     size = (await stat(file)).size;
   } catch {
-    throw new CliError(`the reference ${path} cannot be read`);
+    throw new CliError(`the ${what} ${path} cannot be read`);
   }
-  if (size > MAX_REFERENCE_BYTES) throw new CliError(`the reference ${path} is ${size} bytes, and one is at most ${MAX_REFERENCE_BYTES}`);
+  if (size > MAX_REFERENCE_BYTES) throw new CliError(`the ${what} ${path} is ${size} bytes, and one is at most ${MAX_REFERENCE_BYTES}`);
   const bytes = new Uint8Array(await readFile(file));
-  if (!isPng(bytes)) throw new CliError(`the reference ${path} is not a PNG`);
+  if (!isPng(bytes)) throw new CliError(`the ${what} ${path} is not a PNG`);
   return bytes;
 }
 async function requestOf(context, asked, args) {
@@ -5126,6 +5126,7 @@ async function shapedRequest(context, asked, args) {
   if (kind !== CONCEPT_ART) {
     for (const flag of ["pixel-art", "transparent"]) if (flagOf(args, flag)) throw new CliError(`--${flag} is a concept art's`);
     if (stringsOf(args, "tag").length > 0) throw new CliError("--tag is a concept art's");
+    if (stringOf(args, "mask") !== void 0) throw new CliError("--mask is a concept art's");
   }
   if (kind === "ui-sketch") {
     for (const flag of ["names", "purpose", "size", "tiles"])
@@ -5153,7 +5154,15 @@ async function shapedRequest(context, asked, args) {
   for (const path of paths) references.push(await referenceOf(context, path));
   if (kind === CONCEPT_ART) {
     const { fields, words: words2 } = conceptFields(args, asked, instruction);
-    return { kind, body: { instruction, ...fields }, ...references.length > 0 ? { images: { references } } : {}, words: words2 };
+    const maskPath = stringOf(args, "mask");
+    const mask = maskPath === void 0 ? void 0 : await referenceOf(context, maskPath, "mask");
+    const images = { ...references.length > 0 ? { references } : {}, ...mask === void 0 ? {} : { mask } };
+    return {
+      kind,
+      body: { instruction, ...fields },
+      ...Object.keys(images).length > 0 ? { images } : {},
+      words: mask === void 0 ? words2 : words2.replace(/^(a concept art [^:]*?)(:)/, "$1, within its mask$2")
+    };
   }
   const body = { instruction };
   let words = `${known.words}: ${instruction}`;
@@ -5195,7 +5204,7 @@ async function followed(context, platform, jobId) {
 const generate = {
   name: "generate",
   summary: "Generate an asset, a change of a picture, terrain or a sound on the platform, then pull it, keep it or write it",
-  usage: "<object|creature|concept-art|icons|ui|variant|edit|animate|pose|rotate|state|terrain|terrain-animation|sfx|speech|music> [--instruction <text>] [--source <image id>] [--state <state>] [--into <sprite> --name <name>] [--upper <ground> --lower <ground>] [--terrain <asset>] [--text <text> --voice <voice>] [--out <file>] [--size <c>x<r>|<w>x<h>|<px>] [--transparent] [--pixel-art] [--tiles <c>x<r>] [--tag <tag>]… [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--no-enrich] [--yes]",
+  usage: "<object|creature|concept-art|icons|ui|variant|edit|animate|pose|rotate|state|terrain|terrain-animation|sfx|speech|music> [--instruction <text>] [--source <image id>] [--state <state>] [--into <sprite> --name <name>] [--upper <ground> --lower <ground>] [--terrain <asset>] [--text <text> --voice <voice>] [--out <file>] [--size <c>x<r>|<w>x<h>|<px>] [--transparent] [--pixel-art] [--tiles <c>x<r>] [--tag <tag>]… [--mask <png>] [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--no-enrich] [--yes]",
   options: {
     instruction: {
       type: "string",
@@ -5215,6 +5224,11 @@ const generate = {
       value: "<tag>",
       description: "what a concept art is for, such as anchor, ui, character, environment, prop or level-design; at most 8"
     },
+    mask: {
+      type: "string",
+      value: "<png>",
+      description: "where a concept art is drawn: an opaque black-and-white PNG in its shape, up to 1536 px a side, white drawn and black left empty"
+    },
     names: { type: "string", value: "<list>", description: `an icon set's icons, comma-separated, at most ${MAX_ICONS}` },
     purpose: { type: "string", value: "skill|item", description: "whether an icon set is skills on badges or items alone; item unless given" },
     tiles: { type: "string", value: "<cols>x<rows>", description: "how many tiles a pixel-art concept art is across, 6x4 unless given" },
@@ -5725,7 +5739,7 @@ const move = {
     );
   }
 };
-const version = "0.52.0";
+const version = "0.53.0";
 const manifest = {
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelvibing/cli",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "PixelVibing: pixel art game assets from the command line, and the Skills that teach coding assistants to make them.",
   "license": "MIT",
   "homepage": "https://pixelvibing.com",

package/skills/pixelvibing-concept-art/SKILL.md

@@ -16,7 +16,7 @@ reference to what follows.
 `pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
 
 ```bash
-pixel-vibing-cli generate concept-art --instruction "<the picture>" [--size <w>x<h>] [--transparent] [--tag <tag>]... [--reference <png>]... [--no-enrich] --yes --json
+pixel-vibing-cli generate concept-art --instruction "<the picture>" [--size <w>x<h>] [--transparent] [--mask <png>] [--tag <tag>]... [--reference <png>]... [--no-enrich] --yes --json
 pixel-vibing-cli generate concept-art --instruction "<the area>" --pixel-art --tiles <cols>x<rows> [--no-enrich] --yes --json
 ```
 
@@ -25,7 +25,7 @@ pixel-vibing-cli generate concept-art --instruction "<the area>" --pixel-art --t
 ```json
 { "project": "<id>", "kind": "concept-art", "instruction": "<the picture>",
   "size": { "width": 1536, "height": 1024 }, "background": "transparent", "tags": ["anchor"],
-  "reference_images": ["<image id>"], "enrich": false, "max_percent": 40 }
+  "reference_images": ["<image id>"], "mask_image": "<image id>", "enrich": false, "max_percent": 40 }
 { "project": "<id>", "kind": "concept-art", "instruction": "<the area>", "pixel_art": true,
   "tiles": { "cols": 6, "rows": 4 }, "max_percent": 40 }
 ```
@@ -45,6 +45,15 @@ which every other generation takes as `reference_images`.
   `level-design`, `ui`, `character`, `environment`, `prop`, or one of the project's own
   (`list_tags`). `pixel-vibing-cli tag` (MCP `tag_asset`) changes them later.
 - **References.** Up to 8 to draw from, such as the anchor itself.
+- **A mask.** Keeps the drawing to a shape you choose: an island's coastline, a
+  character's silhouette, a frame for a menu, the open middle of a scene. It is an opaque
+  PNG of black and white only, white where the art is drawn and black where the drawing is
+  left empty, in the drawing's shape: the `--size` (`1536x1024` unless given), or for pixel
+  art the `--tiles` in proportion, such as 3:2 for `6x4`. Any size in that shape is scaled
+  to fit, up to 1536 px a side, so a small one drawn by hand or by a script is enough. A soft edge is fine; grey
+  shading, colour or transparency is refused with the reason before anything is spent.
+  Pass it as `--mask <png>` (MCP: keep it with `upload_image`, then give its id as
+  `mask_image`). With `--transparent`, the black part comes back transparent as well.
 - **A level design.** `--pixel-art --tiles <c>x<r>` (MCP `pixel_art`, `tiles`) draws an area
   of the map as pixel art some tiles across, `6x4` unless given, tagged `level-design`; the
   editor takes it apart into objects and terrain.