Materials

Create a new Material

Creates a new empty Material asset at the specified path. You can set blend_mode, shading_model, and two_sided during creation. Call save_asset after to persist changes to disk.

  cfa create_material --name M_MyMaterial --path /Game/Materials --blend-mode opaque --shading-model default_lit
  cfa create_material --name M_Glass --path /Game/Materials --blend-mode translucent --two-sided true

Create a Material Instance

Creates a Material Instance from a parent material, optionally setting scalar, vector, and texture parameter overrides. Returns error if asset already exists (pass force=true to overwrite). Call save_asset after.

  cfa create_material_instance --parent-path /Game/Materials/M_Base --name MI_Red --path /Game/Materials
  cfa create_material_instance --parent-path /Game/Materials/M_Base --name MI_Custom --scalar-params '{"Roughness": 0.8}' --vector-params '{"BaseColor": {"R":1,"G":0,"B":0,"A":1}}'

Build complete node graph in one atomic call

Builds an entire material node graph atomically: creates expression nodes and wires them together in a single call. All node types are validated BEFORE the existing graph is touched, so a typo'd type aborts with the graph intact. By default clears existing expressions first (safe rebuild -- external references stay intact). Failed connections report the target node's valid input pin names. Preferred over adding nodes one at a time. Call save_asset after.

  cfa build_material_graph --material-path /Game/Materials/M_Test --nodes '[{"type":"Constant3Vector","pos_x":-400,"pos_y":0,"properties":{"Constant":"(R=1,G=0,B=0)"}}]' --connections '[{"from_node":0,"to_node":"material","to_pin":"BaseColor"}]'
  cfa build_material_graph --material-path /Game/Materials/M_Existing --clear-existing false --nodes '[{"type":"Multiply","pos_x":-200,"pos_y":100}]' --connections '[]'

Inspect material properties, parameters, textures

Returns material metadata including blend mode, shading model, and optionally parameters, textures, and shader statistics. Use the include flag to control which sections are returned.

  cfa get_material_info --material-path /Game/Materials/M_Test
  cfa get_material_info --material-path /Game/Materials/M_Test --include parameters,textures,statistics

Bulk-set material properties

Sets one or more material-level properties such as blend mode, shading model, or two-sided in a single call. Recompiles the material by default after changes. Call save_asset after.

  cfa set_material_properties --material-path /Game/Materials/M_Test --blend-mode masked --two-sided true
  cfa set_material_properties --material-path /Game/Materials/M_Test --shading-model unlit --recompile false

Force recompile and save

Forces a recompilation of the material shader and saves the asset. Use after making manual changes to the graph or when the material appears out of date.

  cfa recompile_material --material-path /Game/Materials/M_Test

Apply edits to the asset (clicks the editor's Apply button)

Commits a material's pending edits to the original asset, the exact code path of clicking the Material Editor's Apply button. When the editor is open the edits live on a transient preview copy; this runs the real Apply command so the preview is copied back onto the asset, shaders recompile, and the Apply button disables itself. When the editor is closed it recompiles the asset directly. Apply is expensive, so call it ONCE when the material is complete (after building, validating and recompiling), not after every edit. Returns editor_was_open plus the post-apply compile errors in place: has_errors, error_count, errors[] (each with message, quality_level, platforms) and error_nodes[] when specific nodes can be blamed. If the editor is open and the material has compile errors, the real Apply would pop a blocking Continue/Abort modal, so the commit is skipped (applied=false, blocked_by_compile_errors=true) and the errors are returned instead; fix them and apply again. A clean material or a closed editor commits normally (applied=true). The standalone get_material_errors command returns the same error fields on demand.

  cfa apply_material --material-path /Game/Materials/M_Test

Get material compilation errors

Returns any compilation errors for the material. By default recompiles first to get fresh errors. Use this to diagnose broken material graphs before fixing them.

  cfa get_material_errors --material-path /Game/Materials/M_Test
  cfa get_material_errors --material-path /Game/Materials/M_Test --recompile false

Add comment boxes to material graph

Adds one or more comment boxes to a material graph for visual organization. Each comment has a position, size, text, and optional color. Call save_asset after.

  cfa add_material_comments --material-path /Game/Materials/M_Test --comments '[{"text":"Base Color Setup","pos_x":-500,"pos_y":-200,"size_x":400,"size_y":300}]'

Read graph nodes with verbosity control

Returns all expression nodes in a material graph. Use verbosity to control detail: 'summary' for node list, 'connections' for wiring info, 'full' for all properties. Use type_filter to narrow results to specific node types.

  cfa get_material_graph_nodes --material-path /Game/Materials/M_Test
  cfa get_material_graph_nodes --material-path /Game/Materials/M_Test --verbosity full --type-filter TextureSample

Inspect one material expression node with its available pins

Returns full detail for a single material expression node identified by node_index: its type, properties, and every available input/output pin. Use get_material_graph_nodes first to find the node_index. This is the per-node companion to get_material_graph_nodes.

  cfa get_material_expression_info --material-path /Game/Materials/M_Test --node-index 3

Show which material outputs (BaseColor, etc.) are connected

Returns the connection status of each top-level material output property (Base Color, Metallic, Roughness, Emissive, Normal, and more), reporting which expression node feeds each one. Use this to see how a material graph wires into the final material outputs.

  cfa get_material_property_connections --material-path /Game/Materials/M_Test

Add a material expression node

Adds a single expression node to a material graph. The node definition is a JSON object with type, position, and optional properties. Use build_material_graph instead when creating multiple nodes at once. Call save_asset after.

  cfa add_material_expression --material-path /Game/Materials/M_Test --node '{"type":"Constant3Vector","pos_x":-400,"pos_y":0,"properties":{"Constant":"(R=0.5,G=0.5,B=1.0)"}}'
  cfa add_material_expression --material-path /Game/Materials/M_Test --node '{"type":"TextureSample","pos_x":-600,"pos_y":0}'

Connect two material expression nodes

Wires an output pin of one node to an input pin of another node or the material output. Use to_node 'material' to connect to material-level pins (BaseColor, Normal, etc.). Call save_asset after.

  cfa connect_material_expressions --material-path /Game/Materials/M_Test --from-node 0 --to-node material --to-pin BaseColor
  cfa connect_material_expressions --material-path /Game/Materials/M_Test --from-node 0 --from-pin RGB --to-node 1 --to-pin A

Delete a material expression by index

Removes a single expression node from the material graph by its index. Note that deleting a node shifts indices of subsequent nodes. Call save_asset after.

  cfa delete_material_expression --material-path /Game/Materials/M_Test --node-index 3

Set a property on a material expression

Sets a single property on a material expression node identified by index. Use get_expression_type_info to discover available properties for a node type. Call save_asset after.

  cfa set_material_expression_property --material-path /Game/Materials/M_Test --node-index 0 --property-name Constant --property-value "(R=1,G=0,B=0)"
  cfa set_material_expression_property --material-path /Game/Materials/M_Test --node-index 2 --property-name R --property-value 0.5

Move a material expression node

Repositions a material expression node in the graph editor to the specified X/Y coordinates. Use this to organize graph layout. Call save_asset after.

  cfa move_material_expression --material-path /Game/Materials/M_Test --node-index 0 --pos-x -400 --pos-y 200

Duplicate a material expression

Creates a copy of an existing material expression node at an offset position. The new node has the same type and properties but no connections. Call save_asset after.

  cfa duplicate_material_expression --material-path /Game/Materials/M_Test --node-index 0
  cfa duplicate_material_expression --material-path /Game/Materials/M_Test --node-index 0 --offset-x 200 --offset-y 200

Auto-layout the material graph (data-flow, right-to-left)

Repositions every expression node into clean right-to-left data-flow columns: nodes are measured from their real Slate widgets, layered by longest path to the output sink, pin-aligned to the consumers they feed, and stacked to avoid overlap. The root output node, comments and reroutes keep their positions. Works with the material editor open or closed. Call save_asset after (or apply_material when the editor is open).

  cfa layout_material_graph --material-path /Game/Materials/M_Test

Auto-layout all material expressions (alias of layout_material_graph)

Alias of layout_material_graph: repositions all expression nodes into clean right-to-left data-flow columns (Slate-measured sizes, pin alignment, collision-free). Call save_asset after.

  cfa layout_material_expressions --material-path /Game/Materials/M_Test

Auto-layout a Material Function graph (data-flow, right-to-left)

Same right-to-left data-flow auto-layout as layout_material_graph, but for a Material Function (or layer/blend function) graph: nodes are Slate-measured, layered by longest path to the FunctionOutput sinks, pin-aligned and collision-free. Works open or closed. Call save_asset after.

  cfa layout_material_function_graph --function-path /Game/Materials/Functions/MF_Test

Get all parameters of a material instance

Returns all scalar, vector, and texture parameters of a material instance, including both overridden values and inherited defaults from the parent material.

  cfa get_material_instance_parameters --material-path /Game/Materials/MI_Red

Set a parameter on a material instance

Sets a single parameter override on a material instance. param_type: scalar, vector, texture, static_switch, component_mask, rvt (runtime virtual texture), or sparse_volume_texture. For component_mask, value is a channel mask: [r,g,b,a] bool array, "1,1,0,0", or letters like "rgb". For rvt/sparse_volume_texture, value is the texture asset path. Call save_asset after.

  cfa set_material_instance_parameter --material-path /Game/Materials/MI_Red --param-name Roughness --param-type scalar --value 0.8
  cfa set_material_instance_parameter --material-path /Game/Materials/MI_Red --param-name BaseColor --param-type vector --value "(R=1,G=0,B=0,A=1)"
  cfa set_material_instance_parameter --material-path /Game/Materials/MI_Red --param-name MaskRGB --param-type component_mask --value rgb
  cfa set_material_instance_parameter --material-path /Game/Materials/MI_Red --param-name RVT --param-type rvt --value /Game/VT/RVT_Height

Reparent a material instance

Changes the parent Material (or Material Instance) of a Material Instance Constant. Overrides for parameters that do not exist on the new parent are dropped by the engine. Rejects self-parenting and cycles. Call save_asset after.

  cfa set_material_instance_parent --material-path /Game/Materials/MI_Red --parent-path /Game/Materials/M_NewBase

Clear a parameter override (revert to parent)

Removes a dynamic parameter override (scalar, vector, texture, rvt, sparse volume texture, font) from a Material Instance Constant so it reverts to the parent's value. Returns overrides_removed. Static switch / component-mask overrides are not reverted by this command. Call save_asset after.

  cfa clear_material_instance_parameter --material-path /Game/Materials/MI_Red --param-name Roughness

List available material expression types

Lists all available material expression node types that can be used in material graphs. Use filter to narrow results by name. Returns type names and optionally details about each type.

  cfa list_material_expression_types --filter Texture --max-results 20
  cfa list_material_expression_types --include-details false

Look up pins & properties for a node type

Returns the input/output pins and configurable properties for a material expression type without creating a node. For Custom HLSL nodes, returns the custom_hlsl_schema with code/inputs/outputs documentation. For MaterialFunctionCall, pass function_path to see the function's actual pins.

  cfa get_expression_type_info --type-name Multiply
  cfa get_expression_type_info --type-name Custom
  cfa get_expression_type_info --type-name MaterialFunctionCall --function-path /Engine/Functions/Engine_MaterialFunctions03/Blends/Blend_Overlay
  cfa get_expression_type_info --type-name SubstrateSlabBSDF

Query available material output pins

Returns all available material output pins for a specific material, based on its current settings (blend mode, shading model, Substrate). Reports each pin's name, expected type, connection status, and Substrate state. Use this to discover valid to_pin values for connect_material_expressions with to_node=material.

  cfa get_available_material_pins --material-path /Game/Materials/M_Test

Disconnect a specific input pin

Breaks the connection to a specific input pin on a material expression node. The node and its other connections remain intact. Call save_asset after.

  cfa disconnect_material_expression --material-path /Game/Materials/M_Test --node-index 2 --input-pin A

Find Material Functions by name

Searches for Material Function assets by name. Use include_engine to also search engine-provided functions. Returns asset paths that can be used as MaterialFunctionCall nodes in material graphs.

  cfa search_material_functions --filter Fresnel
  cfa search_material_functions --filter Blend --include-engine true --max-results 10

Diagnose orphaned, dead-end, and unconnected nodes

Analyzes a material graph and reports orphaned nodes (no connections), dead-end nodes (output not connected to anything), and other structural issues. Use before cleanup_material_graph to preview problems.

  cfa validate_material_graph --material-path /Game/Materials/M_Test

Trace upstream/downstream from a node

Recursively traces connections from a node upstream (toward inputs), downstream (toward material output), or both. Use max_depth to control how far to trace. Helpful for understanding data flow in complex graphs.

  cfa trace_material_connection --material-path /Game/Materials/M_Test --node-index 3 --direction upstream --max-depth 5
  cfa trace_material_connection --material-path /Game/Materials/M_Test --node-index 0 --direction both

Delete orphaned/dead-end nodes

Removes orphaned or dead-end nodes from a material graph. Use dry_run to preview what would be deleted without making changes. Mode controls which nodes to target: orphaned (no connections), dead_ends (output unused), or all. Call save_asset after.

  cfa cleanup_material_graph --material-path /Game/Materials/M_Test --dry-run true
  cfa cleanup_material_graph --material-path /Game/Materials/M_Test --mode all

Create a new Material Function asset

Creates a new Material Function asset that can be reused across multiple materials via MaterialFunctionCall nodes. The function is created with one default output node (reported as default_output {node_index,node_guid,name}) so it is always compilable and deterministic, the same node the Unreal editor would inject on first open. Set expose_to_library to make it appear in the material editor function list. Call save_asset after.

  cfa create_material_function --name MF_CustomBlend --path /Game/Materials/Functions --description "Custom blend utility"
  cfa create_material_function --name MF_Helper --expose-to-library false

Create a Material Function Instance

Creates a UMaterialFunctionInstance asset from a parent Material Function, letting you reuse a function with overridden parameters. Set overrides with set_material_function_instance_parameter. Returns error if it exists (pass force=true to reuse). Call save_asset after.

  cfa create_material_function_instance --name MFI_RedTint --parent-path /Game/Materials/Functions/MF_Tint --path /Game/Materials/Functions

Override a parameter on a Material Function Instance

Sets a scalar, vector, or static_switch override on a Material Function Instance. The override is keyed to the parent parameter's ExpressionGUID so it actually applies at compile; a name the parent function does not expose is rejected. Call save_asset after.

  cfa set_material_function_instance_parameter --instance-path /Game/Materials/Functions/MFI_RedTint --param-name TintColor --param-type vector --value "(R=1,G=0,B=0,A=1)"
  cfa set_material_function_instance_parameter --instance-path /Game/Materials/Functions/MFI_RedTint --param-name Strength --param-type scalar --value 0.7

Read overrides on a Material Function Instance

Returns the parent/base function and the scalar, vector, and static_switch parameter overrides currently set on a Material Function Instance.

  cfa get_material_function_instance_parameters --instance-path /Game/Materials/Functions/MFI_RedTint

Set the material attribute layer stack (base or instance)

Sets a Material Attribute Layers stack. On a base Material it makes the material layered (enables bUseMaterialAttributes, adds a MaterialAttributeLayers node wired to the attributes output) and stores the stack as the node default. On a Material Instance it overrides the inherited stack. layers[] are Material Layer function paths (layers[0] is the background); blends[] are Material Layer Blend function paths, one fewer than layers (blends[i] mixes layers[i+1]). For the material to compile, the functions must have usage MaterialLayer / MaterialLayerBlend (create them with create_material_function function_type=layer|blend). An empty string or "none" leaves a slot empty. Call save_asset after.

  cfa set_material_layers --material-path /Game/Materials/M_Layered --layers '["/Game/ML/ML_Rock","/Game/ML/ML_Moss"]' --blends '["/Game/ML/MatLayerBlend_Height"]'

Read the material attribute layer stack

Returns the layer stack of a base Material (the MaterialAttributeLayers node default) or a Material Instance (the effective/overridden stack): each entry's layer function, blend function, enabled flag, and name.

  cfa get_material_layers --material-path /Game/Materials/MI_Layered

Inspect a Material Function

Returns the inputs, outputs, and (per verbosity) internal expression nodes of a Material Function. verbosity=interface returns only the pin interface, usually all you need before calling the function from a material graph; summary adds node counts by type; full (default) adds the other_nodes list, optionally narrowed with type_filter.

  cfa get_material_function_info --function-path /Game/Materials/Functions/MF_CustomBlend --verbosity interface
  cfa get_material_function_info --function-path /Game/MF/MF_Noise --verbosity full --type-filter Texture

Build complete MF node graph in one call

Builds an entire Material Function node graph, similar to build_material_graph but for functions. All node types are validated BEFORE the existing graph is touched, so a typo can never destroy the function. With the MF editor closed (the normal case) the build runs synchronously and returns nodes_created / connections_made / errors; with the editor open it defers across ~5 engine ticks (deferred=true, errors logged) to avoid crashing on stale preview state. Connections resolve to_node/from_node as node indices OR the aliases "output" / "output:Name" (a FunctionOutput) and "input:Name" (a FunctionInput). If the nodes array contains no FunctionOutput, a default output is auto-created and reported as auto_created_output, wire it with to_node="output". Clears existing expressions by default.

  cfa build_material_function_graph --function-path /Game/MF/MF_Fade --nodes '[{"type":"FunctionInput","input_name":"Alpha","input_type":"Scalar"},{"type":"OneMinus"}]' --connections '[{"from_node":0,"to_node":1},{"from_node":1,"to_node":"output"}]'

Add a FunctionInput pin

Adds an input pin to a Material Function. The input type can be Scalar, Vector2, Vector3, Vector4, Texture2D, TextureCube, StaticBool, Bool, or MaterialAttributes. Set sort_priority to control pin ordering. Call save_asset after.

  cfa add_material_function_input --function-path /Game/Materials/Functions/MF_Blend --input-name BaseColor --input-type Vector3
  cfa add_material_function_input --function-path /Game/Materials/Functions/MF_Blend --input-name Strength --input-type Scalar --preview-value 1.0 --use-preview-as-default true

Add a FunctionOutput pin

Adds an output pin to a Material Function. The output receives its type from whatever expression is connected to it. Set sort_priority to control pin ordering when the function has multiple outputs. Call save_asset after.

  cfa add_material_function_output --function-path /Game/Materials/Functions/MF_Blend --output-name Result
  cfa add_material_function_output --function-path /Game/Materials/Functions/MF_Blend --output-name Alpha --sort-priority 1 --pos-y 200

Modify an existing FunctionInput

Modifies properties of an existing FunctionInput node in a Material Function, identified by node_index. You can change the name, type, description, preview value, and sort priority. Call save_asset after.

  cfa set_material_function_input --function-path /Game/Materials/Functions/MF_Blend --node-index 0 --input-name Opacity --input-type Scalar
  cfa set_material_function_input --function-path /Game/Materials/Functions/MF_Blend --node-index 1 --preview-value 0.5 --use-preview-as-default true

Modify an existing FunctionOutput

Modifies properties of an existing FunctionOutput node in a Material Function, identified by node_index. You can change the name, description, and sort priority. Call save_asset after.

  cfa set_material_function_output --function-path /Game/Materials/Functions/MF_Blend --node-index 2 --output-name BlendedColor
  cfa set_material_function_output --function-path /Game/Materials/Functions/MF_Blend --node-index 2 --description "Final blended output" --sort-priority 0

Validate a Material Function

Checks a Material Function for structural issues such as missing inputs/outputs, orphaned nodes, and broken connections. Use this to verify a function is well-formed before using it in materials.

  cfa validate_material_function --function-path /Game/Materials/Functions/MF_Blend

Cleanup orphaned nodes in a Material Function

Removes orphaned nodes from a Material Function graph. Use dry_run to preview which nodes would be deleted without making changes. Call save_asset after.

  cfa cleanup_material_function --function-path /Game/Materials/Functions/MF_Blend --dry-run true
  cfa cleanup_material_function --function-path /Game/Materials/Functions/MF_Blend

Create a Material Parameter Collection

Creates a new UMaterialParameterCollection asset, a global table of scalar/vector parameters that any material can reference via a CollectionParameter node. Returns error if it exists (pass force=true to clear and reuse). Add entries with set_material_parameter_collection_parameter. Call save_asset after.

  cfa create_material_parameter_collection --name MPC_Global --path /Game/Materials

Add or update an MPC scalar/vector entry

Adds a new parameter to a Material Parameter Collection, or updates its default value if it already exists. param_type is scalar or vector. New entries get a unique Id automatically. Returns created=true when a new entry was added. Call save_asset after.

  cfa set_material_parameter_collection_parameter --collection-path /Game/Materials/MPC_Global --param-name TimeScale --param-type scalar --value 1.5
  cfa set_material_parameter_collection_parameter --collection-path /Game/Materials/MPC_Global --param-name WindColor --param-type vector --value "(R=0.2,G=0.4,B=1,A=1)"

List all entries of a Material Parameter Collection

Returns all scalar and vector parameters in a Material Parameter Collection, each with its name, default value, and stable Id.

  cfa get_material_parameter_collection --collection-path /Game/Materials/MPC_Global

Remove an entry from a Material Parameter Collection

Removes a scalar or vector parameter from a Material Parameter Collection by name. Returns removed count. Call save_asset after.

  cfa delete_material_parameter_collection_parameter --collection-path /Game/Materials/MPC_Global --param-name TimeScale