SuperAPI AI 工具集

unreal-conventions

编程与开发

查看项目

更新于 10-16 07:26

技能介绍

用途:这是一份 Unreal Engine 5 C++ 编码规范与架构约定参考,供开发者统一命名、文件组织与对象使用方式,并规避常见陷阱。

主要能力: 命名前缀:Actor 用 A(如 AFrogCharacter)、UObject 用 U(UScoreSubsystem)、Struct 用 F(FLaneConfig)、Enum 用 E(EGameState)、Interface 用 I(IHazardInterface)、Delegate 用 F...Delegate(FOnScoreChanged)、模板用 T(TArray、TMap)。 文件组织:.h 与 .cpp 成对出现,一文件对一主类;文件名与去掉前缀的类名一致(AFrogCharacter 对应 FrogCharacter.h);模块目录中头文件放 /Public/,实现放 /Private/。 UPROPERTY 说明符:EditAnywhere + BlueprintReadWrite 供编辑器编辑与蓝图读写;VisibleAnywhere + BlueprintReadOnly 只读可见,便于调试;空 UPROPERTY() 仅内部使用。 UFUNCTION 说明符:BlueprintCallable 可供蓝图调用;BlueprintImplementableEvent 由蓝图实现;BlueprintNativeEvent 提供 C++ 实现并允许蓝图覆盖。 委托模式:可用 DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam 声明动态多播委托;使用 AddDynamic 前需确认目标函数带 UFUNCTION。 对象生命周期:构造函数中用 CreateDefaultSubobject<T>() 创建组件;运行时用 NewObject<T>() 创建 UObject;UObject 禁止裸 new(会被 GC 回收);非拥有引用用 TWeakObjectPtr<T>;用 UPROPERTY() 防止引用对象被 GC。

使用方式:作为编码与评审时的对照清单,按上述规范书写命名、说明符与组件创建代码。

重要限制:SpawnActor<AActor> 在生成的 Actor 没有 RootComponent 时会静默丢弃 FTransform 参数,只含网格组件而无场景根的动态 Actor 会始终出现在世界原点 (0,0,0)。正确做法是先 SetRootComponent(Mesh) 再 RegisterComponent(),然后显式 SetActorLocation 与 SetActorScale3D。该问题曾在项目中导致连续 7 个冲刺的 VFX 不可见,而 170 个单元测试全部通过,因为测试只验证数学计算而非实际渲染结果。

其它常见模式:运行时初始化放 BeginPlay() 而非构造函数;仅在必要时使用 Tick(),优先用定时器与事件;用 GetWorld()->GetSubsystem() 访问子系统;用 Cast() 做安全类型转换,失败返回 nullptr。