ChildHood/docs/knowledge/坑-UE5引擎.md

坑-UE5引擎

UE5 引擎相关的坑：Actor/Component 生命周期、初始化时序、引擎 API 陷阱等。 条目按 ID 排列。新增条目时同步更新 INDEX.md。

---

[K-001] Actor BeginPlay 时序竞争：子系统 Driver 可能晚于 Character 初始化

• 来源: P-013 实现偏差报告 · 偏差3
• 症状: 在 AChildHoodCharacter::BeginPlay 中通过 ASystemDriver::Get 取 Driver，再读子系统（如收集系统）的进度数据时，可能读到未初始化的值（Progress=0、CollectedIDs 空），导致进度 Widget 显示错误或存档恢复失败。
• 根因: UE5 不保证不同 Actor 的 BeginPlay 执行顺序。Character 可能先于 ASystemDriver 完成 BeginPlay——此时 Driver 虽然存在，但其持有的子系统尚未执行 RestoreFromPersistence。
• 避坑做法: 不要在 BeginPlay / Initialize 里立即创建依赖其他子系统的对象、或读取其状态。改为首次有效 Tick 时懒创建——等到 World 完全就绪、依赖子系统完成初始化后再创建/读取。
• 状态: ✅正式方案（已用于 UCollectionHUDComponent 的进度 Widget 创建）
• 关联: docs/technical/收集系统-技术方案.md §6、Source/.../CollectionHUDComponent.cpp

---

[K-002] Component 持有的 Timer / Widget 必须在 EndPlay 清理，防 Respawn 野指针

• 来源: P-013 实现偏差报告 · 审查修复2
• 症状: 角色 Respawn（销毁旧 Character、重建新 Character）时崩溃——旧 Component 上还挂着 SetTimer 注册的回调，触发时访问已销毁的 UMG Widget，野指针。
• 根因: Component 被销毁时，UE 不会自动清理你手动注册的 FTimerHandle，也不会自动移除 AddToViewport 的 Widget。这些引用悬挂，下次 Tick 或 Timer 触发即崩。
• 避坑做法: 凡是 Component 持有 FTimerHandle（SetTimer 注册过）或 AddToViewport 的 UMG Widget，必须 override EndPlay，在里头：
  • GetWorld()->GetTimerManager().ClearTimer(MyTimerHandle);（清所有相关句柄）
  • if (MyWidget) MyWidget->RemoveFromParent();（Widget 还有效则移除）
• 状态: ✅正式方案（项目所有 Character 持有 Component 的卫生写法，保持一致）
• 关联: Source/.../CollectionHUDComponent.cpp EndPlay