build_blueprint_graph
Build multiple Blueprint nodes, wire their pins, and set pin defaults in one undo transaction, avoiding create-connect round-trips.
Instructions
Build several nodes, wire their pins, and set pin defaults in one pass, wrapped in a single undo transaction -- the way to author a whole graph shape without create -> get_graph_nodes -> connect round-trips (get_function_pins gives you the pin names up front). THE ORDER IS FIXED AND MATTERS: every node first, then ALL connections, then pin_defaults -- so a node whose TYPE depends on a pin default (a generic GetComponentByClass) is connected while still untyped, fails with "... is not compatible with ..." and, under stop_on_error's default true, takes the whole call down; use add_get_component_by_class_node, which is born typed. add_comment_node has no pins at all, so a pin_defaults entry aimed at one also kills the batch. Self-contained: each sub-step runs its command directly, never through the bridge (only these: add_graph_node, add_custom_event_node, add_timeline_to_blueprint, add_cast_node, add_branch_node, add_sequence_node, add_component_bound_event, add_input_action_event_node, add_enhanced_input_action_node, add_actor_begin_overlap_event, add_call_library_function, add_reroute_node, add_comment_node, add_select_node, add_make_struct_node, add_break_struct_node, add_parent_call_node, add_get_component_by_class_node, add_broadcast_node, add_object_bound_event, add_macro_instance_node). add_component_event is NOT usable here; create it with its own call.
Returns: { blueprint_name, graph_name, nodes: [{index, id, command_type, ok, node_id?, custom_event_node_id?, error?}], connections: [{index, ok, error?}], pin_defaults: [{index, ok, error?}], stopped_early, rollback_required, rolled_back, transaction_opened, undo_queue_len_before, undo_queue_len_after, top_transaction_title, rollback_refused_reason?, warning? }. rolled_back reports whether the undo ACTUALLY ran, not the intention: the rollback is refused (rolled_back:false + rollback_refused_reason + warning) whenever the top of the editor's undo stack is not this call's own transaction, because GEditor->UndoTransaction is global and would otherwise revert another agent's or another session's work in memory while the disk stays clean. A payload that fails pre-validation returns instead { success:false, error, validation_errors: [{section, index, id?, error}], transaction_opened:false, blueprint_name, graph_name } and never opens a transaction.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| nodes | Yes | [{id: string, command_type: string, params?: object}, ...] (required, non-empty). 'id' is a caller-chosen local key used to reference the node from 'connections'/'pin_defaults'; 'params' is that command's own param object (blueprint_name/graph_name are auto-filled if omitted). WORKED EXAMPLE (print "hi" on BeginPlay, one call): nodes=[{"id":"beg","command_type":"add_graph_node","params":{"node_type":"event","event_name":"ReceiveBeginPlay"}},{"id":"print","command_type":"add_graph_node","params":{"node_type":"print_string"}}], connections=[{"from_node":"beg","from_pin":"then","to_node":"print","to_pin":"execute"}], pin_defaults=[{"node":"print","pin":"InString","value":"hi"}]. Pin names for a call_function node are knowable up front via get_function_pins (so no create->get_graph_nodes->connect round-trips). Child-override canonical shape (call the parent first), one call: nodes=[{"id":"evt","command_type":"add_graph_node","params":{"node_type":"event","event_name":"ReceiveBeginPlay"}},{"id":"super","command_type":"add_parent_call_node","params":{"function_name":"ReceiveBeginPlay"}}], connections=[{"from_node":"evt","from_pin":"then","to_node":"super","to_pin":"execute"}]. NOTE on add_object_bound_event: it creates TWO nodes; the step's local 'id' resolves to the UK2Node_AddDelegate (wire the external instance into its 'self' pin and the exec flow into 'execute'), while the handler custom event is addressable as "<id>.custom_event" and its real NodeGuid is echoed back as custom_event_node_id. | |
| graph_name | No | Target graph name; defaults to the Blueprint's event graph when omitted | |
| connections | No | [{from_node, from_pin, to_node, to_pin}, ...]; from_node/to_node may be a local 'id' from 'nodes' (or "<id>.custom_event" for an add_object_bound_event step's handler event) or a pre-existing real NodeGuid. | |
| pin_defaults | No | [{node, pin, value}, ...]; node may be a local 'id' from 'nodes' (or "<id>.custom_event") or a pre-existing real NodeGuid. | |
| stop_on_error | No | Stop (and try to roll back the whole transaction) on the first failing step; defaults to true, unlike batch's default false, since connections/pin_defaults depend on earlier nodes existing. With stop_on_error:false there is NO rollback at all -- the editor's global undo is never touched, every step is attempted, and whatever half-built shape remains is cleaned up with delete_node/disconnect_pin. That is the safer mode when other work is live in the editor's undo buffer. | |
| blueprint_name | No | Blueprint name or path. | |
| blueprint_path | No | Alias of `blueprint_name` (same value, same meaning). Accepted because sibling tools spell this parameter differently; prefer `blueprint_name`. |