Mutable

Mutable: Modular characters, built from commands. Unreal Engine 5 command reference with parameters and examples.

36 commands. Each shows its parameters and an example, and has a copyable deep link, so you (or an AI agent) can jump straight to one.

search_mutable_nodes

Rank Mutable node types against keywords (5.8+ only)

Parameter	Type	Required	Description
queries	stringlist	No	Keywords to rank node types against. Pass several to search them all in one call, e.g. ["switch", "texture", "projector"].
filter	string	No	Single keyword. Convenience alias for a one-entry queries array.
category	string	No	Restrict results to one menu category, e.g. Texture, Mesh, Float. Case-insensitive.
max_results	int	No	Maximum matches returned per query.

example

cfa search_mutable_nodes --queries switch,texture,projector --max-results 5

describe_mutable_node

Describe Mutable node types, pins and properties (5.8+ only)

Parameter	Type	Required	Description
node_types	stringlist	No	Node type titles to describe, exactly as returned by search_mutable_nodes. Pass several to describe them all in one call.
node_type	string	No	Single node type title. Convenience alias for a one-entry node_types array.
include_properties	bool	No	Include the node's editable properties and their default values.

example

cfa describe_mutable_node --node-types "Switch (Mesh)","Texture Parameter"

list_mutable_node_categories

List the Mutable node palette categories (5.8+ only)

Parameter	Type	Required	Description
include_nodes	bool	No	Also list the node type titles belonging to each category.

example

cfa list_mutable_node_categories --include-nodes

create_customizable_object

Create a new Customizable Object asset (5.8+ only)

Parameter	Type	Required	Description
asset_path	string	Yes	Content path for the new Customizable Object, e.g. /Game/Chars/CO_Hero.

example

cfa create_customizable_object --asset-path /Game/Chars/CO_Hero

create_customizable_object_instance

Create a Customizable Object Instance (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object the instance is generated from.
asset_path	string	Yes	Content path for the new instance asset, e.g. /Game/Chars/CO_Hero_Inst.

example

cfa create_customizable_object_instance --customizable-object /Game/Chars/CO_Hero --asset-path /Game/Chars/CO_Hero_Inst

get_mutable_graph

Read a Customizable Object's source graph (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object, e.g. /Game/Chars/CO_Hero.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
filter	string	No	Case-insensitive substring matched against node title and class name.
max_results	int	No	Maximum nodes returned. Truncation is always reported.
verbosity	string	No	'summary' returns node guid, title, class and position only. 'full' adds pins, connections and properties.

example

cfa get_mutable_graph --customizable-object /Game/Chars/CO_Hero --filter switch --verbosity full

get_mutable_node

Read Mutable nodes by GUID (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
node_guids	stringlist	No	Node GUIDs to read. Pass several to read them all in one call.
node_guid	string	No	Single node GUID. Convenience alias for a one-entry node_guids array.
include_pins	bool	No	Include the node's pins and what each pin is linked to.
include_properties	bool	No	Include the node's editable properties and their current values.

example

cfa get_mutable_node --customizable-object /Game/Chars/CO_Hero --node-guids 6F2A...,91BC...

add_mutable_node

Add a node to a Customizable Object graph (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
node_type	string	Yes	Node type title exactly as returned by search_mutable_nodes, e.g. 'Switch (Mesh)'.
pos_x	int	No	Graph X position for the new node.
pos_y	int	No	Graph Y position for the new node.
from_node_guid	string	No	Optional node GUID to auto-wire the new node to, using the schema's own autowire pass.
from_pin	string	No	Pin name on from_node_guid to auto-wire from.
from_pin_direction	string	No	Direction of from_pin: 'input' or 'output'. Leave empty when the name is unambiguous.

example

cfa add_mutable_node --customizable-object /Game/Chars/CO_Hero --node-type "Switch (Mesh)" --pos-x 400 --pos-y 120

connect_mutable_nodes

Link two pins in a Customizable Object graph (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
from_node_guid	string	Yes	GUID of the node the connection starts at.
from_pin	string	Yes	Pin name on the source node.
to_node_guid	string	Yes	GUID of the node the connection ends at.
to_pin	string	Yes	Pin name on the target node.
from_pin_direction	string	No	Direction of from_pin: 'input' or 'output'. Defaults to 'output'; anything else is refused.
to_pin_direction	string	No	Direction of to_pin: 'input' or 'output'. Defaults to 'input'; anything else is refused.

example

cfa connect_mutable_nodes --customizable-object /Game/Chars/CO_Hero --from-node-guid 6F2A... --from-pin Mesh --to-node-guid 91BC... --to-pin "Object 0"

disconnect_mutable_pin

Break links on a Customizable Object pin (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
node_guid	string	Yes	GUID of the node owning the pin.
pin	string	Yes	Pin name to disconnect.
direction	string	No	Direction of pin: 'input' or 'output'. Supply it when the name is ambiguous.
target_node_guid	string	No	Break only the link to this node instead of every link on the pin.
target_pin	string	No	Pin name on target_node_guid. Required when target_node_guid is set.
target_pin_direction	string	No	Direction of target_pin.

example

cfa disconnect_mutable_pin --customizable-object /Game/Chars/CO_Hero --node-guid 91BC... --pin "Object 0"

delete_mutable_node

Delete a node from a Customizable Object graph (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
node_guid	string	Yes	GUID of the node to delete. The graph's base object node cannot be deleted.

example

cfa delete_mutable_node --customizable-object /Game/Chars/CO_Hero --node-guid 91BC...

set_mutable_node_property

Write node properties in a Customizable Object graph (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
properties	json	No	Batch of {node_guid, property, value} edits applied in order. Any failed edit fails the whole call.
node_guid	string	No	Single edit: node GUID. Use with property and value instead of the properties array.
property	string	No	Single edit: property name or path; [N] index, [-] append and [Key] map rows work (see set_object_property).
value	any	No	Single edit: free-form JSON value to write.

example

cfa set_mutable_node_property --customizable-object /Game/Chars/CO_Hero --properties '[{"node_guid":"6F2A...","property":"Name","value":"Hair"},{"node_guid":"91BC...","property":"DefaultValue","value":1.0}]'

link_mutable_child_object

Attach child Customizable Objects to a parent's Object Group (5.8+ only)

Parameter	Type	Required	Description
parent	string	Yes	Asset path of the PARENT Customizable Object that owns the Object Group.
children	json	No	Batch form: [{"child":"/Game/...","group":"Torso"}]. An entry detaches with "b_unlink": true (the b_ prefix is required; "unlink" binds to nothing).
child	string	No	Single child asset path.
group	string	No	Object Group node GUID or its GroupName.
unlink	bool	No	Detach the child from its parent instead of attaching it.

example

cfa link_mutable_child_object --parent /Game/Chars/CO_Hero --child /Game/Chars/CO_Jacket --group Torso

list_mutable_child_objects

List the child Customizable Objects attached to a parent (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the PARENT Customizable Object.
group	string	No	Only list children attached to this group, by GUID or GroupName.
max_results	int	No	Maximum children returned.

example

cfa list_mutable_child_objects --customizable-object /Game/Chars/CO_Hero

add_mutable_node_pin

Add a pin to a Mutable node that has an add-pin button (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object, e.g. /Game/Chars/CO_Hero.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
node_guid	string	Yes	GUID of the node to add a pin to.
count	int	No	How many pins to add.

example

cfa add_mutable_node_pin --customizable-object /Game/Chars/CO_Hero --node-guid 6F2A... --count 2

build_mutable_graph

Build a whole Customizable Object graph in one call (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
nodes	json	No	Nodes to create, applied in order: [{id, node_type, pos_x?, pos_y?, properties?}]. Each may carry a free-form 'properties' object.
connections	json	No	Connections made once every node exists, applied in order: [{from, from_pin, to, to_pin, from_pin_direction?, to_pin_direction?}].
layout	bool	No	Place the new nodes without a position beside the nodes they wire to. Existing nodes never move.
dry_run	bool	No	Check the whole spec and report what it would do without changing anything.
continue_on_error	bool	No	Keep going after a failed entry so the error lists every failed entry, not just the first. A build with any failed entry fails and changes nothing either way.

example

cfa build_mutable_graph --customizable-object /Game/Chars/CO_Hero --nodes '[{"id":"sw","node_type":"Switch (Mesh)"},{"id":"mesh","node_type":"Skeletal Mesh","properties":{"Name":"Hair"}}]' --connections '[{"from":"mesh","from_pin":"Mesh","to":"sw","to_pin":"Option 0"}]'

layout_mutable_graph

Auto-arrange a Customizable Object graph (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object whose source graph should be auto-arranged.
macro	string	No	When customizable_object names a Macro Library instead of a Customizable Object, the macro whose graph to target. Optional when the library holds exactly one macro.
insert_reroutes	bool	No	Insert reroute knots on long or crossing wires. Existing reroutes are dissolved first, so running it twice does not accumulate them.
remove_existing_reroutes	bool	No	Dissolve existing reroutes and leave them out. Overrides insert_reroutes.

example

cfa layout_mutable_graph --customizable-object /Game/Chars/CO_Hero

compile_customizable_object

Compile a Customizable Object (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object, e.g. /Game/Chars/CO_Hero.
force	bool	No	Compile even when Mutable considers the object already compiled and up to date. Out-of-dateness is measured against the SAVED package, so an unsaved graph edit still reads as up to date and the compile would be silently skipped. Leave this on unless you deliberately want the skip.
optimization_level	string	No	Optimization level: None, Maximum or FromCustomizableObject. Empty keeps Mutable's own default.
texture_compression	string	No	Texture compression: None, Fast or HighQuality. Empty keeps Mutable's own default.
gather_references	bool	No	Gather every asset reference used by this Customizable Object while compiling. Marks the object modified.
max_results	int	No	Maximum compiler messages returned. Counts are always exact and truncation is reported.

example

cfa compile_customizable_object --customizable-object /Game/Chars/CO_Hero --optimization-level Maximum

validate_customizable_object

Validate a Customizable Object and return a verdict (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object.
compile	bool	No	Also compile the object and fold the compiler's errors and warnings into the verdict. Slower, but the structural pass alone cannot see compile errors.
report_unconnected_inputs	bool	No	Report input pins that are neither connected nor given a default value. Off by default because most Mutable inputs are legitimately optional.
max_results	int	No	Maximum entries returned per issue list. Counts are always exact and truncation is reported.

example

cfa validate_customizable_object --customizable-object /Game/Chars/CO_Hero --compile

list_mutable_parameters

List a Customizable Object's parameters (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	No	Asset path of the Customizable Object. Optional when instance is supplied, in which case the instance's own object is used.
instance	string	No	Asset path of a Customizable Object Instance. When supplied every parameter also reports its current value on that instance.
filter	string	No	Case-insensitive substring matched against parameter names.
max_results	int	No	Maximum parameters returned. Truncation is always reported.
include_options	bool	No	List the selectable option names of every enum (integer) parameter.

example

cfa list_mutable_parameters --instance /Game/Chars/CO_Hero_Inst --filter hair

get_mutable_parameter

Read parameter values off an instance (5.8+ only)

Parameter	Type	Required	Description
instance	string	Yes	Asset path of the Customizable Object Instance to read.
names	stringlist	No	Parameter names to read. Pass several to read them all in one call.
name	string	No	Single parameter name. Convenience alias for a one-entry names array.
range_index	int	No	Range index for multidimensional parameters. -1 reads the single non-ranged value.

example

cfa get_mutable_parameter --instance /Game/Chars/CO_Hero_Inst --names HairStyle,SkinTone

set_mutable_parameter

Write parameter values on an instance (5.8+ only)

Parameter	Type	Required	Description
instance	string	Yes	Asset path of the Customizable Object Instance to write to.
parameters	json	No	Batch of {name, value, range_index} edits applied in order. Any failed edit fails the whole call.
name	string	No	Single edit: parameter name. Use with value instead of the parameters array.
value	string	No	Single edit: new value. An option name for enum, true/false for bool, a number for float, '(R=1,G=0,B=0,A=1)' or '1,0,0,1' for colour, an asset path for texture, mesh and material, and the text form get_mutable_parameter prints for transform and projector.
range_index	int	No	Single edit: range index for a multidimensional parameter. -1 writes the single non-ranged value. At most one past the last existing range value, which appends one, as the editor's Add Layer does.

example

cfa set_mutable_parameter --instance /Game/Chars/CO_Hero_Inst --parameters '[{"name":"HairStyle","value":"Long"},{"name":"SkinTone","value":"(R=0.8,G=0.6,B=0.5,A=1)"}]'

update_mutable_instance

Regenerate a Customizable Object Instance (5.8+ only)

Parameter	Type	Required	Description
instance	string	No	Asset path of the Customizable Object Instance to update. Convenience alias for a one-entry instances list.
instances	stringlist	No	Asset paths of the instances to update. Pass several to update them all in one call; one that cannot be updated fails the call before any update starts.
ignore_close_dist	bool	No	Update even when the instance is far from the camera.
force_high_priority	bool	No	Put this update at the front of Mutable's queue.
wait	bool	No	Wait for the update to finish and report what it actually did. Pass false for fire-and-forget, which cannot tell a built mesh from a failed one.
timeout_seconds	float	No	How long to wait for the update before giving up, in seconds. Only used when wait is true.
max_results	int	No	Maximum Mutable log lines returned per instance in errors and warnings. Truncation is always reported.

example

cfa update_mutable_instance --instance /Game/Chars/CO_Hero_Inst
cfa update_mutable_instance --instances /Game/Chars/CO_Hero_Inst,/Game/Chars/CO_Villain_Inst --timeout-seconds 60

export_mutable_object

Full JSON export of a Customizable Object (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object to export, e.g. /Game/Chars/CO_Hero.
file_path	string	No	Absolute path to write the JSON to. Omit and the export is returned inline unless it is large, in which case it is written under Saved/CodeFizzEditorAgent/Exports/ and the path is returned instead.
include_graph	bool	No	Include the full source graph: every node with its properties, pins and connections.
include_parameters	bool	No	Include the compiled parameters, their defaults, enum options and UI metadata. Needs the object to be compiled.
include_referenced_assets	bool	No	Include the de-duplicated list of external assets the graph references, with the node GUIDs that reference each.
max_results	int	No	Maximum entries per list (parameters, states, components, referenced assets). Truncation is always reported.

example

cfa export_mutable_object --customizable-object /Game/Chars/CO_Hero
cfa export_mutable_object --customizable-object /Game/Chars/CO_Hero --file-path C:/tmp/CO_Hero.json
cfa export_mutable_object --customizable-object /Game/Chars/CO_Hero --include-graph=false

list_mutable_states

List a Customizable Object's states (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	No	Asset path of the Customizable Object. Optional when instance is supplied.
instance	string	No	Asset path of a Customizable Object Instance. When supplied the instance's current state is reported too.

example

cfa list_mutable_states --instance /Game/Chars/CO_Hero_Inst

set_mutable_state

Set the current state of an instance (5.8+ only)

Parameter	Type	Required	Description
instance	string	Yes	Asset path of the Customizable Object Instance to write to.
state	string	Yes	State name, exactly as list_mutable_states reports it.

example

cfa set_mutable_state --instance /Game/Chars/CO_Hero_Inst --state Customization

reset_mutable_parameters

Reset an instance's parameters to their defaults (5.8+ only)

Parameter	Type	Required	Description
instance	string	Yes	Asset path of the Customizable Object Instance to reset.
names	stringlist	No	Parameter names to reset. Omit to reset every parameter.
name	string	No	Single parameter name. Convenience alias for a one-entry names array.

example

cfa reset_mutable_parameters --instance /Game/Chars/CO_Hero_Inst --names Hair,EyeColor

copy_mutable_parameters

Copy an instance's whole parameter state (5.8+ only)

Parameter	Type	Required	Description
instances	stringlist	No	Asset paths of the instances to copy. Pass several to copy them all in one call.
instance	string	No	Single instance asset path. Convenience alias for a one-entry instances array.

example

cfa copy_mutable_parameters --instance /Game/Chars/CO_Hero_Inst

paste_mutable_parameters

Apply a copied parameter state to instances (5.8+ only)

Parameter	Type	Required	Description
descriptor	string	Yes	Descriptor text produced by copy_mutable_parameters.
instances	stringlist	No	Asset paths of the instances to paste into. Pass several to paste into all of them in one call.
instance	string	No	Single instance asset path. Convenience alias for a one-entry instances array.

example

cfa paste_mutable_parameters --instances /Game/Chars/CO_A_Inst,/Game/Chars/CO_B_Inst --descriptor "(BoolParameters=...)"

set_mutable_parameter_ui_metadata

Write Parameter UI Metadata on parameter nodes (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset path of the Customizable Object whose graph holds the parameter nodes.
edits	json	No	Batch of {parameter or node_guid, field, value, value_index} edits applied in order. Any failed edit fails the whole call.
parameter	string	No	Single edit: parameter name whose node carries the metadata.
node_guid	string	No	Single edit: node GUID, when addressing the node directly is easier.
value_index	int	No	Single edit: index into an enum parameter's options, or -1 for the parameter's own metadata.
field	string	No	Single edit: metadata field name.
value	any	No	Single edit: free-form JSON value to write.

example

cfa set_mutable_parameter_ui_metadata --customizable-object /Game/Chars/CO_Hero --edits '[{"parameter":"Hair","field":"UISectionName","value":"Head"},{"parameter":"Hair","value_index":0,"field":"UIOrder","value":3}]'

create_mutable_macro_library

Create a Customizable Object Macro Library (5.8+ only)

Parameter	Type	Required	Description
asset_path	string	Yes	Content path for the new Macro Library, e.g. /Game/Chars/ML_Shared.

example

cfa create_mutable_macro_library --asset-path /Game/Chars/ML_Shared

list_mutable_macros

List a Macro Library's macros (5.8+ only)

Parameter	Type	Required	Description
macro_library	string	Yes	Asset path of the Macro Library, e.g. /Game/Chars/ML_Shared.
filter	string	No	Case-insensitive substring matched against macro name and description.
max_results	int	No	Maximum macros returned. Truncation is always reported.
include_io	bool	No	Include each macro's declared inputs and outputs.

example

cfa list_mutable_macros --macro-library /Game/Chars/ML_Shared

add_mutable_macro

Add macros to a Macro Library (5.8+ only)

Parameter	Type	Required	Description
macro_library	string	Yes	Asset path of the Macro Library to add to.
names	stringlist	No	Names of the macros to add. Pass several to add them all in one call.
name	string	No	Single macro name. Convenience alias for a one-entry names array. Leave empty for an auto-generated name.
description	string	No	Description applied to every macro added by this call.

example

cfa add_mutable_macro --macro-library /Game/Chars/ML_Shared --names TintLayer,MaskBlend

remove_mutable_macro

Remove macros from a Macro Library (5.8+ only)

Parameter	Type	Required	Description
macro_library	string	Yes	Asset path of the Macro Library to remove from.
names	stringlist	No	Names of the macros to remove. Pass several to remove them all in one call.
name	string	No	Single macro name. Convenience alias for a one-entry names array.

example

cfa remove_mutable_macro --macro-library /Game/Chars/ML_Shared --names TintLayer

set_mutable_macro_io

Declare a macro's inputs and outputs (5.8+ only)

Parameter	Type	Required	Description
macro_library	string	Yes	Asset path of the Macro Library.
macro	string	No	Macro to edit. Optional when the library holds exactly one macro.
variables	json	No	Batch of {action, name, unique_id, new_name, direction, pin_type} edits applied in order. Any failed edit fails the whole call.
action	string	No	Single edit: 'add' (default), 'update' or 'remove'.
name	string	No	Single edit: variable name.
unique_id	string	No	Single edit: variable GUID, the only unique key. Use it when two variables share a name.
new_name	string	No	Single edit: new name, for action 'update'.
direction	string	No	Single edit: 'input' or 'output'. Required for add.
pin_type	string	No	Single edit: pin category, e.g. mesh, image, color, float. Required for add.

example

cfa set_mutable_macro_io --macro-library /Game/Chars/ML_Shared --macro TintLayer --variables '[{"action":"add","name":"Base","direction":"input","pin_type":"image"}]'

add_mutable_macro_instance

Place a Macro Instance node in a graph (5.8+ only)

Parameter	Type	Required	Description
customizable_object	string	Yes	Asset owning the graph the node is placed in: a Customizable Object, or a Macro Library when nesting a macro inside another macro.
target_macro	string	No	When customizable_object is a Macro Library, which macro's graph to place the node in.
macro_library	string	Yes	Asset path of the Macro Library holding the macro to instantiate.
macro	string	No	Name of the macro to instantiate. Optional when the library holds exactly one macro.
pos_x	int	No	Graph X position for the new node.
pos_y	int	No	Graph Y position for the new node.
from_node_guid	string	No	Optional node GUID to auto-wire the new node to.
from_pin	string	No	Pin name on from_node_guid to auto-wire from.
from_pin_direction	string	No	Direction of from_pin: 'input' or 'output'.

example

cfa add_mutable_macro_instance --customizable-object /Game/Chars/CO_Hero --macro-library /Game/Chars/ML_Shared --macro TintLayer --pos-x 300

Loading…

PreviousAudio NextControl Rig