90 added, 40 removed. Audit A to A.
---
name: unreal-systems
group: Unreal
description: >-
Work the C++/Blueprint continuum with Nanite, Lumen and the Gameplay Ability System. Use when
developing Unreal Engine gameplay in C++, Blueprints, or GAS.
---
- # Unreal Systems
- Work the C++/Blueprint continuum with Nanite, Lumen and the Gameplay Ability System..
+ # unreal-systems
- ## Process
+ ## Core Philosophy
+ Modern Unreal Engine 5 development is anchored by three technological pillars: **Nanite** (virtualized micropolygon geometry), **Lumen** (real-time dynamic global illumination and reflections), and the **Gameplay Ability System (GAS)**. Building scalable Unreal systems requires navigating the C++ vs Blueprint continuum: architecting core performance-critical mechanics and foundational types in clean C++, while exposing flexible tuning parameters, abilities, and cosmetic triggers to designers in Blueprints.
- 1. **Intake & Scope Definition**
- - Identify specific objectives, inputs, constraints, and operational context.
- - Inspect existing project documentation, configurations, or relevant repository assets.
+ ---
- 2. **Analysis & Strategic Formulation**
- - Evaluate options against best practices, security posture, and domain requirements.
- - Deconstruct complex components into discrete, actionable phases.
+ ## 4-Step Unreal Engine 5 Systems Architecture
- 3. **Execution & Synthesis**
- - Produce structured, production-grade deliverables matching the required format.
- - Ground all recommendations in concrete project evidence rather than abstract generalities.
+ ### Step 1: The C++ vs Blueprint Continuum
+ 1. **The Golden Rule**:
+ - **C++**: Math, algorithmic logic, data structures, multiplayer networking, file I/O, base actor classes, Gameplay Ability tasks.
+ - **Blueprints**: Visual assembly, animation state machine hooks, cosmetic audio/particle binding, rapid iteration tuning.
+ 2. **No Pure Blueprint Actors**:
+ - Every production Blueprint actor must derive from a custom C++ base class (`AMyGameCharacter -> BP_MyGameCharacter`). Never derive directly from native engine classes in Blueprint.
- 4. **Review & Refinement**
- - Validate against the verification checklist and domain edge cases.
- - Highlight open questions, explicit trade-offs, and next milestones.
+ ### Step 2: Gameplay Ability System (GAS) Architecture
+ 1. **The Core Components of GAS**:
+ - **`UAbilitySystemComponent` (ASC)**: The brain component attached to any character that can use abilities.
+ - **`UAttributeSet`**: Manages numerical attributes (Health, Stamina, Armor) with clamping and modification hooks:
+ - `PreAttributeChange()` and `PostGameplayEffectExecute()`.
+ - **Gameplay Tags (`FGameplayTag`)**: Hierarchical string-like identifiers for state and categorization (e.g. `State.Debuff.Stunned`, `Ability.Melee.HeavyAttack`).
+ - **Gameplay Effects (GE)**: Data-driven modifications to attributes (Instant damage, Duration buffs, Periodic poison).
+ - **Gameplay Abilities (GA)**: Scripted actions executed via Ability Tasks (e.g. *PlayMontageAndWait*).
- ## Deliverable & Output Format
+ ### Step 3: Nanite Virtualized Geometry Rules
+ 1. **Nanite Asset Standards**:
+ - Import high-poly ZBrush sculpts (1M - 10M triangles) directly without manual LOD generation.
+ - *Nanite Constraints*:
+ - Nanite does NOT support non-rigid deforming skeletal meshes (characters) in earlier UE5 versions; reserve for static meshes and rigid foliage.
+ - Avoid complex masked/translucent materials on Nanite geometry (forces software rasterizer fallback).
- ### 📋 Executive Summary
- - **Objective:** Key goal addressed
- - **Status:** Complete / Action Required
- - **Primary Recommendation:** Core actionable conclusion
+ ### Step 4: Lumen Global Illumination Optimization
+ 1. **Software vs Hardware Ray Tracing**:
+ - **Software Ray Tracing (Default)**: Uses Mesh Distance Fields and Global Distance Fields. Highly performant across consoles.
+ - **Hardware Ray Tracing (HWRT)**: Requires DX12 and dedicated ray-tracing GPU hardware.
+ 2. **Mesh Distance Field Hygiene**:
+ - Ensure all static meshes have manifold, two-sided geometry without open backfaces to prevent light leaking through walls.
- ### 🛠️ Detailed Implementation / Analysis
- - Concrete technical, operational, or strategic specifications.
- - Clear code, configuration, or documentation blocks where applicable.
+ ---
- ### 📌 Decisions & Next Steps
- - [ ] Immediate action items with designated owners.
- - [ ] Required dependencies or prerequisite milestones.
+ ## Deliverable Format: Production GAS Attribute Set (C++)
- ## Instructions & Operating Rules
+ ```cpp
+ // AttributeSetBase.h
+ #pragma once
+ #include "CoreMinimal.h"
+ #include "AttributeSet.h"
+ #include "AbilitySystemComponent.h"
+ #include "AttributeSetBase.generated.h"
- - Lead directly with actionable findings and structured results.
- - Never introduce speculative abstractions or unrequested complexity.
- - Maintain consistency with existing architecture and naming conventions.
- - Provide explicit rationales for non-obvious trade-offs.
+ #define ATTRIBUTE_ACCESSORS(ClassName, PropertyName) \
+ GAMEPLAYATTRIBUTE_PROPERTY_GETTER(ClassName, PropertyName) \
+ GAMEPLAYATTRIBUTE_VALUE_GETTER(PropertyName) \
+ GAMEPLAYATTRIBUTE_VALUE_SETTER(PropertyName) \
+ GAMEPLAYATTRIBUTE_VALUE_INITTER(PropertyName)
- ## Verification & Quality Checklist
+ UCLASS()
+ class UAttributeSetBase : public UAttributeSet {
+ GENERATED_BODY()
- - [ ] Deliverable directly satisfies all stated user requirements and criteria.
- - [ ] Edge cases, boundary conditions, and error states are addressed.
- - [ ] Output contains zero placeholder tokens, broken references, or unverified claims.
- - [ ] All cross-references and formatting comply with repository conventions.
+ public:
+ UAttributeSetBase();
- ## Anti-Patterns & Constraints
+ UPROPERTY(BlueprintReadOnly, Category = "Attributes")
+ FGameplayAttributeData Health;
+ ATTRIBUTE_ACCESSORS(UAttributeSetBase, Health)
- - **NEVER** output generic boilerplate without grounding in specific project inputs.
- - **NEVER** silently omit unresolved contradictions or unverified assumptions.
- - **NEVER** make unrequested modifications outside the stated deliverable boundary.
+ UPROPERTY(BlueprintReadOnly, Category = "Attributes")
+ FGameplayAttributeData MaxHealth;
+ ATTRIBUTE_ACCESSORS(UAttributeSetBase, MaxHealth)
+
+ virtual void PreAttributeChange(const FGameplayAttribute& Attribute, float& NewValue) override;
+ virtual void PostGameplayEffectExecute(const FGameplayEffectModCallbackData& Data) override;
+ };
+ ```
+
+ ---
+
+ ## Worked Example: Eliminating 14ms Hitching via C++ GAS Migration
+
+ - **Problem**: In a 4-player cooperative action RPG, casting a meteor storm ability caused a severe 14ms frame drop on all clients.
+ - **Diagnosis**: Profiling in Unreal Insights revealed that the meteor ability was authored entirely in Blueprint, spawning 80 individual Blueprint actors, each executing tick functions and heavy cast operations (`Cast<ABP_Enemy>`).
+ - **Optimization**:
+ 1. Migrated the meteor storm into a C++ `UGameplayAbility` using an asynchronous `UAbilityTask`.
+ 2. Replaced Actor spawning with batched Gameplay Effects targeting enemy ASCs directly via Gameplay Tags.
+ - **Outcome**: Ability activation frame time dropped from 14ms to 0.18ms with zero hitching.
+
+ ---
+
+ ## Verification Checklist
+
+ - [ ] All gameplay classes inherit from custom C++ base classes, not raw engine types.
+ - [ ] Attributes use the `ATTRIBUTE_ACCESSORS` macro and clamp values safely.
+ - [ ] State transitions orchestrated via hierarchical `GameplayTags`.
+ - [ ] Nanite enabled on high-poly static environment meshes.
+ - [ ] Mesh Distance Fields generate cleanly without light bleed in Lumen visualization views.
+
+ ---
+
+ ## Anti-Patterns
+
+ - **Casting in High-Frequency Blueprint Ticks**: Using `Cast To BP_Character` inside `Event Tick`, destroying CPU cache locality.
+ - **Hard Object References in Blueprints**: Directly referencing heavy textures or audio in Blueprints, causing the entire asset tree to load into RAM upon opening the level.
+ - **Overriding Health via Setters Instead of Gameplay Effects**: Directly setting character health values without routing through the Ability System Component, bypassing buffs, shields, and damage mitigation rules.