<!-- skill: Unreal Engine | version: 1.0.0 | description: Build games in UE5 — Blueprints to C++, Nanite/Lumen, packaging | category: Games -->

## Instructions
- Start Blueprint-first for gameplay prototyping, convert hot paths and systems to C++ once the design is proven. `BlueprintNativeEvent` bridges both.
- Project hygiene: `Content/ProjectName/` folders (Maps, Blueprints, Meshes, Materials, Audio), no loose root assets, redirectors fixed immediately (Right-click > Fix Up).
- Performance budget early: Nanite for dense static geo, Lumen for dynamic GI — but profile on TARGET hardware (`stat unit`, `stat gpu`), and know the fallback (baked lighting, LODs) for weak machines like a Pi (which cannot run UE5 editor — develop on desktop).
- Input: Enhanced Input System (mapping contexts per state: menu/gameplay/vehicle). Never use raw key events in actors.
- Game flow: GameMode + GameState + PlayerController + SaveGame; persistence via SaveGame slots, settings via GameUserSettings.
- Source control: Git LFS for uassets, `.gitignore` (Binaries/, DerivedDataCache/, Intermediate/, Saved/), one person per map or use locking.
- Cooking matters: cook early (`File > Cook Content`) — uncooked references, missing redirectors, and editor-only nodes surface at cook time, not in PIE.
- Blueprints stay readable: pure functions for math, collapsed graphs with named sections, macro libraries for repeats, max ~30 nodes per graph before splitting into functions.
- Collision done once: custom trace/object channels per project (`Project Settings > Collision`), simple-box collision for gameplay meshes, complex-as-simple only for static backdrops.
- Audio: Sound Cues + attenuation + concurrency limits (max voices per class) so 50 gunshots don't stack into distortion; master/submix hierarchy for volume + mute groups.
- Save discipline: `SaveGame` objects versioned (`SaveVersion` int, migrate on load), settings in `GameUserSettings` + `ApplySettings`, autosave slot rotation (3 slots, never one).
## Examples
- Third-person template → retarget own character (IK Rig + Retargeter) → custom ability with Gameplay Ability System or plain component.
- Menu flow: MainMenu map → buttons (Start/Settings/Quit) via UMG widget switcher → OpenLevel with loading screen.
- Pickup system: `SphereComponent` overlap → interface call `IPickupable::Pickup` → DataTable row drives mesh/icon/effect — no per-item Blueprint.
## Workflows
1. Template project → folders → core loop gray-boxed (player, goal, fail).
2. Systems (health/inventory/dialogue) as Components + data (DataTables/CurveTables).
3. Content pass: meshes, materials (Material Instances, never duplicate masters), audio mix.
4. Optimization pass: stat unit < 16ms target, Nanite triangle counts, texture budgets, packaged dev build test.
5. Package (Project Launcher profiles per platform) → playtest packaged build, never ship editor-tested only.
6. Post-launch: crash reporter triage (top 3 callstacks first), hotfix branch per release, cooked patch/DLC test before pushing.
## Templates
```cpp
// HealthComponent.h — reusable C++ component pattern
UCLASS(ClassGroup=(Custom), meta=(BlueprintSpawnableComponent))
class UHealthComponent : public UActorComponent {
  GENERATED_BODY()
public:
  UPROPERTY(EditAnywhere, BlueprintReadWrite) float MaxHealth = 100.f;
  UPROPERTY(BlueprintReadOnly) float Health;
  UFUNCTION(BlueprintCallable) void Damage(float Amount);
  DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnDied);
  UPROPERTY(BlueprintAssignable) FOnDied OnDied;
};
```
```cpp
// Damage implementation — clamp, broadcast once, Blueprint-hookable
void UHealthComponent::Damage(float Amount) {
  if (Health <= 0.f || Amount <= 0.f) return;
  Health = FMath::Clamp(Health - Amount, 0.f, MaxHealth);
  if (Health <= 0.f) OnDied.Broadcast();
}
```
- Enhanced Input mapping-context asset: `IA_Move (WASD+stick)` / `IA_Look (mouse+stick)` / `IA_Jump`, gameplay context vs UI context swapped on menu open.
- DataTable row struct pattern: `FItemRow : public FTableRowBase` with `Name/Text/Price/Mesh/EffectClass` — designers fill rows, code reads rows.
## Tools
- UE5 editor needs a real GPU desktop — not the Pi. SARAH manages docs, checklists, config/data files around the project.
- Automation: Unreal Automation Tool (BuildCookRun), config `.ini` edits via file tools.
- `stat unit`, `stat game`, `stat gpu`, `stat rhi` console commands for frame triage; Unreal Insights (`Trace`) for deep captures.
## Advanced
- GAS vs components: Gameplay Ability System pays off past ~10 abilities with replication; below that, plain `UActorComponent` + interfaces ship faster and debug easier.
- Replication: `ReplicatedUsing=OnRep_` + `GetLifetimeReplicatedProps` for state, RPCs (`Server/NetMulticast`) for events, relevancy + dormancy for scale; test with 2 PIE clients + dedicated server checked from day one.
- Materials: Material Instances with scalar/vector params (never duplicate master graphs); texture streaming pools sized per platform (`r.Streaming.PoolSize`), virtual textures for big landscapes.
- World Partition + Data Layers for open worlds (streaming cells, HLOD layers); Level Instances for collaborative multi-dev maps.
- Packaging profiles: Development (console + debug) → Test (near-shipping) → Shipping (no console); `Project Launcher` custom profiles per store (Steam/Epic) with DLC/chunk config.
- Troubleshooting: black materials in packaged build → uncooked/unreferenced assets (add to Asset Manager primary lists); Blueprint nativization crash → disable nativization, move logic to C++; 100% shader compiles on load → DerivedDataCache misconfigured or version mismatch; multiplayer works in PIE but not packaged → replication/collision defaults differ, check `DefaultEngine.ini` net driver.
## Documentation
- UE5 docs: https://dev.epicgames.com/documentation/unreal-engine
- C++ API: https://dev.epicgames.com/documentation/en-us/unreal-engine/API
- Enhanced Input: https://dev.epicgames.com/documentation/en-us/unreal-engine/enhanced-input-in-unreal-engine

## Templates
```cpp
// HealthComponent.h — reusable C++ component pattern
UCLASS(ClassGroup=(Custom), meta=(BlueprintSpawnableComponent))
class UHealthComponent : public UActorComponent {
  GENERATED_BODY()
public:
  UPROPERTY(EditAnywhere, BlueprintReadWrite) float MaxHealth = 100.f;
  UPROPERTY(BlueprintReadOnly) float Health;
  UFUNCTION(BlueprintCallable) void Damage(float Amount);
  DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnDied);
  UPROPERTY(BlueprintAssignable) FOnDied OnDied;
};
```

## Tools
- UE5 editor needs a real GPU desktop — not the Pi. SARAH manages docs, checklists, config/data files around the project.
- Automation: Unreal Automation Tool (BuildCookRun), config `.ini` edits via file tools.

## Documentation
- UE5 docs: https://dev.epicgames.com/documentation/unreal-engine
- C++ API: https://dev.epicgames.com/documentation/en-us/unreal-engine/API