Blueprint Graphs

⚠️ disconnect_pin() Signature — 4 Args Only

disconnect_pin breaks all connections from a single named pin. Do not call it like connect_nodes (which takes 6 args):

# CORRECT — 4 args: path, graph, node_id, pin_name
unreal.BlueprintService.disconnect_pin(bp_path, "EventGraph", custom_event_id, "then")

# WRONG — 6 args crashes with "takes at most 4 arguments (6 given)"
# unreal.BlueprintService.disconnect_pin(bp_path, graph, src_id, src_pin, tgt_id, tgt_pin)

To remove a specific edge, disconnect the output pin on the source node (e.g. "then"). Because the other end is the only connection on that exec pin, the single-pin disconnect is equivalent to removing the edge.

⚠️ Property Name Gotchas

⚠️ discover_nodes() vs get_nodes_in_graph() — Different Object Types

get_nodes_in_graph() returns FBlueprintNodeInfo objects — these have node_title, node_id, pos_x, pos_y, node_type.

discover_nodes() returns FBlueprintNodeTypeInfo objects — these have display_name (NOT node_title), spawner_key, category, tooltip, is_pure, is_latent, keywords.

# get_nodes_in_graph — use node_title
nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, graph)
for n in nodes:
    print(n.node_title, n.node_id)  # node_title is correct here

# discover_nodes — use display_name (NOT node_title)
matches = unreal.BlueprintService.discover_nodes(bp_path, "Broadcast")
for m in matches:
    print(m.display_name, m.spawner_key)  # display_name, NOT node_title

Also: search discover_nodes by function name, not variable type. To find the Broadcast Delegate node for a StateTreeDelegate variable, search "Broadcast" — NOT "Dispatcher" or "StateTreeDelegate".

⚠️ Branch Node Pin Names

Use then and else, NOT true/false:

# WRONG
connect_nodes(path, func, branch_id, "true", target_id, "execute")

# CORRECT
connect_nodes(path, func, branch_id, "then", target_id, "execute")
connect_nodes(path, func, branch_id, "else", target_id, "execute")

⚠️ UE5.7 Uses Doubles for Math

⚠️ Compile Before Using Variables in Nodes

unreal.BlueprintService.add_variable(path, "Health", "float", "100.0")
unreal.BlueprintService.compile_blueprint(path)  # REQUIRED before adding nodes
unreal.BlueprintService.add_get_variable_node(path, func, "Health", x, y)

⚠️ Node IDs Are GUID Strings, Not Small Integers

Do not assume Blueprint nodes have numeric IDs like 0 or 1. get_nodes_in_graph() returns GUID strings in node.node_id.

nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, graph)
for node in nodes:
    print(node.node_id, node.node_title)

For function graphs, find nodes by node_type or node_title. For event-style overrides, find nodes by the display title Unreal shows in the graph, not by the raw override function name.

⚠️ Event-Style Overrides Use "EventGraph" — NOT the Function Name

When an override is event-style (void/latent functions like ReceiveTreeStart, ReceiveTick, ReceiveLatentEnterState, ReceiveStateCompleted), the event node lives inside "EventGraph". Do NOT use the function name as the graph name — that graph doesn't exist.

# WRONG — returns 0 nodes, creates nothing
nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, "ReceiveTreeStart")
node_id = unreal.BlueprintService.add_function_call_node(bp_path, "ReceiveTreeStart", ...)

# CORRECT — event-style overrides are in EventGraph
nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, "EventGraph")
node_id = unreal.BlueprintService.add_function_call_node(bp_path, "EventGraph", ...)

Common event-style overrides and their graph name → node title:

Only function-style overrides (non-void, like GetStaticDescription) create a separate function graph.

⚠️ Do Not Guess Blueprint Function Node Names

Blueprint display titles and internal UFunction names are often not the same.

Common examples:

If you do not already know the exact callable name, do not guess and do not batch multiple node creations into one shot. Use one of these two patterns:

1. discover_nodes() + create_node_by_key() for deterministic editor-style creation.
2. add_function_call_node() only after discovery, or when you already know the exact function name.

import unreal

bp_path = "/Game/StateTree/Tasks/STT_Chase"
graph = "EventGraph"

matches = unreal.BlueprintService.discover_nodes(bp_path, "Get Actor Location")
actor_get_location = next(
    node for node in matches
    if node.spawner_key.startswith("FUNC AActor::") or node.spawner_key.startswith("FUNC Actor::")
)

node_id = unreal.BlueprintService.create_node_by_key(
    bp_path, graph, actor_get_location.spawner_key, 400, 0)
assert node_id, actor_get_location.spawner_key

If a node-create call returns an empty ID, stop immediately. Re-read the graph, inspect the error output, and fix the lookup before creating anything else.

⚠️ Complex Graphs: Create and Verify One Node at a Time

For fragile graph work such as STT_* task Blueprints, timers, delegate workflows, or any graph being built from a screenshot:

1. Create one node.
2. Re-read the graph and confirm the returned GUID exists.
3. Read that node's pins.
4. Only then create the next node.
5. After all required nodes exist, connect one edge at a time and verify the new connection appears in get_connections().

Do not create 4-6 nodes in one tool call when some of them have unresolved function names. That makes cleanup harder and leaves duplicate nodes behind on retry.

⚠️ Recovery After a Failed Graph Attempt

If a graph-edit attempt fails partway through:

1. Call get_nodes_in_graph() and get_connections() to see the true post-failure state.
2. Remove orphaned nodes with delete_node().
3. Remove stale links with disconnect_pin().
4. Retry from a clean baseline.

Do not invent helper names like disconnect_all_pins(). Use the real APIs that exist.

Examples for StateTree task blueprints:

⚠️ Delay vs Set Timer by Event

When a user asks for a "timer" or "timed delay" in a Blueprint, use Set Timer by Event, NOT Delay:

The pattern for Set Timer by Event requires a Custom Event:

Important: after add_custom_event_node(...), immediately re-read the graph and re-find that callback by the returned node_id. Do not assume the title will be exactly the event name you passed in. Unreal can display custom event titles as multi-line labels such as OnTimerFinished + Custom Event.

Do not silently substitute a Create Event / Create Delegate node plus a separate function graph when the user asked for a Custom Event node or when the target graph should visibly contain the callback in EventGraph. A Create Event delegate can compile and still be the wrong implementation for the requested graph shape.

import unreal

bp_path = "/Game/MyBlueprint"
graph = "EventGraph"

# 1. Add Set Timer by Event node
timer_id = unreal.BlueprintService.add_function_call_node(
    bp_path, graph, "KismetSystemLibrary", "K2_SetTimerDelegate", 300, 0)

# 2. Set the Time pin
unreal.BlueprintService.set_node_pin_value(bp_path, graph, timer_id, "Time", "1.0")

# 3. Add a Custom Event node — this is the callback
custom_event_id = unreal.BlueprintService.add_custom_event_node(
    bp_path, graph, "OnTimerFinished", 300, 300)

# 4. Connect the Custom Event's delegate output to the timer's Delegate pin
unreal.BlueprintService.connect_nodes(
    bp_path, graph, custom_event_id, "OutputDelegate",
    timer_id, "Delegate")

# 5. Wire: EnterState → Set Timer by Event
unreal.BlueprintService.connect_nodes(
    bp_path, graph, enter_state_id, "then", timer_id, "execute")

# 6. Wire: Custom Event → Finish Task (or whatever follows)
unreal.BlueprintService.connect_nodes(
    bp_path, graph, custom_event_id, "then", finish_id, "execute")

⚠️ StateTree Task Timer Workflow: Always Discover Real Titles and Pins First

For STT_* Blueprint tasks, do not guess event titles or pin names. The stable pattern is:

1. override_function(bp, "ReceiveLatentEnterState")
2. get_nodes_in_graph(bp, "EventGraph") and locate the event by title Event EnterState
3. After add_custom_event_node(...), call get_nodes_in_graph() again and re-find the callback by the returned GUID
4. Treat the callback title as display-only evidence; custom event titles can be multi-line and should not be your primary lookup key
5. get_node_pins() on every newly created node
6. Wire using the actual pin names returned by the graph

Current UE 5.7 / VibeUE graph details for this workflow:

Success for this workflow also requires the callback node in EventGraph to be a real custom event node, typically K2Node_CustomEvent in a fresh node listing. K2Node_CreateDelegate is a different node type and should not be treated as equivalent when the requested outcome is a visible custom event callback in the graph.

import unreal

bp_path = "/Game/StateTree/STT_Rotate"
graph = "EventGraph"

unreal.BlueprintService.override_function(bp_path, "ReceiveLatentEnterState")

timer_id = unreal.BlueprintService.add_function_call_node(
    bp_path, graph, "KismetSystemLibrary", "K2_SetTimerDelegate", 520, 0)
custom_id = unreal.BlueprintService.add_custom_event_node(
    bp_path, graph, "OnTimerFinished", 0, 420)
finish_id = unreal.BlueprintService.add_function_call_node(
    bp_path, graph, "StateTreeTaskBlueprintBase", "FinishTask", 520, 420)

nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, graph)
enter_node = next((n for n in nodes if n.node_title == "Event EnterState"), None)
custom_node = next((n for n in nodes if n.node_id == custom_id), None)
assert enter_node, "Event EnterState not found"
assert custom_node, f"Custom event {custom_id} not found after create"

custom_pins = unreal.BlueprintService.get_node_pins(bp_path, graph, custom_node.node_id)
print("CUSTOM EVENT TITLE:", custom_node.node_title)
print("CUSTOM EVENT PINS:", [p.pin_name for p in custom_pins])

unreal.BlueprintService.set_node_pin_value(bp_path, graph, timer_id, "Time", "1.0")
unreal.BlueprintService.set_node_pin_value(bp_path, graph, timer_id, "bLooping", "false")
unreal.BlueprintService.set_node_pin_value(bp_path, graph, finish_id, "bSucceeded", "true")

assert unreal.BlueprintService.connect_nodes(bp_path, graph, enter_node.node_id, "then", timer_id, "execute")
assert unreal.BlueprintService.connect_nodes(bp_path, graph, custom_node.node_id, "OutputDelegate", timer_id, "Delegate")
assert unreal.BlueprintService.connect_nodes(bp_path, graph, custom_node.node_id, "then", finish_id, "execute")

Use add_create_event_node() only when you need a Create Event / Create Delegate node. For Set Timer by Event, a Custom Event node is the simpler callback source and matches the Blueprint editor workflow shown in screenshots.

If a previous attempt already inserted a Create Event node for this timer callback, treat that as the wrong graph shape when the request is for a custom event. Remove the wrong node, remove any stale callback function graph that only existed to support that delegate node, then create the real Custom Event node and verify it by node ID and node type.

⚠️ Verification Is Mandatory Before Claiming Success

After any graph edit, verify all three layers:

1. Connections: call get_connections() and confirm the exact expected wiring.
2. Pins: if a connection fails, call get_node_pins() and use the real pin names.
3. Compile: inspect compile_blueprint(...).success, num_errors, and errors.

For any node you claim you created, also re-read the graph with get_nodes_in_graph() and confirm that node actually exists in the graph after the edit. A returned node ID from a create call is not enough.

For Custom Event timer callbacks, verify both of these before wiring:

1. The returned GUID appears in a fresh get_nodes_in_graph() result.
2. get_node_pins() on that exact node shows the pins you intend to use, typically OutputDelegate and then for the callback path.

Also verify that the node type is the expected custom event form rather than K2Node_CreateDelegate.

result = unreal.BlueprintService.compile_blueprint(bp_path)
assert result.success, result.errors

nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, graph)
for node in nodes:
    print(f"NODE {node.node_id} {node.node_title}")

connections = unreal.BlueprintService.get_connections(bp_path, graph)
for conn in connections:
    print(f"{conn.source_node_title}.{conn.source_pin_name} -> {conn.target_node_title}.{conn.target_pin_name}")

unreal.EditorAssetLibrary.save_asset(bp_path)

Never print MODIFIED or describe the graph as complete until the expected connections are present and compile succeeds. Never describe a node as present until it appears in a fresh get_nodes_in_graph() result. Never treat compile success alone as proof that the graph matches the requested design.

Required Success Gate For Graph Edits

If you edit a graph, your success check must answer all of these from live asset data:

1. Which required node titles are present?
2. Which exact connection lines prove the intended wiring exists?
3. Did compile succeed with zero relevant errors?

If you cannot answer those three questions from tool output, the task is not complete yet.

For complex graph tasks, also answer these two questions before claiming completion:

4. Which node IDs were created successfully, one by one?
5. What cleanup was done after any failed intermediate attempt?

Common mistake: Using Delay when the user says "timer". Delay is a latent action that pauses the execution chain. Set Timer by Event is non-blocking and fires a separate event — this is critical for State Tree tasks, animation blueprints, and any actor that must keep ticking during the wait period.

Accessing Members of Another Blueprint (add_member_get_node)

Use add_member_get_node to read a property or component that belongs to another class (not the current Blueprint). This creates a getter node with a Target input pin.

Target (input) — the object reference (e.g. your BP_Cube variable output)
MemberName (output) — the property value (e.g. the CubeMesh component)

# Get the CubeMesh component from a "Cube" variable of type BP_Cube
mesh_id = unreal.BlueprintService.add_member_get_node(
    bp_path, graph, "BP_Cube_C", "CubeMesh", 400, 0)

# Connect: Cube (from validated get) -> Target of the member getter
unreal.BlueprintService.connect_nodes(bp_path, graph, val_get_id, "Cube", mesh_id, "self")
# Output pin name matches the member name: "CubeMesh"
unreal.BlueprintService.connect_nodes(bp_path, graph, mesh_id, "CubeMesh", next_id, "Target")

The TargetClass must be the generated class name (BP_Cube_C, not BP_Cube). The function resolves it via the same 3-step fallback as create_blueprint.

Validated Get Nodes (add_validated_get_node)

Use add_validated_get_node to create a Validated Get — a variable getter with execution pins that only continues on the valid path if the object reference is non-null.

Pin names produced:

import unreal

bp_path = "/Game/BP_MyActor"
graph = "EventGraph"

# Compile first so the variable type is resolved
unreal.BlueprintService.compile_blueprint(bp_path)

# Add BeginPlay + validated get + some function call
begin_id = unreal.BlueprintService.add_event_node(bp_path, graph, "ReceiveBeginPlay", 0, 0)
val_get_id = unreal.BlueprintService.add_validated_get_node(bp_path, graph, "MyObject", 300, 0)
call_id = unreal.BlueprintService.add_function_call_node(bp_path, graph, "MyObject", "SomeFunction", 700, 0)

# Execution flow: BeginPlay -> ValidatedGet (Is Valid path) -> SomeFunction
unreal.BlueprintService.connect_nodes(bp_path, graph, begin_id, "then", val_get_id, "execute")
unreal.BlueprintService.connect_nodes(bp_path, graph, val_get_id, "then", call_id, "execute")

# Data flow: MyObject output -> function Target
unreal.BlueprintService.connect_nodes(bp_path, graph, val_get_id, "MyObject", call_id, "self")

unreal.BlueprintService.compile_blueprint(bp_path)
unreal.EditorAssetLibrary.save_asset(bp_path)

Only Object/Actor reference variables support Validated Get (ValidatedObject variation). Primitive types (int, float, bool) produce a Branch-style impure get instead.

Workflows

Override a Parent Function (BlueprintImplementableEvent / BlueprintNativeEvent)

Use list_overridable_functions to discover what can be overridden, then override_function to create the graph. After that, use get_nodes_in_graph + set_node_pin_value to wire in return values.

import unreal

bp_path = "/Game/StateTree/STT_Rotate"

# Step 1: See all overridable functions and which are already overridden
funcs = unreal.BlueprintService.list_overridable_functions(bp_path)
for f in funcs:
    status = "OVERRIDDEN" if f.already_overridden else "available"
    print(f"{f.function_name} ({f.owner_class}) [{status}] -> {f.return_type}")
# ⚠️ UE Python strips `b` prefix: use `already_overridden` and `is_native_event` (not `b_already_overridden`)

# Step 2: Create the override graph (idempotent — safe to call even if already exists)
unreal.BlueprintService.override_function(bp_path, "GetStaticDescription")

# Step 3: Inspect the new graph — find the result node
nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, "GetStaticDescription")
result_node = next((n for n in nodes if "Result" in n.node_type), None)

# Step 4: Set the return value pin directly (for FText/FString returns use the pin name)
if result_node:
    unreal.BlueprintService.set_node_pin_value(bp_path, "GetStaticDescription", result_node.node_id, "ReturnValue", "Rotate Cube")

# Step 5: Compile and save
unreal.BlueprintService.compile_blueprint(bp_path)
unreal.EditorAssetLibrary.save_asset(bp_path)

⚠️ Event-style vs Function-style overrides

override_function automatically picks the right approach based on is_event_style:

Never call add_event_node manually for override functions — override_function handles it.

For event-style overrides, the visible node title is usually the friendly event name Unreal shows in the graph, such as Event EnterState, not the raw function name like ReceiveLatentEnterState.

⚠️ list_overridable_functions vs list_functions

Always call list_overridable_functions when the user asks "what functions can I override?" or "override the X function". Never guess function names — they are case-sensitive.

Create Function with Logic

import unreal

bp_path = "/Game/BP_Player"

# Create function with parameters
unreal.BlueprintService.create_function(bp_path, "TakeDamage", is_pure=False)
unreal.BlueprintService.add_function_input(bp_path, "TakeDamage", "Amount", "float", "0.0")
unreal.BlueprintService.add_function_output(bp_path, "TakeDamage", "NewHealth", "float")
unreal.BlueprintService.compile_blueprint(bp_path)

# Add nodes (entry=0, result=1)
get_health = unreal.BlueprintService.add_get_variable_node(bp_path, "TakeDamage", "Health", -400, -100)
subtract = unreal.BlueprintService.add_math_node(bp_path, "TakeDamage", "Subtract", "Float", -200, 0)
set_health = unreal.BlueprintService.add_set_variable_node(bp_path, "TakeDamage", "Health", 200, 0)

# Connect nodes
unreal.BlueprintService.connect_nodes(bp_path, "TakeDamage", 0, "then", set_health, "execute")
unreal.BlueprintService.compile_blueprint(bp_path)
unreal.EditorAssetLibrary.save_asset(bp_path)

Add Enhanced Input Action Node

Use add_input_action_node() to create an Enhanced Input Action event node in a Blueprint:

import unreal

bp_path = "/Game/BP_ThirdPersonCharacter"
ia_path = "/Game/Input/IA_Ragdoll"

# Create the Enhanced Input Action node
node_id = unreal.BlueprintService.add_input_action_node(bp_path, "EventGraph", ia_path, -800, 2500)

if node_id:
    # Connect to other nodes - Output pins are: Started, Ongoing, Triggered, Completed, Canceled
    set_physics = unreal.BlueprintService.add_function_call_node(bp_path, "EventGraph", "PrimitiveComponent", "SetSimulatePhysics", -400, 2500)
    unreal.BlueprintService.connect_nodes(bp_path, "EventGraph", node_id, "Started", set_physics, "execute")
    
    unreal.BlueprintService.compile_blueprint(bp_path)
    unreal.EditorAssetLibrary.save_asset(bp_path)

Important: The Input Action asset must exist first. Create it with InputService.create_action() if needed.

Node Layout Best Practices

Layout Constants

GRID_H = 200   # Horizontal spacing
GRID_V = 150   # Vertical spacing
DATA_ROW = -150  # Data getters above execution
EXEC_ROW = 0     # Main execution row

Execution Flow (Left to Right)

# Entry (0,0) → Branch (200,0) → SetVar (400,0) → Return (800,0)

Data Flow (Above Execution)

# Getters at Y=-150, math at Y=-75, execution at Y=0
get_health = add_get_variable_node(bp_path, func, "Health", 200, -150)
subtract = add_math_node(bp_path, func, "Subtract", "Float", 200, -75)
branch = add_branch_node(bp_path, func, 200, 0)

Branch Layout (True/False Paths)

# True path: Y=0 (same row)
# False path: Y=150 (offset down)
set_armor = add_set_variable_node(bp_path, func, "Armor", 400, 0)    # True
set_health = add_set_variable_node(bp_path, func, "Health", 400, 150)  # False

Reposition Entry/Result (CRITICAL)

Entry and Result nodes are stacked at (0,0) by default:

nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, func_name)
for node in nodes:
    if "FunctionEntry" in node.node_type:
        unreal.BlueprintService.set_node_position(bp_path, func_name, node.node_id, 0, 0)
    elif "FunctionResult" in node.node_type:
        unreal.BlueprintService.set_node_position(bp_path, func_name, node.node_id, 800, 0)

Common Function Call Classes

For add_function_call_node(path, graph, class, func, x, y):

• KismetMathLibrary — Math (Add_DoubleDouble, Multiply_DoubleDouble, Sin, Sqrt)
• KismetSystemLibrary — System (PrintString, Delay, K2_SetTimerDelegate)
• KismetStringLibrary — String (Concat_StrStr, MakeLiteralString, Contains)
• KismetArrayLibrary — Array operations (Array_Length, Array_Random, Array_Add, Array_Remove, Array_Clear)
• GameplayStatics — Game (GetPlayerController, SpawnActor)
• Actor — Actor functions, but discover the exact callable/spawner first for graph nodes like Get Actor Location and Set Actor Location
• PrimitiveComponent — Physics (SetSimulatePhysics)
• SceneComponent — Transform (AddRelativeRotation, SetRelativeLocation)

Array Operations

Array operations use wildcard pins — the TargetArray and element pins start with no type until a typed array is connected. The engine automatically propagates the array element type through all wildcard pins when you connect a typed array variable.

⚠️ Random Element From Array — Use Array_Random, NOT Manual Length+Random+Get

When you need a random element from an array, use Array_Random — a single node that returns a random item. Do NOT manually build Array_Length → RandomIntegerInRange → Array_Get. That pattern has 3 nodes, is harder to wire, and Array_Get is deprecated in UE5.

# CORRECT — single node, editor shows it as "Random Array Item"
arr_rand_id = unreal.BlueprintService.add_function_call_node(
    bp_path, "EventGraph", "KismetArrayLibrary", "Array_Random", 600, 200)
# Pins: TargetArray (in, wildcard), OutItem (out, wildcard), OutIndex (out, int)

# Or via build_graph:
{"ref": "rand", "type": "spawner_key", "params": {"key": "FUNC KismetArrayLibrary::Array_Random"}}

Available Array Functions (KismetArrayLibrary)

⚠️ Array Get — Use discover_nodes First

Array_Get is marked BlueprintInternalUseOnly and is replaced by the dedicated K2Node_GetArrayItem node in modern UE5. Do NOT try to call Array_Get directly.

To get an element from an array by index:

# 1. Discover the correct node key
result = unreal.BlueprintService.discover_nodes(bp_path, "MyFunction", "get array")
# Look for: "Get" with key "NODE K2Node_GetArrayItem"

# 2. Create the node
node_id = unreal.BlueprintService.create_node_by_key(bp_path, "MyFunction", "NODE K2Node_GetArrayItem", 400, 200)

Wildcard Pin Type Propagation

When you connect a typed array to an array function's TargetArray pin, the engine automatically resolves all wildcard pins on that node to the correct element type. This is handled by UK2Node_CallArrayFunction.

Pattern for array operations in build_graph:

result = unreal.BlueprintService.build_graph(bp_path, graph_name,
    nodes=[
        # Get the array variable
        {"ref": "get_arr", "type": "variable_get", "params": {"variable": "MyTargetPoints"}},
        # Get array length
        {"ref": "arr_len", "type": "spawner_key", "params": {"key": "FUNC KismetArrayLibrary::Array_Length"}},
        # Get random element
        {"ref": "arr_rand", "type": "spawner_key", "params": {"key": "FUNC KismetArrayLibrary::Array_Random"}},
    ],
    connections=[
        # Connect typed array to wildcard pins — type propagation happens automatically
        ["get_arr.MyTargetPoints", "arr_len.TargetArray"],
        ["get_arr.MyTargetPoints", "arr_rand.TargetArray"],
    ],
    auto_layout=True
)

Common Mistakes with Arrays

1. Using Array_Get directly → Deprecated, use NODE K2Node_GetArrayItem instead
2. Not connecting the typed array source first → Wildcard pins stay unresolved → compile error: "The type of Target Array is undetermined"
3. Guessing pin names → Always use get_node_pins() to verify pin names after node creation

Batch Graph Builder (build_graph)

When to Use

Use build_graph when you need to create 3+ nodes with connections in a single call. It is significantly faster and less error-prone than creating nodes one-at-a-time for complex graphs.

Use the individual add_*_node + connect_nodes methods when:

• You need to create 1-2 nodes
• You need to inspect pins between node creations
• The exact function name is uncertain (use discover_nodes first)

Node Types

Connection Format

Connections use "RefOrGUID.PinName" format: {"from_": "A.then", "to": "B.execute"}

⚠️ Key name is from_ (with underscore) because from is a Python reserved keyword. UE Python maps the C++ UPROPERTY From to from_.

The ref part can be either:

• A local ref from the Nodes array (e.g. "MkInst")
• An existing node GUID already in the graph (32-char hex string from get_nodes_in_graph())

This allows build_graph to wire new nodes to existing nodes in a single call:

# Mix local refs with existing GUIDs
existing_id = "EB9221E84DFFF609028F9DAA6267B654"  # from get_nodes_in_graph()
connections = [
    {"from_": f"{existing_id}.OutputPin", "to": "NewNode.InputPin"},  # existing → new
    {"from_": "NewNode.OutputPin", "to": "OtherNew.InputPin"},        # new → new
]

Pin aliases supported:

• execute / exec → first exec input pin
• then / output → first exec output pin
• value / result → first non-exec output pin
• True → then, False → else (Branch node)

Example: BeginPlay → PrintString

import unreal

bp_path = "/Game/BP_MyActor"

result = unreal.BlueprintService.build_graph(
    bp_path,
    "EventGraph",
    # Nodes
    [
        {"ref": "BP", "type": "event", "params": {"event": "ReceiveBeginPlay"}},
        {"ref": "Print", "type": "print_string", "params": {}},
    ],
    # Connections
    [
        {"from_": "BP.then", "to": "Print.execute"},
    ],
    # Pin defaults
    [
        {"node_ref": "Print", "pin_name": "InString", "value": "Hello World!"},
    ],
    True,  # auto-layout
    True   # compile after
)

print(f"Success: {result.b_success}")
print(f"Nodes: {result.nodes_created}/{result.nodes_created + result.nodes_failed}")
print(f"Connections: {result.connections_made}/{result.connections_made + result.connections_failed}")
if result.errors:
    for e in result.errors:
        print(f"  ERROR: {e}")

Example: Branch with Math

result = unreal.BlueprintService.build_graph(
    bp_path,
    "EventGraph",
    [
        {"ref": "BP", "type": "event", "params": {"event": "ReceiveBeginPlay"}},
        {"ref": "GetHP", "type": "variable_get", "params": {"variable": "Health"}},
        {"ref": "Cmp", "type": "comparison", "params": {"operation": "Less", "operand_type": "Double"}},
        {"ref": "Branch", "type": "branch", "params": {}},
        {"ref": "PrintLow", "type": "print_string", "params": {}},
        {"ref": "PrintOK", "type": "print_string", "params": {}},
    ],
    [
        {"from_": "BP.then", "to": "Branch.execute"},
        {"from_": "GetHP.Health", "to": "Cmp.A"},
        {"from_": "Cmp.ReturnValue", "to": "Branch.Condition"},
        {"from_": "Branch.then", "to": "PrintLow.execute"},
        {"from_": "Branch.else", "to": "PrintOK.execute"},
    ],
    [
        {"node_ref": "Cmp", "pin_name": "B", "value": "25.0"},
        {"node_ref": "PrintLow", "pin_name": "InString", "value": "Health is low!"},
        {"node_ref": "PrintOK", "pin_name": "InString", "value": "Health OK"},
    ],
    True, True
)

StateTreeDelegate Broadcast — Replace Finish Task with Broadcast Delegate

When a StateTree task Blueprint has a StateTreeDelegate variable (e.g. FinishRotatingDispatcher) and the user wants the custom event timer callback to broadcast that delegate instead of calling Finish Task, the graph must:

1. Disconnect CustomEvent.then → Finish Task.execute
2. Delete the Finish Task node
3. Discover the Broadcast Delegate spawner key (search "Broadcast")
4. Create a Broadcast Delegate node + a variable GET for the delegate
5. Connect CustomEvent.then → Broadcast.execute and GET.FinishRotatingDispatcher → Broadcast.Dispatcher

import unreal

bp_path = "/Game/StateTree/Tasks/STT_Rotate"
graph = "EventGraph"

# Step 1: Find node GUIDs
nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, graph)
custom_node = next((n for n in nodes if "CustomEvent" in n.node_type or "Custom Event" in n.node_title), None)
finish_node = next((n for n in nodes if "Finish Task" in n.node_title), None)
assert custom_node and finish_node, "Nodes not found"

# Step 2: Disconnect CustomEvent.then (correct: 4 args)
unreal.BlueprintService.disconnect_pin(bp_path, graph, custom_node.node_id, "then")

# Step 3: Delete Finish Task
unreal.BlueprintService.delete_node(bp_path, graph, finish_node.node_id)

# Step 4: Discover Broadcast Delegate node — search "Broadcast" NOT "Dispatcher"
matches = unreal.BlueprintService.discover_nodes(bp_path, "Broadcast", "", 10)
for m in matches:
    print(m.display_name, m.spawner_key)  # display_name, NOT node_title

broadcast_node = next((m for m in matches if "Broadcast" in m.display_name), None)
assert broadcast_node, "Broadcast Delegate node not found"

# Step 5: Build replacement — Broadcast + GET variable
result = unreal.BlueprintService.build_graph(
    bp_path, graph,
    [
        {"ref": "Broadcast", "type": "spawner_key", "params": {"key": broadcast_node.spawner_key}},
        {"ref": "GetDisp", "type": "variable_get", "params": {"variable": "FinishRotatingDispatcher"}},
    ],
    [
        {"from_": f"{custom_node.node_id}.then", "to": "Broadcast.execute"},
        {"from_": "GetDisp.FinishRotatingDispatcher", "to": "Broadcast.Dispatcher"},
    ],
    [], True, True
)
print(f"Success: {result.b_success}, errors: {result.errors}")

Target (self) on the Broadcast node connects to self by default when the Blueprint is the correct class (StateTreeTaskBlueprintBase). You do not need to wire it manually.

Round-Trip: Export → Modify → Rebuild

Use get_graph_definition to capture an existing graph, modify the definition, then rebuild with build_graph:

import unreal

bp_path = "/Game/BP_MyActor"
graph = "EventGraph"

# Export current graph
nodes, connections, defaults, error = unreal.BlueprintService.get_graph_definition(
    bp_path, graph)

# Inspect exported nodes
for n in nodes:
    print(f"  {n.ref}: {n.type} {n.params}")

# Modify (add a new node, change a connection, etc.)
# Then rebuild in a different graph or blueprint

Auto-Layout (auto_layout_graph)

auto_layout_graph arranges all nodes in a graph using a simplified Sugiyama algorithm:

• Layers are assigned by BFS on execution (exec pin) flow
• Pure data nodes are placed in the same layer as their first consumer
• Event/entry nodes sort to the top of each layer
• Column width: 400px, Row height: 200px

unreal.BlueprintService.auto_layout_graph(bp_path, "EventGraph")

Make Struct and Make Instanced Struct

Use make_struct to create a K2Node_MakeStruct for any struct type (engine or user-defined). Use instanced_struct to wrap a struct into FInstancedStruct — required when a pin expects FInstancedStruct (e.g. Make State Tree Event.Payload).

⚠️ The Value pin on Make Instanced Struct is a wildcard. It resolves to the struct's fields only after the struct type is set via struct param. Do not try to split or connect it before the node type is resolved — connecting by field name (e.g. Value.TargetPawn) will fail.

Correct pattern — build_graph example:

result = unreal.BlueprintService.build_graph(
    bp_path,
    "EventGraph",
    [
        # 1. Make the struct with its fields populated
        {"ref": "MkPayload", "type": "make_struct", "params": {"struct": "FStartChasingPayload"}},
        # 2. Wrap it in FInstancedStruct
        {"ref": "MkInst", "type": "instanced_struct", "params": {"struct": "FStartChasingPayload"}},
    ],
    [
        # Wire the struct output into the instanced struct Value pin
        {"from_": "MkPayload.StartChasingPayload", "to": "MkInst.Value"},
        # Wire MkInst output into whatever consumes FInstancedStruct
        {"from_": "MkInst.ReturnValue", "to": "MkState.Payload"},
    ],
    [],
    True, True
)

Pin names for make_struct: The output pin name matches the struct type name exactly as Unreal exposes it (e.g. StartChasingPayload for FStartChasingPayload). If uncertain, create the node, then call get_node_pins() to read the actual output pin name before connecting.

Pin names for instanced_struct: Input is Value, output is ReturnValue.

Error Handling

build_graph returns FBuildGraphResult with detailed audit:

• b_success — True only if zero node failures AND zero compile errors
• nodes_created / nodes_failed — individual node creation results
• connections_made / connections_failed — wiring results
• defaults_set / defaults_failed — pin default results
• ref_to_node_id — maps your local refs to engine GUIDs
• errors — critical failures (node not found, class not found, compile errors)
• warnings — non-fatal issues (pin mismatch, connection rejected)

Always check result.errors and result.warnings after a build_graph call.