add_graph_node
Creates a single node in a Blueprint, material, MetaSound, PCG, or Control Rig graph and returns its node ID and pins so you can wire it immediately.
Instructions
Create one node in a graph and return it with its node_id and pins, so connect_pins and set_pin_default_value can wire it without another read.
Works in a Blueprint graph (Animation and Widget Blueprints included) and in the graph of a material, material function, sound cue, MetaSound Source, PCG graph or Control Rig. To create and wire several Blueprint nodes in one undo step use build_blueprint_graph. Every call adds a new node, except event and custom_event, which give back the one already there; remove_graph_node takes a spare node out.
Each value comes from a read: event_name from list_overridable_functions, function_name from get_class_functions (an engine library's list is long enough to come back as a file: get_mcp_audit_report reads its report_path), variable_name from get_blueprint_variables, struct_type from list_structs, enum_path from list_enums, and graph_name from get_blueprint_functions; get_function_pins previews a node's pins before it exists. When a call_function names both, function_library wins over target_class, and node_position wins over position_x and position_y. node_type keywords ignore case. Example: {"asset_path": "/Game/Blueprints/BP_Door", "node_type": "call_function", "function_name": "PrintString", "function_library": "KismetSystemLibrary"}.
In another asset, node_type is its editor's own node: a material expression class (/Script/Engine.MaterialExpressionConstant), a sound node type (WavePlayer with sound_wave_path, Mixer, Random...), a MetaSound class path from list_metasound_node_types (UE.Sine.Audio, with major_version), a PCG settings class from list_pcg_node_types (PCGSubgraphSettings with subgraph_path embeds a graph), or a Control Rig unit (SetTransform, TwoBoneIKSimple..., with node_name). Those assets are saved by their editor, and a Control Rig is compiled.
A Blueprint is compiled only with compile=true and never saved, and the call is refused during Play-in-Editor (see force). event creates a real override, finding the interface or parent class itself; a name that is not an overridable event is an error, and an interface function with a return value needs add_blueprint_function with override=true. custom_event takes no parameters, so an RPC or anything with arguments must be a function. get_component_by_class makes a node already typed to target_class, so its ReturnValue connects without a cast. Check class in the reply: an async or latent node that comes back as K2Node_CallFunction does nothing, though it compiles clean.
Returns: { node_id, class, title, pos_x, pos_y, comment, pins: [{ name, direction, type, linked_to, default }], blueprint_name, graph_name, compiled, plus the fields of its node_type } -- event: event_name, is_override (true for a live override), already_exists; custom_event: event_name, node_title, already_existed; cast: cast_to; call_function: function_library, function; make_struct and break_struct: struct_type; select: index_pin, return_value_pin, option_pins, option_count, index_enum; macro_instance: input_pins, output_pins; get_component_by_class: component_class, return_pin_type (when it does not name the class, the pin stayed generic).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cases | No | Optional string array of case pins for switch_int/switch_string/switch_name | |
| force | No | Optional. This command is REFUSED while a Play-in-Editor session is running: it either compiles a Blueprint (the reinstancer can retain a world, and CheckForWorldGCLeaks is Fatal -- it KILLS the editor) or writes to disk (Editor.AllowSavingAssetsDuringPIE=0 makes the engine refuse the write, so it would report success without writing a byte). Stop PIE and retry instead; force=true runs it anyway, at your own risk. | |
| scope | No | Optional scope hint for variable_get/variable_set: 'auto' (default; a function-local variable declared in the target graph wins, else a self/member variable), 'local' (function-local variable ONLY), or 'member' (member variable only -- self, or on target_class when supplied). Ignored by other node types. | |
| compile | No | Optional bool, default false: compile the Blueprint after placing the node. Ignored inside build_blueprint_graph, which never compiles its steps. | |
| arguments | No | Optional string array of argument names for format_text | |
| enum_path | No | Enum path or name; required for switch_enum and enum_literal nodes. Optional for select: the enum then drives the Index pin and one option pin is generated per enum entry. | |
| node_name | No | Control Rig only: the name to give the node (a taken name gets a suffix; the reply's node_id is the real one). | |
| node_type | Yes | In a Blueprint, one of event, custom_event, call_function, print_string, variable_get, variable_set, branch, sequence, self, cast, spawn_actor (alias spawn_actor_from_class), create_widget, make_struct, break_struct, get_array_item, select, make_array, make_set, make_map, switch_int, switch_string, switch_name, switch_enum, enum_literal, format_text, foreach, foreach_with_break, do_once, gate, flipflop, for_loop, while_loop, is_valid, add_delegate, macro_instance, get_component_by_class, or a graph node class (AnimGraphNode_Slot, /Script/AnimGraph.AnimGraphNode_SequencePlayer); for another asset, see the description | |
| asset_path | No | The graph asset: a Blueprint by name (resolved under /Game/Blueprints) or full path, or the path of a material, material function, sound cue, MetaSound Source, PCG graph or Control Rig. Pass the FULL path when a Blueprint short name is ambiguous: a bare name that matches two assets resolves to one of them silently. | |
| dispatcher | No | Event-dispatcher (multicast delegate) name; required for add_delegate node type. Must already exist in the COMPILED class (add_event_dispatcher + compile_blueprint), and it binds on self only -- for a dispatcher on another class use add_object_bound_event. | |
| event_name | No | Event name; required for event and custom_event node types (e.g. "ReceiveActorBeginOverlap", "ReceiveBeginPlay" for event) | |
| graph_name | No | Target graph name; defaults to the Blueprint's event graph when omitted | |
| index_type | No | Optional alias of enum_path for node_type=select. | |
| num_inputs | No | Optional input-pin count for make_array/make_set/make_map (added after spawn) | |
| position_x | No | Node X position on the graph canvas (ignored when node_position is set) | |
| position_y | No | Node Y position on the graph canvas (ignored when node_position is set) | |
| struct_type | No | Struct type; required for make_struct and break_struct nodes: a UScriptStruct path (/Game/.../S_Foo.S_Foo), bare name, or engine alias (Vector/Rotator/Transform...) | |
| macro_source | No | Set to "standard_macros" to skip this Blueprint's own MacroGraphs and resolve macro_graph_name only in the engine StandardMacros library. Only read for node_type=macro_instance. | |
| option_count | No | Optional, select only: total number of option pins to end up with (default the built-in 2; ignored when an enum drives the index). | |
| target_class | No | Class owning the function or cast/spawn target class; required for cast, create_widget and get_component_by_class. For call_function it is searched STRICTLY: a function that is not on that class is an error, never a silent fallback to another library; it also resolves a user BlueprintFunctionLibrary by asset path ("/Game/Dir/BFL_X"). For get_component_by_class it is the component class to fetch (a UActorComponent subclass). For variable_get/variable_set it names the class that owns the variable, producing a non-self member-access node (with a 'target' pin) instead of a self-context node. For create_widget it names the widget class to construct (e.g. WBP_Foo_C, a full asset path, or the widget Blueprint short name); the node exposes that widget's Expose-On-Spawn pins. | |
| function_name | No | Function to call; required for call_function node type | |
| macro_library | No | Optional, macro_instance only: asset path of a macro LIBRARY Blueprint to resolve macro_graph_name in -- the only way to reach a third-party or project macro library. | |
| major_version | No | MetaSound only: the node class's major version (default 1), as list_metasound_node_types gives it. | |
| node_position | No | Node canvas position as [x, y]; takes precedence over position_x/position_y | |
| subgraph_path | No | PCG only, with node_type=PCGSubgraphSettings: the PCG graph to embed. | |
| variable_name | No | Variable to get/set; required for variable_get and variable_set | |
| blueprint_name | No | Older name of asset_path, still accepted. | |
| blueprint_path | No | Alias of `blueprint_name` (same value, same meaning). Accepted because sibling tools spell this parameter differently; prefer `blueprint_name`. | |
| sound_wave_path | No | Sound cue, WavePlayer only: the sound wave it plays. | |
| function_library | No | Optional, call_function only: the library class owning function_name, used instead of target_class -- an engine library by name ("KismetMathLibrary", "KismetSystemLibrary", "GameplayStatics", "KismetStringLibrary", with or without the U prefix, or any /Script/Engine class) or a user BlueprintFunctionLibrary asset path ("/Game/Dir/BFL_X", "/Game/Dir/BFL_X.BFL_X" or the "..._C" class). Searched strictly, like target_class. | |
| macro_graph_name | No | Macro graph name; required for node_type=macro_instance. Resolved against this Blueprint's own MacroGraphs first, then the engine StandardMacros; "<library-path>:<MacroGraphName>" (e.g. "/Game/Lib/ML_X.ML_X:MyMacro") resolves it in that macro library instead. |