name: unreal-engine
description: >
Comprehensive Unreal Engine C++ and Blueprint development assistant with deep project structure understanding.
Use when helping with Unreal Engine projects, including: C++ gameplay programming, Blueprint development,
input system configuration (Enhanced Input), Gameplay Ability System (GAS), project structure navigation,
asset discovery and referencing, plugin integration (experimental/beta), API lookups for underdocumented features,
and debugging. Triggers on any Unreal Engine development question, especially when working within a .uproject directory.

Unreal Engine Development Assistant

Core Philosophy: Zero Assumptions

CRITICAL: Never make assumptions about the user's project. Every Unreal project is unique in structure, assets, and configuration. Always verify before suggesting code or assets.

Pre-Flight Discovery Protocol

When a user asks for Unreal Engine help, ALWAYS execute this discovery sequence FIRST:

1. Locate the .uproject File

find . -maxdepth 2 -name "*.uproject" -type f

If found: Read it to extract:
- Engine version from "EngineAssociation" field
- Project name from filename
- Enabled plugins from "Plugins" array
- Module dependencies from "Modules" array

Example .uproject structure:

{
  "FileVersion": 3,
  "EngineAssociation": "5.7",  // ← Engine version
  "Category": "",
  "Description": "",
  "Modules": [
    {
      "Name": "ProjectName",  // ← Module name
      "Type": "Runtime",
      "LoadingPhase": "Default",
      "AdditionalDependencies": ["Engine", "GameplayAbilities"]
    }
  ],
  "Plugins": [
    {"Name": "EnhancedInput", "Enabled": true},
    {"Name": "GameplayAbilities", "Enabled": true}
  ]
}

2. Map the Project Structure

Standard Unreal project layout:

ProjectRoot/
├── ProjectName.uproject       ← Project file
├── Source/                    ← C++ source code
│   ├── ProjectName/           ← Main module
│   │   ├── Public/            ← Header files (.h)
│   │   ├── Private/           ← Implementation files (.cpp)
│   │   └── ProjectName.Build.cs ← Build configuration
│   └── ProjectNameEditor/ (optional) ← Editor-only code
├── Content/                   ← All assets (.uasset files)
│   ├── Blueprints/           ← Common location for BPs
│   ├── Input/                ← Input Actions & Mapping Contexts
│   ├── Characters/           ← Character assets
│   ├── UI/                   ← UMG widgets
│   └── [project-specific folders]
├── Config/                    ← Configuration .ini files
│   ├── DefaultEngine.ini     ← Engine settings
│   ├── DefaultInput.ini      ← Legacy input config
│   └── DefaultGame.ini       ← Game-specific config
├── Plugins/                   ← Project plugins
├── Intermediate/              ← Build artifacts (ignore)
├── Saved/                     ← Logs, configs (ignore)
└── Binaries/                  ← Compiled executables (ignore)

Execute these discovery commands:

# Find C++ classes
view Source/*/Public
view Source/*/Private

# Discover Content assets (especially Input Actions)
find Content -type f -name "*.uasset" | head -50

# For Input Actions specifically
find Content -type f -name "*IA_*" -o -name "*InputAction*"

# For Input Mapping Contexts
find Content -type f -name "*IMC_*" -o -name "*InputMappingContext*"

# Find Blueprint classes
find Content -type f -name "BP_*.uasset"

3. Understand Existing Code

Before suggesting ANY code:
- Read existing character/controller classes to understand patterns
- Check what components are already added
- Identify naming conventions (e.g., IA_ prefix for Input Actions)
- Look for existing helper classes or base classes

# Example: Find character class
find Source -name "*Character.h" -o -name "*Character.cpp"

Input System Handling

Enhanced Input System (UE5+)

NEVER assume input action names. Always discover them first:

# Find Input Actions in Content
find Content -type f \( -name "IA_*.uasset" -o -name "*InputAction*.uasset" \)

# Find Input Mapping Contexts
find Content -type f \( -name "IMC_*.uasset" -o -name "*MappingContext*.uasset" \)

Common Input Action patterns:
- IA_Move or IA_Movement (Axis2D)
- IA_Look (Axis2D)
- IA_Jump (Boolean)
- IA_Interact (Boolean)

But ALWAYS verify - projects use different naming conventions.

Binding Input Actions in C++

Template for Enhanced Input binding:

#include "EnhancedInputComponent.h"
#include "EnhancedInputSubsystems.h"
#include "InputAction.h"

// In SetupPlayerInputComponent
void AMyCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
    Super::SetupPlayerInputComponent(PlayerInputComponent);

    // Cast to Enhanced Input Component
    if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(PlayerInputComponent))
    {
        // Bind actions - VERIFY THESE ASSET PATHS EXIST
        EnhancedInput->BindAction(MoveAction, ETriggerEvent::Triggered, this, &AMyCharacter::Move);
        EnhancedInput->BindAction(LookAction, ETriggerEvent::Triggered, this, &AMyCharacter::Look);
        EnhancedInput->BindAction(JumpAction, ETriggerEvent::Started, this, &AMyCharacter::Jump);
    }
}

Header declarations:

UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Input")
UInputAction* MoveAction;

UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Input")
UInputAction* LookAction;

.uasset Files and Blueprint Reading

.uasset files are binary and mostly unreadable in text editors, BUT:
- Some metadata is visible (asset names, paths, GUIDs)
- Property names and string values may be readable
- Useful for discovering asset references and dependencies
- Do NOT rely on .uasset contents for implementation details

Better approach: Use find to discover assets, then ask user to verify or describe them.

Gameplay Ability System (GAS)

When working with GAS projects (check .uproject for "GameplayAbilities" plugin):

Critical GAS Setup Requirements

1. Build.cs dependencies:

PublicDependencyModuleNames.AddRange(new string[] { 
    "Core", "CoreUObject", "Engine", "InputCore",
    "GameplayAbilities",
    "GameplayTags", 
    "GameplayTasks"
});

2. Ability System Component placement:
- For single-player or listen-server: Can be on Character
- For dedicated server: Usually on PlayerState (for player-owned actors)
- For AI/NPCs: Can be on Character or custom actor

3. Key GAS classes:
- UAbilitySystemComponent - The core component
- UGameplayAbility - Base class for abilities
- UAttributeSet - Holds gameplay attributes (health, stamina, etc.)
- UGameplayEffect - Modifies attributes
- FGameplayTag - Tags for ability system

Common GAS Patterns

Granting abilities:

// In C++
AbilitySystemComponent->GiveAbility(
    FGameplayAbilitySpec(AbilityClass, 1, INDEX_NONE, this)
);

Activating abilities:

// By class
AbilitySystemComponent->TryActivateAbilityByClass(AbilityClass);

// By tag
FGameplayTagContainer TagContainer;
TagContainer.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Dash")));
AbilitySystemComponent->TryActivateAbilitiesByTag(TagContainer);

Plugin-Specific Guidance

Unknown or Experimental Plugins

When encountering unfamiliar plugins (e.g., Mutable, MutableClothing, RelativeIKOp):

1. Search for official documentation:

web_search: "Unreal Engine [PluginName] documentation API"
web_search: "Unreal Engine [PluginName] usage examples"

1. Check source code (if accessible):

# Engine plugins location (if user has source build)
find /path/to/UE5/Engine/Plugins -name "PluginName"

1. Be transparent: "This plugin is experimental/underdocumented. Let me search for the latest information..."

API Knowledge Gaps

When uncertain about API usage:

1. Search Epic's documentation:

web_search: "Unreal Engine [ClassName] API [EngineVersion]"

1. Search community resources:

web_search: "Unreal Engine [feature] example code C++"

1. Check Epic Developer Community forums
2. Look for example projects (Lyra, Valley of the Ancient, ActionRPG)

Common Pitfalls to Avoid

❌ WRONG: Making Assumptions

// DON'T assume this exists
EnhancedInput->BindAction(IA_Jump, ETriggerEvent::Started, this, &AMyCharacter::Jump);

✓ CORRECT: Discovery First

# Find what Input Actions actually exist
find Content -name "*IA_*"
# Then ask user or use discovered names

❌ WRONG: Generic Action Names

// Too generic - what if they use IA_PlayerJump?
UPROPERTY(EditAnywhere, Category = "Input")
UInputAction* JumpAction;

✓ CORRECT: Verify Asset Names

# Discover actual naming convention
find Content/Input -name "*.uasset"
# Results might show: IA_Jump, IA_PlayerJump, InputAction_Jump, etc.

Version-Specific Considerations

Engine Version Detection

Always check .uproject for "EngineAssociation":
- 5.0-5.4: Stable Enhanced Input, Experimental GAS improvements
- 5.5+: Mutable/Customization systems, new input features
- 4.27: Legacy input system, requires manual Enhanced Input setup

Version-Specific Features

When suggesting code, CHECK if features exist in that version:

web_search: "Unreal Engine [feature] [version] availability"

Workflow Decision Tree

User asks for Unreal help
    │
    ├─> Find .uproject ─> Extract version & plugins
    │
    ├─> Map project structure ─> View Source/ and Content/
    │
    ├─> Identify question type:
    │   ├─> Input system? ─> Discover Input Actions/Contexts
    │   ├─> GAS-related? ─> Check GAS setup, discover abilities
    │   ├─> Plugin-specific? ─> Search documentation
    │   └─> General C++? ─> Read existing classes for patterns
    │
    ├─> Provide solution with:
    │   ├─> Verified asset references
    │   ├─> Version-appropriate code
    │   └─> Project-specific patterns
    │
    └─> If uncertain about API/plugin ─> Search documentation

Best Practices Checklist

Before providing ANY code suggestion:

• [ ] Found and read .uproject file
• [ ] Identified engine version
• [ ] Mapped Source/ directory structure
• [ ] Discovered Content/ assets (especially for input/blueprints)
• [ ] Read existing class files for patterns
• [ ] Verified asset paths and names
• [ ] Checked plugin availability
• [ ] Searched documentation for uncertain APIs
• [ ] Used project-specific naming conventions

Quick Reference Commands

# Engine version
grep "EngineAssociation" *.uproject

# Find C++ classes
find Source -name "*.h" -o -name "*.cpp" | head -20

# Find Input Actions
find Content -name "IA_*.uasset" -o -name "*InputAction*.uasset"

# Find Blueprints
find Content -name "BP_*.uasset" | head -20

# Find config files
ls -la Config/

# Check for GAS
grep -i "GameplayAbilities" *.uproject

Detailed References

This skill includes comprehensive reference documentation for specific topics. Load these when needed:

references/enhanced_input.md

Load when working with Enhanced Input System:
- Detailed API reference for Input Actions, Mapping Contexts, Triggers
- Complete binding examples and patterns
- Value type handling (Digital, Axis1D, Axis2D, Axis3D)
- Console commands and debugging tips
- Migration from legacy input system

references/gameplay_ability_system.md

Load when working with GAS:
- Complete setup guide (ASC, AttributeSet, Abilities, Effects)
- Replication strategies (PlayerState vs Character placement)
- Granting and activating abilities
- Gameplay Tags usage
- Attribute modification patterns
- Common GAS patterns (damage, cooldowns, costs)
- Debugging and best practices

references/common_pitfalls.md

Load when troubleshooting or encountering errors:
- Input system issues and solutions
- GAS activation problems
- Build and compilation errors
- Blueprint/C++ integration issues
- Asset reference problems
- Plugin troubleshooting
- Performance debugging
- Emergency recovery procedures