vfx

pixelkiln vfx presets
pixelkiln vfx parts
pixelkiln vfx --preset explosion --part scorch_mark --out fx/explosion --game-pack
pixelkiln vfx --preset heal_pillar --sprite sprites/hero.png --out fx/hero-heal
pixelkiln vfx --recipe fx/explosion.vfx.json --out fx/explosion-v2
pixelkiln vfx --effect <saved effect id> --out fx/explosion --force

Builds an animated pixel-art effect with PixelLab's VFX workbench (Create VFX), exports it, and downloads it. PixelLab only offers the workbench as an MCP tool, with no REST endpoint, so this command talks to PixelLab's MCP server with the same PIXELLAB_API_KEY. The workbench is a renderer, not a model: it is free on a subscription and the same recipe renders the same pixels every time.

• vfx presets and vfx parts print PixelLab's current lists: whole-effect presets (explosion, lightning_strike, heal_pillar, portal, aura, and more) and parts to layer on (scorch_mark, spark_burst, stun_stars, rain_streaks, and about 90 others).
• Start from exactly one of --preset <name>, --recipe <file>, or --effect <id>, or from --part alone. --part <name> is repeatable and adds parts on top, in order.
• --sprite builds the effect around a character: a local PNG or JPEG, a URL, or a PixelLab reference such as character:<id>:south.
• --fps <n> sets the frame rate (1–60). --name sets the name saved to your PixelLab "My effects"; it defaults to the preset or the output's file name.
• --out <base> writes <base>.png (spritesheet), <base>.gif, <base>.json (an Aseprite-style frame atlas pointing at the sheet, with the effect's anchor in meta.anchor), and <base>.vfx.json. --game-pack adds <base>-game.zip: every piece as its own clip (the whole effect, the layers behind and in front of the sprite, each part) plus a manifest.json saying where each plays. Existing files are replaced only with --force.
• <base>.vfx.json records the saved effect's id, its edit link on pixellab.ai, the frame facts, the sprite it was built around, and the effect's full recipe. Pass it back as --recipe to render the same effect again; it reuses the recorded sprite unless you pass --sprite.
• Every run saves the effect to your My effects, where its sliders can be moved on pixellab.ai. Pick the changes up with --effect <id> --force, which exports over the saved effect and keeps its name.
• --json prints the export facts and paths; --dry-run sends nothing.

For effects that need more than presets and parts (your own layers, exact timing, a projectile you drew), use the vfx_workbench tool from an MCP client such as Claude Code. Then pull the result into the project with pixelkiln vfx --effect <id>.

To plan, lock, and pack effects with the rest of a project's art, declare them in the manifest instead, with the vfx generator. A .vfx.json record from this command works there as a recipe.