Unreal

C++/Blueprint 架构边界

• 强制要求：任何每帧运行的逻辑（Tick）必须用 C++ 实现——Blueprint VM 开销和缓存未命中使得逐帧 Blueprint 逻辑在规模化时成为性能负担
• Blueprint 中不可用的数据类型（uint16、int8、TMultiMap、带自定义哈希的 TSet）必须在 C++ 中实现
• 主要引擎扩展——自定义角色移动、物理回调、自定义碰撞通道——需要 C++；永远不要仅用 Blueprint 实现
• 通过 UFUNCTION(BlueprintCallable)、UFUNCTION(BlueprintImplementableEvent) 和 UFUNCTION(BlueprintNativeEvent) 将 C++ 系统暴露给 Blueprint——Blueprint 是面向设计师的 API，C++ 是引擎
• Blueprint 适用于：高层游戏流程、UI 逻辑、原型验证和 Sequencer 驱动的事件

Nanite 使用约束

• Nanite 单场景支持硬性上限 1600 万个实例——大型开放世界的实例预算需据此规划
• Nanite 在像素着色器中隐式推导切线空间以减少几何体数据大小——Nanite 网格不要存储显式切线
• Nanite 不兼容：骨骼网格（使用标准 LOD）、带复杂裁剪操作的遮罩材质（需仔细基准测试）、样条网格和程序化网格组件
• 出货前始终在 Static Mesh Editor 中验证 Nanite 网格兼容性；在制作早期启用 r.Nanite.Visualize 模式以提前发现问题
• Nanite 擅长：密集植被、模块化建筑集、岩石/地形细节，以及任何高面数静态几何体

内存管理与垃圾回收

• 强制要求：所有 UObject 派生指针必须用 UPROPERTY() 声明——没有 UPROPERTY 的裸 UObject* 会被意外垃圾回收
• 对非拥有引用使用 TWeakObjectPtr<> 以避免 GC 导致的悬挂指针
• 对非 UObject 的堆分配使用 TSharedPtr<> / TWeakPtr<>
• 永远不要跨帧边界存储裸 AActor* 指针而不做空检查——Actor 可能在帧中间被销毁
• 检查 UObject 有效性时调用 IsValid() 而非 != nullptr——对象可能处于待销毁状态

Gameplay Ability System（GAS）要求

• GAS 项目设置必须在 .Build.cs 文件的 PublicDependencyModuleNames 中添加 "GameplayAbilities"、"GameplayTags" 和 "GameplayTasks"
• 每个技能必须继承 UGameplayAbility；每个属性集继承 UAttributeSet 并带正确的 GAMEPLAYATTRIBUTE_REPNOTIFY 宏用于复制
• 所有游戏事件标识符使用 FGameplayTag 而非纯字符串——标签是分层的、复制安全的、可搜索的
• 通过 UAbilitySystemComponent 复制游戏逻辑——永远不手动复制技能状态

Unreal 构建系统

• 修改 .Build.cs 或 .uproject 文件后始终运行 GenerateProjectFiles.bat
• 模块依赖必须显式声明——循环模块依赖会导致 Unreal 模块化构建系统的链接失败
• 正确使用 UCLASS()、USTRUCT()、UENUM() 宏——缺失反射宏会导致静默运行时错误，而非编译错误

技术交付物

GAS 项目配置（.Build.cs）

public class MyGame : ModuleRules
{
    public MyGame(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        PublicDependencyModuleNames.AddRange(new string[]
        {
            "Core", "CoreUObject", "Engine", "InputCore",
            "GameplayAbilities",   // GAS 核心
            "GameplayTags",        // 标签系统
            "GameplayTasks"        // 异步任务框架
        });

        PrivateDependencyModuleNames.AddRange(new string[]
        {
            "Slate", "SlateCore"
        });
    }
}

属性集——生命值与耐力

UCLASS()
class MYGAME_API UMyAttributeSet : public UAttributeSet
{
    GENERATED_BODY()