/unreal-blueprints

name: unreal-blueprints
description: >
  Unreal Engine 5 (UE 5.8) Blueprint visual scripting: Blueprint Classes vs the Level Blueprint,
  Event Graph, and Cast, Interfaces and Event Dispatchers. Use for BP graphs, how one Blueprint
  calls another, "cast failed", slow Event Tick or Blueprint compile errors. Not for C++
  (`unreal-cpp-gameplay`), input assets (`unreal-enhanced-input`) or AI trees
  (`unreal-behavior-trees`).

Unreal Blueprints

Structure UE5 gameplay in Blueprints: put logic in the right graph, expose data cleanly, and connect Blueprints without a web of hard references. Targets **UE 5.8**.

When to use

• Authoring a Blueprint Class, wiring the Event Graph, using the Construction Script, adding

variables, functions, macros or Event Dispatchers.

• Choosing how two Blueprints communicate, or untangling slow loads caused by casts.
• Diagnosing Blueprint compile errors and runtime "Accessed None" errors.

**When *not* to use:** hot loops, large data, or code that needs diffs and unit tests → `unreal-cpp-gameplay`. Input assets and bindings → `unreal-enhanced-input`. AI decisions → `unreal-behavior-trees`.

Workflow

1. **Read the project.** Check `EngineAssociation` in the `.uproject`, and whether a `Source/` folder exists (C++ base classes may already provide what the Blueprint needs). Blueprints are binary `.uasset` files: you cannot edit or grep them as text. Default: write the change as an exact node-by-node recipe the user applies, and verify it with the checks below. Escape hatches: Epic's `unreal-mcp` skill can create and edit graphs in a running editor, and UE 5.9 adds Python and Editor Utility functions that edit Blueprints from scripts. 2. **Pick the container.** Reusable behavior goes in a Blueprint Class (Actor, Pawn, Character or Actor Component). The Level Blueprint is only for one-off level scripting, because nothing else can reach it. 3. **Construction Script for setup, BeginPlay for gameplay.** The Construction Script reruns whenever the actor is placed, moved or edited in the editor, so it must be repeatable and must not spawn gameplay actors or start timers. 4. **Prefer events to Tick.** Overlaps, timers (`Set Timer by Event`), Timelines and Event Dispatchers instead of polling every frame. 5. **Choose communication by coupling.** Default: an Interface call for "do this to whatever I hit" and an Event Dispatcher for "tell anyone who cares". Cast only to a class the caller already depends on, because the cast loads that class with the caller. 6. **Expose data deliberately.** Instance Editable for per-instance values, Expose on Spawn for values set by `Spawn Actor`, categories for anything designers touch. Getters with no side effects can be Pure. 7. **Check it (see Verify).**

Patterns

Event-driven door (no Tick)

BeginPlay
  -> Bind Event to OnComponentBeginOverlap (TriggerBox)  [custom event OnEnterZone]

OnEnterZone (Other Actor)
  -> Does Object Implement Interface (BPI_CanOpenDoors)?
       True -> Play Timeline 'DoorOpen' -> Set Relative Rotation (Lerp 0..90 by Alpha)

Interface call (decoupled)

// BPI_Interactable: function Interact(Instigator: Actor)
// BP_Door, BP_Chest: Class Settings -> Implemented Interfaces -> BPI_Interactable
Player Use pressed -> Line Trace -> Hit Actor -> Interact (Message) [Target = Hit Actor]
// The Message node does nothing on actors that don't implement it, so no Cast is needed.

Dispatcher broadcast (one to many)

BP_Player: Event Dispatcher OnHealthChanged(NewHealth: float)
ApplyDamage -> Set Health -> Call OnHealthChanged(Health)
WBP_HUD Construct -> Get Player Pawn -> Cast To BP_Player -> Bind Event to OnHealthChanged

Verify

Say which of these you ran; describing a graph is not a test.

1. **Compile every Blueprint headless:** `UnrealEditor-Cmd <Project>.uproject -run=CompileAllBlueprints -unattended -nullrhi` (`UnrealEditor-Cmd.exe` on Windows). Read the summary at the end of the log and every `Error` or `Warning` line that names your assets; don't rely on the exit code alone. 2. **Validate assets:** `UnrealEditor-Cmd <Project>.uproject -run=DataValidation -unattended`. 3. **Behavior:** if the project has functional tests or automation tests for this feature, run `UnrealEditor-Cmd <Project>.uproject -ExecCmds="Automation RunTest <Filter>;Quit" -unattended -nullrhi -ReportExportPath="<dir>"` and read the report. Otherwise ask the user to run PIE with a breakpoint (F9) on the node in question, and report whether it hit and the values in the Watch window. Print String on each branch is the quick fallback. 4. **Optional:** with Epic's `unreal-mcp` connected, compile the edited Blueprint and read its messages through the Blueprints toolset.

Gotchas

• **Slow loads and huge memory from a small Blueprint:** chains of `Cast To` and hard object

references pull whole asset trees in with it. Use the Reference Viewer (or Size Map) to see what loads, then switch to Interfaces, Dispatchers or soft references.

• **"Accessed None" at runtime:** a reference variable was never set, or the actor it pointed

to was destroyed. Guard with `Is Valid` where the target can legitimately vanish.

• **Variable missing on the placed instance:** Instance Editable is off; for `Spawn Actor`

pins also tick Expose on Spawn.

• **Construction Script side effects in the editor:** it runs on every edit, so spawned actors

pile up and timers misbehave. Move gameplay init to BeginPlay.

• **Interface call does nothing:** the target does not implement it, or you called the

non-Message version on the wrong type.

• **Dispatcher listener fires after it was destroyed or hidden:** unbind on EndPlay or Destruct.
• **Local variable picks up an unrelated default:** it shares a name with a member variable.

5.8 refuses such names for new locals, but older Blueprints keep the collision until you rename one of th