# Unreal

> Expert game development with Unreal Engine - architecture, C++/Blueprint, rendering (RenderGraph/Nanite/Lumen), physics (Chaos), animation, AI, multiplayer, and performance.

- Skill: `j4flmao/unreal` (Agent Skill)
- Install (CLI): `npx skillmds@latest add j4flmao/unreal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/j4flmao/unreal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: j4flmao (https://skillmd.com/u/j4flmao)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/j4flmao/unreal

---


# Unreal Engine Deep Engineering Guide

Unreal Engine is a C++ game engine with a powerful actor-component framework (UObject/AActor), Blueprint visual scripting, the Chaos physics system, and the modern rendering stack built on RenderGraph, Nanite virtualized geometry, and Lumen GI.

## 1. Engine Architecture

```
Unreal Engine 5
  Modules (UObject-based reflection)
    Core, Engine, Renderer, RHI (D3D12/Vulkan/Metal), Niagara, Chaos
  Engine loop -> UEngine::Tick -> UWorld::Tick -> Actor::Tick
  GWorld: The current UWorld (loaded levels)
```

- `UObject` base: GC (garbage collector), reflection (UFUNCTION/UPROPERTY), serialization.
- `AActor`: spawnable entity; placement via `UWorld::SpawnActor<T>()`.
- `UActorComponent`: reusable behavior attached to actors.

### 1.1 The Game Framework

| Class | Role |
|-------|------|
| `UGameInstance` | Per-process, survives level loads, global save data |
| `UWorld` | The active level + subsystems (GameMode, GameState) |
| `AGameModeBase` | Rules: spawn points, teams, win condition (server-only) |
| `AGameStateBase` | Replicated match state |
| `APlayerController` | Input + view; replicated to owner |
| `APawn`/`ACharacter` | The controllable entity |

Rule: GameMode is server-only; never game logic from clients. Use `GameState` for replicated data.

## 2. UObject Reflection & C++ / Blueprint

### 2.1 Macros

```cpp
UCLASS()
class MYGAME_API APlayerCharacter : public ACharacter {
    GENERATED_BODY()
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stats")
    int32 MaxHealth = 100;

    UFUNCTION(BlueprintCallable, Category="Stats")
    void Heal(int32 Amount);
};
```

- UPROPERTY: serialized, reflected, GC-tracked.
- UFUNCTION: callable from Blueprint/other C++, serialization of delegates.
- Naming: `U` prefix for UObject, `A` for Actor, `F` for structs, `T` for templates.

### 2.2 C++ vs Blueprint Decision

| Concern | Choose |
|---------|--------|
| Data, core logic, perf-critical hot loops | C++ |
| Designer-facing flow, tuning, event wiring | Blueprint |
| Heavy algorithms (async, math-costly) | C++ + Async tasks |
| Prototypes and small features early | Blueprint then port to C++ |

Rule: Blueprint is for content, C++ is for code. Keep hot paths in native.

### 2.3 Compilation & Deployment

- `Build.cs`/`Target.cs` (UBT). Module dependencies declared there.
- Hot Reload (Live Coding) in editor; full build via Build.bat.
- UE 5 compile times: keep modules small; use IWYU.
- `PCHUsage`, `CppWarnings`, UnityBuild.
## 3. Rendering Pipeline (Modern UE5)

### 3.1 RenderGraph

UE5 renderer records a DAG of passes; the RenderGraph merges/splits passes, computes transient resources, and drives barriers automatically:

```
SceneColorInit -> BasePass (GBuffer) -> LightCulling -> DeferredShading
               -> Reflection capture -> Sky -> Translucency -> PostProcess -> Present
```

Resources auto-lifecycled (scopes), driver-managed. You can author custom passes via `FRenderingCompositePass` or `FSceneRenderer`.

### 3.2 Nanite

- Virtualized geometry: clusters, hierarchical LOD (HLOD), custom datastreams.
- Efficient for high-poly static meshes; NOT for skinned/animated meshes (fallback classic LODs).
- Enable on large static scenes; avoid vertex-modifying effects.

### 3.3 Lumen

- Global illumination (GI) via radiance cache (software ray tracing), optionally hardware RT.
- GPU-heavy; disable on low-end; control with `Lumen.` console vars.
- For stylized/flat art, skip Lumen; use precomputed lightmaps.

### 3.4 Niagara Particles

- GPU/CPU emitters; prefer `NiagaraDataInterfaceArrays` for bulk data.
- Minimize material complexity in particle shaders.

## 4. Physics — Chaos

- Chaos replaced PhysX in UE5.
- `FPhysicsSolver` fixed substep at `PhysicsSubstep` (default 0.0083s).
- `USceneComponent::SetSimulatePhysics(true)` to enable RigidBody.
- Contact: `OnComponentHit` / `OnComponentBeginOverlap` delegates.
- Destruction: `AChaosDestructible` with geometry collections.

### 4.1 Tunneling & CCD

Fast small projectiles: enable `bCCDEnablePhysics` on the body; or use sweep `UKismetSystemLibrary::LineTraceSingle` per tick.

### 4.2 Level Streaming

`UWorld::StreamLevel` async; `RegisterActor`/`UnregisterActor` for hot unload.

## 5. Animation

- Animation Blueprint (AnimGraph): blend spaces, aim offset, state machine, layered blend per bone.
- Controls Rig (IK) via `UAnimationBlueprintLibrary`.
- Cached Pose / reduce `FAnimNode_*` graph cost.
- Root motion drives movement; `bUseControllerRotationYaw=false` for root-motion characters.

## 6. AI

- `UAIController` + `UBehaviorTree` + Blackboard.
- BT: Selector/Sequence nodes; decorators (conditions), services (refresh), tasks.
- `UNavigationSystemV1` for path finding; `NavMesh`/`NavLinkProxy`.
- `UAIPerceptionComponent` for senses.

## 7. Multiplayer / Netcode

### 7.1 Replication

- RPCs: `UFUNCTION(Server)` / `Multicast` / `Client`.
- Replicated properties: `UPROPERTY(Replicated)` + `GetLifetimeReplicatedProps`.
- `ReplicatedUsing` for on-rep callbacks.

### 7.2 Network Architecture

- Dedicated server (no rendering), or listen server (client+host).
- Tick rate: `NetServerMaxTickRate` (default 30) for server simulation.
- Client-side prediction with `ServerMove` RPC + `ClientAckGoodMove`.
- `UCharacterMovementComponent` handles built-in prediction/reconciliation.

### 7.3 Replication Optimization

- `Dormancy`: actors freeze replication when unchanged (`DORM_DormantAll`).
- `NetUpdateFrequency`: throttle per-actor replication (default 100Hz, reduce for background actors).
- Property conditions: `COND_OwnerOnly`, `COND_InitialOnly`.
- Push model (UE5): `MARK_PROPERTY_DIRTY` + `NET_SERIALIZATION`.

## 8. UI (UMG)

- Widget Blueprints (UMG) for in-game HUDs.
- `UUserWidget::NativeConstruct` for init; `NativeTick` for per-frame logic.
- Keep tick logic in C++ via `BlueprintNativeEvent`; avoid Blueprint Tick.
- `Invalidation Box` to reduce widget re-rendering.

## 9. Asset Pipeline

- Content Browser assets (.uasset) are binary, versioned, auto-serialized.
- Cook + Stage: `Cook.bat` + `Stage.bat` per platform.
- Asset Manager: async loading, soft references (`TSoftObjectPtr`, `TSoftClassPtr`).
- Hot-loaded assets via `AsyncLoadAsset` / `StreamableManager`.

## 10. Performance Rules (Lead Level)

1. Profile first: `stat unit`, `stat gpu`, `ProfileGPU`, `stat game`, Unreal Insights.
2. Minimize tick cost: disable tick on actors that don't need it; use timers for periodic logic.
3. Avoid `GetAllActorsOfClass` in tick; maintain manager lists.
4. Object pools for frequently spawned/destroyed actors.
5. GC: minimize UObject allocation in hot paths; use native allocators for transient data.
6. Shader complexity: keep material instruction count <200 for mobile, <500 for PC.
7. LODs mandatory for foliage, large scenes.

### 10.1 Frame Budget Template

| System | Budget (ms) @ 60fps |
|--------|---------------------|
| Gameplay (Tick) | 2.0 |
| Physics (Chaos) | 2.0 |
| Animation | 2.0 |
| AI / NavMesh | 1.5 |
| Rendering (CPU) | 3.0 |
| Rendering (GPU) | 8.3-14.0 |
| UI | 1.0 |
| Netcode | 1.0 |
| Misc / Driver | 2.0 |

## 11. Anti-Patterns

| Anti-pattern | Consequence | Fix |
|--------------|-------------|-----|
| Blueprint Tick heavy logic | Slow, GC | Move to C++ |
| Actor with no tick disabled | CPU wasted | Set bCanEverTick=false |
| Massive Blueprint inheritance chains | Hard to maintain, slow | Composition over deep inheritance |
| Not setting NetUpdateFrequency | Bandwidth | Lower on background actors |
| Full scene replication every frame | Network spike | Dormancy + conditions |
| Nanite on skinned meshes | Error | Fallback LODs |
| Lumen on low-end GPU | Frame drops | Disable or use baked GI |

## 12. When to NOT Use Unreal

- Mobile-only lightweight games → Unity, Godot, or native platform SDKs.
- Scripting-heavy tools/modding without C++ → Unity + C# or Godot + GDScript.
- Tiny canvas/2D games → Godot, Cocos2d, web engine.
- Maximum native rendering control with zero abstraction → Vulkan/custom engine.

## 13. References

- `skills/game/game-engine/ecs-pattern/SKILL.md` — ECS patterns, useful alongside Chaos/UObject
- `skills/game/game-engine/patterns/SKILL.md` — engine design pattern catalog
- `skills/game/multiplayer-netcode/SKILL.md` — netcode prediction and reconciliation
- `skills/game/game-development/vulkan/SKILL.md` — low-level GPU rendering under the RHI
- `skills/game/game-development/physics-engine/SKILL.md` — physics solver internals (Chaos)