在 Unreal Engine 项目中实现碰撞检测…

适用于 UE 项目中的碰撞通道/配置、LineTrace/Sweep/Overlap、OnHit/Overlap 事件、Physics Body、Physical Material 和 Chaos 物理系统实现。

适用场景

解决思路

1. 读取 `.agents/ue-project-context.md`，确认 UE 版本（UE 5.0 起默认 Chaos，PhysX 已弃用）。
2. 确认哪些模块需要在 `Build.cs` 加入 `PhysicsCore` 和 `Engine`。
3. 确认项目使用带 physics asset 的 skeletal mesh，还是主要用 static mesh collision。
4. 确认是否有 dedicated server targets，以决定物理模拟是否服务端运行。
5. 若未明确，先判断需求属于：collision setup、trace queries、collision events、physics simulation、physical materials。
6. 内置对象通道：`ECC_WorldStatic`、`ECC_WorldDynamic`、`ECC_Pawn`、`ECC_PhysicsBody`、`ECC_Vehicle`、`ECC_Destructible`；trace 通道：`ECC_Visibility`、`ECC_Camera`；自定义：`ECC_GameTraceChannel1..ECC_GameTraceChannel18`。
7. 响应类型：`ECR_Ignore` / `ECR_Overlap`（事件，不阻挡）/ `ECR_Block`（物理阻挡+事件）。
8. 内置 profile：`BlockAll`、`BlockAllDynamic`、`OverlapAll`、`OverlapAllDynamic`、`Pawn`、`PhysicsActor`、`NoCollision`。
9. 在 C++ 中优先用 `SetCollisionProfileName` 一次性设置；再用 `SetCollisionEnabled`（`NoCollision | QueryOnly | PhysicsOnly | QueryAndPhysics`）、`SetCollisionObjectType`、`SetCollisionResponseToAllChannels`、`SetCollisionResponseToChannel` 覆盖单项。
10. 区分 object type channels（物体是什么：Pawn、WorldDynamic、Vehicle，每个组件只有一个）与 trace channels（查询找什么：Visibility、Camera、Weapon）；`ByObjectType` 匹配目标 object type，`ByChannel` 用查询者 trace channel 并检查响应。
11. 对多数 gameplay trace 使用 trace channels（`ECC_Visibility`、自定义 `Weapon`）；用 overlap 查询“找所有 pawn”时使用 object type（`ECC_Pawn`）。
12. 自定义通道写入 `DefaultEngine.ini` 的 `[/Script/Engine.CollisionProfile]`，用 `+DefaultChannelResponses=(Channel=...,DefaultResponse=...,bTraceType=True/False,bStaticObject=False,Name=...)`；`bTraceType=True` 为 trace channel，`False` 为 object type channel；用 `+Profiles=(Name=...,CollisionEnabled=...,ObjectTypeName=...,CustomResponses=...)` 定义 profile。
13. 参考 `references/collision-channel-setup.md` 获取完整 profile 示例。
14. 配置 `FCollisionQueryParams`：设置 `TraceTag` 便于 profiling/debug；默认 `bTraceComplex=false`；需要物理材质时 `bReturnPhysicalMaterial=true`；需要面索引时才 `bReturnFaceIndex=true`；用 `AddIgnoredActor(this)` 和 `AddIgnoredComponent(MyComp)` 忽略自身。
15. 从 `WorldCollision.h` 经 `UWorld` 调用 world-level trace：`LineTraceSingleByChannel`、`LineTraceMultiByChannel`、`LineTraceSingleByObjectType`（先用 `FCollisionObjectQueryParams` 和 `AddObjectTypesToQuery`）、`LineTraceSingleByProfile`。
16. 用 `CollisionShape.h` 的 `FCollisionShape` 做 sweep：`MakeSphere`、`MakeBox`、`MakeCapsule`；调用 `SweepSingleByChannel`、`SweepMultiByChannel`、`SweepSingleByObjectType`、`SweepSingleByProfile`。
17. 用 overlap 查询：`OverlapMultiByObjectType`（如 `FCollisionObjectQueryParams(ECC_Pawn)` 配 `FCollisionShape::MakeSphere`），遍历 `FOverlapResult` 取 `GetActor()`；也可用 `OverlapMultiByChannel` 走通道响应而非 object type 匹配。
18. 使用 `FHitResult` 关键字段：`bBlockingHit`、`ImpactPoint`、`ImpactNormal`、`Distance`、`BoneName`、`GetActor()`、`GetComponent()`；若 `bReturnPhysicalMaterial=true`，用 `Hit.PhysMaterial.Get()` 和 `UPhysicalMaterial::DetermineSurfaceType` 取 `EPhysicalSurface`。
19. 用 Blueprint-layer traces（`Kismet/KismetSystemLibrary.h`）：`LineTraceSingle`、`SphereTraceSingle` 使用 `ETraceTypeQuery`（映射到 `ECollisionChannel`）、`EDrawDebugTrace`；`LineTraceSingleByProfile` 可按 profile 查询。
20. 用 async traces：调用 `AsyncLineTraceByChannel` 拿 `FTraceHandle`，下一帧用 `QueryTraceData` 读取 `FTraceDatum`，再取 `OutHits`。
21. Debug 可视化：`DrawDebugLine`、`DrawDebugSphere`（来自 `DrawDebugHelpers.h`），用 `#if ENABLE_DRAW_DEBUG` 包裹以便 shipping 编译掉；注意 `bPersistentLines` 和 `LifeTime` 参数。
22. 参考 `references/trace-patterns.md` 获取完整 gameplay patterns（hitscan、melee sweep、AoE、ground detection、async sensors）。
23. 绑定碰撞事件 delegate：`OnComponentHit`（参数 HitComp, OtherActor, OtherComp, NormalImpulse, FHitResult）、`OnComponentBeginOverlap`（OverlappedComp, OtherActor, OtherComp, OtherBodyIndex, bFromSweep, SweepResult）、`OnComponentEndOverlap`（OverlappedComp, OtherActor, OtherComp, OtherBodyIndex）。
24. Hit 事件要求：碰撞启用为 `QueryAndPhysics`，双方响应 `ECR_Block`，并调用 `SetNotifyRigidBodyCollision(true)`；否则 `OnComponentHit` 不触发。
25. Overlap 事件要求：双方响应 `ECR_Overlap`，且双方都 `SetGenerateOverlapEvents(true)`。
26. 物理体模拟：用 `SetSimulatePhysics(true)`、`SetEnableGravity(true)`、`SetMassOverrideInKg`、`SetLinearDamping`、`SetAngularDamping`、`GetMass`。
27. 施加力/冲量：`AddImpulse`（`bVelChange=true` 忽略质量）、`AddImpulseAtLocation`（产生扭矩）、`AddForce`（每 tick 持续）、`AddRadialImpulse`、`SetPhysicsLinearVelocity`（少用）。
28. 设置 `FBodyInstanceCore` 关键标志：`bSimulatePhysics`、`bOverrideMass`、`bEnableGravity`、`bAutoWeld`、`bStartAwake`、`bGenerateWakeEvents`、`bUpdateKinematicFromSimulation`。
29. 选择碰撞复杂度：`CTF_UseDefault`、`CTF_UseSimpleAndComplex`、`CTF_UseSimpleAsComplex`、`CTF_UseComplexAsSimple`（昂贵，仅静态可用作物理）。
30. 创建物理约束：`UPhysicsConstraintComponent`，`SetupAttachment`，`SetConstrainedComponents`，用 `SetAngularSwing1Limit`、`SetAngularTwistLimit`、`SetLinearXLimit` 设置角/线性限制，再 `RegisterComponent`。
31. 使用命名约束预设：Fixed（全部 angular/linear locked）、Hinge（一轴 angular free，linear locked）、Prismatic（angular locked，一轴 linear free）、Ball-and-Socket（angular free，linear locked）。
32. 配置 `UPhysicalMaterial`：`Friction`、`StaticFriction`、`Restitution`、`Density`（g/cm^3，用于按体积算质量）、`SurfaceType`（`SurfaceType_Default`、`SurfaceType1..SurfaceType62`）；`FrictionCombineMode` / `RestitutionCombineMode` 可选 Average、Min、Multiply、Max。
33. 运行时覆盖物理材质：`SetPhysMaterialOverride`；从 trace 检测表面需 `bReturnPhysicalMaterial=true`，再用 `DetermineSurfaceType` 并 switch。
34. 使用 Chaos（UE5 默认，PhysX 移除）：`FChaosScene` 拥有 solver，含 `StartFrame()`、`SetUpForFrame()`、`EndFrame()`；物理在专用线程运行，游戏线程在同步点读结果。
35. 对快速小物体穿透薄几何时启用 substepping：Project Settings > Physics 的 `MaxSubsteps`、`MaxSubstepDeltaTime`，将物理 tick 分成更小增量。
36. 使用 async physics：通过 `UPhysicsSettings::bTickPhysicsAsync` 启用，在需要物理线程输入回调的组件上使用 `UAsyncPhysicsInputComponent`。
37. 调整 `UPhysicsSettingsCore`：`DefaultGravityZ`（默认 -980 cm/s^2）、`BounceThresholdVelocity`、`MaxAngularVelocity`、`MaxDepenetrationVelocity`、`ContactOffsetMultiplier`、`FChaosSolverConfiguration SolverOptions`。
38. 配置 `EPhysicalSurface`：Project Settings > Physics > Physical Surface 中映射 62 个槽位 `SurfaceType1..SurfaceType62`。
39. 对 Chaos Destructibles 使用 `UGeometryCollectionComponent`；断裂阈值由 `FPhysicalMaterialStrength`（TensileStrength、CompressionStrength、ShearStrength）和 `FPhysicalMaterialDamageModifier`（DamageThresholdMultiplier）驱动。
40. Cloth simulation：在 Mesh asset 的 Clothing → Add Clothing Data 启用；`UClothingAssetBase` 附着到 `USkeletalMeshComponent`；用 `GetClothingSimulationInteractor` 获取 `UClothingSimulationInteractor`；调用 `PhysicsAssetUpdated()` 在 physics asset 变化后重新同步，调用 `SetAnimDriveSpringStiffness` 混合动画与布料。
41. Field System：放置 `AFieldSystemActor`，添加 `URadialFalloff`、`URadialVector`、`UUniformVector`、`UBoxFalloff` 等 field nodes；运行时 spawn `AFieldSystemActor`，创建 field 和 `UFieldSystemMetaDataFilter`，配置 `SetRadialFalloff`、`SetMetaDataFilterType`，再 `GetFieldSystemComponent()->ApplyPhysicsField(true, EFieldPhysicsType::Field_ExternalClusterStrain, Meta, Falloff)`。
42. 避免错误碰撞响应：Overlap 事件需要双方 `ECR_Overlap` 且双方 `bGenerateOverlapEvents=true`。
43. 避免每 Tick 对大量 actor 做 trace：用 async traces 或 timer 节流到 5–10 Hz。
44. 区分 `QueryOnly`（仅 trace，无力）与 `PhysicsOnly`（仅力，trace 跳过）；两者都要时用 `QueryAndPhysics`。
45. 避免默认用复杂碰撞：`bTraceComplex=true` 贵 4–10 倍，默认 `false`，只在精确地形交互时启用。
46. 不要漏掉 `SetNotifyRigidBodyCollision`：`OnComponentHit` 无此标志永不触发，它与碰撞响应是分开的。
47. 区分 Sweep 与 Overlap：Sweep 是形状沿路径移动（移动、弹道），Overlap 是固定点形状（AoE、接近检测），不要替代。
48. Dedicated server 上禁用不需要的 skeletal ragdoll：设置 `bSimulateSkeletalMeshOnDedicatedServer=false`，除非需要服务器精度。
49. Multiplayer 中物理模拟默认在服务端运行；碰撞事件默认只在服务端触发，客户端要显式 RPC 复制；客户端通过 `FRepMovement`（由 `bReplicateMovement` 控制）看到复制的位置/速度，物理状态本身不复制；客户端预测物理在本地模拟并与服务端权威校正；纯装饰物理（ragdoll、碎片、环境道具）可客户端独立模拟。
50. 在 `Build.cs` 加依赖：`PublicDependencyModuleNames.AddRange(new string[] { Core, CoreUObject, Engine, PhysicsCore });`。
51. 相关技能：`ue-actor-component-architecture` 了解 `UPrimitiveComponent` 生命周期、attachment、registration；`ue-ai-navigation` 了解 trace-based sensing 和 navmesh overlap；`ue-gameplay-abilities` 了解基于 trace/overlap 的 targeting；`ue-cpp-foundations` 了解 delegate 绑定语法和 UFUNCTION 要求。

适用边界 · 注意事项

• 不适用于非 Unreal Engine 项目。
• 不需要碰撞检测、Trace 查询或物理模拟的纯逻辑/UI 项目不适用。
• 仍依赖已弃用 PhysX 的旧项目需先确认 UE 版本与 Chaos 迁移状态。