@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/unity/references/lifecycle-deep-dive.md

@@ -0,0 +1,75 @@
+# MonoBehaviour lifecycle — deep dive (Unity 6)
+
+Full execution order for a `MonoBehaviour`, and the exact reason each callback exists. Reference:
+Unity Manual "Order of execution for event functions".
+
+## Initialization (once per object, in this order)
+
+1. **`Awake`** — called when the script instance is loaded, **even if the component is disabled**, and
+   before any `Start`. Cache `GetComponent`/`TryGetComponent`, allocate internal state. Do NOT reach
+   into *other* objects here — their `Awake` may not have run yet.
+2. **`OnEnable`** — every time the object/component becomes enabled (including re-enable). Subscribe to
+   C# events, register with managers, enable input actions. Must be mirrored by `OnDisable`.
+3. **`Start`** — once, just before the first `Update`, and **only if the component is active**. Safe
+   place for cross-object wiring because every object's `Awake` has already run. If an object is created
+   disabled and never enabled, `Start` never runs.
+
+Across a scene: all `Awake`s run, then all `OnEnable`s, then all `Start`s — so `Start` is your
+"everyone exists now" hook.
+
+## Physics loop (`FixedUpdate`) — 0..n times per frame
+
+- Runs on a fixed timestep (`Time.fixedDeltaTime`, default 0.02s = 50 Hz). May run zero times (high FPS)
+  or several times (low FPS) per rendered frame.
+- **All `Rigidbody` work goes here:** `AddForce`, `MovePosition`, `MoveRotation`, velocity changes.
+  Setting `transform.position` directly on a physics body fights the solver → jitter/tunneling.
+- Do NOT read edge-triggered input here (`WasPressedThisFrame`) — you'll miss events. Read in `Update`,
+  store the intent, consume it in `FixedUpdate`.
+- Collision/trigger callbacks (`OnCollisionEnter`, `OnTriggerEnter`, and their `Stay`/`Exit`, plus 2D
+  variants) fire from the physics step.
+
+## Game logic loop (per frame)
+
+4. **`Update`** — once per rendered frame. Input, timers, non-physics movement, state machines.
+   Frame-rate independent movement multiplies by `Time.deltaTime`.
+5. **`LateUpdate`** — after every `Update` in the scene has run. Camera follow, look-at, IK, procedural
+   bone adjustments — anything that must read the *final* positions of objects that moved this frame.
+
+## Rendering-adjacent (advanced)
+
+- `OnPreCull`, `OnBecameVisible`/`OnBecameInvisible`, `OnWillRenderObject`, `OnRenderImage` (Built-in RP;
+  URP/HDRP use `RenderPipelineManager` callbacks / render features instead).
+- `OnDrawGizmos` / `OnDrawGizmosSelected` — Editor scene-view debug drawing only.
+- `OnGUI` — legacy IMGUI, called multiple times per frame; editor tooling only, never runtime gameplay.
+
+## Teardown
+
+6. **`OnDisable`** — when the object/component disables (and just before `OnDestroy`). Unsubscribe from
+   everything subscribed in `OnEnable`, disable input actions, stop coroutines you own. A missing
+   unsubscribe here is the #1 cause of leaks and "handler fired twice after re-enable".
+7. **`OnDestroy`** — once, when the object is destroyed (or scene unloads / app quits). Release native
+   handles, dispose `IDisposable`s (`NativeArray`, `InputActionAsset` you `new`ed), final cleanup.
+8. **`OnApplicationQuit`** / `OnApplicationPause` / `OnApplicationFocus` — app-level lifecycle for
+   save-on-quit and mobile pause handling.
+
+## Coroutine yield timing (where a coroutine resumes)
+
+| `yield return` | Resumes |
+| --- | --- |
+| `null` | next frame, after `Update` |
+| `new WaitForSeconds(t)` | after `t` scaled seconds (affected by `Time.timeScale`) |
+| `new WaitForSecondsRealtime(t)` | after `t` real seconds (ignores `timeScale`) |
+| `new WaitForFixedUpdate()` | after the next physics step |
+| `new WaitForEndOfFrame()` | after rendering, before present (good for screen capture) |
+| `new WaitUntil(() => cond)` / `WaitWhile(...)` | when the predicate flips |
+| another `IEnumerator` | when the nested coroutine completes |
+
+Gotcha: `new WaitForSeconds(t)` allocates every call — cache the instance if you yield it in a loop, or
+switch to `Awaitable.WaitForSecondsAsync`.
+
+## Script execution order
+
+If object A must initialize before object B, don't rely on scene order — set it in
+`Project Settings → Script Execution Order`, or better, express the dependency explicitly (have B pull
+what it needs in its own `Start`, or use an explicit init call). `[DefaultExecutionOrder(n)]` sets it
+per-class in code.

package/skills/shared/unreal/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: unreal
+description: "Use when building, scripting or debugging a game in Unreal Engine 5 with Blueprint or C++ — the gameplay framework (Actor, Pawn, Character, GameMode, PlayerController), Actor lifecycle and tick, the reflection macros and garbage collection, Enhanced Input, multicast delegates, UMG widgets, Paper2D, and Blueprint-to-C++ parity in both directions. NOT Godot (that is `godot`), NOT Unity or MonoBehaviour (that is `unity`), NOT language-only C++ memory and RAII questions with no Unreal types (that is `cpp`)."
+tags: [unreal, ue5, blueprint, unreal-engine, gamedev]
+recommends: [cpp, gamedev-shipping, gamedev-multiplayer, game-design, gamedev-physics, godot, unity]
+profiles: [full]
+origin: ai-hub
+---
+
+# Unreal Engine 5 (Blueprint + C++)
+
+Build and debug UE5 games with the grain of the engine: the Gameplay Framework for structure,
+reflection macros so C++ and Blueprint see the same types, Enhanced Input for controls, UMG for
+UI, Paper2D for 2D — and a clean Blueprint↔C++ boundary so either can call the other. Hands
+3D-only concerns (shaders, physics, netcode, shipping) to the siblings below.
+
+## Version contract — read first
+
+Target **Unreal Engine 5.x** (patterns valid 5.3+; current stable **UE 5.8**, the last UE5 line
+before UE6). Emit modern UE5 APIs only. **Never emit these deprecated / legacy patterns:**
+
+| Never emit | Use instead (UE5) |
+| --- | --- |
+| Legacy input: Project-Settings Action/Axis Mappings + `InputComponent->BindAction/BindAxis(FName,…)` | **Enhanced Input**: `UInputAction` + `UInputMappingContext` + `UEnhancedInputComponent->BindAction(…)`, context added via `UEnhancedInputLocalPlayerSubsystem` (default since 5.1; legacy deprecated 5.2) |
+| Raw `UObject*` / `AActor*` as a **UPROPERTY member** | `TObjectPtr<T>` for UPROPERTY members (raw `T*` is fine for locals/params) |
+| `GENERATED_UCLASS_BODY()` | `GENERATED_BODY()` |
+| `TAssetPtr<T>` / `FStringAssetReference` | `TSoftObjectPtr<T>` / `FSoftObjectPath` |
+| `ANY_PACKAGE` in `FindObject` / `StaticLoadObject` | explicit package or `FTopLevelAssetPath` |
+| Slate/Canvas `DrawText`/`HUD` for game UI | **UMG** (`UUserWidget`) |
+| `AGameMode` as the default base for a solo game | `AGameModeBase` (use `AGameMode` only when you need `MatchState`/multiplayer login flow) |
+| `DECLARE_MULTICAST_DELEGATE` for a Blueprint-bindable event | `DECLARE_DYNAMIC_MULTICAST_DELEGATE…` + `BlueprintAssignable` |
+| `bCanEverTick = true` "just in case" | leave tick **off**; drive logic from events/overlaps/timers (`FTimerManager`) |
+| Hard-referencing / loading heavy assets at runtime by path | soft refs + `FStreamableManager` async load (hard refs only via `ConstructorHelpers` in the constructor) |
+
+**Blueprint vs C++ — and the hybrid.** Blueprint: designer-facing tweaks, per-level scripting,
+UI wiring, rapid iteration, one-off actors. C++: core systems, performance-critical/tick-heavy
+code, base classes, math, anything you want unit-tested or diffable in git. **Default to the
+hybrid**: write the base class in C++ (`UCLASS(Blueprintable)`), expose tunables with
+`UPROPERTY(EditAnywhere, BlueprintReadWrite)` and hooks with `BlueprintImplementableEvent` /
+`BlueprintNativeEvent`, then create a **Blueprint subclass** for designers to set defaults, wire
+assets, and script the specifics — C++ speed and testability with Blueprint iteration.
+
+## Gameplay Framework — who owns what
+
+| Class | Responsibility | Lifetime / scope |
+| --- | --- | --- |
+| `AActor` | Anything placeable/spawnable in a level; holds components. | Per instance in a level/world |
+| `UActorComponent` / `USceneComponent` | Reusable behavior/data on an Actor; `USceneComponent` adds a transform. | Owned by its Actor |
+| `APawn` | An Actor that can be **possessed** and driven by a controller. | Per instance |
+| `ACharacter` | A Pawn with a `CapsuleComponent`, `SkeletalMesh`, and `CharacterMovementComponent` (walk/jump/crouch, networked). | Per instance |
+| `AController` / `APlayerController` / `AAIController` | The "brain" that possesses a Pawn; `APlayerController` maps a human player to input, camera, and UI. | One per player/AI |
+| `APlayerState` | Per-player **replicated** state that must survive respawn (name, score, team). | One per player |
+| `AGameModeBase` | The rules of the match; spawns players, defines default Pawn/Controller/HUD classes. **Server-only** — never exists on clients. | One per level |
+| `AGameStateBase` | Game-wide **replicated** state all clients need (match phase, shared score, player array). | One, replicated |
+| `AHUD` / `UUserWidget` | On-screen UI; prefer UMG `UUserWidget` over `AHUD` canvas drawing. | Per PlayerController |
+
+Rule of thumb: **transient input/camera → PlayerController; persistent per-player data →
+PlayerState; match rules → GameMode (server); shared world state → GameState.** Full
+responsibilities and a spawn-order diagram → `references/gameplay-framework.md`.
+
+## Actor lifecycle, components & attachment
+
+Order for a spawned/placed Actor: **constructor** (set defaults, create subobjects — never
+gameplay logic) → `PostInitializeComponents` → `BeginPlay` (world is live; safe to start logic)
+→ `Tick(DeltaSeconds)` each frame (only if enabled) → `EndPlay` / `Destroyed` (release).
+
+```cpp
+AMyActor::AMyActor()
+{
+    PrimaryActorTick.bCanEverTick = false;                         // opt in only if you truly tick
+    RootComponent = CreateDefaultSubobject<USceneComponent>(TEXT("Root"));
+    Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
+    Mesh->SetupAttachment(RootComponent);                          // attach in the CONSTRUCTOR
+}
+void AMyActor::BeginPlay() { Super::BeginPlay(); /* start logic here, not in ctor */ }
+```
+
+- **Create components** with `CreateDefaultSubobject<T>(TEXT("Name"))` in the constructor; store
+  them in a `UPROPERTY() TObjectPtr<T>` so they're kept alive and visible.
+- **Attach in the constructor** with `SetupAttachment`; **at runtime** use
+  `AttachToComponent(Parent, FAttachmentTransformRules::SnapToTargetNotIncludingScale)`.
+- Prefer timers over tick for periodic work:
+  `GetWorldTimerManager().SetTimer(Handle, this, &AMyActor::Fn, 1.f, true);`
+
+## Reflection macros & garbage collection
+
+Macros register types with Unreal Header Tool (UHT) so they get GC, serialization, editor, and
+Blueprint support. Put `GENERATED_BODY()` first inside the class.
+
+```cpp
+UENUM(BlueprintType)
+enum class ETeam : uint8 { Red, Blue };
+
+USTRUCT(BlueprintType)                       // value type, visible to BP; no GC of itself
+struct FLoadout { GENERATED_BODY()
+    UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 Ammo = 30;
+};
+
+UCLASS(Blueprintable)                        // Blueprintable = can be subclassed in BP
+class MYGAME_API AWeapon : public AActor {
+    GENERATED_BODY()
+public:
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Combat") float Damage = 10.f;
+    UPROPERTY(VisibleAnywhere) TObjectPtr<UStaticMeshComponent> Mesh;   // GC-tracked ref
+    UFUNCTION(BlueprintCallable, Category="Combat") void Fire();
+};
+```
+
+Common `UPROPERTY` specifiers: `EditAnywhere` (edit on instances + defaults),
+`EditDefaultsOnly` (class defaults only), `VisibleAnywhere` (read-only in editor);
+`BlueprintReadWrite` (get + set in BP) vs `BlueprintReadOnly` (get only); always give a
+`Category`.
+
+**Garbage collection — the #1 gotcha.** The GC frees any `UObject` that no reachable `UPROPERTY`
+points to. A UObject reference stored **without** `UPROPERTY()` is invisible to GC: it will be
+collected out from under you and the pointer dangles/crashes. So:
+
+- Store every long-lived `UObject`/`AActor` reference in a `UPROPERTY() TObjectPtr<T>`.
+- For a non-owning "might already be dead" reference (don't keep it alive, must null-check), use
+  `TWeakObjectPtr<T>` and `.IsValid()`.
+- Never `new`/`delete` a `UObject` — spawn Actors with `SpawnActor<T>()` and create other UObjects
+  with `NewObject<T>()`; the GC owns their lifetime. `new`/`delete` and smart pointers apply only
+  to **non-`UObject`** C++ types.
+
+## Delegates & events
+
+```cpp
+// Dynamic multicast = Blueprint-assignable + serializable. Params need a typed macro variant.
+DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnHealthChanged, float, NewHealth);
+
+UPROPERTY(BlueprintAssignable, Category="Events")     // shows as a red event node in BP
+FOnHealthChanged OnHealthChanged;
+
+// C++ side: bind and fire.
+OnHealthChanged.AddDynamic(this, &AMyActor::HandleHealth);   // dynamic → AddDynamic + UFUNCTION
+OnHealthChanged.Broadcast(NewHealth);
+```
+
+Use a **dynamic** multicast delegate whenever Blueprint must bind to the event (`BlueprintAssignable`);
+its handler must be a `UFUNCTION`. Use a plain `DECLARE_MULTICAST_DELEGATE…` (bind with
+`AddUObject`/`AddLambda`) only for C++-to-C++ events that never touch Blueprint. Overlap/hit
+events (`OnComponentBeginOverlap`, `OnActorHit`) are already dynamic multicast — bind with
+`AddDynamic`.
+
+## Blueprint ↔ C++ parity
+
+Same graph, two languages. Left = the Blueprint node; right = the C++ that does the same thing.
+
+| Blueprint node | C++ |
+| --- | --- |
+| Event **BeginPlay** | `virtual void BeginPlay() override;` (call `Super::BeginPlay()`) |
+| Event **Tick (Delta Seconds)** | `virtual void Tick(float DeltaSeconds) override;` |
+| **Spawn Actor from Class** | `GetWorld()->SpawnActor<AWeapon>(Class, Loc, Rot);` |
+| **Cast To** `X` | `if (AX* P = Cast<AX>(Obj)) { … }` (always null-check) |
+| **Set Timer by Event** | `GetWorldTimerManager().SetTimer(H, this, &A::Fn, Rate, bLoop);` |
+| **Print String** | `UE_LOG(LogTemp, Warning, TEXT("v=%d"), V);` / `GEngine->AddOnScreenDebugMessage(...)` |
+| **Get Player Controller** | `UGameplayStatics::GetPlayerController(this, 0);` |
+| **Bind Event to** `OnClicked` | `Button->OnClicked.AddDynamic(this, &U::Fn);` |
+
+**Expose C++ → Blueprint:**
+
+```cpp
+UFUNCTION(BlueprintCallable, Category="X") void DoThing();     // callable node (has exec pins)
+UFUNCTION(BlueprintPure,     Category="X") int32 GetScore() const;  // pure node (no exec pins)
+UPROPERTY(EditAnywhere, BlueprintReadWrite) float Speed = 600.f;    // exposed variable
+```
+
+**Call Blueprint ← C++** (the hybrid hooks — declare in C++, implement/override in the BP subclass):
+
+```cpp
+// No C++ body — Blueprint provides the whole implementation. C++ just calls OnScored().
+UFUNCTION(BlueprintImplementableEvent) void OnScored(int32 Points);
+
+// C++ gives a default; Blueprint may override. Implement the C++ default in OnDamaged_Implementation.
+UFUNCTION(BlueprintNativeEvent) void OnDamaged(float Amount);
+void AMyActor::OnDamaged_Implementation(float Amount) { Health -= Amount; }
+// Call the event from C++ by its plain name: OnScored(10);  OnDamaged(5.f);
+```
+
+Mapping table (every specifier), full expose/override examples, and the C++-base-+-BP-subclass
+workflow → `references/blueprint-cpp-parity.md`.
+
+## UMG (UI)
+
+UI is a `UUserWidget` (design the visuals in a WBP asset; drive logic in C++ or its BP graph).
+Bind C++ members to named widgets with `meta=(BindWidget)` — the C++ name must match the WBP
+widget.
+
+```cpp
+UCLASS() class UHealthWidget : public UUserWidget { GENERATED_BODY()
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UProgressBar> HealthBar;   // name matches WBP
+    UFUNCTION(BlueprintCallable) void SetHealth(float Pct);
+};
+// Create + show from a PlayerController:
+UHealthWidget* W = CreateWidget<UHealthWidget>(PC, WidgetClass);
+W->AddToViewport();
+```
+
+Layout with panels (Canvas/V-H Box/Overlay/Grid); `SetVisibility`,
+`RemoveFromParent` to hide/close; anchors + a design resolution for scaling.
+
+## Paper2D (2D)
+
+Enable the Paper2D plugin. Core types:
+
+- **Sprite** (`UPaperSprite` asset, `UPaperSpriteComponent`) — a single textured quad.
+- **Flipbook** (`UPaperFlipbook` asset, `UPaperFlipbookComponent`) — frames + FPS = animation;
+  `SetFlipbook(...)` to swap states (idle/run/jump).
+- **`APaperCharacter`** — a `ACharacter` whose mesh is a flipbook; you get
+  `CharacterMovementComponent` (walk/jump) for free, driven by Enhanced Input just like 3D.
+- **Tile maps** (`UPaperTileMap`, `UPaperTileMapComponent`) for level geometry.
+
+2D uses the same Gameplay Framework, Enhanced Input, and lifecycle as 3D — only the visual
+components differ. Constrain movement to a plane and use an orthographic camera.
+
+## Packaging & build config (brief)
+
+- **Build configurations**: `Debug`, `DebugGame`, `Development` (default for iteration —
+  optimized engine, hot-reloadable game code), `Shipping` (fully optimized, logging/console
+  stripped — ship this), `Test`.
+- **Target files** (`*.Target.cs`) define Game/Editor/Client/Server targets; **module rules**
+  (`*.Build.cs`) declare module dependencies (e.g. `"EnhancedInput"`, `"UMG"`, `"Paper2D"`).
+- Package from **Platforms ▸ <target> ▸ Package Project**, or automate with
+  `RunUAT BuildCookRun` (cook content → stage → package). Per-platform settings live in
+  `Config/DefaultGame.ini` / `Default<Platform>Engine.ini`.
+
+This is the minimum. Deep shipping — cooking, pak/IoStore, certification, size/perf budgets, CI —
+is owned by [`gamedev-shipping`](../gamedev-shipping/SKILL.md). Overview + a starter `.Build.cs` →
+`references/packaging.md`.
+
+## Guardrails & gotchas
+
+- **UPROPERTY-or-GC'd**: any UObject ref you keep must be a `UPROPERTY()` or it will be garbage
+  collected and crash. This is the most common Unreal C++ bug.
+- **Enhanced Input only** — no legacy Action/Axis mappings; add the `UInputMappingContext` via the
+  local player subsystem in `BeginPlay`/on-possess, bind actions on `UEnhancedInputComponent`.
+- **GameMode is server-only** — never read it on a client; put client-visible state on GameState
+  or PlayerState and replicate.
+- **No gameplay in the constructor** — the world isn't ready. Do it in `BeginPlay`.
+- **Always null-check `Cast<T>()`** and `SpawnActor` results; they can return `nullptr`.
+- **Don't `new`/`delete` UObjects** — `NewObject`/`SpawnActor` and let GC free them. Header
+  changes need a full editor recompile (Live Coding covers `.cpp` bodies only).
+- **Regenerate project files** after adding classes/modules; add module deps in `*.Build.cs`
+  (missing `"EnhancedInput"`/`"UMG"` = linker errors).
+- **Multiplayer**: replicate state with `UPROPERTY(Replicated)`, gate server actions behind
+  `HasAuthority()` → see `gamedev-multiplayer`.
+
+## Related skills
+
+- [`cpp`](../cpp/SKILL.md) — plain C++/RAII/smart-pointer ownership for **non-UObject** code; this
+  skill owns the Unreal reflection + GC model layered on top.
+- [`gamedev-shipping`](../gamedev-shipping/SKILL.md) — deep cooking/packaging/store submission.
+- [`gamedev-multiplayer`](../gamedev-multiplayer/SKILL.md) — replication, RPCs, authority.
+- [`gamedev-physics`](../gamedev-physics/SKILL.md) — Chaos physics, collision, constraints.
+- [`game-design`](../game-design/SKILL.md) — mechanics/loops before you build them.
+- [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) — the other engines; route there
+  when the project is Godot or Unity, not Unreal.
+
+## Checklist
+
+- [ ] Correct base class chosen (Actor/Pawn/Character; GameMode**Base** unless match-state needed).
+- [ ] No legacy input — Enhanced Input (`UInputAction` + `UInputMappingContext` + subsystem).
+- [ ] Every long-lived UObject/Actor ref is a `UPROPERTY() TObjectPtr<T>` (GC-safe).
+- [ ] Components made in ctor via `CreateDefaultSubobject` + `SetupAttachment`; no logic in ctor.
+- [ ] Tick left off unless required; periodic work on a timer/event.
+- [ ] C++↔BP boundary correct: `BlueprintCallable`/`Pure` to expose, `BlueprintImplementableEvent`/
+      `NativeEvent` for BP-overridable hooks; BP-bound delegates are dynamic multicast.
+- [ ] UI is UMG (`UUserWidget` + `BindWidget`), not HUD canvas drawing.
+- [ ] Server-only vs replicated state placed correctly (GameMode server-only).
+- [ ] Module deps (`EnhancedInput`/`UMG`/`Paper2D`) added in `*.Build.cs`; project files regenerated.

package/skills/shared/unreal/evals/README.md

@@ -0,0 +1,12 @@
+# Eval harness — `unreal` skill
+
+These cases are run by the ai-hub skill-eval harness (a Claude agent with the full catalog loaded)
+or read manually. **Triggering**: the `unreal` description must fire on real UE5 Blueprint/C++
+requests — including symptom-only ones (a garbage-collected UObject) — while staying quiet on
+near-misses that belong to `godot`, `unity`, `cpp`, `game-design`, or `gamedev-shipping`, routing
+each to that sibling. **Capability**: with `SKILL.md` + references loaded, the generated UE5 code
+must satisfy the `must_include` rubric — Enhanced Input (never legacy mappings), GC-safe
+`UPROPERTY() TObjectPtr<T>` refs, `GENERATED_BODY()`, no logic in the constructor, correct
+Blueprint exposure, a dynamic multicast delegate, and the right `.Build.cs` module — and beat the
+no-skill baseline. Run 3–5 trials per prompt (LLM routing is non-deterministic); a prompt passes
+on a majority.

package/skills/shared/unreal/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: unreal
+
+should_trigger:
+  - prompt: "In my UE5 project, write a Character in C++ that moves and jumps with Enhanced Input, then let designers subclass it in Blueprint."
+    why: "Core hybrid workflow: C++ ACharacter base + Enhanced Input + Blueprint subclass — the skill's central use case."
+  - prompt: "How do I expose this C++ function and a float variable to Blueprint so a designer can call and tweak them?"
+    why: "Blueprint↔C++ parity / exposure via BlueprintCallable + UPROPERTY(EditAnywhere, BlueprintReadWrite)."
+  - prompt: "My UObject keeps getting garbage collected and the pointer crashes at random — I'm holding it in a plain member. What's wrong?"
+    why: "Symptom-only trigger for the GC/UPROPERTY(TObjectPtr) rule — the #1 Unreal C++ gotcha this skill owns."
+  - prompt: "What's the difference between GameMode, GameState, PlayerController and PlayerState, and where do I put the player's score?"
+    why: "Gameplay Framework responsibilities — the reference table routes score to PlayerState and match rules to server-only GameMode."
+  - prompt: "Set up a Paper2D player with idle/run/jump flipbook animations that swap on movement."
+    why: "Paper2D (APaperCharacter + UPaperFlipbookComponent) is explicitly covered for 2D."
+  - prompt: "I want a UMG health bar widget in C++ bound to a progress bar in the WBP and shown on screen."
+    why: "UMG basics: UUserWidget + meta=(BindWidget) + CreateWidget/AddToViewport."
+  - prompt: "Declare an event other Blueprints and C++ can bind to when the player dies, and broadcast it from C++."
+    why: "Dynamic multicast delegate + BlueprintAssignable + Broadcast/AddDynamic is owned here."
+
+should_not_trigger:
+  - prompt: "In Godot 4, how do I structure nodes and connect signals for my player scene?"
+    route_to: "godot"
+    why: "Godot's node/signal model is a different engine; unreal must not answer engine-specific Godot questions."
+  - prompt: "My Unity MonoBehaviour Start() runs before my other script's Awake() — how do I fix the execution order?"
+    route_to: "unity"
+    why: "Unity/C#/MonoBehaviour lifecycle belongs to the unity skill, not Unreal's Actor lifecycle."
+  - prompt: "Explain unique_ptr vs shared_ptr ownership and how to avoid a use-after-free in my plain C++ library."
+    route_to: "cpp"
+    why: "Pure C++ smart-pointer/RAII with no Unreal types goes to cpp; unreal owns only the UObject/GC model layered on top."
+  - prompt: "Design the core game loop and progression economy for my roguelike before I build anything."
+    route_to: "game-design"
+    why: "Mechanics/loop/economy design is engine-agnostic and precedes implementation — game-design, not unreal."
+  - prompt: "Tune Unreal's cook settings, pak/IoStore, and set up CI to produce signed console builds."
+    route_to: "gamedev-shipping"
+    why: "Deep cooking/packaging/certification pipeline is delegated to gamedev-shipping; unreal only covers the build-config overview."
+
+capability:
+  - scenario: "Author a UE5 first-person Character in C++ that walks and jumps via Enhanced Input, exposes a movement-speed tunable, fires a Blueprint-bindable OnDied event, and is meant to be subclassed in Blueprint."
+    must_include:
+      - "Uses Enhanced Input (UInputAction + UInputMappingContext + UEnhancedInputComponent->BindAction, context added through UEnhancedInputLocalPlayerSubsystem) — NOT legacy Action/Axis mappings or InputComponent->BindAxis"
+      - "Class derives from ACharacter (or APawn) and uses GENERATED_BODY(), not GENERATED_UCLASS_BODY()"
+      - "Components/refs kept alive via UPROPERTY() using TObjectPtr<T> rather than a raw UObject*/AActor* member"
+      - "Adds the input mapping context in BeginPlay (or on possession), not in the constructor, and does no gameplay logic in the constructor"
+      - "Exposes the speed tunable with UPROPERTY(EditAnywhere, BlueprintReadWrite) and marks it UCLASS(Blueprintable) for the Blueprint subclass"
+      - "Declares the death event as a DECLARE_DYNAMIC_MULTICAST_DELEGATE... with a UPROPERTY(BlueprintAssignable) member and Broadcast()s it (dynamic, not plain multicast)"
+      - "Lists the EnhancedInput module dependency in the .Build.cs"

package/skills/shared/unreal/references/blueprint-cpp-parity.md

@@ -0,0 +1,109 @@
+# Blueprint ↔ C++ parity (UE5)
+
+Blueprint and C++ compile to the same reflected types. This is the full mapping + the exposure
+specifiers + the hybrid (C++ base, Blueprint subclass) workflow.
+
+## Node ↔ C++ mapping
+
+| Blueprint node | C++ equivalent |
+| --- | --- |
+| Event BeginPlay | `virtual void BeginPlay() override;` — call `Super::BeginPlay()` first |
+| Event Tick (Delta Seconds) | `virtual void Tick(float DeltaSeconds) override;` (enable `PrimaryActorTick.bCanEverTick`) |
+| Construction Script | `virtual void OnConstruction(const FTransform& T) override;` |
+| Spawn Actor from Class | `GetWorld()->SpawnActor<AType>(Class, Loc, Rot, Params);` |
+| Spawn Actor Deferred + Finish | `SpawnActorDeferred<AType>(...)` then `UGameplayStatics::FinishSpawningActor(A, T)` |
+| Cast To `X` | `if (AX* P = Cast<AX>(Obj)) { … }` (null on failure — always check) |
+| Get Player Controller / Pawn / Character | `UGameplayStatics::GetPlayerController(this, 0)` / `GetPlayerPawn` / `GetPlayerCharacter` |
+| Get Game Mode / Game State | `GetWorld()->GetAuthGameMode<AMyGameMode>()` / `GetGameState<AMyGameState>()` |
+| Set Timer by Event / by Function | `GetWorldTimerManager().SetTimer(Handle, this, &A::Fn, Rate, bLoop, Delay);` |
+| Delay | `FTimerHandle` one-shot timer, or a latent node from C++ via `FLatentActionInfo` |
+| Print String | `UE_LOG(LogTemp, Warning, TEXT("x=%d"), X);` or `GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::Green, TEXT("hi"));` |
+| Bind Event to `OnClicked` / `OnComponentBeginOverlap` | `Button->OnClicked.AddDynamic(this, &U::Handler);` |
+| Get / Set variable | `UPROPERTY` member read/write |
+| Make / Break struct | aggregate init / field access on a `USTRUCT` |
+| Line Trace By Channel | `GetWorld()->LineTraceSingleByChannel(Hit, Start, End, ECC_Visibility, Params);` |
+| Attach Actor/Component to | `AttachToComponent(Parent, FAttachmentTransformRules::SnapToTargetNotIncludingScale)` |
+| Destroy Actor | `Destroy();` |
+
+## Expose C++ → Blueprint
+
+```cpp
+// --- Class visibility ---
+UCLASS(Blueprintable)         // can be subclassed as a Blueprint
+UCLASS(BlueprintType)         // can be used as a variable type / pin in Blueprint
+// (both are common together on gameplay classes)
+
+// --- Functions ---
+UFUNCTION(BlueprintCallable, Category="Combat")
+void Fire();                                  // impure node with exec pins (may have side effects)
+
+UFUNCTION(BlueprintPure, Category="Combat")
+float GetDamage() const;                      // pure node, no exec pins (read-only getter)
+
+UFUNCTION(BlueprintCallable, meta=(WorldContext="WorldContextObject"))
+static AItem* SpawnItem(UObject* WorldContextObject);   // static → library-style node
+
+// --- Properties ---
+UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stats")
+float Speed = 600.f;                          // editable in editor + get/set in BP graph
+
+UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category="Config")
+TSubclassOf<AWeapon> WeaponClass;             // pick a class in the editor; read-only in BP
+
+UPROPERTY(BlueprintAssignable, Category="Events")
+FOnDied OnDied;                               // dynamic multicast delegate, bindable in BP
+```
+
+Specifier cheats: `EditAnywhere` (instances + defaults) · `EditInstanceOnly` · `EditDefaultsOnly`
+(class defaults only) · `VisibleAnywhere` (read-only in editor). `BlueprintReadWrite` (get+set) vs
+`BlueprintReadOnly` (get only). `meta=(AllowPrivateAccess="true")` exposes a `private` member.
+`meta=(ClampMin="0", ClampMax="100")` bounds a numeric field in the editor.
+
+## Call Blueprint ← C++ (overridable hooks)
+
+Two ways to let a Blueprint subclass provide/override behavior a C++ base invokes:
+
+```cpp
+// (1) Implemented entirely in Blueprint. C++ declares it and calls it; there is NO C++ body.
+UFUNCTION(BlueprintImplementableEvent, Category="Events")
+void OnScored(int32 Points);
+
+// (2) C++ gives a default implementation; Blueprint MAY override (and can call Parent).
+UFUNCTION(BlueprintNativeEvent, Category="Events")
+void OnDamaged(float Amount);
+void AMyActor::OnDamaged_Implementation(float Amount)   // note the _Implementation suffix
+{
+    Health = FMath::Max(0.f, Health - Amount);
+}
+
+// Call BOTH from C++ by their plain names — the reflected thunk dispatches to BP if overridden:
+void AMyActor::ApplyHit(float Dmg) { OnDamaged(Dmg); OnScored(10); }
+```
+
+To call an arbitrary Blueprint-defined function by name (rare — prefer the hooks above):
+`FindFunction(FName("MyFn"))` + `ProcessEvent(Fn, &Params)`.
+
+## The hybrid workflow (recommended default)
+
+1. **C++ base class** (`UCLASS(Blueprintable)`): fields, systems, tick/perf-critical logic,
+   the math. Expose tunables (`UPROPERTY(EditAnywhere, BlueprintReadWrite)`) and hooks
+   (`BlueprintImplementableEvent` / `BlueprintNativeEvent`).
+2. **Blueprint subclass** (Content Browser → Blueprint Class → pick your C++ class): designers
+   set default values, assign meshes/materials/sounds/`TSubclassOf` refs, and script the hooks
+   and per-instance behavior on the graph.
+3. **Spawn/reference the Blueprint class**, not the C++ class, from the game (via a
+   `TSubclassOf<AMyActor>` UPROPERTY the designer fills in) — otherwise the Blueprint's default
+   values and graph never run.
+
+Why: C++ gives speed, testability, and clean git diffs; Blueprint gives fast iteration and a
+designer-editable surface. The reflection macros are the seam that keeps both in sync.
+
+## Gotchas
+
+- A `BlueprintAssignable` delegate must be a **dynamic** multicast (`DECLARE_DYNAMIC_MULTICAST_DELEGATE…`);
+  a plain multicast delegate won't show in Blueprint.
+- `AddDynamic` handlers must be `UFUNCTION`s; a non-`UFUNCTION` method silently fails to bind.
+- Overriding a `BlueprintNativeEvent` in C++ means overriding `Fn_Implementation`, never `Fn`.
+- Changing a `UFUNCTION`/`UPROPERTY` signature is a header change → full recompile, not Live Coding.
+- Renaming a C++ property that a Blueprint references breaks the pin; use
+  `UPROPERTY(meta=(DeprecatedProperty))` or a Core Redirect to migrate.

package/skills/shared/unreal/references/gameplay-framework.md

@@ -0,0 +1,95 @@
+# UE5 Gameplay Framework — responsibilities & flow
+
+The Gameplay Framework is Unreal's opinionated skeleton for a game. Put each responsibility in
+the class that owns it; fighting the framework is the usual cause of "where does this code go?"
+
+## The classes
+
+### AActor
+Base for anything with a presence in a level — placed or spawned at runtime. Holds a tree of
+components rooted at `RootComponent` (a `USceneComponent` giving it a transform). Actors are
+GC'd UObjects; spawn with `SpawnActor<T>()`, remove with `Destroy()`. Everything below is an
+Actor except components.
+
+### UActorComponent / USceneComponent / UPrimitiveComponent
+Reusable, composable behavior/data attached to an Actor.
+- `UActorComponent` — logic/data, no transform (e.g. an inventory or health component).
+- `USceneComponent` — adds a transform; can be attached in a hierarchy.
+- `UPrimitiveComponent` — a scene component with geometry that renders/collides
+  (`UStaticMeshComponent`, `USkeletalMeshComponent`, `UCapsuleComponent`, `UBoxComponent`).
+Prefer composition (small components) over deep Actor inheritance.
+
+### APawn
+An Actor that a controller can **possess** and drive. Minimal by itself (add a mesh + movement
+if you want them). Use a bare Pawn for non-humanoid controllables (a ship, a camera, a ball).
+
+### ACharacter
+A Pawn preconfigured for a walking humanoid: `UCapsuleComponent` (collision), a
+`USkeletalMeshComponent`, and a `UCharacterMovementComponent` that implements walking, falling,
+jumping, crouching, and swimming — all **network-replicated** with client prediction. In 2D,
+`APaperCharacter` is the equivalent with a flipbook mesh.
+
+### AController / APlayerController / AAIController
+The "brain" that possesses a Pawn. The Pawn is the body; the controller persists across
+possession changes.
+- `APlayerController` — one per human player: receives input, owns the camera
+  (`PlayerCameraManager`), owns/creates the player's UI, and is the client's authority link.
+  Input setup and HUD widgets live here (or on the Character it possesses).
+- `AAIController` — drives an AI Pawn (behavior tree, perception, navmesh pathing).
+
+### APlayerState
+Per-player **replicated** data that must survive the Pawn dying/respawning: display name, score,
+ping, team. Lives on every machine for every player. Do NOT put transient input here.
+
+### AGameModeBase / AGameMode
+The **rules** of the current level/match. Defines the default classes (`DefaultPawnClass`,
+`PlayerControllerClass`, `HUDClass`, `GameStateClass`, `PlayerStateClass`), handles login and
+where/what to spawn for a joining player. **Exists only on the server / authority** — clients
+have `nullptr`. Use `AGameModeBase` (lean) by default; use `AGameMode` only when you need its
+`MatchState` machine (WaitingToStart → InProgress → …) for match-based multiplayer.
+
+### AGameStateBase / AGameState
+Game-wide state that **all clients** need to see: current match phase, shared/team score, the
+replicated array of `APlayerState`. Replicated from the server. This is how clients learn
+game-level facts (the GameMode that owns those facts is server-only).
+
+### AHUD / UUserWidget
+On-screen UI. `AHUD` is the legacy immediate-mode canvas; **prefer UMG** — build a `UUserWidget`,
+`CreateWidget` + `AddToViewport` from the `APlayerController`.
+
+## Where does my code go?
+
+| I need to… | Put it on |
+| --- | --- |
+| Read input, move the camera, open menus | `APlayerController` (or the possessed `Character`) |
+| Store score/name that survives respawn | `APlayerState` |
+| Decide who wins, when the match starts, where to spawn | `AGameModeBase` (server) |
+| Share match phase / team score with all clients | `AGameStateBase` (replicated) |
+| Make a thing that walks and jumps | `ACharacter` / `APaperCharacter` |
+| Make a reusable ability (health, inventory) | a `UActorComponent` added to the owner |
+| Make a placeable prop / pickup / trigger | `AActor` with the right components |
+
+## Startup / spawn order (server or standalone)
+
+```
+Level loads
+  → GameMode spawned (authority only)
+    → for each player: PlayerController spawned
+      → GameMode spawns the Pawn/Character (DefaultPawnClass) at a PlayerStart
+        → PlayerController Possesses the Pawn
+          → PlayerState created & associated
+  → GameState spawned and replicated to clients
+  → All actors: PostInitializeComponents → BeginPlay
+```
+
+Client join adds: connect → PlayerController (client proxy) → GameState/PlayerState replicate
+down → possessed Pawn replicates down. Remember: the client never sees the GameMode.
+
+## Possession pattern
+
+```cpp
+// Give a player a new body (e.g. respawn or vehicle enter):
+APlayerController* PC = UGameplayStatics::GetPlayerController(this, 0);
+ACharacter* NewBody = GetWorld()->SpawnActor<ACharacter>(BodyClass, SpawnT);
+PC->Possess(NewBody);          // controller now drives NewBody; input/camera follow
+```