unreal-engine · diff
git:20260911.25436b5 to git:20261005.2bc0998
52 added, 80 removed. Audit A to A.
---
name: unreal-engine
description: "Build Unreal Engine workflows with Blueprints, C++, editor Python, and Unreal Automation Tool build or packaging jobs."
category: game-engines
risk: safe
source: self
source_type: self
date_added: "2026-08-26"
- tags: ["unreal-engine", "ue5", "unreal-python", "blueprints", "uat", "buildcookrun", "claude"]
+ tags: ["unreal-engine", "ue5", "unreal-python", "uat", "buildcookrun", "headless", "deterministic"]
tools: ["claude", "cursor", "gemini", "codex"]
---
# Unreal Engine 5 Editor & Pipeline AI Skill Guide (Claude)
## Overview & Engine Architecture
- Unreal Engine 5 is a high-fidelity real-time engine centered on **UObject reflection**, **Blueprints**, **C++ gameplay modules**, and editor extensibility via **Editor Utility Widgets**, **Python Editor scripting**, and **Unreal Automation Tool (UAT)**. Rendering pillars include **Nanite**, **Lumen**, and the **Niagara** VFX system. Claude operates as a Principal UE Technical Director, specializing in **Python editor automation**, **module/target.cs hygiene**, **asset migration**, and **BuildCookRun packaging**.
- ### Unreal Engine 5 Core Stack
+ Unreal Engine 5.x combines **UObject/C++**, **Blueprints**, **Editor Python (`import unreal`)**, and **UAT BuildCookRun** packaging. Rendering: **Nanite, Lumen, Niagara**. Claude acts as Principal UE TD: **editor automation only in Python**, **deterministic cooked builds**, **World Partition / Data Layers**, **no game-thread blocking in tools**.
+ **Version pin:** Engine association in `.uproject` (e.g. `5.4`, `5.5`) — CI must build with matching `EngineAssociation` and `-engine=` path.
+
```
┌─────────────────────────────────────────────────────────────┐
- │ Unreal Engine 5 Architecture │
- │ │
- │ Gameplay Framework │
- │ ├── UObject / AActor / APawn / ACharacter / UActorComponent│
- │ ├── GameMode / GameState / PlayerController │
- │ └── Blueprints + C++ (REFLECTION UCLASS/UFUNCTION) │
- │ │
- │ Editor & Automation │
- │ ├── Python Editor Scripting (`unreal` module) │
- │ ├── Editor Utility Blueprints / Widgets │
- │ └── UAT / BuildCookRun / Gauntlet │
- │ │
- │ Rendering & Content │
- │ ├── Nanite / Lumen / Virtual Shadow Maps │
- │ ├── Niagara / Chaos Physics │
- │ └── Asset Registry / DataLayers / World Partition │
+ │ Editor Python / UBT → Cook → Stage → Pak → Archive │
+ │ UnrealEditor-Cmd.exe -ExecutePythonScript=... │
+ │ RunUAT.bat BuildCookRun -project=... -platform=Win64 │
└─────────────────────────────────────────────────────────────┘
```
---
- ## Operational Capabilities & Agent Directives
+ ## When to use / when not to
- 1. **Python for Editor Ops**: Use `import unreal` for batch renaming, material assignment, level validation - not for shipping game runtime.
- 2. **C++ Module Discipline**: Keep public headers minimal; use `UCLASS`, `UPROPERTY`, `UFUNCTION` correctly for GC and Blueprint exposure.
- 3. **World Partition Awareness**: Prefer Data Layers and streaming-safe actor placement over monolithic persistent levels for large worlds.
- 4. **Cook/Package Automation**: Drive packaging through UAT `BuildCookRun` with explicit `-platform`, `-clientconfig`, and `-archivedirectory`.
- 5. **Never Block the Game Thread**: Move heavy I/O and procedural work off the game thread; respect Slate/editor tick constraints in tools.
+ **Use when:** batch asset fixes, validation, packaging, render queue via Movie Render Queue (MRQ), commandlet-style automation.
+ **Do not use when:** `import unreal` in shipped game modules — Python is Editor-only. Do not assume Python works in packaged game.
+
---
- ## Production Python: Batch Rename Static Meshes in Content Browser
+ ## Operational Capabilities & Agent Directives
- Run from Output Log / Editor Python, or `UnrealEditor-Cmd.exe` with `-ExecutePythonScript=`:
+ 1. **Python scope**: Run via Editor, `UnrealEditor-Cmd`, or `-ExecutePythonScript=` — never in runtime game code.
+ 2. **UAT packaging**: Explicit `-platform`, `-clientconfig=Development|Shipping`, `-archivedirectory`, `-pak`; log `Saved/Logs`.
+ 3. **Deterministic cooks**: Pin `-cookflavor`, disable stray `-iterate` when you need clean QA; store `Build.version` artifact; for MRQ use fixed **warm-up frames**, **seed** in sequencer settings, fixed **anti-aliasing** samples.
+ 4. **Color**: OCIO / OpenColorIO for MRQ; sRGB vs linear EXR outputs — tag output format in job preset; Lumen exposure can vary slightly GPU-to-GPU — document tolerance for pixel tests.
+ 5. **Maps list**: Packaging fails if maps missing from **Project Settings → Packaging** — automate validation Python that reads `ProjectSettings` packaging maps.
+ 6. **Live Coding**: Disable in CI — hot reload causes nondeterministic Blueprint compile state.
- ```python
- # ==============================================================================
- # UE5 Editor Python: prefix-rename selected Static Mesh assets
- # ==============================================================================
- import unreal
+ ---
- PREFIX = "SM_Hero_"
- asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
- editor_util = unreal.EditorUtilityLibrary
- system_lib = unreal.SystemLibrary
- editor_asset_lib = unreal.EditorAssetLibrary
+ ## Production Python: validate packaging maps
- selected = editor_util.get_selected_assets()
- if not selected:
- unreal.log_warning("No assets selected.")
- else:
- rename_data = []
- for asset in selected:
- if not isinstance(asset, unreal.StaticMesh):
- unreal.log(f"Skip non-static-mesh: {asset.get_name()}")
- continue
- old_name = asset.get_name()
- if old_name.startswith(PREFIX):
- continue
- path = asset.get_path_name()
- package_path = path.rsplit("/", 1)[0]
- new_name = PREFIX + old_name
- rename_data.append(
- unreal.AssetRenameData(asset, package_path, new_name)
- )
- unreal.log(f"Queue rename: {old_name} -> {new_name}")
+ ```python
+ import unreal
- if rename_data:
- asset_tools.rename_assets(rename_data)
- unreal.log(f"Renamed {len(rename_data)} assets.")
+ settings = unreal.get_default_object(unreal.ProjectPackagingSettings)
+ maps = list(settings.get_editor_property("maps_to_cook"))
+ unreal.log(f"Maps to cook: {len(maps)}")
+ for m in maps:
+ if not unreal.EditorAssetLibrary.does_asset_exist(m):
+ raise RuntimeError(f"Missing map asset: {m}")
+ unreal.log("Packaging map validation OK")
```
+ Run: `UnrealEditor-Cmd.exe "Game.uproject" -ExecutePythonScript=validate_maps.py -stdout -unattended -nop4 -nosplash`
+
---
- ## Technical Troubleshooting Matrix
+ ## UAT BuildCookRun (Windows)
- | Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
- | :--- | :--- | :--- |
- | **Python `unreal` import fails outside Editor** | Module only exists in Editor/Cmd editor builds. | Run via Editor Python or `UnrealEditor-Cmd` with ExecutePythonScript. |
- | **Packaging fails on missing maps** | Maps not in Project Settings → Packaging → List of maps. | Add maps / use `-allmaps` carefully; verify Asset Registry. |
- | **Blueprint compile errors after C++ change** | Hot reload / Live Coding mismatch. | Restart editor or rebuild target; fix UPROPERTY breakage. |
- | **Nanite mesh looks wrong** | Unsupported features or fallback mesh. | Check Nanite settings; validate material domain and WPO usage. |
+ ```bat
+ Engine\Build\BatchFiles\RunUAT.bat BuildCookRun ^
+ -project="C:\Game\Game.uproject" ^
+ -noP4 -platform=Win64 -clientconfig=Shipping ^
+ -build -cook -stage -pak -archive ^
+ -archivedirectory="C:\Game\Dist"
+ ```
+ **Headless:** `-unattended -stdout` on Cmd editor; `-NullRHI` for some commandlets — not for GPU MRQ.
+
---
- ## Essential CLI Patterns
+ ## Failure taxonomy
- ```bash
- # UAT BuildCookRun (example Windows)
- RunUAT.bat BuildCookRun ^
- -project="C:\work\MyGame\MyGame.uproject" ^
- -platform=Win64 -clientconfig=Development ^
- -build -cook -stage -pak -archive ^
- -archivedirectory="C:\work\MyGame\Dist"
- ```
+ | Symptom | Cause | Fix |
+ | :--- | :--- | :--- |
+ | `unreal` import fails | Running outside Editor | Use Editor-Cmd |
+ | Cook missing asset | Never saved / redirector | Resave content; fix up redirectors |
+ | Shader compile storm | New RHI / clean DDC | Warm DDC cache in CI |
+ | MRQ flicker | Temporal AA / Lumen | Fixed sample count; disable temporal for golden |
+ | Python rename silent fail | Asset registry not refreshed | `unreal.EditorAssetLibrary.save_directory` |
- ### Essential Paths
- - **Project**: `*.uproject`, `Source/`, `Content/`, `Config/`
- - **Engine**: `Engine/Build/BatchFiles/RunUAT.bat`
- - **Saved logs**: `Saved/Logs/`
+ GitHub/community: BuildCookRun `-clean` when upgrading engine minor — stale `DerivedDataCache` causes obscure cook failures.
---
## Agent Operational Directive
- > **MANDATORY**: Use Python/`unreal` for editor automation only. For packaging, prefer UAT BuildCookRun with explicit platform and config. Preserve UObject reflection macros when exposing C++ to Blueprints.
+
+ > **MANDATORY**: Editor Python only. Pin engine version. Validate maps before UAT. For pixel-regression renders, fix MRQ warm-up, exposure, and output color space; document GPU variance.