Blueprints

🧠 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 System Skill

For node-level graph editing (adding nodes, connecting pins, wiring logic, timers, layout), load the blueprint-graphs skill.

Critical Rules

⚠️ Components added with add_component are NOT on the CDO

add_component creates a SCS node template, not an instance on the class default object. So the obvious way to configure it silently does nothing — get_components_by_class on the CDO returns an empty list and the loop body never runs:

# WRONG - prints [], the mesh is never assigned, and nothing errors
cdo = unreal.get_default_object(bp.generated_class())
for c in cdo.get_components_by_class(unreal.SkeletalMeshComponent):
    c.set_editor_property("skeletal_mesh_asset", mesh)

# CORRECT - go through the service, which edits the SCS template
BS.set_component_property(BP, "Windmill", "SkeletalMeshAsset", "/Game/X/SK_Windmill.SK_Windmill")
BS.set_component_property(BP, "Windmill", "AnimationMode", "AnimationBlueprint")
BS.set_component_property(BP, "Windmill", "AnimClass", "/Game/X/ABP_Windmill.ABP_Windmill_C")

Values are strings: an asset takes its object path (/Game/X/SK.SK), a class takes the _C path, an enum takes the entry name. Read back with get_component_property to confirm — it returns the resolved object, e.g. /Script/Engine.SkeletalMesh'/Game/X/SK_Windmill.SK_Windmill'. Components that come from the parent C++ class are on the CDO and can be set directly; only SCS-added ones need the service.

Level Blueprints: pass the MAP path

Every unreal.BlueprintService.* function that takes a blueprint_path also accepts a map/world path (e.g. /Game/Maps/MainMenu) and resolves it to that level's Level Blueprint — inspect and edit level scripts exactly like normal Blueprints. Explicit subobject paths (/Game/Maps/MyMap.MyMap:PersistentLevel.MyMap) work too. Compile still goes through unreal.BlueprintEditorLibrary.compile_blueprint(...) on the returned/loaded level script, and the MAP asset is what you save afterwards (unreal.EditorAssetLibrary.save_asset("/Game/Maps/MyMap")).

⚠️ Engine BlueprintTools args are {refPath} objects, NOT strings

Every UObject/UClass argument to the engine BlueprintTools toolset (blueprint, asset_type, graph, parent_class, …) is a reference object {"refPath": "<object path>"}, and these tools return the same shape. Passing a plain string fails with "<x> is not a valid object path for property '<arg>'". This rule is only for the engine BlueprintTools call_tool path — VibeUE's own unreal.BlueprintService.* Python methods still take plain string paths.

The refPath must be the full object path — /Game/Dir/Asset.Asset (the asset name repeated after the dot). A bare package path (/Game/Dir/Asset, no .Asset) is rejected. Two safe ways to get one:

# (a) Reuse what create/load returns — it is already a {refPath} object:
bp_ref = call_tool("create", "editor_toolset.toolsets.blueprint.BlueprintTools",
                   {"folder_path": "/Game/BP", "asset_name": "BP_X",
                    "asset_type": {"refPath": "/Script/Engine.Actor"}})["returnValue"]

# (b) Build one from a package path you already have:
def bp_ref_of(p):  # "/Game/Dir/BP_X" -> {"refPath": "/Game/Dir/BP_X.BP_X"}
    name = p.rsplit("/", 1)[-1].split(".")[0]
    return {"refPath": p if "." in p.rsplit("/", 1)[-1] else f"{p}.{name}"}

All the arguments={"blueprint": path, ...} / {"blueprint": bp, ...} examples in the sub-docs are shorthand — wrap the path with bp_ref_of(...) (or reuse the returned ref) when you actually call. On success these tools return {"returnValue": null}; an error comes back as a Parameter error.

⚠️ Creating a Blueprint — engine BlueprintTools.create

Blueprint basics now live on the engine's BlueprintTools toolset (VibeUE extends the native MCP endpoint). Create a Blueprint with call_tool, not unreal.BlueprintService.create_blueprint (that method was cut):

# CORRECT — folder_path + asset_name are strings; asset_type is a {refPath} class reference.
result = call_tool(
    tool_name="create",
    toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
    arguments={"folder_path": "/Game/Blueprints", "asset_name": "BP_MyActor",
               "asset_type": {"refPath": "/Script/Engine.Actor"}},
)
# -> {"returnValue": {"refPath": "/Game/Blueprints/BP_MyActor.BP_MyActor"}}
bp_ref = result["returnValue"]   # reuse this {refPath} object for later BlueprintTools calls

The folder and asset name are passed separately (folder_path + asset_name) — do not jam a full asset path into one argument. asset_type is the parent class as a {refPath}: /Script/Engine.Actor, /Script/Engine.Pawn, /Script/Engine.Character, or a Blueprint's generated class "/Game/.../BP_Base.BP_Base_C".

Blueprint Types in add_variable — engine BlueprintTools.add_variable

Adding a variable is also an engine BlueprintTools call now (unreal.BlueprintService.add_variable was cut). Use call_tool with blueprint, name, type_name (and add_object_variable / add_struct_variable for object- and struct-typed variables):

# CORRECT — blueprint is a {refPath} object; name/type_name are strings
call_tool(
    tool_name="add_variable",
    toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
    arguments={"blueprint": {"refPath": "/Game/BP_MyActor.BP_MyActor"}, "name": "Health", "type_name": "float"},
)

When the variable's type is a Blueprint class, use the Blueprint asset name directly in type_name. Do not add _C, and do not construct a generated class path — just use the name ("BP_Enemy", or the full "/Game/Blueprints/BP_Enemy"). Appending _C ("BP_Enemy_C") or guessing a generated class path is wrong; the type system resolves Blueprint names automatically via asset search.

Engine structs need the F prefix: color variables are "FLinearColor" / "FColor" — plain "LinearColor" / "Color" is not resolved. Unsure of a type string? Use the surviving unreal.BlueprintService.search_variable_types("Linear") to look it up.

Supported primitive type_name values (exact): bool, int, float, byte, name, string, text, Vector, Rotator, Transform, Vector2D, LinearColor. Use int (not int32) and float (not double) — add_variable rejects int32/double with "Unknown type 'int32'. Supported: …". For other engine structs (e.g. FColor, FGameplayTag) use add_struct_variable with struct_type; for object/class refs use add_object_variable with object_class as a {refPath}:

# Object-reference variable — object_class is a {refPath} to the class
call_tool("add_object_variable", "editor_toolset.toolsets.blueprint.BlueprintTools",
    {"blueprint": {"refPath": "/Game/BP_MyActor.BP_MyActor"}, "name": "DeathFX",
     "object_class": {"refPath": "/Script/Niagara.NiagaraSystem"}})

Struct/object/enum types from Python — add_member_variable (VibeUE delta)

From inside execute_python_code, unreal.BlueprintService.add_member_variable(bp_path, name, type_string, default="", is_array=False, container_type="") creates a member variable with full type-string support — structs, objects, enums, and containers — in one batchable Python call (no call_tool round-trip). It takes the same type strings as add_function_local_variable ("float", "FVector", "FStateTreeDelegateDispatcher", "AActor"):

unreal.BlueprintService.add_member_variable(bp_path, "FinishRotatingDispatcher", "FStateTreeDelegateDispatcher")
unreal.BlueprintService.add_member_variable(bp_path, "Waypoints", "FVector", "", True)  # FVector array
unreal.BlueprintEditorLibrary.compile_blueprint(unreal.EditorAssetLibrary.load_asset(bp_path))

Returns False (with the reason in the log) on a duplicate name or an unresolvable type string. Compile after adding — the variable is registered but the class is only rebuilt on compile.

Removing one variable — remove_member_variable (VibeUE delta)

unreal.BlueprintService.remove_member_variable(bp_path, name, force=False) removes exactly one member variable. The engine alternative, BlueprintEditorLibrary.remove_unused_variables, sweeps every unreferenced variable — use this when you want to delete just one. It counts Get/Set references across all graphs first: with references present and force=False it refuses (returns False, logs the referencing graphs and node counts); with force=True it removes the variable and its referencing nodes. A component name (from the Simple Construction Script) is refused with a pointer to the component API. Verifies by readback and returns True only when the variable is gone.

unreal.BlueprintService.remove_member_variable(bp_path, "UnusedScratch")        # refuses if referenced
unreal.BlueprintService.remove_member_variable(bp_path, "OldHealth", True)       # force: nodes go too

⚠️ Adding a function graph — engine BlueprintTools.add_function_graph

Creating a function graph moved to the engine toolset (create_function / add_function on BlueprintService were cut). Use call_tool with blueprint + graph_name:

call_tool(
    tool_name="add_function_graph",
    toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
    arguments={"blueprint": {"refPath": "/Game/Blueprints/BP_MyActor.BP_MyActor"}, "graph_name": "DoThing"},
)

Refining the graph afterward still uses the surviving VibeUE delta methods (add_function_parameter, add_function_local_variable, get_function_parameters, get_function_info, override_function, open_function_graph).

⚠️ Method Name Gotchas

⚠️ Property Name Gotchas

⚠️ Python Naming: Boolean b Prefix Is Stripped

UE Python strips the lowercase b prefix from boolean properties. Always use the name without it:

Do not use b_already_overridden, b_is_event_style, etc. — these will raise AttributeError.

Exception: the string-based CDO accessors get_property / set_property take the native C++ property name, so booleans KEEP the b prefix there ("bReplicates", not "replicates"). See the next section.

⚠️ CDO Properties: get_property / set_property (replication, lifespan, etc.)

Use these to read/write Class Default Object properties like replication or initial lifespan:

import unreal
bp = "/Game/Blueprints/TestActor"

# READ — returns a single value: str, or None if the property wasn't found. NOT a (success, value) tuple!
value = unreal.BlueprintService.get_property(bp, "bReplicates")   # "True" / "False" (a STRING)
life  = unreal.BlueprintService.get_property(bp, "InitialLifeSpan")  # "5.000000"

# WRONG — raises ValueError: too many values to unpack
# success, value = unreal.BlueprintService.get_property(bp, "bReplicates")

# WRITE — values are strings; returns bool
unreal.BlueprintService.set_property(bp, "bReplicates", "True")

# Compile via the engine BlueprintTools toolset (compile_blueprint was cut from BlueprintService):
# call_tool(tool_name="compile_blueprint",
#           toolset_name="editor_toolset.toolsets.blueprint.BlueprintTools",
#           arguments={"blueprint": {"refPath": "/Game/Blueprints/TestActor.TestActor"}})
unreal.EditorAssetLibrary.save_asset(bp)

Rules:

• Returns str or None — UE Python collapses bool Func(..., Out&) into one return value. This applies to every get_*_info method too (get_variable_info, get_function_info, get_component_info, get_node_details): they return the info struct or None, never a tuple.
• Property names are the native C++ names: bReplicates, InitialLifeSpan, bCanBeDamaged — the b prefix is NOT stripped here (a stripped name returns None).
• Values read back as strings: compare value == "True", not value is True.
• On UE 5.3+, set_property maps the deprecated GameplayEffect CDO fields InheritableGameplayEffectTags and InheritableOwnedTagsContainer to their Asset Tags and Target Tags GameplayEffect Components. Writing only the legacy fields is otherwise erased by UGameplayEffect::PreSave.

⚠️ Info Struct Fields (don't guess — these are the complete lists)

get_blueprint_info(path) → BlueprintDetailedInfo: blueprint_name, blueprint_path, parent_class, is_widget_blueprint, variables, functions, components.

Component API quick reference (all on unreal.BlueprintService)

These signatures are complete — no need to discover_python_class them again:

Root component behavior: components added with no parent_name go to root level. The first scene component added this way replaces the auto-generated DefaultSceneRoot and becomes the root; later parentless scene components become floating siblings, NOT children of the root. To build a hierarchy, pass parent_name when adding, or use reparent_component / set_root_component.