Unity Vfx Graph

Visual Effect Graph

With --output json, results use {success, command, data, errors, warnings}. Check the exit status and envelope success first; tool-result fields in this skill are relative to data. Read failure codes from errors[0].code; see unity-cli-usage for exit-code recovery.

Author and inspect .vfx Visual Effect Graph assets: read a graph's contexts, blocks, operators and parameters, discover the node library, and apply authoring mutations. The VFX authoring API is internal to Unity, so these operations run through dedicated bridge tools (vfx_*) rather than direct component edits. This skill is the VFX complement to unity-asset-management, which handles generic asset, material, and import operations.

Use When

• The user wants to inspect a .vfx graph's structure (contexts, blocks, operators, parameters, links, layout).
• The user wants to discover which blocks, operators, contexts, or templates are available.
• The user wants to build or modify a graph: add/remove/link nodes, set values and settings, manage the blackboard, systems, events, subgraphs, sticky notes, groups, or canvas layout.
• The user wants to verify a graph compiles, or find out why it does not.
• The user wants to drive an exposed parameter on a live VisualEffect (vfx_runtime), read/write VFX project settings or editor preferences (vfx_settings), or bake a Mesh into an SDF Texture3D (vfx_bake_sdf).

Do Not Use When

• The task is generic asset, material, or import work; use unity-asset-management.
• The request is about editing arbitrary serialized fields on a scene component; use unity-gameobject-edit. (vfx_runtime is only for VisualEffect public-API calls like SetFloat/SendEvent.)
• The work is play-mode lifecycle control or input simulation; use unity-playmode-testing.

Preferred Flow

Prerequisite: the target project must have com.unity.visualeffectgraph installed. The Bridge keeps it optional; VFX_PACKAGE_MISSING means to report the missing package and obtain the user's intended package setup before authoring a graph. Input errors return {error, code} without Console Error logs; inspect the response before continuing. Runtime playback uses send_event with OnPlay.

1. Baseline. vfx_describe_graph before mutating. Note the three oracles it carries: errors (validation + compile errors, on by default), compile (outcome of the last recompile), and layout (overlapCount + overlapping node pairs). Write down the baseline overlapCount: a hand-made graph often has a non-zero one (node sizes are estimated generously), and your job is to not add to it.
2. Discover names. vfx_list_library with kind (block default, operator, context, parameter, template) and a filter whenever you are not certain of an exact descriptor name — the leading | and |_ separators in names like |Set|_Color are load-bearing.
3. Mutate narrowly with vfx_apply, one op at a time. Every op response carries compile.success; read it. If it is false, the graph no longer compiles — compile.exception / compile.errors / compile.logs say why. Fix that before doing anything else; never stack more ops on a broken graph. An op that returns error was not applied at all.
4. Place what you added — mandatory; move nothing else. Add ops only keep a new node off existing ones. Before you report, run vfx_apply op:"auto_layout". Its default scope, nodes, places only the nodes created this session — operators, and a parameter canvas node for every link made from a parameter — in free space directly left of what they feed, aligned with the consuming block's row and stacked per consumer, and moves nothing that existed before. (One exception, reported as shiftedDown: a context that grew over the next context of its own system pushes that lower part of the system down, vertically only, as a person would.) A person's canvas is theirs: re-laying out a whole system for one added block is never the right answer. Pass scope:"touched" (re-lay out every system edited this session), scope:"all", or contexts:[…] only when the user asks for a tidy-up.
5. Box the feature with its note. A person keeps the nodes of one feature in a group box with a sticky note explaining it; do the same for what you added: group_nodes with your new nodes and note:{title, contents} creates the box and the note inside it (left of the members). Read nonMembersInside in the response — if the box swallows nodes that are not yours, move your own nodes closer together (move_node; nodes created this session move freely) and run group_nodes again, or drop the box and keep just the note. A block cannot be grouped; name it in the note.
6. Verify and only then report. Re-run vfx_describe_graph and confirm all three: compile.success == true, no errors[] entry with type: "Error", and layout.overlapCount no higher than your baseline with no listed overlap involving a node you created (on a graph you built from scratch that means 0). Quote those three facts in your completion report. (get_compilation_state is C# script compilation and says nothing about a VFX graph; use compile / describe instead.)

Invocation: every tool runs as unity-cli raw <tool> --json '<json>'. Add --output json for a structured (parseable) result, and --port <N> to target a specific bridge (default 6400).

unity-cli raw vfx_describe_graph --json '{"assetPath":"Assets/FX/Burst.vfx"}'
unity-cli raw vfx_list_library --json '{"kind":"block","filter":"turbulence"}'
unity-cli raw vfx_apply --json '{"op":"add_block","assetPath":"Assets/FX/Burst.vfx","contextType":"Update","blockName":"Turbulence","settings":{"NoiseType":"Perlin"}}'
unity-cli raw vfx_apply --json '{"op":"add_operator","assetPath":"Assets/FX/Burst.vfx","operatorName":"Multiply"}'
unity-cli raw vfx_apply --json '{"op":"link_slots","assetPath":"Assets/FX/Burst.vfx","from":{"node":"operator","operatorIndex":0,"slot":0},"to":{"node":"block","contextType":"Update","blockIndex":0,"slot":0}}'
unity-cli raw vfx_apply --json '{"op":"add_parameter","assetPath":"Assets/FX/Burst.vfx","parameterName":"Rate","type":"Float","value":42.5,"min":0,"max":100}'
unity-cli raw vfx_describe_graph --json '{"assetPath":"Assets/FX/Burst.vfx","include":["errors"],"includeSlots":false}'
unity-cli raw vfx_apply --json '{"op":"add_block","assetPath":"Assets/FX/Burst.vfx","contextType":"Update","blockName":"Turbulence","autoCompile":false}'
unity-cli raw vfx_apply --json '{"op":"compile","assetPath":"Assets/FX/Burst.vfx"}'
unity-cli raw vfx_apply --json '{"op":"auto_layout","assetPath":"Assets/FX/Burst.vfx"}'
unity-cli raw vfx_apply --json '{"op":"group_nodes","assetPath":"Assets/FX/Burst.vfx","title":"Liquid turbulence","nodes":[{"node":"parameter","parameterIndex":12},{"node":"operator","operatorIndex":3}],"note":{"title":"Liquid turbulence","contents":"Relative-mode Perlin turbulence: Drag pulls velocity toward the noise field."}}'