Blueprint Graphs

🧠 Brains complement: IF an unreal-engine-skills-manager tool (external MCP) exists in this session, call it with {action: "load", skill: "blueprint-fundamentals"} for UE domain knowledge on this topic — correct APIs, architecture, best practices — and treat it as the rubric for any review / "best practices" question. If no such tool is available (e.g. running under Claude Code or Codex without that MCP), skip this line entirely and proceed with this skill alone — do NOT attempt the call.

Blueprint Graph Editing Skill

Also load blueprints skill when creating new blueprints, adding variables/components, or overriding functions. This skill covers node-level graph editing — adding nodes, wiring pins, setting values, and layout.

Critical Rules

⚠️ Nothing works during Play-In-Editor — and it fails SILENTLY

Every BlueprintService method resolves its target through LoadBlueprint(), which fails while PIE is running. You get no error. You get an empty array, False, or an empty-string node id — which reads exactly like "that node type doesn't exist" or "that spawner key is wrong". It is very easy to spend a long time debugging a correct call that was only ever blocked by PIE.

les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
if les.is_in_play_in_editor():
    raise RuntimeError("Stop PIE first - BlueprintService returns empty results during play")

Check this FIRST when any call returns nothing unexpectedly, before doubting a spawner key, a search term, or a graph name. The tell: unreal.EditorAssetLibrary.does_asset_exist(bp_path) also returns False for an asset you know exists. Asset writes during PIE are unsafe anyway — stop PIE, then re-run.

⚠️ Method Name Gotchas

⚠️ Engine BlueprintTools call_tool args are {refPath} objects, not strings. Every arguments={"blueprint": path, ...} / {"blueprint": bp_path} below is shorthand — the engine toolset needs {"refPath": "/Game/Dir/BP.BP"} (full object path, .AssetName suffix required) and returns {"returnValue": null} on success. See the blueprints skill for the bp_ref_of() helper. VibeUE's own unreal.BlueprintService.* methods are unaffected — they take plain string paths.

Node creation moved to the engine toolset. The old per-node convenience creators (add_function_call_node, add_event_node, add_get_variable_node, add_set_variable_node, add_member_get_node, add_validated_get_node) and the basics (create_blueprint, compile_blueprint, add_variable, create_function) are gone from unreal.BlueprintService. Create nodes one of three ways:

1. Batch (preferred for 2+ nodes): unreal.BlueprintService.build_graph(...) — the VibeUE delta. Node type values (function_call, event, variable_get, variable_set, branch, print_string, member_get, validated_get, …) live inside build_graph. See build-graph.md.
2. Single node: the engine BlueprintTools.create_node tool via call_tool (args graph, type_id, pos):

   call_tool(
       tool_name="create_node",
       toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
       arguments={"blueprint": bp_path, "graph": "EventGraph",
                  "type_id": "Development|PrintString", "pos": [400, 0]})

   type_id examples: 'Development|PrintString', 'AddEvent|EventBeginPlay', 'AddEvent|Custom|MyEvent', a function 'Utilities|...', a macro 'Utilities|FlowControl|ForLoop', a dispatcher handler 'Default|EventDispatcherOnDamaged'.
3. Editor-style spawner key: create_node_by_key() still works for deterministic creation after discover_nodes().

The surviving wiring/inspection methods (connect_nodes, disconnect_pin, get_connections, get_node_pins, set_node_pin_value, add_custom_event_node, add_macro_instance_node, the timeline + custom-event-input CRUD, build_graph, auto_layout_*, etc.) are the VibeUE focus and remain unchanged. Engine basics — BlueprintTools.create, .compile_blueprint, .add_variable, .add_function_graph — also go through call_tool against that same toolset.

⚠️ 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

⚠️ Read graphs cheaply: get_graph_summary() first, filtered get_nodes_in_graph() second

A full get_nodes_in_graph() dump of a big graph is the most token-expensive read in this toolset (every node ships its full pin list twice). Default reading order:

# 1. Fixed-size overview — payload independent of graph size
s = unreal.BlueprintService.get_graph_summary(bp_path, "EventGraph")  # None if bp/graph not found
print(s.node_count, s.connection_count, s.compile_status)
print(s.entry_points)      # ["Event BeginPlay|<node_id>", ...]
print(s.node_type_counts)  # ["K2Node_CallFunction x12", ...]

# 2. Drill in with filters: max nodes, name/type/id substring, and pins off
nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, "EventGraph", 25, "SpawnActor", False)
# args 3-5 are optional: max_nodes=0 (all), name_filter="" (all), include_pins=True

Only fall back to the unfiltered full dump when you genuinely need every pin of every node.

⚠️ Component/widget bound events: use create_component_bound_event(), never create_node_by_key

A K2Node_ComponentBoundEvent (e.g. On Clicked (MyButton)) built via create_node_by_key + configure_node compiles clean but never fires at runtime — the delegate binding params (including the generated handler function name) can only be initialized atomically:

node_id = unreal.BlueprintService.create_component_bound_event(
    bp_path, "EventGraph", "MyButton", "OnClicked", 100, 100)

Idempotent: if the bound event already exists, the existing node's id is returned. Works for any component delegate (OnComponentBeginOverlap, widget OnClicked/OnValueChanged, ...).

⚠️ Override events are idempotent

create_node_by_key("EVENT Actor::ReceiveBeginPlay") (and EVENT CUSTOM::Name) returns the existing node's id when the blueprint already has that event — a blueprint can hold each override event only once, and a duplicate would break compilation. Don't treat "node id I didn't just place" as an error; wire into it.

⚠️ 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".

👀 Reading the User's Live Graph Selection — get_selected_nodes()

get_nodes_in_graph() returns every node in a graph. To act on just the nodes the user has highlighted in the open Blueprint editor, use get_selected_nodes() instead. Returned objects are the same FBlueprintNodeInfo shape as get_nodes_in_graph() — same node_id, node_title, node_type, pos_x, pos_y, pin_names, and pins fields — so you can pass node.node_id straight into get_node_pins(), set_node_position(), delete_node(), etc.

The Blueprint MUST already be open in the editor. Selection state lives on the Slate panel, not on the asset; closing the editor discards it. Calling get_selected_nodes() for a closed asset returns an empty array (and logs a warning).

# Caller knows the asset
selected = unreal.BlueprintService.get_selected_nodes("/Game/BP_Player")

# Caller does NOT know which asset the user is looking at — empty path
# returns the selection from the first open Blueprint editor that has one.
selected = unreal.BlueprintService.get_selected_nodes("")

for n in selected:
    print(f"selected: {n.node_title} ({n.node_type}) @ ({n.pos_x}, {n.pos_y})")
    pins = unreal.BlueprintService.get_node_pins("/Game/BP_Player", "EventGraph", n.node_id)

Use this when the user says "this node", "the selected node(s)", "what I have highlighted", or "the one I'm looking at". An empty result means nothing is selected in any open Blueprint editor — ask the user to click a node in the graph rather than guessing.

🧭 "What am I looking at?" — get_focused_graph_context()

When the user says "this Blueprint", "the graph I have open", "the current material", or "what I'm looking at" without naming the asset, call get_focused_graph_context() first instead of guessing a path or chaining list_graphs → get_selected_nodes. It returns the asset and the focused graph in one shot — VibeUE's analogue of Epic's GetDockedContext(). It anchors on the globally-active editor tab (falling back to the first open supported editor).

It covers both Blueprint-family editors and the Material editor. Fields:

ctx = unreal.BlueprintService.get_focused_graph_context()
if ctx.found and ctx.graph_kind != "Material":
    # asset_path + graph_name drop straight into the other Blueprint tools
    nodes = unreal.BlueprintService.get_nodes_in_graph(ctx.asset_path, ctx.graph_name)
    sel = [n.node_id for n in ctx.selected_nodes]

Materials: when graph_kind == "Material", the Blueprint graph tools (get_nodes_in_graph, build_graph) do not apply — use MaterialNodeService keyed by ctx.asset_path. selected_nodes is still populated (material expression nodes), but graph_name is the internal material-graph name, not a Blueprint graph tab.

found == False means no Blueprint/Material editor is open — ask the user to open the asset rather than guessing a path.

💬 Comment Boxes — add_comment_node() / add_comment_around_nodes()

Comment boxes are the coloured bubbles that visually group nodes (the editor shortcut is C after selecting nodes). Two APIs:

• add_comment_node(blueprint_path, graph_name, comment_text, pos_x, pos_y, width, height, r, g, b, a) — explicit position and size. Use when you already know exactly where you want the box.
• add_comment_around_nodes(blueprint_path, graph_name, comment_text, node_ids, padding, r, g, b, a) — computes the bounding box of the supplied nodes (plus padding, default 40 px) and pads room for the title bar. This is the programmatic equivalent of select-then-press-C.

✍️ Write informative comment text — this is the whole point

Comment boxes are documentation that lives next to the code. A future reader (human or LLM) should be able to glance at the comment and understand what this group of nodes accomplishes and why, without re‑reading every pin. Treat the comment text the same way you'd treat a function header comment.

Good comments explain intent and behaviour:

• "Pick a random patrol point and cache its world location for the Move To task"
• "On Damage > 0: play hit reaction, flash material, decrement Health"
• "Debounce input — ignore re‑presses within 0.25s of the last fire"
• "Early‑out when the owning controller is not locally controlled (server‑auth path)"

Bad comments restate node titles or are filler:

• "Print String" ❌ (just the node name)
• "Logic" / "Stuff" / "TODO" ❌ (says nothing)
• "Branch + Set Variable" ❌ (mechanical, not intent)
• The user's verbatim request like "add a comment around the nodes" ❌ — that's the task, not the meaning

Workflow: before calling add_comment_around_nodes, inspect the selected nodes (titles, pin connections, variables they read/write) and synthesise a one‑line description of what the group does. If the user gave you a hint ("this is the patrol picker"), build on it; if they didn't, derive it from the nodes themselves. Use multiple lines (\n) when the group has a non‑trivial flow worth narrating.

sel = unreal.BlueprintService.get_selected_nodes("/Game/BP_Player")
ids = [n.node_id for n in sel]

# Derive intent from the selected nodes (event, variables read/written, called
# functions) and write a comment that documents WHY this group exists.
comment = (
    "Pick a random patrol point on EnterState\n"
    "Caches the chosen point's world location into PatrolPointLocation\n"
    "so the subsequent Move To task has a stable target."
)

unreal.BlueprintService.add_comment_around_nodes(
    "/Game/BP_Player", "EventGraph", comment, ids)

Both functions return the new comment node's node_id (a GUID string), or "" on failure. Colour parameters are RGBA in 0–1 range; the default is the standard pale yellow. Unknown node_ids passed to add_comment_around_nodes() are skipped with a warning — if all IDs are invalid, the call returns "".

Standard editor behaviour applies: any K2 nodes whose bounds fall inside the comment box get picked up and dragged with it (GroupMovement mode).

⚠️ 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

The editor still displays "Make Literal Float", but its spawner is FUNC KismetSystemLibrary::MakeLiteralDouble. A build_graph function_call node (or engine create_node) targeting "KismetSystemLibrary", "MakeLiteralFloat" resolves to nothing silently — use MakeLiteralDouble, or discover_nodes(bp, "Make Literal Float") and spawn via the returned spawner_key.

⚠️ Compile Before Using Variables in Nodes

The variable must exist on the compiled skeleton class before a getter/setter can resolve it. Add the variable and compile through the engine BlueprintTools toolset, then create the variable_get node (here via build_graph):

# Engine basics go through call_tool / BlueprintTools
call_tool(tool_name="add_variable",
          toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
          arguments={"blueprint": path, "name": "Health", "type": "float", "default": "100.0"})
call_tool(tool_name="compile_blueprint",
          toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
          arguments={"blueprint": path})  # REQUIRED before adding nodes

# Now the getter resolves — VibeUE build_graph
unreal.BlueprintService.build_graph(path, func,
    [{"ref": "GetHP", "type": "variable_get", "params": {"variable": "Health"}}],
    [], [], True, True)

⚠️ Verify Pins Immediately After Adding Variable Get/Set Nodes

A variable Get/Set node can occasionally be created with zero pins (the variable property failed to resolve on the skeleton class at spawn time). The create call still returns a GUID, so you won't notice until every connect_nodes against it returns False. After creating a variable node, check its pins before wiring anything (create it via build_graph's variable_get; ref_to_node_id maps your ref back to the GUID):

r = unreal.BlueprintService.build_graph(bp_path, graph,
    [{"ref": "Get", "type": "variable_get", "params": {"variable": "Armor"}}],
    [], [], False, False)
gid = r.ref_to_node_id["Get"]
pins = unreal.BlueprintService.get_node_pins(bp_path, graph, gid)
if not pins:  # corrupt node — recover
    unreal.BlueprintService.delete_node(bp_path, graph, gid)
    call_tool(tool_name="compile_blueprint",
              toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
              arguments={"blueprint": bp_path})
    r = unreal.BlueprintService.build_graph(bp_path, graph,
        [{"ref": "Get", "type": "variable_get", "params": {"variable": "Armor"}}],
        [], [], False, False)
    gid = r.ref_to_node_id["Get"]
    assert unreal.BlueprintService.get_node_pins(bp_path, graph, gid)

Recovery notes:

• delete_node can return False here — confirm with a fresh get_nodes_in_graph() and don't leave a stray pin-less duplicate behind (two nodes with the same title, one never connected).
• Compiling between delete and re-add refreshes the skeleton class so the retry resolves.
• This is another reason to create one node at a time instead of batching 4–6 creates in one call.

⚠️ The Result Node's execute Pin MUST Be Wired — the Warning Is Not Minor

Compile warning ReturnNode Exec pin has no connections means the execution chain never reaches the Return Node, so the function's output parameters are never set — callers always get default values. The function is broken even though compile.success is True.

Every non-pure function needs an exec path Entry.then → ... → Result.execute. For a "compute-only" function (e.g. read a variable, compare, return bool), wire the entry directly to the result — connecting only the data pin is not enough:

# CheckDeath: IsDead = (Health <= 0)
connect_nodes(bp, "CheckDeath", entry_id, "then", result_id, "execute")        # exec — REQUIRED
connect_nodes(bp, "CheckDeath", lessequal_id, "ReturnValue", result_id, "IsDead")  # data

Do not dismiss this warning in your summary or claim the function "works". Treat any ReturnNode compile warning as a wiring bug and fix it before reporting success. (If the function has no side effects, the cleaner fix is making it pure, but wiring the exec chain is the minimal correct repair.)

⚠️ 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")
# ...and creating into "ReceiveTreeStart" (build_graph or create_node) goes nowhere

# CORRECT — event-style overrides are in EventGraph
nodes = unreal.BlueprintService.get_nodes_in_graph(bp_path, "EventGraph")
unreal.BlueprintService.build_graph(bp_path, "EventGraph",
    [{"ref": "Call", "type": "function_call",
      "params": {"class": "KismetSystemLibrary", "function": "PrintString"}}],
    [], [], True, True)

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. A build_graph function_call node (or engine BlueprintTools.create_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.

Variable get/set keys: own variables, and the qualified form

SPAWN K2Node_VariableGet|<MenuName> (and ...VariableSet) binds a variable the Blueprint owns — one of its own variables, an inherited one, or an SCS component. A variable you just added with add_member_variable() works immediately; the action database has no spawner for it yet, so the service binds it as a self member directly. Menu names use the variable's display spelling, and a bool drops its b prefix: bIsOpen is "Get Is Open" (the raw "Get bIsOpen" is accepted too).

A variable owned by an unrelated class is refused, because binding one silently produces a node that fails to compile with "uses an invalid target". When you deliberately want another class's property wired through the node's Target pin, qualify the key with its owning class:

# Refused — ACharacter is not in this Actor Blueprint's hierarchy:
unreal.BlueprintService.create_node_by_key(bp, "EventGraph", "SPAWN K2Node_VariableGet|Get Jump Max Count", 0, 0)   # -> ""

# Deliberate cross-class read, wired through the Target pin:
unreal.BlueprintService.create_node_by_key(
    bp, "EventGraph", "SPAWN K2Node_VariableGet|Get Jump Max Count|Character", 0, 0)                                # -> node id

Format: SPAWN <NodeClass>|<MenuName>|<OwnerClass>. If the named class is one the Blueprint already derives from, the node is bound as a self member instead (no redundant Target pin).

⚠️ Standard Macro nodes (ForEachLoop, etc.) — do NOT use create_node_by_key

Macro instances (K2Node_MacroInstance) have no spawner key, so discover_nodes() won't find them and create_node_by_key() fails silently (returns empty, no error). Use the dedicated method instead:

import unreal
node_id = unreal.BlueprintService.add_macro_instance_node(bp_path, graph, "ForEachLoop", x, y)

Supported shorthands:

A full AssetPath:GraphName string is also accepted for user-defined macro libraries (e.g. /Game/Macros/ML_X.ML_X:MyMacro).

Notes:

• IsValid places one node exposing both Is Valid and Is Not Valid exec outputs — there is no separate IsNotValid macro.
• MultiGate is K2Node_MultiGate (a distinct node type), not a StandardMacro — it is not in this list.
• To create a macro graph on a MacroLibrary Blueprint, use create_macro_graph(lib_path, "MacroName") (the engine BlueprintTools.add_function_graph path asserts on MacroLibrary BPs). To create the library asset itself from Python (issue #449):

  f = unreal.BlueprintMacroFactory()   # NOT BlueprintFactory
  unreal.AssetToolsHelpers.get_asset_tools().create_asset("ML_X", "/Game/Macros", unreal.Blueprint, f)
  unreal.BlueprintService.create_macro_graph("/Game/Macros/ML_X", "MyMacro")
  # reference it from a graph: add_macro_instance_node(bp, graph, "/Game/Macros/ML_X.ML_X:MyMacro", x, y)