在虚幻引擎中用 Actor-Component…

处理 UE 的 Actor 与组件设计：生命周期、组件创建与挂载、生成、Tick、接口与组合模式。

适用场景

解决思路

1. 先阅读 `.agents/ue-project-context.md`，了解项目的子系统清单、编码约定以及已有的 actor 层级和组件模式，确认已建立的基类与命名约定。
2. 动手前先澄清需求：是从零新建 actor 还是给已有 actor 加行为；是纯逻辑（UActorComponent）还是需要世界位置（USceneComponent）；是否有生成需求（延迟初始化、对象池、网络生成）；是否是生命周期 bug（BeginPlay/构造函数混淆、组件未初始化）；是否需要通过接口实现跨 actor 行为。
3. 牢记组合优于继承的心智模型：AActor 是拥有组件的容器，行为、渲染、碰撞、逻辑都由 UActorComponent 子类表达；层级为 UObject → AActor → 拥有 N 个 UActorComponent → USceneComponent（增加 transform 与挂载）→ UPrimitiveComponent（增加碰撞与渲染）。
4. 永远不要对 actor 使用 new/delete，始终用 SpawnActor 创建、用 Destroy 销毁。
5. 掌握生命周期顺序：Constructor（CreateDefaultSubobject、tick 配置、默认值）→ PostActorCreated（仅生成的 actor，在构造脚本前）→ PostInitializeComponents（所有组件已初始化，世界可访问）→ BeginPlay（游戏运行中，完整逻辑可用，组件的 BeginPlay 在此触发）→ Tick(DeltaTime) → EndPlay(EEndPlayReason)（清理，ClearAllTimers，调用 Super）→ Destroyed（GC 前，避免复杂逻辑）。
6. 构造函数在 Class Default Object（CDO）上最先运行，CDO 上 GetWorld() 返回 nullptr；绝不要在构造函数中访问世界或其他 actor，把依赖世界的代码放到 BeginPlay。
7. 在构造函数中只做构造期工作：用 CreateDefaultSubobject 创建组件、SetRootComponent、设置 PrimaryActorTick.bCanEverTick、TickInterval 等。
8. 在 BeginPlay 中写依赖世界的逻辑，并始终先调用 Super::BeginPlay()。
9. 在 PostInitializeComponents 中给自身组件绑定委托（它在 BeginPlay 之前调用，组件已初始化且世界存在），并调用 Super::PostInitializeComponents()。
10. 在 EndPlay 中清理，例如 GetWorld()->GetTimerManager().ClearAllTimersForObject(this)，并调用 Super::EndPlay(EndPlayReason)；注意 EndPlay 原因包括 Destroyed、LevelTransition、EndPlayInEditor、RemovedFromWorld、Quit。
11. 网络生命周期注意：客户端上 BeginPlay 可能在所有复制属性到达前触发，依赖复制状态的初始化用 OnRep_ 回调；PostNetReceive() 在每次复制更新（含首次）后触发，用 bHasInitialized 标志保护一次性初始化；PostNetInit 不是标准 AActor 虚函数，不要当作通用初始化钩子。
12. 按三层选择组件类型：UActorComponent（无 transform、无渲染碰撞，用于纯逻辑如生命值、背包、AI 数据）；USceneComponent（有 transform、无渲染碰撞，用于变换锚点、分组、轴心）；UPrimitiveComponent（有 transform、有渲染碰撞，用于网格、形状等可见或可碰撞对象）。
13. 构造函数中创建默认组件（会出现在 Details 面板）：用 CreateDefaultSubobject 注册为子对象，随 actor 序列化并在蓝图中可见；用 SetRootComponent 设根，用 SetupAttachment 设置父子关系（无需世界）。
14. 运行时动态添加组件：用 NewObject 创建（不会自动注册到世界），再 SetupAttachment(GetRootComponent())，然后 RegisterComponent() 赋予世界存在感（渲染代理、物理），最后设置属性。
15. 移除组件时区分：DestroyComponent() 注销并标记 GC（不可逆）；UnregisterComponent() 从世界移除但不销毁（可逆），以后可能重新启用时用 Unregister。
16. 注意构造函数创建的组件是拥有的子对象并参与 actor 的 GC 根；运行时用 NewObject 创建的组件除非加入 UPROPERTY 数组，否则不会自动序列化。
17. 挂载时区分：构造函数用 SetupAttachment（无需世界）；运行时用 AttachToComponent（世界必须存在），并指定 FAttachmentTransformRules（如 SnapToTargetNotIncludingScale）和骨骼网格上的命名插槽；分离用 DetachFromComponent(FDetachmentTransformRules::KeepWorldTransform)。
18. 激活控制：构造函数中把可选组件的 bAutoActivate 设为 false；运行时用 Activate()（内部会检查 ShouldActivate()）、Deactivate()、SetActive(true, bReset)。
19. 标准生成：配置 FActorSpawnParameters（Owner、Instigator、SpawnCollisionHandlingOverride 如 AdjustIfPossibleButAlwaysSpawn、Name 用于复制的确定性唯一名），再调用 GetWorld()->SpawnActor<T>(Class, Location, Rotation, Params)。
20. 延迟生成：当 actor 的 BeginPlay 需要读取必须先设置的数据时，用 SpawnActorDeferred 生成，设置数据（如 SetEnemyData），再调用 FinishSpawning(SpawnTransform)（它会触发 PostInitializeComponents 然后 BeginPlay）。
21. 高频 actor（子弹、弹壳）使用对象池：预生成，返回时隐藏并禁用碰撞，复用时重新启用；取用时遍历池检查 IsHidden()（IsHidden 反映池的非激活状态；IsActive() 只存在于 UActorComponent，不存在于 AActor），没有可用再 SpawnActor 并加入池。
22. Tick 配置：在构造函数中设置 PrimaryActorTick.bCanEverTick、bStartWithTickEnabled（可在 BeginPlay 中再启用）、TickInterval（节流，如 0.1f 约 10Hz）、TickGroup（TG_PrePhysics 默认处理输入/移动 → TG_DuringPhysics 物理耦合逻辑 → TG_PostPhysics 相机/IK → TG_PostUpdateWork 最终读取）。
23. 组件 Tick：在组件构造函数中设置 PrimaryComponentTick.bCanEverTick = true，并用 PrimaryComponentTick.TickGroup 控制顺序，API 与 actor tick 相同。
24. Tick 依赖：用 ActorA->AddTickPrerequisiteActor(ActorB) 让 ActorA 在 ActorB 之后 tick；用 ComponentA->AddTickPrerequisiteComponent(ComponentB) 控制组件顺序。
25. 避免不必要的 Tick（即使无变化也有每帧开销）：延迟/重复事件用 FTimerHandle 与 GetWorld()->GetTimerManager().SetTimer；状态变化用委托/多播委托（如 HealthComp->OnDeath.AddDynamic）；碰撞事件用 OnComponentBeginOverlap/OnActorBeginOverlap；只在真正需要每帧时 tick（平滑插值、物理子步、流式查询）。
26. 用 UINTERFACE 模式解耦：声明时用 UINTERFACE(MinimalAPI, Blueprintable) 的 UInteractable : public UInterface 加 GENERATED_BODY()，实现类用 UFUNCTION(BlueprintNativeEvent, BlueprintCallable) 声明如 OnInteract(AActor* Instigator)。
27. 实现接口：在 UCLASS 中同时继承 AActor 和 IInteractable，并实现 virtual void OnInteract_Implementation(AActor* Instigator) override。
28. 通过接口调用：先判断 Target->Implements<UInteractable>()，再用 Execute_ 前缀调用 IInteractable::Execute_OnInteract(Target, GetPawn())，无需 Cast。
29. 接口与组件的选择：接口用于能力声明（“可被交互”），尤其当蓝图类需要实现时；组件用于行为有自身状态、需要 tick、或被多种 actor 以相同方式复用时。
30. 优先用组件而非深层继承：不要 ACharacter → AHero → ASwordHero → AFireSwordHero，而是扁平基类 ABaseCharacter 加组合组件（UHealthComponent、UInventoryComponent、UAbilityComponent、UStatusComponent）。
31. 组件间通信不要让组件持有兄弟组件的裸指针：通过 owner 查询（GetOwner()->FindComponentByClass<UHealthComponent>()）或用委托完全解耦（HealthComp->OnDeath.AddDynamic(AbilityComp, &UAbilityComponent::OnOwnerDied)）。
32. 数据驱动组合：用 UDataAsset（如 UEnemyData）按类型变化配置，在 BeginPlay 或 SpawnActorDeferred 时读取；在 Initialize 中设置 HealthComp->SetMaxHealth(Data->MaxHealth)，并遍历 Data->AdditionalComponents 用 NewObject 创建并 RegisterComponent。
33. 避免继承滥用：不要为每种变体建一个类（AFireEnemy、AIceEnemy），而是一个类配多个 DataAsset（UEnemyData_Fire、UEnemyData_Ice），在 BeginPlay 读取。
34. 避免用 Tick 轮询代替事件：不要在 Tick 中检查 HealthComp->IsDead()，而是在 BeginPlay 中绑定 HealthComp->OnDeath.AddDynamic 并 SetActorTickEnabled(false)。
35. 每个生命周期重写都必须调用 Super::（BeginPlay、EndPlay、PostInitializeComponents 等），否则会破坏复制、GC 和蓝图事件转发。
36. 不要存储裸 actor 指针（actor 销毁后会崩溃），改用 TWeakObjectPtr<AActor> 并在使用前检查 IsValid()。
37. 参考相关技能：ue-cpp-foundations（UCLASS/UPROPERTY/UFUNCTION 宏）、ue-gameplay-framework（GameMode、PlayerController、Pawn）、ue-physics-collision（UPrimitiveComponent 通道、扫描、重叠事件）。

适用边界 · 注意事项

• 项目不使用虚幻引擎或采用非 Actor-Component 架构时。
• 只需要纯 C++/蓝图小改动、不涉及 actor 生命周期、组件、生成或 tick 时。
• 无法访问项目上下文文件且不需要遵循既有基类与命名约定时。