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.

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.

Two assets, and they are not the same thing

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.

Find the node before you name 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.

Search by idea

Several keywords in one call, results ranked. Ignores spacing and case.

bash

cfa search_mutable_nodes --queries "mesh,switch,group,parameter" --max-results 5

Read the exact pins and properties

Every pin and editable property, plus the description Unreal itself carries for the node.

bash

cfa describe_mutable_node --node-types "Mesh Section,Skeletal Mesh Make,Object Group"

Build the body

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.

Create the Customizable Object

The recipe asset. Everything else hangs off its Base Object node.

bash

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

Build the mesh chain

Skeletal 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.

bash

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"}}]'

Compile it

Compilation walks out from the Base Object and turns the graph into runtime parameters.

bash

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

A parameter node nothing reaches produces nothing

Compilation starts at the Base Object and walks outward, so a parameter node that is not connected back to it compiles silently to no parameter at all. If list_mutable_parameters returns fewer than you expected, the node is almost certainly orphaned rather than broken.

Add a wardrobe

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.

Attach the garments

Each child is its own Customizable Object. Attach several in one call, and pass --unlink to detach.

bash

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"}]'

Recompile the parent

The group's options are resolved during the parent's compile, not the child's.

bash

cfa compile_customizable_object --customizable-object /Game/Chars/CO_Hero --force

See what you can now change

Every runtime parameter with its type, default and options.

bash

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

Give every component a unique name

Two components sharing a name across the parent and its children compile perfectly cleanly, then fail when the character is built, showing only Error Updating in the preview. Wire a Static String node into each Skeletal Mesh Component's Name pin so each one is distinct. Same naming does not merge them.

Wear it

An 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.

Create an instance

One configured result of the recipe.

bash

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

Choose an outfit

Set several parameters in one call. An option that does not exist is refused, with the valid ones listed.

bash

cfa set_mutable_parameter --instance /Game/Chars/CO_Hero_Inst --name Outfit --value Jacket

Rebuild the mesh

Applies the parameter values and regenerates the skeletal mesh.

bash

cfa update_mutable_instance --instance /Game/Chars/CO_Hero_Inst

Keep it readable, and take it with you

Lay the graph out

Arranges the nodes and adds reroute points so a long wire follows a lane instead of cutting across the graph.

bash

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

Export the whole object

Every parameter with its options and UI metadata, its states, components, and the assets it references.

bash

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

Round trip the graph

Pull the graph out as one document, then compare or patch it back. Pass a file the CLI wrote straight back in.

bash

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

Unreal Engine 5.8 and later

Every command here needs 5.8. On 5.6 and 5.7 each one returns an explicit message naming the version and changes nothing, so a script written against 5.8 fails clearly rather than halfway through.

Loading…

PreviousBuild Sound with AI NextGrow a Tree with AI