unreal-best-practices

Unreal Engine 5.x 最佳实践指南

“先研究”原则

在实现任何游戏玩法系统之前，务必先调查 Epic 是否提供了更新、专为此设计的系统。 Epic Games 不断推出现代框架，以取代临时拼凑的解决方案。使用最新推荐的系统可以获得更好的性能、更简单的网络功能、更便于设计师使用的工作流，以及更好的未来兼容性。

工作流：

1. 确定问题领域（输入、能力、音频、粒子、AI、UI、移动等）
2. 查看下方的现代系统速查表
3. 如果不确定，请搜索 Epic 的文档和 UE Public Roadmap，了解最新系统状态
4. 优先选择可用于正式生产的现代系统，而非旧式方案
5. 对于实验性系统：在决定采用前先评估其成熟度——在原型中使用，不要用于正式发布的构建

为何这很重要： Epic 通过实际行动而非仅靠公告来表明发展方向。当他们重构第一人称／第三人称模板，改用 GAS 和 Enhanced Input，或 Fortnite 采用 Game Feature Plugins 和 CommonUI 时，这就是生态系统发展方向最明确的信号。

官方文档（务必查阅以获取最新详情）

来源	URL
Epic 文档中心	https://dev.epicgames.com/documentation/en-us/unreal-engine
UE Public Roadmap	https://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap
Lyra 示例项目	https://dev.epicgames.com/documentation/en-us/unreal-engine/lyra-sample-game-in-unreal-engine
UE 发行说明	https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-release-notes
Epic 社区教程	https://dev.epicgames.com/community/learning
实验性功能列表	https://dev.epicgames.com/documentation/en-us/unreal-engine/experimental-features
Allar 的 UE5 风格指南	https://github.com/Allar/ue5-style-guide
Tom Looman 的 UE5 指南	https://tomlooman.com
X157 Dev Notes（Lyra）	https://x157.github.io/UE5/

Lyra Starter Game 是 Epic 为现代 UE5 架构提供的权威参考实现。它展示了 GAS、Enhanced Input、Game Feature Plugins、CommonUI、GameplayMessageSubsystem、Gameplay Tags 和模块化游戏玩法模式，所有内容均源自 Fortnite 的生产代码库。

现代系统速查表

有关各个系统、迁移路径和文档链接的详细信息，请参阅 references/modern-systems.md。

UE 5.7 中的系统状态：

领域	旧系统	现代系统	状态
输入	BindAction/BindAxis	Enhanced Input	已投入生产 -- 自 5.1 起旧系统已弃用
能力	临时布尔值/计时器	Gameplay Ability System (GAS)	已投入生产 -- 推荐用于以能力为核心的游戏
状态/分类	枚举、布尔值、字符串	Gameplay Tags	已投入生产 -- 现代 UE 的基础
AI 行为	行为树	StateTree	自 5.1 起已投入生产 -- 可替代行为树，行为树仍受支持
AI 交互	手动编写脚本	Smart Objects	自 5.1 起已投入生产
粒子/VFX	Cascade	Niagara	已投入生产 -- Cascade 自 5.0 起已弃用
音频	SoundCue	MetaSounds	已投入生产（核心功能）-- SoundCue 尚未弃用
音频混音	静态配置	Audio Modulation	已投入生产
渲染（几何体）	手动设置 LOD	Nanite	自 5.0 起已投入生产
渲染（光照）	烘焙光照贴图	Lumen	自 5.0 起已投入生产
关卡流送	World Composition / Level Streaming	World Partition	已投入生产 -- World Composition 已弃用
UI（多平台）	原始 UMG	CommonUI + UMG	Beta（用于 Fortnite）
移动	CharacterMovementComponent	Mover 2.0	实验性 -- 仍推荐使用 CMC
程序化内容	手动/Blueprint 脚本	PCG Framework	自 5.7 起已投入生产
架构	单体模块	Game Feature Plugins	已投入生产（Lyra/Fortnite）
消息传递	直接使用委托/类型转换	GameplayMessageSubsystem	已投入生产（Lyra）
动画（移动）	状态机/混合树	Motion Matching (PoseSearch)	实验性
动画（交互）	手动同步 Montage	Motion Warping	可用于生产环境
动画（绑定）	仅使用外部 DCC 工具	Control Rig	已投入生产（核心功能）
资产选择	硬编码的 switch/if 链	Chooser Tables	自 5.4 起为 Beta
网络（大规模）	默认复制	Iris	自 5.7 起为 Beta
对话	第三方插件	CommonConversation	实验性（不推荐）

C++ 和 Blueprint 最佳实践

有关详细模式、通信方式和性能指南，请参阅 references/blueprint-and-cpp.md。

黄金标准模式：抽象 C++ 基类 + Blueprint 子类。

C++ (UCLASS(Abstract))                  Blueprint Subclass
+----------------------------------+    +---------------------------+
| Base class logic                 |    | Visual/gameplay config    |
| - Core systems & algorithms     |    | - Asset references        |
| - Networking & replication       |    | - Tuning values           |
| - Performance-critical code      |    | - Event responses         |
| - BlueprintImplementableEvent    |    | - Designer iteration      |
| - UPROPERTY(EditDefaultsOnly)   |    | - One-off behaviors       |
+----------------------------------+    +---------------------------+

决策矩阵：

• C++：基类、系统、性能关键代码、网络、编辑器工具
• Blueprint：游戏逻辑、配置、原型设计、VFX 触发器、UI 布局
• 两者：C++ 定义框架，Blueprint 填充游戏玩法细节

关键规则：

• 避免使用 Event Tick -- 改用计时器、事件和委托（可提升 20-30% 的性能）
• 跨 Blueprint 通信时优先使用 Blueprint 接口而非类型转换（可避免硬引用）
• 对于暂时不需要的资产，使用 TSoftObjectPtr<>（防止内存膨胀）
• 缓存引用，而不是每帧搜索
• Blueprint Nativization 已在 UE 5.0 中移除 -- 将性能热点路径手动转换为 C++

数据驱动设计

请参阅 references/data-driven-design.md，了解数据表、数据资产、主资产、资产管理器和 Gameplay Tag 模式。

核心原则：将数据与逻辑分离。 让设计师无需修改代码即可进行配置。

资产类型	最适用于	主要特点
Data Table	大型同质数据集（100 项以上）	支持 CSV/JSON 导入，行使用 FTableRowBase
Data Asset	独特的复杂定义（Boss、技能树）	完整继承，包含 UObject 成员
Primary Data Asset	需要生命周期管理的资产	集成 Asset Manager，支持异步加载
Gameplay Tags	分层状态/分类	替代枚举，可由设计师创建

Gameplay Tags 是基础构件——将其用于状态管理、能力分类、伤害类型、动画状态、输入绑定和跨系统通信。始终使用 FGameplayTagContainer，而不是 TArray<FGameplayTag>。

项目组织

请参阅 references/project-organization.md，了解命名约定、文件夹结构和模块化架构模式。

命名前缀约定（标准）：

前缀	类型	前缀	类型
BP_	Blueprint	IA_	Input Action
WBP_	Widget Blueprint	IMC_	Input Mapping Context
DA_	Data Asset	GA_	Gameplay Ability
DT_	Data Table	GE_	Gameplay Effect
SM_	Static Mesh	NS_	Niagara System
SK_	Skeletal Mesh	AM_	Animation Montage
M_	Material	ABP_	Animation Blueprint
MI_	Material Instance	BS_	Blend Space
T_	Texture	S_	Sound Wave

文件夹结构：按功能划分，而非按资产类型划分。

性能与调试

请参阅 references/performance-and-debugging.md，了解 Tick 优化、对象池、GC 管理、性能分析和 Unreal Insights。

性能优化要点：

1. 禁用不需要 Tick 的 Actor/组件上的 Tick（bCanEverTick = false）
2. 使用计时器和事件，而非逐帧轮询
3. 对频繁生成/销毁的 Actor（投射物、粒子）使用对象池
4. 对静态几何体使用 Nanite——无需手动创建 LOD
5. 使用 Unreal Insights 进行性能分析（-trace=cpu,gpu,frame,counters），不要凭猜测行事
6. 在复制属性上使用 COND_* 标志，以尽量减少网络带宽占用
7. 使用 Reference Viewer 审查资产引用，防止内存膨胀

Lyra 的关键设计模式

Lyra 确立了以下模式，作为 Epic 推荐的架构：

1. Game Feature Plugins：可在运行时注入基础游戏的独立功能。采用单向依赖——核心游戏永不引用功能插件。
2. Experience System：基于 Game Feature Plugins 构建、支持异步加载的游戏模式配置。优于传统的 GameMode 子类化方式。
3. GameplayMessageSubsystem：基于 Tag 的发布-订阅消息机制。消除游戏系统之间的紧密耦合。
4. GAS + Gameplay Tags：通过数据定义能力，通过 Tag 激活能力，并基于 Tag 进行阻止/取消。
5. Enhanced Input + Tag Binding：通过 Gameplay Tags（而非直接调用函数）将 Input Actions 映射到 Gameplay Abilities。
6. CommonUI：支持平台感知的 UI，具备自动输入设备切换和焦点管理功能。
7. Primary Data Assets + Asset Manager：通过基于 Bundle 的内存管理，实现可控的异步加载。

特定版本的破坏性变更

影响开发实践的主要变更：

• UE 5.0：FVector → 3 个 double；TObjectPtr<> 在 UPROPERTY 中取代原始指针
• UE 5.1：Enhanced Input 成为默认选项；弃用旧版输入系统
• UE 5.3：新项目默认使用 C++20；BuildSettingsVersion.V5
• UE 5.5：弃用旧版统计分析器 → 改用 Unreal Insights；Zen Loader 可用于生产环境；Path Tracer 可用于生产环境
• UE 5.6：移除 Swarm Manager；FString::Appendf 强制要求格式字符串为 static constexpr；提升 HWRT 性能
• UE 5.7：PCG Framework 可用于生产环境；Substrate 可用于生产环境；FindObject 使用 EFindObjectFlags；BuildSettingsVersion.V6