ue5-cpp-gameplay

快速开始

• 确认目标类类型（AActor、UActorComponent、UObject、USaveGame 等）。
• 在实现前定义所需的 Blueprint 接口。
• 同时输出头文件和源文件。

API 锚点（UE5.6-UE5.8）

• 反射和 UObject 锚点：
  • UCLASS、USTRUCT、UENUM、UINTERFACE、GENERATED_BODY()
  • UPROPERTY(...)、UFUNCTION(...)
• 核心游戏类型锚点：
  • AActor、UActorComponent、UDataAsset、UGameInstanceSubsystem
  • 在头文件中使用 TObjectPtr<>，并使用 TSubclassOf<> 引用类
• 复制锚点：
  • GetLifetimeReplicatedProps(...)
  • Net/UnrealNetwork.h 中的 DOREPLIFETIME(...)
  • ReplicatedUsing=OnRep_*、UFUNCTION(Server/Client/NetMulticast, ...)
• Gameplay Tag 锚点：
  • FGameplayTag、FGameplayTagContainer
  • 显式执行标签请求／匹配检查，并提供安全回退行为

实现阶段约定

• 每项游戏 C++ 任务都必须定义：
  • 公共头文件 API 表面（Blueprint/API 可见性）
  • 私有运行时实现路径（.cpp）
  • 所有权／生命周期模型（构造、初始化、拆除）
  • 网络权限规则（仅单人游戏或复制流程）
  • 验证方法（编译假设、使用示例、边缘情况行为）
• 若缺少任何一项，实现规范即不完整。

工作流

1) 类型与文件结构

• 使用 Unreal 宏和 UE5 指针约定（头文件中使用 TObjectPtr）创建类型声明。
• 生成成对的 .h 和 .cpp 文件，在头文件中使用前置声明，并在源文件中包含具体头文件。
• 保持类的职责精简且可复用。

2) 公共 API 设计

• 在实现前定义 Blueprint API（BlueprintCallable、BlueprintPure、分类、元数据）。
• 仅公开最少的可调用接口；除非确有需要，否则辅助方法不要使用 UFUNCTION。
• 明确声明输入／输出约定和失败行为。

3) 运行时实现

• 在 .cpp 中实现逻辑，包含空值检查、权限校验和明确的分支行为。
• 按需启用 Tick；优先使用事件驱动更新。
• 明确处理初始化顺序（BeginPlay、InitializeComponent 或子系统初始化）。

4) 复制和 RPC（需要时）

• 仅为客户端可见的实际状态添加复制属性和 OnRep_* 处理程序。
• 使用 DOREPLIFETIME(...) 在 GetLifetimeReplicatedProps(...) 中注册属性。
• 使用服务器权威的 RPC 入口处理客户端请求。

5) GameplayTags 和数据驱动钩子

• 使用 FGameplayTag／FGameplayTagContainer 和显式标签名称。
• 在运行时验证必需标签，并为缺失的标签提供回退方案。
• 可调参数优先使用 DataAsset 驱动配置，而非硬编码常量。

6) 验证输出

• 确保输出包含两个文件及所需的 include。
• 确认文档说明了 Blueprint 暴露、复制行为和错误处理路径。
• 对于行为不明显的情况，提供用法代码片段或调用流程。

约束

• 创建类时，始终提供匹配的 .h 和 .cpp。
• 使用兼容 UE5.6-UE5.8 的非弃用 API。
• 尽量减少 include；在头文件中使用前置声明。
• 除非明确要求，否则避免硬编码资源路径。
• 在头文件的 UPROPERTY 对象引用中优先使用 TObjectPtr<>。
• 对任何会影响网络的游戏操作，明确执行服务器权威检查。

故障处理

• 症状：类编译成功，但未显示在蓝图中。
  • 定位：缺少 BlueprintType/Blueprintable/BlueprintCallable 元数据。
  • 修复：添加所需的反射说明符，并重新生成项目文件和构建项目。
• 症状：出现未解析的符号或头文件循环依赖。
  • 定位：检查头文件包含关系图，以及前置声明的误用。
  • 修复：将大型头文件包含移至 .cpp 文件，并在头文件中保留前置声明。
• 症状：复制的属性未在客户端更新。
  • 定位：检查 GetLifetimeReplicatedProps(...) 以及 Actor/组件的复制标志。
  • 修复：使用 DOREPLIFETIME(...) 注册属性，并确保所属 Actor 已启用复制。
• 症状：OnRep_* 从未触发。
  • 定位：检查属性写入路径和网络角色。
  • 修复：在服务器权威路径中修改属性，并确认属性值确实发生变化。
• 症状：RPC 可调用，但运行时被忽略。
  • 定位：检查 RPC 说明符和调用点的权威性。
  • 修复：确保请求路径为客户端->服务器，并在服务器端进行验证。
• 症状：GameplayTag 逻辑静默失效。
  • 定位：检查标签名称是否无效，以及是否缺少标签配置。
  • 修复：在启动时验证标签，并添加明确的回退行为保护。

UE5.6-UE5.8 兼容性说明

• 上述反射、复制和 GameplayTag API 在 UE5.6-UE5.8 中均保持稳定。
• 需要运行时行为时，优先使用稳定的核心 API，而非仅限编辑器的辅助工具。

升级处理

• 当用户要求进行超出单个游戏类范围的插件/模块级重构时，升级处理。
• 当解决方案需要修改自定义引擎源代码时，升级处理。