Build a Modular Character
A guided example: author a Customizable Object graph, wire a skeletal mesh through to a component, attach garments as child objects, compile it, then swap outfits and colours on an instance at runtime.
Loading…
A guided example: author a Customizable Object graph, wire a skeletal mesh through to a component, attach garments as child objects, compile it, then swap outfits and colours on an instance at runtime.
This walkthrough builds a modular character: one body, a wardrobe of garments that swap at runtime, and a colour you can change per instance. Mutable is how Unreal does interchangeable character parts, and every command here needs Unreal Engine 5.8 or later. They are all listed in the Mutable reference.
A Customizable Object is the recipe: a node graph describing every variation the character can have. Compiling it produces the runtime parameters. A Customizable Object Instance is one configured result, holding a value per parameter and building a skeletal mesh from them. You author the recipe once and make as many instances as you want from it.
Node titles are not guessable, so search for the idea and read the pins off whatever comes back. Both commands take several queries at once.
Several keywords in one call, results ranked. Ignores spacing and case.
cfa search_mutable_nodes --queries "mesh,switch,group,parameter" --max-results 5Every pin and editable property, plus the description Unreal itself carries for the node.
cfa describe_mutable_node --node-types "Mesh Section,Skeletal Mesh Make,Object Group"A skeletal mesh does not plug straight into a character. It travels a chain of four nodes before it reaches a component, and every link is type checked, so a wrong one fails loudly rather than quietly.
The recipe asset. Everything else hangs off its Base Object node.
cfa create_customizable_object --asset-path /Game/Chars/CO_HeroSkeletal Mesh into Mesh Section, into Skeletal Mesh Make, into Skeletal Mesh Object Make, into a component. Set the mesh first, because the node's output pins only appear once it has one.
cfa build_mutable_graph --customizable-object /Game/Chars/CO_Hero \
--nodes '[{"id":"sk","node_type":"Skeletal Mesh","properties":{"SkeletalMesh":"/Game/Chars/SK_Body"}},
{"id":"ms","node_type":"Mesh Section"},
{"id":"mk","node_type":"Skeletal Mesh Make"},
{"id":"om","node_type":"Skeletal Mesh Object Make"},
{"id":"comp","node_type":"Skeletal Mesh Component","properties":{"ReferenceSkeletalMesh":"/Game/Chars/SK_Body"}}]'Compilation walks out from the Base Object and turns the graph into runtime parameters.
cfa compile_customizable_object --customizable-object /Game/Chars/CO_Herolist_mutable_parameters returns fewer than you expected, the node is almost certainly orphaned rather than broken.There are two ways to offer a choice. An enum and a switch is right for swapping one mesh section. An object group is the modular character pattern: its options are whole child objects, each with its own mesh chain, so one option can bring several meshes at once. Those children can be separate assets, which is how the same jacket gets shared by every character that wants it instead of being copied into each one.
Each child is its own Customizable Object. Attach several in one call, and pass --unlink to detach.
cfa link_mutable_child_object --parent /Game/Chars/CO_Hero \
--children '[{"child":"/Game/Wardrobe/CO_Jacket","group":"Outfit"},
{"child":"/Game/Wardrobe/CO_Pullover","group":"Outfit"}]'The group's options are resolved during the parent's compile, not the child's.
cfa compile_customizable_object --customizable-object /Game/Chars/CO_Hero --forceEvery runtime parameter with its type, default and options.
cfa list_mutable_parameters --customizable-object /Game/Chars/CO_HeroAn instance holds one value per parameter. Set them, then rebuild its mesh. A configuration can be copied onto other instances or reset back to defaults.
One configured result of the recipe.
cfa create_customizable_object_instance --customizable-object /Game/Chars/CO_Hero --asset-path /Game/Chars/CO_Hero_InstSet several parameters in one call. An option that does not exist is refused, with the valid ones listed.
cfa set_mutable_parameter --instance /Game/Chars/CO_Hero_Inst --name Outfit --value JacketApplies the parameter values and regenerates the skeletal mesh.
cfa update_mutable_instance --instance /Game/Chars/CO_Hero_InstArranges the nodes and adds reroute points so a long wire follows a lane instead of cutting across the graph.
cfa layout_mutable_graph --customizable-object /Game/Chars/CO_HeroEvery parameter with its options and UI metadata, its states, components, and the assets it references.
cfa export_mutable_object --customizable-object /Game/Chars/CO_HeroPull the graph out as one document, then compare or patch it back. Pass a file the CLI wrote straight back in.
cfa export_graph --asset /Game/Chars/CO_Hero --domain mutable > hero.json
cfa diff_graph --json @hero.json --asset /Game/Chars/CO_Hero2 --domain mutable