For AI agents

The fx CLI and the MCP server

Mageloom FX ships with fx, a command line that makes effects with no window: generate, look, adjust, bake, export. Every command works on files and answers with paths and a one-line summary, so an agent spends few tokens. fx mcp serves the same commands over MCP.

The loop

$ fx options --json                    # families, materials, styles, looks, sliders
$ fx gen nova --seed 7 --material frost --style grim --out /abs/work/a.json --json
$ fx preview /abs/work/a.json --out /abs/work/a.png   # 8 frames in one 512 px PNG
$ fx tune /abs/work/a.json --energy 0.7 --tempo 0.6 --out /abs/work/b.json
$ fx edit /abs/work/b.json --path layers.hero-2.tune.size --value 1.3
$ fx bake /abs/work/b.json --out /abs/work/b_sheet.png
$ fx export_godot /abs/work/b.json --folder /abs/game/assets/fx --preset mobile
$ fx export_godot_live /abs/work/b.json --folder /abs/game/fx
$ fx export_unity /abs/work/b.json --folder /abs/game/Assets/Effects --preset mobile
$ fx export_unity_live /abs/work/b.json --folder /abs/game/Assets/Effects

gen writes the lead of a batch of twelve. --pick 3 writes another from the same batch, a new --seed gives a new batch. --look cinema|blend|painted picks the look, --look-mix 0..1 anything between.
tune moves the whole-effect sliders from 0 to 1, 0.5 as generated: energy, scale, tempo and density.
edit sets one field by dot path, and validates before it writes. fx describe lists the layer ids and roles without printing the whole recipe.
mutate and candidates vary a recipe from its genes. Locked layers stay put.
export_godot writes a linked folder into a Godot project: sheets, scenes, scripts, recipe.json and fxforge.json. Run it again to re-export in place. A change that would break scenes is refused unless you pass --new-folder or --force.
export_unity writes a Unity 6 package (early access) into a Unity project: the effect folder and the shared MageloomFX scripts, which build 2D and 3D prefabs on import. Run it again to update it in place; GUIDs and prefab references hold. --zip writes a zip instead.
export_godot_live and export_unity_live write Live 3D: the engine replays the effect from its own particle tracks and Mageloom FX's shaders, so it turns with the camera and stays sharp at any size. Godot 4.4 or later (Forward+, Mobile, Compatibility); Unity 6 (URP and Built-in). No bake and no GPU. Run again to update in place; a one-shot becoming a loop needs --new-folder or --force.
The rig, in all four exports: per-instance tint, hue_shift and recolour, effect_scale and speed, a ground decal and a light in 3D, and the events impact, hold_started, released and finished. --no-rig, --no-decal and --no-light leave parts out.
Pixel art, on bake, export_godot and export_unity: --pixel 16..128, --palette auto|mageloom16|mageloom32|<.gpl or .hex file>, --colours 2..64, --dither off|bayer2|bayer4, --fps, --upscale 1..8, --outline on. Hard alpha, one palette for the sheet, nearest filtering set in the engine.
Direction sets, on the same three: --directions 4|8 with --pitch iso|iso30|top|side|<degrees> bakes one sheet row per camera direction; the Godot scene and Unity prefab get a set_direction helper. --separate writes a sheet per direction, --split keeps floor and air apart.
--size alone keeps the 8 x 3 grid; --held with no sizes bakes at 20 FPS. Linked folders re-export with their own saved settings.

The sample Godot project

$ fx sample godot /abs/work/sample --json     # an empty or new folder only; needs a GPU for the sheets

Writes a Godot 4.4+ project to try effects in: an arena with a caster and a target, six starters (Fireball, Frost nova, Poison cloud, Level up, Heal burst, Holy shield) exported as Live 3D and as rigged sheets, and a short demo.gd. Keys 1 to 6 cast them, Tab switches Live 3D and sheets, C turns the hue 120 degrees. A folder with anything in it is refused. Not in MCP (it writes a whole project); the app makes the same from Help.

Shapes

$ fx shape new rock --name "Meteor Rock" --cracks 0.5 --crack-glow 0.9 --seed 9 --json
$ fx shape show meteor-rock --preview /abs/work/rock.png
$ fx shape set /abs/work/a.json --element hero-4 --shape meteor-rock --out /abs/work/b.json

Shards and crystal elements can draw a parametric shape: a base (rock, shard, crystal, sphere), seven values from 0 to 1 and a seed. Shapes go into a library on disk and travel inside the recipe that uses them. fx mesh import takes your own .glb, .gltf or .obj as a piece, or as a figure for the cast stage. fx material new makes a material of your own beside the 16 built-ins.

Speed and support

$ fx perf /abs/work/b.json --json    # game budget, a timed bake, live frame times
$ fx bench --json                    # fixed benchmark, same recipes on every machine
$ fx sysinfo --json                  # version, OS, CPU, GPU for a bug report

perf rates the sheet a Godot export would bake (green, amber or red) with VRAM, overdraw and one-line hints. Nothing is sent anywhere.

Output

Add --json to any command for one line of JSON:

{"ok":true,"cmd":"gen","summary":"...","data":{...}}
{"ok":false,"cmd":"gen","error":{"code":"bad_value","exit":2,"field":"family",
  "message":"--family novaa is not a known value.","allowed":["nova","projectile",...]}}

Exit	Code	Meaning
0		ok
2	`usage`, `bad_value`, `missing`	unknown command or flag, bad or missing value
3	`input`	cannot read the input, or it is not a recipe
4	`invalid`	the recipe fails validation, or the edit would make it fail
5	`gpu`	no usable GPU
6	`not_connected`	not in this build
7	`output`	cannot write the output
8	`network`	`update-check` and `share` only: could not reach mageloomfx.com
1	`internal`	a bug

fx help lists the commands, fx help <cmd> shows flags, and fx help --json gives the whole registry in one call.

MCP server

fx mcp serves over stdio. The default, --tools compact, lists four tools (about 1.5 KB of schemas): run takes a command line, preview returns the PNG as an image, plus help and status. --tools full lists one typed tool per command, the docs as resources and two prompts, make_effect and tweak_effect.

Claude Code:

$ claude mcp add mageloom -- /path/to/fx mcp
$ claude mcp add mageloom-full -- /path/to/fx mcp --tools full

Claude Desktop, Cursor or any other MCP client: add an entry to its mcpServers config.

{
  "mcpServers": {
    "mageloom": { "command": "/path/to/fx", "args": ["mcp"] }
  }
}

Give absolute paths in every call: some clients start the server in a folder of their own choosing.

The Claude Code skill

The app comes with a skill folder that teaches an agent the loop above and loads the full guide only when the task needs it. Copy it into ~/.claude/skills/ for every project, or .claude/skills/ for one. With a skill and a shell, the agent runs fx directly and you don't need the MCP server at all.

The skill and the full agent guide ship inside the app download. Questions: [email protected].