@pixelvibing/cli 0.53.0 → 0.55.0

package/dist/pixel-vibing-cli.js

@@ -3428,8 +3428,9 @@ function setPieces(asset) {
 function namesOf(name, count) {
   return count === 1 ? [name] : Array.from({ length: count }, (_, index) => `${name}/${index}`);
 }
-function nameFor(asset, record, given2) {
-  const name = given2 ?? record.assets[asset.id]?.name ?? asset.name ?? SET_NAMES[asset.kind] ?? `${asset.kind}-${asset.id.slice(0, 8)}`;
+function nameFor(asset, record, given2, key, hd) {
+  const platform = asset.name ?? SET_NAMES[asset.kind] ?? `${asset.kind}-${asset.id.slice(0, 8)}`;
+  const name = given2 ?? record.assets[key]?.name ?? (hd ? `${platform}-hd` : platform);
   const problem = nameProblem(name);
   if (problem !== null) throw new CliError(`${name} is not a name a picture can be landed under (${problem}): give one with --as`);
   return name;
@@ -3442,13 +3443,22 @@ async function pullAsset(platform, local, ref, given2, options = {}) {
   if (asset.kind === "terrain") {
     throw new CliError(`${asset.id} is a terrain set: land it from the editor's Library, which cuts a set into the cells its brush paints. Nothing was landed`);
   }
-  const record = await readRecord(local);
-  const name = nameFor(asset, record, given2);
   const pieces = setPieces(asset);
+  const hd = options.hd === true;
+  const drawnSmooth = asset.data.pixelArt === false;
+  if (hd && pieces === null) throw new CliError(`${asset.id} is a ${asset.kind}: only a UI's pieces and icons have an HD version. Nothing was landed`);
+  if (hd && !drawnSmooth && pieces?.some((piece) => piece.hd === void 0 || asset.attachments?.[piece.hd] === void 0)) {
+    throw new CliError(`${asset.id} was made before its pieces were kept as drawn, so it has no HD version. Nothing was landed`);
+  }
+  const lifted = hd && !drawnSmooth;
+  const key = lifted ? `${asset.id}/hd` : asset.id;
+  const record = await readRecord(local);
+  const name = nameFor(asset, record, given2, key, lifted);
   const reference = REFERENCE_KINDS.has(asset.kind);
   const names = pieces === null ? namesOf(name, asset.images.length) : pieceNames(name, pieces);
   const files = names.map((each) => `${reference ? "ref" : "out"}/${each}.png`);
-  const pulled = { id: asset.id, kind: asset.kind, name, hash: asset.hash, files, data: asset.data };
+  const version2 = pieces === null ? {} : { version: drawnSmooth || lifted ? "hd" : "pixel-art" };
+  const pulled = { id: asset.id, kind: asset.kind, name, hash: asset.hash, files, ...version2, data: asset.data };
   const base = `/projects/${encodeURIComponent(project)}`;
   const json2 = async (path, init2) => (await platform.call(path, init2)).json();
   const art = await json2(`${base}/art`);
@@ -3456,7 +3466,9 @@ async function pullAsset(platform, local, ref, given2, options = {}) {
   const held = (each) => reference ? references.get(each) : art.pictures[each];
   const landing = [];
   for (const [index, each] of names.entries()) {
-    const image = asset.images[index].id;
+    const own = asset.images[index];
+    const drawn = lifted ? asset.attachments?.[pieces?.[index]?.hd] : void 0;
+    const image = drawn?.id ?? own.id;
     const holds = held(each);
     if (holds === image) continue;
     if (holds !== void 0) {
@@ -3464,7 +3476,8 @@ async function pullAsset(platform, local, ref, given2, options = {}) {
         `the project's art already holds ${reference ? "a reference" : "a picture"} named ${each}, of something else: nothing was landed. Give this one another name with --as`
       );
     }
-    landing.push({ name: each, image, piece: pieces?.[index] ?? null });
+    const piece = pieces?.[index] ?? null;
+    landing.push({ name: each, image, piece: piece === null || drawn === void 0 ? piece : asDrawn(piece, drawn.width / own.width) });
   }
   if (landing.length > 0) {
     if (reference) {
@@ -3478,13 +3491,24 @@ async function pullAsset(platform, local, ref, given2, options = {}) {
       await json2(`${base}/art/land`, { method: "POST", body: { revision: art.revision, assets } });
     }
   }
-  await writeRecord(local, { ...record, assets: { ...record.assets, [asset.id]: { kind: asset.kind, name, hash: asset.hash, files } } });
+  await writeRecord(local, { ...record, assets: { ...record.assets, [key]: { kind: asset.kind, name, hash: asset.hash, files } } });
   await bringFolder(platform, local, { map: false, aside: options.aside === true });
   return { ...pulled, current: landing.length === 0 };
 }
+function asDrawn(piece, scale) {
+  if (piece.nineGrid === void 0 || !Number.isFinite(scale) || scale <= 1) return piece;
+  const grown = (inset) => Math.round(inset * scale);
+  const { top, right, bottom, left } = piece.nineGrid;
+  return { ...piece, nineGrid: { top: grown(top), right: grown(right), bottom: grown(bottom), left: grown(left) } };
+}
 function pulledWords(pulled) {
   const where = pulled.files.length === 1 ? `pixelvibing/${pulled.files[0]}` : `${pulled.files.length} pictures under pixelvibing/`;
-  return pulled.current ? `${pulled.name} is current: the project's art holds it, and ${where} is what the platform has.` : `Pulled ${pulled.name}, ${pulled.kind}, into the project's art, and wrote ${where}.`;
+  const said = pulled.current ? `${pulled.name} is current: the project's art holds it, and ${where} is what the platform has.` : `Pulled ${pulled.name}, ${pulled.kind}, into the project's art, and wrote ${where}.`;
+  if (pulled.version === "hd" && pulled.data.pixelArt === false)
+    return `${said} It was drawn without pixel art, so its pieces are HD and there is no pixel-art version.`;
+  if (pulled.version === "hd") return `${said} These are the pieces as drawn (HD).`;
+  if (pulled.version === "pixel-art") return `${said} These are the pixel-art pieces; --hd lands them as drawn.`;
+  return said;
 }
 const date = (at) => at.slice(0, 10);
 function listed(assets) {
@@ -3518,9 +3542,10 @@ More: pixel-vibing-cli list${kind === void 0 ? "" : ` ${kind}`}${tag2 === null ?
 const pull = {
   name: "pull",
   summary: "Land one asset, by its id or its name, in the project's art, and write it into the local project",
-  usage: "<id|name> [--as <name>] [--aside]",
+  usage: "<id|name> [--as <name>] [--aside] [--hd]",
   options: {
     as: { type: "string", value: "<name>", description: "land it under this name instead of the platform's" },
+    hd: { type: "boolean", description: "land a UI's pieces or icons as drawn (HD), beside the pixel-art ones, instead of read back on the pixel grid" },
     aside: { type: "boolean", description: "keep a folder's own map and art under pixelvibing/before-platform/, and write it from the platform" }
   },
   positionals: [1, 1],
@@ -3528,7 +3553,10 @@ const pull = {
     const local = await projectHere(context.io.cwd);
     linkedOf(local);
     const platform = await signedIn(context);
-    const pulled = await pullAsset(platform, local, args.positionals[0], stringOf(args, "as"), { aside: flagOf(args, "aside") });
+    const pulled = await pullAsset(platform, local, args.positionals[0], stringOf(args, "as"), {
+      aside: flagOf(args, "aside"),
+      hd: flagOf(args, "hd")
+    });
     answer(context, pulled, pulledWords(pulled));
   }
 };
@@ -4508,33 +4536,58 @@ function shapeProblem(shape, index, canvas) {
   return null;
 }
 function sketchProblem(sketch) {
-  if (typeof sketch.instruction !== "string" || sketch.instruction.trim() === "") return "the sketch has no description";
-  if (sketch.instruction.length > MAX_SKETCH_INSTRUCTION)
-    return `the description is ${sketch.instruction.length} characters; it is at most ${MAX_SKETCH_INSTRUCTION}`;
+  const problems = sketchProblems(sketch);
+  return problems.length === 0 ? null : problems.join("; ");
+}
+function sketchProblems(sketch) {
+  const problems = [];
+  if (typeof sketch.instruction !== "string" || sketch.instruction.trim() === "") problems.push("the sketch has no description");
+  else if (sketch.instruction.length > MAX_SKETCH_INSTRUCTION)
+    problems.push(`the description is ${sketch.instruction.length} characters; it is at most ${MAX_SKETCH_INSTRUCTION}`);
   const { canvas, shapes } = sketch;
   if (!SKETCH_CANVASES.some((size) => size.width === canvas.width && size.height === canvas.height)) {
-    return `the canvas is ${canvas.width} × ${canvas.height}; a sketch is ${SKETCH_CANVASES.map((size) => `${size.width} × ${size.height}`).join(", ")}`;
+    problems.push(
+      `the canvas is ${canvas.width} × ${canvas.height}; a sketch is ${SKETCH_CANVASES.map((size) => `${size.width} × ${size.height}`).join(", ")}`
+    );
+    return problems;
   }
-  if (shapes.length === 0) return "the sketch has no shape";
-  if (shapes.length > MAX_SKETCH_SHAPES) return `the sketch has ${shapes.length} shapes; it holds at most ${MAX_SKETCH_SHAPES}`;
-  const labels = /* @__PURE__ */ new Map();
+  if (shapes.length === 0) problems.push("the sketch has no shape");
+  if (shapes.length > MAX_SKETCH_SHAPES) problems.push(`the sketch has ${shapes.length} shapes; it holds at most ${MAX_SKETCH_SHAPES}`);
+  const labels = /* @__PURE__ */ new Set();
+  const twice = /* @__PURE__ */ new Set();
+  const sound = [];
   for (const [index, shape] of shapes.entries()) {
     const problem = shapeProblem(shape, index, canvas);
-    if (problem !== null) return problem;
+    if (problem !== null) {
+      problems.push(problem);
+      continue;
+    }
+    sound.push(index);
     const key = shape.label.trim().toLowerCase();
-    if (labels.has(key)) return `"${shape.label.trim()}" is the label of two shapes`;
-    labels.set(key, shape.label.trim());
+    if (labels.has(key) && !twice.has(key)) {
+      twice.add(key);
+      problems.push(`"${shape.label.trim()}" is the label of two shapes`);
+    }
+    labels.add(key);
   }
-  for (const [index, shape] of shapes.entries()) {
+  const overlapping = /* @__PURE__ */ new Set();
+  for (const index of sound) {
+    const shape = shapes[index];
     for (let y = shape.y; y < shape.y + shape.height; y += 1) {
       for (let x = shape.x; x < shape.x + shape.width; x += 1) {
         if (!inShape(shape, x + 0.5, y + 0.5)) continue;
-        const other = shapes.findIndex((them, at) => at < index && inShape(them, x + 0.5, y + 0.5));
-        if (other >= 0) return `"${shapes[other]?.label.trim()}" and "${shape.label.trim()}" overlap`;
+        for (const other of sound) {
+          if (other >= index || !inShape(shapes[other], x + 0.5, y + 0.5)) continue;
+          const pair = `"${shapes[other]?.label.trim()}" and "${shape.label.trim()}" overlap`;
+          if (!overlapping.has(pair)) {
+            overlapping.add(pair);
+            problems.push(pair);
+          }
+        }
       }
     }
   }
-  return null;
+  return problems;
 }
 function sentShape(shape) {
   const caption = shape.caption?.trim() ?? "";
@@ -4677,6 +4730,748 @@ function terrainSetPatch(pngs, masks, codec2) {
 const TERRAIN_CELLS_PER_TILE = [32, 64];
 const REFERENCE_ROLES = ["style", "source", "variant"];
 const DEFAULT_TERRAIN_CELLS = 32;
+const VFX_RAMPS = ["arcane", "blood", "electric", "fire", "frost", "holy", "nature", "poison", "shadow", "smoke", "water"];
+const VFX_PARTS_RANGE = { min: 1, max: 6 };
+const VFX_COLOURS_RANGE = { min: 2, max: 12 };
+const VFX_SLIDERS = {
+  size: { min: 0.25, max: 4 },
+  amount: { min: 0.25, max: 3 },
+  speed: { min: 0.25, max: 3 },
+  start: { min: 0, max: 1 },
+  end: { min: 0, max: 1 }
+};
+const VFX_PRESETS = [
+  {
+    name: "aura",
+    description: "A flickering aura of power around a standing character: flame tongues behind, sparks rising in front. Seamless loop. Best around a character.",
+    loops: true
+  },
+  { name: "energy_orb", description: "A crackling ball of energy (projectile head or charge-up) with orbiting sparks. Seamless loop.", loops: true },
+  { name: "explosion", description: "Fireball explosion: flash, a billowing fire mass that burns out, a shockwave ring, debris. One-shot.", loops: false },
+  {
+    name: "firelight",
+    description: "Warm, flickering firelight from below, as from a campfire at the subject's feet; the far side sinks into the dark. It lights your sprite (shown on a sample asteroid when there is none). Loop.",
+    loops: true
+  },
+  { name: "flame", description: "A burning flame (campfire, torch, brazier). Seamless loop.", loops: true },
+  {
+    name: "ground_sigil",
+    description: "Summoning circle on the ground, seen from low above, turning, with light rising out of it. Best with a character standing in its middle.",
+    loops: true
+  },
+  {
+    name: "heal_pillar",
+    description: "A soft column of healing light with a ground ring and rising sparkles. Seamless loop; good around a character.",
+    loops: true
+  },
+  { name: "impact_burst", description: "A hit spark: white flash, rays and a ring punching outward, sparks. One-shot, small.", loops: false },
+  {
+    name: "light_sweep",
+    description: "A light circling the subject: sunlight moving across a rock, a planet turning, an asteroid tumbling past a star. It lights your sprite (shown on a sample asteroid when there is none). Seamless loop.",
+    loops: true
+  },
+  { name: "lightning_strike", description: "A bolt strikes down from above, flashes, hits the ground with a shockwave and sparks. One-shot.", loops: false },
+  {
+    name: "magic_circle",
+    description: "Front-facing arcane circle: rings, a hexagram and a rune band that turn slowly, twinkling motes. Seamless loop.",
+    loops: true
+  },
+  { name: "portal", description: "An upright swirling portal: churning core, glowing rim, orbiting motes. Seamless loop.", loops: true },
+  {
+    name: "rim_glow",
+    description: "A pulsing rim of light around the subject's outline, as if something bright stands right behind it (a portal, a halo, an explosion). It lights your sprite (shown on a sample asteroid when there is none). Seamless loop.",
+    loops: true
+  },
+  {
+    name: "shield_bubble",
+    description: "A protective bubble: shimmering rim, glints running round it. Seamless loop. Best around a character.",
+    loops: true
+  },
+  {
+    name: "shockwave",
+    description: "A stomp or landing: a ring of force racing out along the ground, kicking up dust. One-shot, seen from low above.",
+    loops: false
+  },
+  { name: "slash_arc", description: "A sword slash: a crescent that sweeps open, then fades, with a few glints. One-shot.", loops: false },
+  { name: "smoke_puff", description: "A puff of smoke that billows up and thins away. One-shot.", loops: false }
+];
+const VFX_PARTS = [
+  {
+    name: "alert_pop",
+    description: "A red ! pops up above a character's head with a bounce and burst lines, holds, then vanishes: spotted, surprised, warning.",
+    loops: false,
+    tags: ["alert", "exclamation", "ui", "surprise", "warning", "icon"]
+  },
+  {
+    name: "aura_flames",
+    description: "Flickering tongues of power rising behind a standing character, a ring at the feet, sparks in front.",
+    loops: true,
+    tags: ["aura", "power", "buff", "flames", "charge", "rage"]
+  },
+  {
+    name: "blaster_bolt",
+    description: "A hot capsule of energy with a white core and speed lines behind, flying right (+x): laser, plasma or blaster shots.",
+    loops: true,
+    tags: ["projectile", "laser", "blaster", "energy", "shot", "bolt"]
+  },
+  {
+    name: "blood_splat",
+    description: "A red splat on the hit point with droplets spraying out and falling. Stylised gore; recolour for green ichor or slime.",
+    loops: false,
+    tags: ["blood", "hit", "gore", "splatter", "impact", "droplets"]
+  },
+  {
+    name: "bolt_strike",
+    description: "A bolt strikes down from above onto the anchor, flashes, a shockwave and sparks where it hits.",
+    loops: false,
+    tags: ["lightning", "electric", "bolt", "storm", "strike", "thunder"]
+  },
+  {
+    name: "breath_cone",
+    description: "A billowing cone of flame and sparks pouring right (+x) from the anchor: fire breath, flamethrower; frost or poison gas in other colours.",
+    loops: true,
+    tags: ["breath", "cone", "flamethrower", "spray", "fire", "gas"]
+  },
+  {
+    name: "bubble_shield",
+    description: "A see-through dithered bubble around a character: bright rim, a shine highlight, glints running round: shield, barrier, protect.",
+    loops: true,
+    tags: ["shield", "bubble", "barrier", "protect", "buff"]
+  },
+  {
+    name: "bubbles_rise",
+    description: "Round bubbles of a few sizes rising and wobbling up from the ground: underwater, a bubbling pool, potions, drowning.",
+    loops: true,
+    tags: ["bubbles", "water", "underwater", "rising", "ambient", "potion"]
+  },
+  {
+    name: "buff_arrows",
+    description: "Up-arrows rising from the feet behind a character and fading out: a stat buff, power-up, attack or speed boost.",
+    loops: true,
+    tags: ["buff", "arrows", "status", "powerup", "rising"]
+  },
+  {
+    name: "burn_status",
+    description: "Small flames licking up around and over a character, embers and a hot rim on the sprite: on fire, burn damage over time.",
+    loops: true,
+    tags: ["burn", "fire", "status", "flames", "dot"]
+  },
+  {
+    name: "burning_edge",
+    description: "Sparks flickering up off the sprite's whole outline in a loop: on fire, powered up, cursed, overheating.",
+    loops: true,
+    tags: ["outline", "burn", "aura", "sparks", "loop"]
+  },
+  {
+    name: "campfire",
+    description: "A drawn campfire: five tongues from one hot bed, fanning out and flickering, a few sparks, lighting the scene.",
+    loops: true,
+    tags: ["fire", "campfire", "bonfire", "camp", "loop"]
+  },
+  {
+    name: "candle_flame",
+    description: "A small calm drawn teardrop flame that sways a little, lighting the sprite: candles, lanterns, wicks, a match.",
+    loops: true,
+    tags: ["fire", "candle", "flame", "light", "loop"]
+  },
+  {
+    name: "cartoon_boom",
+    description: "A drawn cartoon explosion: a hot flash, lobed fire clouds thrown out and cooling, then smoke. Bombs, barrels, crits.",
+    loops: false,
+    tags: ["explosion", "fire", "cartoon", "boom", "impact"]
+  },
+  {
+    name: "charge_up",
+    description: "Motes of energy swirling in from all round and gathering at one point, a glow swelling there. Charging a spell.",
+    loops: false,
+    tags: ["charge", "gather", "energy", "magic", "converge"]
+  },
+  {
+    name: "charm_hearts",
+    description: "Three small pink hearts circling the head evenly, passing in front and behind, with twinkles: charmed, infatuated, love status.",
+    loops: true,
+    tags: ["charm", "hearts", "love", "status", "orbit"]
+  },
+  {
+    name: "claw_marks",
+    description: "Three parallel claw scratches ripping diagonally across the target, then crumbling away. Beast attacks, rakes, scratches.",
+    loops: false,
+    tags: ["claw", "scratch", "slash", "beast", "hit", "melee"]
+  },
+  {
+    name: "claw_swipe",
+    description: "Three drawn claw marks raked across in a quick swipe, one a beat after the other, crumbling away. Beasts, monsters.",
+    loops: false,
+    tags: ["claw", "swipe", "beast", "scratch", "hit"]
+  },
+  {
+    name: "cloud_puff",
+    description: "A looping drawn cloud clump wobbling in place, lit from above. Rain or storm clouds over a head, sky decor, dreams.",
+    loops: true,
+    tags: ["cloud", "sky", "weather", "loop", "cartoon"]
+  },
+  {
+    name: "coin_burst",
+    description: "Gold coins pop out of the anchor with a flash ring and glints, arc up and fall away: loot drops, pickups, rewards.",
+    loops: false,
+    tags: ["coins", "loot", "pickup", "gold", "reward", "burst"]
+  },
+  {
+    name: "collect_pop",
+    description: "A quick gold glint and ring popping on the anchor, sparkles drifting up and out: an item, coin or power-up being picked up.",
+    loops: false,
+    tags: ["pickup", "collect", "sparkle", "glint", "item", "reward"]
+  },
+  {
+    name: "comet_trail",
+    description: "A bright head streaking across with a long tapered ribbon tail: comets, magic missiles, wisps; a throw's trail.",
+    loops: false,
+    tags: ["comet", "ribbon", "trail", "missile", "projectile"]
+  },
+  {
+    name: "confetti_pop",
+    description: "A pop of multicoloured paper confetti thrown up from the anchor, flipping as it falls: wins, celebrations, achievements.",
+    loops: false,
+    tags: ["confetti", "celebration", "win", "party", "reward", "burst"]
+  },
+  {
+    name: "crater_dust",
+    description: "A ring of dust clouds billowing out and up from a ground impact, then breaking apart. Heavy landings, slams, boulders.",
+    loops: false,
+    tags: ["dust", "impact", "ground", "slam", "landing", "cloud"]
+  },
+  {
+    name: "curse_skulls",
+    description: "Little pale skulls drifting up around a character's head and fading, with dark motes: cursed, doomed, death mark, hex.",
+    loops: true,
+    tags: ["curse", "skulls", "status", "death", "hex", "debuff"]
+  },
+  {
+    name: "debris_burst",
+    description: "Chunks of rock or wood thrown out of a hit, arcing down under gravity.",
+    loops: false,
+    tags: ["debris", "rocks", "chunks", "impact", "break", "rubble"]
+  },
+  {
+    name: "debuff_arrows",
+    description: "Down-arrows sinking from above the head behind a character and fading: a stat debuff, weaken, slow or armour break.",
+    loops: true,
+    tags: ["debuff", "arrows", "status", "weaken", "curse"]
+  },
+  {
+    name: "dust_kick",
+    description: "Two small dust puffs pushing out sideways along the ground and breaking up: footsteps, landings, skids, dashes.",
+    loops: false,
+    tags: ["dust", "landing", "footstep", "ground", "puff", "jump"]
+  },
+  {
+    name: "dust_puff",
+    description: "A small drawn dust puff kicked up from the ground: footsteps, jumps, an item dropping, a skid start.",
+    loops: false,
+    tags: ["dust", "puff", "ground", "footstep", "cartoon"]
+  },
+  {
+    name: "dust_trail",
+    description: "Dust puffs rolling off the feet and trailing behind (to the left) as they break up. Loop for running, dashing, skidding.",
+    loops: true,
+    tags: ["dust", "trail", "run", "dash", "ground", "loop"]
+  },
+  {
+    name: "ember_rise",
+    description: "Glowing embers drifting up from the ground and winking out: fire, heat, burning.",
+    loops: true,
+    tags: ["embers", "fire", "sparks", "rising", "heat", "ambient"]
+  },
+  {
+    name: "fire_blast",
+    description: "A drawn explosion: a flash, round fire billows burning out into smoke puffs, a pressure ring. Noise version: fireball.",
+    loops: false,
+    tags: ["explosion", "fire", "blast", "boom", "smoke"]
+  },
+  {
+    name: "fire_ring",
+    description: "A ring of flickering flames standing on the ground around the anchor, embers rising: trapped in fire, burning ground, fire wall.",
+    loops: true,
+    tags: ["fire", "ring", "ground", "flames", "trap", "area"]
+  },
+  {
+    name: "fire_wall",
+    description: "A wide wall of drawn flame: seven tongues rising and flickering from one burning line. Fire walls, burning ground.",
+    loops: true,
+    tags: ["fire", "wall", "barrier", "burning", "loop"]
+  },
+  {
+    name: "fireball",
+    description: "An explosion's fire mass: a flash, billowing fire that burns out into smoke, a pressure ring.",
+    loops: false,
+    tags: ["explosion", "fire", "blast", "boom", "smoke"]
+  },
+  {
+    name: "fireflies",
+    description: "Glowing fireflies drifting slowly and blinking on and off around the anchor: night, forests, swamps, calm magic.",
+    loops: true,
+    tags: ["fireflies", "night", "nature", "ambient", "glow", "forest"]
+  },
+  {
+    name: "fireworks",
+    description: "A rocket streaking up and bursting into a falling shower of sparkles. Celebrations, victories, level-ups.",
+    loops: false,
+    tags: ["fireworks", "celebrate", "victory", "sparkle", "burst"]
+  },
+  {
+    name: "flame_aura",
+    description: "Drawn tongues of power rising behind a standing character, a ring at the feet, sparks. Noise version: aura_flames.",
+    loops: true,
+    tags: ["aura", "power", "buff", "flames", "charge", "rage"]
+  },
+  {
+    name: "flame_jet",
+    description: "A roaring jet of fire blasting sideways (to the right) from the anchor, widening into billows, sparks flying: flamethrower, fire breath.",
+    loops: true,
+    tags: ["fire", "jet", "breath", "flamethrower", "stream", "attack"]
+  },
+  {
+    name: "flame_ring",
+    description: "A ring of drawn flame tongues on the ground around the anchor, embers rising: trapped in fire. Noise version: fire_ring.",
+    loops: true,
+    tags: ["fire", "ring", "ground", "flames", "trap", "area"]
+  },
+  {
+    name: "flame_tongue",
+    description: "One big drawn cartoon flame, wide at the root, its tip whipping and curling: fire elementals, a burning spot, a cartoon blaze.",
+    loops: true,
+    tags: ["fire", "cartoon", "flame", "elemental", "loop"]
+  },
+  {
+    name: "flamethrower",
+    description: "A drawn jet of fire blasting right from the anchor, sparks flying: flamethrower, fire breath. Noise version: flame_jet.",
+    loops: true,
+    tags: ["fire", "jet", "breath", "flamethrower", "stream", "attack"]
+  },
+  {
+    name: "flash_burst",
+    description: "A hit flash: a white-hot core, rays and a ring punching outward. The heart of a hit spark.",
+    loops: false,
+    tags: ["hit", "impact", "flash", "spark", "punch", "rays"]
+  },
+  {
+    name: "freeze_status",
+    description: "Icy crust and cold tint on the sprite, ice crystals around the feet and glinting frost specks: frozen, chilled, slowed.",
+    loops: true,
+    tags: ["freeze", "ice", "status", "frost", "cold"]
+  },
+  {
+    name: "frost_mist",
+    description: "Low cold mist drifting sideways in dithered bands around the feet, a few frost glints: winter, swamps, graveyards, spooky.",
+    loops: true,
+    tags: ["mist", "fog", "frost", "cold", "ground", "ambient"]
+  },
+  {
+    name: "grass_cut",
+    description: "Grass clippings bursting up from a cut tuft and falling back around it. Cutting bushes and grass, trampling, foliage hits.",
+    loops: false,
+    tags: ["grass", "leaves", "cut", "bush", "environment", "nature"]
+  },
+  {
+    name: "ground_cracks",
+    description: "Glowing cracks race out along the ground from the impact point, cool down and fade. Ground slams, earth magic, lava.",
+    loops: false,
+    tags: ["cracks", "ground", "slam", "impact", "earth", "lava"]
+  },
+  {
+    name: "heal_column",
+    description: "A soft column of light standing on the ground, a ring at its base and sparkles rising.",
+    loops: true,
+    tags: ["heal", "holy", "buff", "light", "pillar", "column", "restore"]
+  },
+  {
+    name: "heal_plus",
+    description: "Green plus signs and motes float up off a body that flashes a glowing outline: healing received, regen ticks, potions.",
+    loops: false,
+    tags: ["heal", "plus", "regen", "potion", "restore", "ui"]
+  },
+  {
+    name: "hit_star",
+    description: "A sharp star flashing on the hit point with specks flying off. The classic hit spark for punches and blows.",
+    loops: false,
+    tags: ["hit", "impact", "spark", "star", "punch", "flash"]
+  },
+  {
+    name: "holy_aura",
+    description: "A golden radiance with light spikes behind a character, a glowing rim and streaks of light rising: blessed, divine, holy buff.",
+    loops: true,
+    tags: ["holy", "aura", "light", "buff", "divine", "blessing"]
+  },
+  {
+    name: "hurt_flash",
+    description: "The sprite blinks white twice, its outline lit hot: the classic took-damage flash. Recolour red for damage, gold for buffs.",
+    loops: false,
+    tags: ["hit", "hurt", "damage", "flash", "blink", "sprite"]
+  },
+  {
+    name: "ice_shatter",
+    description: "A flash and a ring of cold, then ice shards bursting out and tumbling down. Breaking a freeze, an ice spell's hit.",
+    loops: false,
+    tags: ["ice", "shatter", "frost", "break", "hit"]
+  },
+  {
+    name: "ice_spikes",
+    description: "A cluster of faceted ice spikes erupting from the ground under the anchor, holding, then sinking back: frost attacks, traps.",
+    loops: false,
+    tags: ["ice", "frost", "spikes", "ground", "attack", "freeze"]
+  },
+  {
+    name: "item_glint",
+    description: "A sharp four-point glint flashes now and then on an item's upper right, a smaller one lower left: shiny pickups, gems, loot.",
+    loops: true,
+    tags: ["glint", "shine", "pickup", "gem", "loot", "sparkle"]
+  },
+  {
+    name: "landing_dust",
+    description: "Drawn dust clouds rolling out flat to both sides of a landing and thinning away. Heavy landings, stomps, slides.",
+    loops: false,
+    tags: ["dust", "landing", "ground", "stomp", "cartoon"]
+  },
+  {
+    name: "lava_pool",
+    description: "A slowly churning pool of glowing lava on the ground with bubbles popping and embers: lava, molten ground, fire traps, hell.",
+    loops: true,
+    tags: ["lava", "fire", "pool", "ground", "molten", "hazard"]
+  },
+  {
+    name: "leaf_fall",
+    description: "Autumn leaves drifting down and swaying around the anchor: forests, autumn, wind, nature magic, a shaken tree.",
+    loops: true,
+    tags: ["leaves", "nature", "autumn", "weather", "ambient", "falling"]
+  },
+  {
+    name: "level_up",
+    description: "A pillar of light bursts up from the feet, halos rise up the body, up-arrows and sparkles float away: level up, rank up, power gain.",
+    loops: false,
+    tags: ["levelup", "pillar", "buff", "reward", "holy", "arrows"]
+  },
+  {
+    name: "lightning_arcs",
+    description: "Small jagged arcs of electricity crackling on and off around a body, with spark glints: shocked, charged, electrified.",
+    loops: true,
+    tags: ["lightning", "electric", "shock", "status", "crackle", "charge"]
+  },
+  {
+    name: "magic_orb",
+    description: "A glowing orb on the anchor with a tapered tail and motes streaming left: a magic missile flying right (+x).",
+    loops: true,
+    tags: ["projectile", "orb", "magic", "missile", "spell", "trail"]
+  },
+  {
+    name: "muzzle_flash",
+    description: "A bright three-pronged flash bursting right (+x) from the anchor, then sparks and a smoke wisp: gunshots, cannons, wands.",
+    loops: false,
+    tags: ["muzzle", "flash", "gun", "shot", "fire", "projectile"]
+  },
+  {
+    name: "on_fire",
+    description: "Small drawn flames licking up around a character, embers, a hot rim: on fire, burn damage. Noise version: burn_status.",
+    loops: true,
+    tags: ["burn", "fire", "status", "flames", "dot"]
+  },
+  {
+    name: "orbit_motes",
+    description: "Glowing motes and glints circling a character, passing in front and behind: magic charge, enchantment, wisps, a buff.",
+    loops: true,
+    tags: ["orbit", "motes", "magic", "buff", "arcane", "aura"]
+  },
+  {
+    name: "poison_bubbles",
+    description: "Green bubbles and specks rising off the body and popping, with a sickly pulsing rim on the sprite: poisoned, toxic, sick.",
+    loops: true,
+    tags: ["poison", "status", "bubbles", "toxic", "debuff"]
+  },
+  {
+    name: "portal_swirl",
+    description: "An upright swirling portal: churning core, glowing rim, orbiting motes.",
+    loops: true,
+    tags: ["portal", "void", "gate", "teleport", "magic", "arcane"]
+  },
+  {
+    name: "rain_streaks",
+    description: "Rain falling straight down as thin streaks, near and far, with little splashes on the ground: wet weather, storms, gloom.",
+    loops: true,
+    tags: ["rain", "weather", "water", "storm", "ambient"]
+  },
+  {
+    name: "rocket_exhaust",
+    description: "Round smoke puffs streaming left from an exhaust flame, flying right (+x): rockets, fire trails. Noise version: smoke_trail.",
+    loops: true,
+    tags: ["trail", "smoke", "rocket", "exhaust", "projectile", "missile"]
+  },
+  {
+    name: "rune_circle",
+    description: "A magic circle on the ground: rings, a hexagram and a rune band turning slowly, twinkling motes.",
+    loops: true,
+    tags: ["magic", "circle", "sigil", "summon", "ground", "arcane"]
+  },
+  {
+    name: "rune_orbit",
+    description: "Four glowing rune glyphs evenly circling a character's waist on a faint ring, in front and behind: spellcasting, enchant, arcane buff.",
+    loops: true,
+    tags: ["runes", "orbit", "arcane", "magic", "buff", "enchant"]
+  },
+  {
+    name: "scorch_mark",
+    description: "A charred patch on the ground with embers smouldering and flickering in it. Loop: after explosions, fire spells, burning.",
+    loops: true,
+    tags: ["scorch", "burn", "ground", "fire", "embers", "aftermath"]
+  },
+  {
+    name: "shadow_aura",
+    description: "Dark smoke wisps billowing up behind a character from a shadow pool, pale motes rising: dark power, curse, corruption.",
+    loops: true,
+    tags: ["shadow", "aura", "dark", "curse", "smoke", "debuff"]
+  },
+  {
+    name: "shield_break",
+    description: "A bubble shield flickering, then bursting in a flash into shards that fly out and fall. A broken guard or barrier.",
+    loops: false,
+    tags: ["shield", "break", "barrier", "bubble", "shatter"]
+  },
+  {
+    name: "shockwave_ring",
+    description: "A ring of force racing out along the ground with dust kicked up. A stomp, a landing, an impact.",
+    loops: false,
+    tags: ["impact", "stomp", "landing", "ground", "ring", "dust"]
+  },
+  {
+    name: "sky_beam",
+    description: "A pillar of light slams down onto the anchor, flares wide, rings out on the ground and thins away: smite, blessing, summon, revive.",
+    loops: false,
+    tags: ["beam", "holy", "light", "smite", "summon", "revive"]
+  },
+  {
+    name: "slam_dust",
+    description: "Round dust clouds billowing out and up from a ground impact: landings, slams, boulders. Noise version: crater_dust.",
+    loops: false,
+    tags: ["dust", "impact", "ground", "slam", "landing", "cloud"]
+  },
+  {
+    name: "slash_trail",
+    description: "A weapon swing: a bright crescent sweeping past the sprite, then dithering away. Sword, axe and claw swings.",
+    loops: false,
+    tags: ["slash", "swing", "sword", "melee", "hit", "arc"]
+  },
+  {
+    name: "sleep_zzz",
+    description: "Z letters drifting up and to the right off the head, growing as they rise and fading: asleep, resting, sleep status.",
+    loops: true,
+    tags: ["sleep", "zzz", "status", "rest", "idle"]
+  },
+  {
+    name: "smoke_column",
+    description: "A looping column of drawn smoke puffs rising, swaying, growing and fading. Chimneys, campfires, burning wrecks.",
+    loops: true,
+    tags: ["smoke", "column", "chimney", "fire", "loop"]
+  },
+  {
+    name: "smoke_poof",
+    description: "A drawn cartoon poof: round smoke puffs bursting out all round, rising and burning away. Vanish, teleport (z front hides the sprite).",
+    loops: false,
+    tags: ["smoke", "poof", "cartoon", "vanish", "teleport"]
+  },
+  {
+    name: "smoke_puff",
+    description: "A puff of smoke that billows up and thins away: dust clouds, poofs, after an explosion.",
+    loops: false,
+    tags: ["smoke", "puff", "poof", "dust", "cloud"]
+  },
+  {
+    name: "smoke_trail",
+    description: "A churning smoke plume streaming left from an exhaust flame on the anchor, flying right (+x): rockets; a fire trail in fire colour.",
+    loops: true,
+    tags: ["trail", "smoke", "rocket", "exhaust", "projectile", "missile"]
+  },
+  {
+    name: "snowfall",
+    description: "Snowflakes drifting down around the anchor, near ones as little crystals, far ones as dots.",
+    loops: true,
+    tags: ["snow", "weather", "winter", "cold", "ambient", "ice"]
+  },
+  {
+    name: "soft_glow",
+    description: "A soft pool of light on the ground, gently breathing: under a character, a pickup, a lamp.",
+    loops: true,
+    tags: ["glow", "light", "ground", "pool", "ambient", "aura"]
+  },
+  {
+    name: "spark_burst",
+    description: "Sparks flying out of a point and fading: hits, clashes, sword strikes, electricity.",
+    loops: false,
+    tags: ["sparks", "hit", "clash", "impact", "electric"]
+  },
+  {
+    name: "sparks_shower",
+    description: "Hot sparks spraying out of a point in a cone and arcing down: metal on metal, sword clashes, grinding, welding.",
+    loops: false,
+    tags: ["sparks", "metal", "clash", "hit", "shower", "impact"]
+  },
+  {
+    name: "speed_lines",
+    description: "Pale wind streaks rushing left past the anchor, behind and over a sprite moving right (+x): dashes, sprints, charges.",
+    loops: true,
+    tags: ["speed", "dash", "motion", "wind", "lines", "movement"]
+  },
+  {
+    name: "sprite_dust",
+    description: "The sprite's own pixels lifting off as dust and drifting away: disintegrate, fade out, teleport out (pair with the sprite's dissolve).",
+    loops: false,
+    tags: ["disintegrate", "dust", "teleport", "vanish", "sprite"]
+  },
+  {
+    name: "square_sigil",
+    description: "A ground seal of two counter-turning squares inside two rings, a glowing heart and motes rising: casting, warding, a trap glyph.",
+    loops: true,
+    tags: ["sigil", "magic", "circle", "ground", "ward", "arcane"]
+  },
+  {
+    name: "star_burst",
+    description: "Chunky cartoon stars pop out of the anchor in a ring and hang before blinking away: bonks, KOs, rewards, pickups.",
+    loops: false,
+    tags: ["stars", "cartoon", "burst", "hit", "reward", "pickup"]
+  },
+  {
+    name: "steam_puffs",
+    description: "A steam jet from the ground, round puffs that billow up and dissolve: vents, geysers, kettles. Noise version: steam_vent.",
+    loops: true,
+    tags: ["steam", "smoke", "vent", "geyser", "rising", "ambient"]
+  },
+  {
+    name: "steam_vent",
+    description: "A hissing jet of steam from a point on the ground, puffs that billow up, widen and dissolve: vents, geysers, kettles, hot springs.",
+    loops: true,
+    tags: ["steam", "smoke", "vent", "geyser", "rising", "ambient"]
+  },
+  {
+    name: "stun_stars",
+    description: "Three little stars circling evenly just above the head on a faint ring, passing in front and behind: stunned, dazed, dizzy.",
+    loops: true,
+    tags: ["stun", "dizzy", "stars", "status", "daze"]
+  },
+  {
+    name: "swing_slash",
+    description: "A drawn weapon swing that whips: the edge races round, then is reeled in from behind and crumbles. Swords, axes.",
+    loops: false,
+    tags: ["slash", "sword", "swing", "melee", "hit"]
+  },
+  {
+    name: "teleport_in",
+    description: "Motes swirling in and a column of light narrowing to a flash where the sprite appears. Arrivals, summons, respawns.",
+    loops: false,
+    tags: ["teleport", "arrive", "summon", "beam", "magic"]
+  },
+  {
+    name: "thrust_streak",
+    description: "A straight lance of light stabbing out from the sprite and fading forward, with speed lines. Spear, rapier, dash attacks.",
+    loops: false,
+    tags: ["thrust", "stab", "spear", "melee", "dash", "hit"]
+  },
+  {
+    name: "torch_fire",
+    description: "A drawn torch flame: three teardrop tongues whipping at the tips, a spark or two, lighting the sprite. Torches, braziers.",
+    loops: true,
+    tags: ["fire", "torch", "flame", "brazier", "loop"]
+  },
+  {
+    name: "torch_flame",
+    description: "A small flickering teardrop flame with a licking tongue and a spark or two: torches, candles, braziers, a burning spot.",
+    loops: true,
+    tags: ["fire", "flame", "torch", "light", "ambient"]
+  },
+  {
+    name: "twinkles",
+    description: "Little stars twinkling in and out around the anchor: magic, shine, enchantment, treasure.",
+    loops: true,
+    tags: ["sparkles", "twinkle", "magic", "shine", "stars", "ambient"]
+  },
+  {
+    name: "vine_growth",
+    description: "Twisting green vines sprouting from the ground and curling up around the anchor, leaves popping, then withering: entangle, roots, nature.",
+    loops: false,
+    tags: ["nature", "vines", "roots", "entangle", "growth", "ground"]
+  },
+  {
+    name: "water_drips",
+    description: "Water drops forming on a body and dripping off its lower half, wet glints: soaked, wet status, just out of water, melting.",
+    loops: true,
+    tags: ["water", "drips", "wet", "status", "soaked"]
+  },
+  {
+    name: "water_ripple",
+    description: "Thin rings rippling out on a water surface around the feet, with glints. Loop for wading, standing in water, puddles.",
+    loops: true,
+    tags: ["water", "ripple", "wading", "environment", "ambient", "puddle"]
+  },
+  {
+    name: "water_splash",
+    description: "A crown of droplets thrown up out of water and falling back, with ripples spreading on the surface. Landings, dives, stones.",
+    loops: false,
+    tags: ["water", "splash", "droplets", "ripple", "landing", "environment"]
+  },
+  {
+    name: "wind_gusts",
+    description: "Light streaks of wind sweeping left to right across the anchor with flecks of debris: wind, gales, speed, haste.",
+    loops: true,
+    tags: ["wind", "air", "gust", "weather", "speed", "ambient"]
+  },
+  {
+    name: "zigzag_slash",
+    description: "A slash along a path, not a circle: a zigzag (sharp corners, frantic cuts) or an S (smooth). Reshape it by patching its points.",
+    loops: false,
+    tags: ["slash", "zigzag", "sword", "axe", "melee", "hit", "combo", "path"]
+  }
+];
+const PRESET_NAMES = new Set(VFX_PRESETS.map((preset) => preset.name));
+const PART_NAMES = new Map(VFX_PARTS.map((part) => [part.name, part]));
+const HEX = /^#[0-9a-f]{6}$/i;
+const SLIDERS = ["size", "amount", "speed", "start", "end"];
+function colourProblem(colour) {
+  if (typeof colour === "string") {
+    return VFX_RAMPS.includes(colour) ? null : `"${colour}" is not a colour ramp`;
+  }
+  if (!Array.isArray(colour) || colour.length < VFX_COLOURS_RANGE.min || colour.length > VFX_COLOURS_RANGE.max || !colour.every((one) => typeof one === "string" && HEX.test(one))) {
+    return `a colour is a ramp's name or ${VFX_COLOURS_RANGE.min}–${VFX_COLOURS_RANGE.max} #rrggbb colours`;
+  }
+  return null;
+}
+function partProblem(part, at) {
+  if (!PART_NAMES.has(part.part)) return `part ${at}: "${part.part}" is not a part`;
+  if (part.colour !== void 0) {
+    const problem = colourProblem(part.colour);
+    if (problem) return `part ${at}: ${problem}`;
+  }
+  for (const slider of SLIDERS) {
+    const value = part[slider];
+    if (value === void 0) continue;
+    const { min, max } = VFX_SLIDERS[slider];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+      return `part ${at}: ${slider} is between ${min} and ${max}`;
+    }
+  }
+  if ((part.start ?? 0) >= (part.end ?? 1)) return `part ${at}: start comes before end`;
+  return null;
+}
+function vfxProblem(ask) {
+  const hasPreset = ask.preset !== void 0;
+  const hasParts = ask.parts !== void 0;
+  if (hasPreset === hasParts) return "an effect is a preset or parts, one of the two";
+  if (hasPreset) return PRESET_NAMES.has(ask.preset) ? null : `"${ask.preset}" is not a preset`;
+  const parts = ask.parts;
+  if (parts.length < VFX_PARTS_RANGE.min || parts.length > VFX_PARTS_RANGE.max) {
+    return `an effect has ${VFX_PARTS_RANGE.min} to ${VFX_PARTS_RANGE.max} parts`;
+  }
+  for (const [index, part] of parts.entries()) {
+    const problem = partProblem(part, index + 1);
+    if (problem) return problem;
+  }
+  return null;
+}
 const MORE_KINDS = {
   variant: "a variant",
   edit: "an edit",
@@ -4688,7 +5483,8 @@ const MORE_KINDS = {
   "terrain-animation": "an animated terrain set",
   sfx: "a sound effect",
   speech: "speech",
-  music: "music"
+  music: "music",
+  vfx: "a visual effect"
 };
 const MORE_NAMES = { state: "creature-state", "animated-terrain": "terrain-animation" };
 const UUID$4 = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
@@ -4725,7 +5521,10 @@ const OWN_OPTIONS = {
   voice: ["speech"],
   seconds: ["sfx"],
   loop: ["sfx"],
-  out: ["sfx", "speech", "music"]
+  out: ["sfx", "speech", "music", "vfx"],
+  preset: ["vfx"],
+  part: ["vfx"],
+  subject: ["vfx"]
 };
 const MORE_OPTIONS = {
   source: { type: "string", value: "<image id>", description: "a change's picture: an image of the account's, such as a generation's or a sprite's" },
@@ -4764,7 +5563,23 @@ const MORE_OPTIONS = {
   voice: { type: "string", value: "<voice>", description: `the voice speech is said in: ${VOICES.join(", ")}` },
   seconds: { type: "string", value: "<seconds>", description: `a sound effect's length, ${SFX_SECONDS.min} to ${SFX_SECONDS.max}` },
   loop: { type: "boolean", description: "a sound effect that loops seamlessly" },
-  out: { type: "string", value: "<file>", description: "where a sound is written, pixelvibing/sounds/ unless given" }
+  out: {
+    type: "string",
+    value: "<path>",
+    description: "where a sound is written, pixelvibing/sounds/ unless given; the folder an effect's frames are written in, pixelvibing/effects/ unless given"
+  },
+  preset: { type: "string", value: "<preset>", description: `a ready visual effect: ${VFX_PRESETS.map((preset) => preset.name).join(", ")}` },
+  part: {
+    type: "string",
+    multiple: true,
+    value: "<part>[,colour=<ramp|#rrggbb/#rrggbb…>][,size=<n>][,amount=<n>][,speed=<n>][,start=<0-1>][,end=<0-1>]",
+    description: `a part of a visual effect, given once for each, up to six: ${VFX_PARTS.map((part) => part.name).join(", ")}; colour is a ramp (${VFX_RAMPS.join(", ")}) or colours dark to light`
+  },
+  subject: {
+    type: "string",
+    value: "<image id>",
+    description: "the image a visual effect is drawn around, an image of the account's of at most 256 px a side"
+  }
 };
 function wholeOf(args, name, least, most) {
   const given2 = stringOf(args, name);
@@ -4780,6 +5595,21 @@ function fractionOf(args, name, least, most) {
   if (!Number.isFinite(value) || value < least || value > most) throw new CliError(`--${name} is a number from ${least} to ${most}`);
   return value;
 }
+function partOf(given2) {
+  const [name, ...settings] = given2.split(",").map((each) => each.trim());
+  const part = { part: name ?? "" };
+  for (const setting of settings) {
+    const [key, value] = setting.split("=").map((each) => each.trim());
+    if (value === void 0 || value === "") throw new CliError(`--part's ${key} is given as ${key}=<value>`);
+    if (key === "colour" || key === "color") part.colour = value.includes("/") || value.startsWith("#") ? value.split("/") : value;
+    else if (key === "size" || key === "amount" || key === "speed" || key === "start" || key === "end") {
+      const number2 = Number(value);
+      if (!Number.isFinite(number2)) throw new CliError(`--part's ${key} is a number`);
+      part[key] = number2;
+    } else throw new CliError(`--part takes colour, size, amount, speed, start and end, not ${key}`);
+  }
+  return part;
+}
 const given = (args, name) => args.values[name] !== void 0;
 function ownOnly(args, kind) {
   for (const [option, kinds] of Object.entries(OWN_OPTIONS)) {
@@ -4887,6 +5717,18 @@ async function moreRequest(context, kind, args, instruction, reference) {
       words: `${words} from ${terrain}${instruction === "" ? "" : `: ${instruction}`}`
     };
   }
+  if (kind === "vfx") {
+    const preset = stringOf(args, "preset");
+    const given2 = args.values.part;
+    const parts = given2 === void 0 ? void 0 : (Array.isArray(given2) ? given2 : [given2]).map((each) => partOf(String(each)));
+    const ask = { ...preset === void 0 ? {} : { preset }, ...parts === void 0 ? {} : { parts } };
+    const problem = vfxProblem(ask);
+    if (problem !== null) throw new CliError(`${problem}: give --preset, or --part once for each part`);
+    const subject = stringOf(args, "subject");
+    if (subject !== void 0 && !UUID$4.test(subject)) throw new CliError("--subject is an image's id");
+    const what = preset ?? (parts ?? []).map((each) => each.part).join(", ");
+    return { kind, body: { ...ask, ...subject === void 0 ? {} : { subject } }, words: `${words}: ${what.replace(/_/g, " ")}` };
+  }
   if (kind === "speech") {
     const text2 = stringOf(args, "text")?.trim() ?? "";
     const voice = stringOf(args, "voice");
@@ -4923,7 +5765,7 @@ async function withPatch(platform, project, request) {
   return { ...request, body: { ...body, upperLabel, lowerLabel }, images: { patch } };
 }
 function landsInArt(kind, request) {
-  if (SOUNDS.has(kind) || kind === "terrain" || kind === "terrain-animation") return false;
+  if (SOUNDS.has(kind) || kind === "terrain" || kind === "terrain-animation" || kind === "vfx") return false;
   return !(KEPT_WITH_A_SPRITE.has(kind) && request.body.into !== void 0);
 }
 async function finishedMore(context, platform, local, kind, job, args) {
@@ -4948,6 +5790,33 @@ async function finishedMore(context, platform, local, kind, job, args) {
     }
     return { value: { job: job.id, sounds: written }, words: `Wrote ${written.join(", ")}.` };
   }
+  if (kind === "vfx") {
+    const frames = job.result?.images ?? [];
+    if (frames.length === 0) throw new CliError("the job is done, and made no frame");
+    const out = stringOf(args, "out");
+    const folder = out === void 0 ? join(artOf(local), "effects", `vfx-${job.id.slice(0, 8)}`) : resolve(context.io.cwd, out);
+    const data = job.result?.data ?? {};
+    const names = frames.map((_, index) => `frame-${String(index + 1).padStart(2, "0")}.png`);
+    const timings = {
+      frames: names.map((file, index) => ({ file, ms: data.frames?.[index]?.ms ?? null })),
+      width: data.width ?? null,
+      height: data.height ?? null,
+      anchor: data.anchor ?? null,
+      loops: data.loops === true
+    };
+    const files = [];
+    for (const [index, frame] of frames.entries()) files.push([join(folder, names[index]), await platform.web.imageBytes(frame)]);
+    files.push([join(folder, "effect.json"), new TextEncoder().encode(`${JSON.stringify(timings, null, 2)}
+`)]);
+    for (const [target, bytes] of files) {
+      if (out === void 0) await artBoundary(local).writeFileReplacing(target, bytes);
+      else {
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, bytes);
+      }
+    }
+    return { value: { job: job.id, effect: folder, frames: frames.length }, words: `Wrote ${frames.length} frames and effect.json into ${folder}.` };
+  }
   if (kind === "terrain" || kind === "terrain-animation") {
     return {
       value: { job: job.id },
@@ -5203,8 +6072,8 @@ 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>]… [--mask <png>] [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--no-enrich] [--yes]",
+  summary: "Generate an asset, a change of a picture, terrain, a sound or a visual effect 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|vfx> [--instruction <text>] [--source <image id>] [--state <state>] [--into <sprite> --name <name>] [--upper <ground> --lower <ground>] [--terrain <asset>] [--text <text> --voice <voice>] [--preset <preset> | --part <part>…] [--subject <image id>] [--out <path>] [--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",
@@ -5739,7 +6608,7 @@ const move = {
     );
   }
 };
-const version = "0.53.0";
+const version = "0.55.0";
 const manifest = {
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelvibing/cli",
-  "version": "0.53.0",
+  "version": "0.55.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/SKILL.md

@@ -48,6 +48,7 @@ Load the Skill for the kind before you generate it:
 | another of a result, a change to it, setting it in motion, a pose, turning it, a creature's state | `pixelvibing-change` |
 | ground that joins everywhere, or ground that moves | `pixelvibing-terrain` |
 | a sound effect, a line of speech, a piece of music | `pixelvibing-sound` |
+| a spell, a hit, an explosion, an aura: an animated visual effect | `pixelvibing-effect` |
 
 ## What every generation shares
 

package/skills/pixelvibing-effect/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: pixelvibing-effect
+description: Generate visual effects for this game on PixelVibing — an animated spell, hit, explosion, aura, shield or portal, from a ready preset or built from parts, around one of the game's sprites or on its own — with pixel-vibing-cli or the PixelVibing MCP server, written as frames with their timings. Use when the game needs an effect.
+---
+
+# Visual effect
+
+Load the `pixelvibing` Skill first: who is signed in, the limit.
+
+An effect is drawn from a ready **preset** or from tuned **parts**, never from words: pick the
+ones that fit what the person describes. `pixel-vibing-cli generate --help` lists every preset
+and part by name; read it rather than guessing one.
+
+## With the CLI
+
+```bash
+pixel-vibing-cli generate vfx --preset <preset> [--subject <image id>] [--out <folder>] --yes --json
+pixel-vibing-cli generate vfx --part <part>[,colour=<ramp>][,size=<n>][,start=<0-1>][,end=<0-1>] --part <part> … [--subject <image id>] --yes --json
+```
+
+Each writes the effect's frames, `frame-01.png` on, and `effect.json` — each frame's time in
+milliseconds, the effect's size, the point it is anchored at and whether it loops — into
+`pixelvibing/effects/`, or the folder `--out` names, once its job is done.
+
+## With the MCP server
+
+```json
+{ "project": "<id>", "preset": "explosion", "max_percent": 30 }
+{ "project": "<id>", "parts": [{ "part": "fire_blast", "colour": "frost" }, { "part": "shockwave_ring", "start": 0.1, "end": 0.6 }], "max_percent": 30 }
+```
+
+with the tool `generate_effect`. `get_job` follows the job and, once done, names its frames in
+order, with each frame's time in `data.frames`.
+
+## Choosing it
+
+- **A preset** is a whole effect: `explosion`, `lightning_strike`, `portal`, `heal_pillar`,
+  `magic_circle`, `slash_arc`, `shield_bubble` and more. One preset, nothing else.
+- **Parts** build one: one to six, such as `fire_blast` with `shockwave_ring` and `debris_burst`
+  for a big explosion. Each takes:
+  - `colour`: a ramp's name (arcane, blood, electric, fire, frost, holy, nature, poison, shadow,
+    smoke, water), or 2 to 12 colours dark to light, to match the game's palette; on the CLI,
+    colours are joined by `/`, as `colour=#1a0b2e/#7f3ffb/#e8d5ff`.
+  - `size`, `amount` and `speed`: 1 is the part as made.
+  - `start` and `end`: when it plays, as fractions of a one-shot — a flash at 0, the
+    shockwave from 0.1, debris from 0.15.
+- **A subject** is a sprite the effect is drawn around, an image of the account's of at most
+  256 px a side: an aura, a shield, a heal on a character.
+- **What it costs.** Every effect costs the same, a preset's or six parts'.
+- **Where it goes.** The game plays the frames at their times, placed at the anchor; copy them
+  into the game's own folder when that is where the engine looks. Effects are not part of the
+  map, the export or the sealed container.

package/skills/pixelvibing-icons/SKILL.md

@@ -22,7 +22,9 @@ pixel-vibing-cli generate icons --names "<name>,<name>,..." --purpose <skill|ite
   "icon_size": 32, "instruction": "<theme>", "enrich": false, "max_percent": 40 }
 ```
 
-`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands each icon.
+`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands each icon as pixel art, and
+`pull <job id> --hd` lands them as drawn (HD), beside them; `get_asset` with `"version": "hd"` reads
+them so.
 
 ## Writing it
 

package/skills/pixelvibing-ui/SKILL.md

@@ -30,7 +30,10 @@ The layout goes in the call itself, as `canvas` and `shapes`, with the same fiel
   "reference_images": ["<image id>"], "max_percent": 40 }
 ```
 
-`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands each piece.
+`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands each piece as pixel art, and
+`pull <job id> --hd` lands them as drawn (HD), beside them; `get_asset` with `"version": "hd"` reads
+them so. A UI drawn with `--no-pixel-art` is HD alone. A shape nothing was drawn for is named in the
+result's `missing`: generate the UI again for it rather than retrying the whole set blind.
 
 ## Writing it