1---2name: unreal3description: Use for Unreal Engine 4/5 games — C++ gameplay, Blueprints, Actors/UCLASS, Gameplay Ability System, asset pipeline, performance. Triggers — .uproject/.uasset, 'unreal', 'ue4', 'ue5', 'blueprint'.4---56# Unreal Engine Development78## When to use9- Writing or reviewing Unreal C++ gameplay classes, components, or subsystems10- Designing or debugging Blueprint graphs11- Setting up asset import pipelines, LODs, or streaming12- Profiling and fixing CPU/GPU frame-time issues13- Configuring build targets, packaging, and platform-specific settings14- Integrating third-party plugins or Marketplace assets1516## Workflow17181. **Classify the task** — gameplay logic, rendering, physics, UI (UMG), networking, build/package, or asset pipeline.192. **Confirm UE version** — UE4 vs UE5 (Nanite, Lumen, PCG, Motion Matching differ significantly). Check `UE_VERSION` in `Build.cs` or the `.uproject` file.203. **Choose the right abstraction layer**:21 - Pure game logic → C++ `AActor` / `UActorComponent` subclass.22 - Designer-facing behaviour → expose via `UPROPERTY(EditAnywhere, BlueprintReadWrite)` and `UFUNCTION(BlueprintCallable)`.23 - Prototype quickly → Blueprint; port hot paths to C++ once stable.244. **Scaffold the class** using the UE editor wizard (`New C++ Class`) to get correct macros, module includes, and `UCLASS()`/`USTRUCT()` boilerplate auto-generated.255. **Add headers conservatively** — include only what the `.cpp` needs; forward-declare in `.h`. Slow compile times are the biggest UE productivity killer.266. **Implement and wire up**:27 - Override lifecycle hooks in the correct order: `PostInitializeComponents → BeginPlay → Tick → EndPlay`.28 - Register delegates with `AddDynamic` for Blueprint-compatible events.297. **Test in PIE** (Play-In-Editor) before packaging. Use `stat unit`, `stat fps`, and the Session Frontend Profiler to catch regressions immediately.308. **Profile with Unreal Insights** for CPU traces; **RenderDoc** or **Nvidia Nsight** for GPU.319. **Package** via `Project → Package Project` (or `RunUAT BuildCookRun`) targeting the platform. Check log for cook errors before QA.3210. **Audit** against .claude/checklists/performance.md and .claude/checklists/security.md before shipping.3334## Standards3536### C++ conventions37- Every exposed UObject must have `GENERATED_BODY()` and a valid module in `Build.cs`.38- Use `TObjectPtr<>` (UE5) instead of raw `UObject*` pointers — enables GC tracking.39- Prefer `FName`/`FText`/`FString` for the correct semantic purpose: `FName` for identity, `FText` for UI, `FString` for manipulation.40- Mark read-only Blueprint references `BlueprintReadOnly`; expose mutators through explicit `UFUNCTION`.41- Keep `Tick()` bodies under 0.1 ms. Move anything heavier to async tasks, timers, or events.42- Log with `UE_LOG(LogYourCategory, Warning, TEXT("..."))` — never `printf`.4344### Blueprints45- Blueprints own visual state and designer-tweakable data; C++ owns logic and performance-critical paths.46- Compile all Blueprints before packaging (`Editor → Blueprints → Compile All Blueprints`).47- Name events and variables explicitly — avoid default `NewVar_0` names.4849### Asset pipeline50- Import source assets at full resolution; use LOD groups and Nanite (UE5) for runtime resolution.51- Texture sizes must be power-of-two; use `BC7` for colour, `BC5` for normal maps, `BC4` for greyscale.52- Redirect assets via `Asset Manager` instead of direct `StaticLoadObject` — supports async loading.5354### Networking (multiplayer)55- Mark server-authoritative state `Replicated` and `UPROPERTY(ReplicatedUsing=OnRep_*)`.56- RPCs: Server (`_Implementation`), Client, NetMulticast — validate authority with `HasAuthority()`.57- Never trust client input; validate on the server before applying.5859### Do not60- Do not call `LoadObject` / `StaticFindObject` at runtime in shipping builds — use Soft References and async load.61- Do not tick actors that don't need per-frame updates; disable with `PrimaryActorTick.bCanEverTick = false`.62- Do not use global `GEngine->AddOnScreenDebugMessage` in shipping; wrap in `#if !UE_BUILD_SHIPPING`.63- Do not commit intermediate `.uasset` binary conflicts — always re-save through the editor after a merge.6465## Common mistakes to avoid6667| Mistake | Fix |68|---|---|69| Holding `UObject*` in non-UObject classes without `UPROPERTY` | The GC will collect it mid-frame. Use `UPROPERTY` or `FWeakObjectPtr`. |70| Calling `BeginPlay` logic in the constructor | Constructors run in the editor on CDO; use `BeginPlay` for runtime init. |71| Hot-reloading C++ with live delegates bound | Can crash the editor; unbind delegates in `EndPlay` before reloading. |72| Streaming levels that stall the game thread | Always use async level loading (`LoadStreamLevel` with a delegate). |73| Packaging without cooking redirectors | Players see missing asset errors; run `Fix Up Redirectors` before cook. |74| Blueprint nativisation left enabled in UE4 | Produces brittle compiled code; disable unless specifically needed. |7576## Output format7778- New C++ class: `.h` and `.cpp` pair with full UE boilerplate, matching module includes in `Build.cs`.79- Blueprint guidance: numbered step-by-step with node names in `code` formatting.80- Profiling report: table of hotspots with ms budget vs. actual and one recommended fix each.81- Architecture decision: diagram description → rationale → trade-offs, referencing .claude/templates/architecture.md.8283## Related checklists84- .claude/checklists/performance.md85- .claude/checklists/security.md86- .claude/checklists/qa.md8788## Related agents89- .claude/agents/core/orchestrator.md90- .claude/agents/engineering/devops-engineer.md
muxammadmamajonov