unreal-engine

Unreal Engine 开发助手

核心理念：零假设

至关重要：绝不要对用户的项目作出假设。每个 Unreal 项目的结构、资产和配置都各不相同。提出代码或资产建议前，务必先进行核实。

预检发现流程

用户寻求 Unreal Engine 帮助时，务必先执行以下发现流程：

1. 定位 .uproject 文件

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

如果找到：读取文件并提取以下信息：

• "EngineAssociation" 字段中的引擎版本
• 文件名中的项目名称
• "Plugins" 数组中的已启用插件
• "Modules" 数组中的模块依赖项

.uproject 结构示例：

{
  "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. 梳理项目结构

标准 Unreal 项目布局：

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)

执行以下发现命令：

# 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. 了解现有代码

提出任何代码建议前：

• 阅读现有的角色/控制器类，了解代码模式
• 检查已添加的组件
• 确认命名约定（例如，输入动作使用 IA_ 前缀）
• 查找现有的辅助类或基类

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

输入系统处理

Enhanced Input System（UE5+）

绝不要假设输入动作的名称。务必先查明：

# 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" \)

常见输入动作模式：

• IA_Move 或 IA_Movement（Axis2D）
• IA_Look（Axis2D）
• IA_Jump（Boolean）
• IA_Interact（Boolean）

但务必进行核实——不同项目使用的命名约定可能不同。

在 C++ 中绑定输入动作

Enhanced Input 绑定模板：

#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);
    }
}

头文件声明：

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

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

.uasset 文件与 Blueprint 读取

.uasset 文件是二进制文件，在文本编辑器中大多无法读取，但：

• 可以看到部分元数据（资产名称、路径、GUID）
• 属性名称和字符串值可能可读
• 可用于查找资产引用和依赖项
• 不要依赖 .uasset 内容获取实现细节

更好的方法：使用 find 查找资产，然后请用户核实或描述这些资产。

Gameplay Ability System（GAS）

处理 GAS 项目时（检查 .uproject 中是否包含 "GameplayAbilities" 插件）：

GAS 的关键设置要求

1. Build.cs 依赖项：

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

2. Ability System Component 的位置：

• 单人游戏或监听服务器：可以放在 Character 上
• 专用服务器：通常放在 PlayerState 上（适用于由玩家拥有的 Actor）
• AI/NPC：可以放在 Character 或自定义 Actor 上

3. 关键 GAS 类：

• UAbilitySystemComponent - 核心组件
• UGameplayAbility - Ability 的基类
• UAttributeSet - 保存游戏属性（生命值、耐力等）
• UGameplayEffect - 修改属性
• FGameplayTag - Ability System 的标签

常见 GAS 模式

授予 Ability：

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

激活 Ability：

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

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

特定插件指南

未知或实验性插件

遇到不熟悉的插件时（例如 Mutable、MutableClothing、RelativeIKOp）：

1. 搜索官方文档：

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

2. 检查源代码（如果可以访问）：

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

3. 坦诚说明：“此插件仍处于实验阶段/文档不完善。让我查找最新信息……”

API 知识盲区

不确定 API 用法时：

1. 搜索 Epic 的文档：

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

2. 搜索社区资源：

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

3. 查看 Epic Developer Community 论坛
4. 查找示例项目（Lyra、Valley of the Ancient、ActionRPG）

应避免的常见陷阱

❌ 错误：作出假设

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

✓ 正确：先进行发现

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

❌ 错误：使用通用动作名称

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

✓ 正确：核实资产名称

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

特定版本注意事项

检测引擎版本

务必检查 .uproject 中的 "EngineAssociation"：

• 5.0-5.4：Enhanced Input 稳定，GAS 改进处于实验阶段
• 5.5+：Mutable/Customization 系统、新的输入功能
• 4.27：旧版输入系统，需要手动设置 Enhanced Input

特定版本的功能

提供代码建议时，请检查该版本是否支持相关功能：

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

工作流决策树

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

最佳实践检查清单

提供任何代码建议之前：

• 找到并阅读 .uproject 文件
• 确认引擎版本
• 梳理 Source/ 目录结构
• 查找 Content/ 资源（尤其是输入/蓝图相关资源）
• 阅读现有类文件，了解其模式
• 验证资源路径和名称
• 检查插件是否可用
• 对不确定的 API 查阅文档
• 遵循项目特定的命名约定

快速参考命令

# 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

详细参考资料

此技能包含特定主题的综合参考文档。需要时加载以下文档：

references/enhanced_input.md

使用 Enhanced Input System 时加载：

• Input Actions、Mapping Contexts 和 Triggers 的详细 API 参考
• 完整的绑定示例和模式
• 值类型处理（Digital、Axis1D、Axis2D、Axis3D）
• 控制台命令和调试技巧
• 从旧版输入系统迁移

references/gameplay_ability_system.md

使用 GAS 时加载：

• 完整的设置指南（ASC、AttributeSet、Abilities、Effects）
• 复制策略（PlayerState 与 Character 的放置位置）
• 授予和激活技能
• Gameplay Tags 的用法
• 属性修改模式
• 常见 GAS 模式（伤害、冷却时间、消耗）
• 调试和最佳实践

references/common_pitfalls.md

排查问题或遇到错误时加载：

• 输入系统问题及解决方案
• GAS 激活问题
• 构建和编译错误
• Blueprint/C++ 集成问题
• 资源引用问题
• 插件故障排查
• 性能调试
• 紧急恢复流程