AI-Friendly Unreal C++ Guidelines

AI-Friendly Unreal C++ Code Guidelines

This skill provides guidance for writing Unreal Engine C++ code optimized for AI tool compatibility.

Core Principle

Human-friendly code = AI-friendly code

Research (arXiv 2601.02200v1) shows CodeHealth >= 9 reduces AI tool error rates by 15-30%.

Three Pillars

Pillar	Key Practices
Explicit Expression	this->, explicit types, namespaces, parameter names
Structural Clarity	One class per file, consistent ordering, header/source separation
Bounded Complexity	50-line functions, 3-level nesting, 4 parameters max

Quick Rules

Explicit Expression

// Use this-> for members
this->Health += Delta;

// Explicit types over auto
APlayerState* State = GetPlayerState();

// Full namespaces
UE::Math::FVector Position;

// Named parameters in headers
void SetTransform(FVector Location, FRotator Rotation, FVector Scale);

Structural Clarity

// One class per file
// MyActor.h -> AMyActor only

// Consistent section order
class AMyActor
{
public:    // Constructors, then public methods
protected: // Protected methods, then protected variables
private:   // Private methods, then private variables
};

// Forward declarations over includes
class UInventoryComponent;  // Instead of #include

Complexity Limits

Metric	Limit
Function length	<= 50 lines
Nesting depth	<= 3 levels
Parameters	<= 4 (use struct if more)

Use Early Return pattern to reduce nesting:

for (auto* Actor : Actors)
{
    if (!Actor) continue;
    if (!Actor->IsAlive()) continue;
    ProcessActor(Actor);
}

Unreal-Specific

• Type prefixes: A (Actor), U (UObject), F (struct), I (interface), E (enum), T (template)
• UPROPERTY metadata: Include Category, ToolTip, ClampMin/Max
• UFUNCTION metadata: Include DisplayName, Keywords
• TObjectPtr (UE5): Prefer over raw pointers in UPROPERTY
• Avoid complex macros: Use templates/functions instead

Issue Detection

When inspecting code, check for:

Critical Issues

• Functions > 100 lines
• Nesting > 3 levels
• Multiple classes per file
• Complex macros obscuring logic

Warnings

• Missing this-> on member access
• Unnecessary auto usage
• Missing parameter names in headers
• Functions 50-100 lines

Informational

• Missing Doxygen documentation
• Could use forward declarations
• Missing UPROPERTY metadata

Additional Resources

Reference Files

For detailed patterns and complete code examples:

• references/guidelines.md - Complete guidelines with all code examples
• references/checklist.md - Quick reference checklist for code review

Usage

When analyzing or refactoring code:

1. Read the target file(s)
2. Check against the three pillars
3. Identify issues by severity (Critical > Warning > Info)
4. For refactoring, show before/after with explanations
5. Follow user's language preference for output