@pixelvibing/cli 0.53.0 → 0.54.0

package/dist/pixel-vibing-cli.js

@@ -4677,6 +4677,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 +5430,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 +5468,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 +5510,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 +5542,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 +5664,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 +5712,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 +5737,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 +6019,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 +6555,7 @@ const move = {
     );
   }
 };
-const version = "0.53.0";
+const version = "0.54.0";
 const manifest = {
   version
 };

package/package.json

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