Collider.h

USTRUCT ×7 UENUM ×1

Source/MassBattle/Public/Fragments/Collider.h

概述 Overview

碰撞与物理系统的 fragment 集合:配置 FCollider(胶囊形状、质量、碰撞组、PBD 开关、压力场开关)、共享配置 FPhysicsShared(PBD / 摩擦 / 空气阻力 / 压力场参数,按 archetype 去重)与 FPressureFieldConfig(压力场密度参数),外加网格注册模式枚举 EGridRegisterMode 和四个 PBD 求解用的邻居数据载体(FAgentPBDData / FCapsulePBDData / FSegmentPBDData / FBoxObstPBDData)。

Collision and physics fragment collection: config FCollider (capsule shape, mass, collision groups, PBD switches, pressure-field switches), shared config FPhysicsShared (PBD / friction / air-drag / pressure-field knobs, deduplicated per archetype) and FPressureFieldConfig (pressure-field density parameters), plus the grid-registration enum EGridRegisterMode and four PBD neighbor data carriers (FAgentPBDData / FCapsulePBDData / FSegmentPBDData / FBoxObstPBDData).

EGridRegisterMode UENUM

碰撞体注册到空间网格的方式,由 FCollider::GridRegisterMode 使用。

How the collider registers into the spatial grid; used by FCollider::GridRegisterMode.

值 Value	说明 Description
`SingleCell`	仅注册到 Agent 占用的主单元。Register to only the primary cell the agent occupies.
`MultipleCells`	注册到所有重叠单元(推荐巨型单位)。Register to all overlapping cells (recommended for giant units).
`None`	不注册到邻居网格(Agent 不参与空间查询)。Do not register to the neighbor grid (agent won't participate in spatial queries).

FCollider USTRUCT

碰撞体配置 fragment(FA_MassBattleBaseFragment 派生)。定义胶囊形状(Radius/Height)、PBD 碰撞质量与开关、碰撞组、网格注册方式与压力场参与开关。PBD / 摩擦等精细参数已迁移至 FPhysicsShared。

Collider config fragment (derived from FA_MassBattleBaseFragment). Defines the capsule shape (Radius/Height), PBD mass and switches, collision groups, grid registration mode and pressure-field participation. Fine-grained PBD / friction knobs have moved to FPhysicsShared.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`Radius`	`float`	`34.f`	球体(胶囊端盖)半径(ClampMin=0)。Sphere (capsule cap) radius (ClampMin=0).
`Height`	`float`	`108.f`	圆柱体(胶囊轴)高度(ClampMin=0)。Cylinder (capsule shaft) height (ClampMin=0).
`Mass`	`float`	`1.0f`	质量,用于 PBD 碰撞计算,重的物体推开轻的(ClampMin=0.001)。Mass for PBD collision logic; heavier objects push lighter ones (ClampMin=0.001).
`RelativeRotation`	`FRotator3f`	`ZeroRotator`	碰撞体相对 Agent 旋转的相对旋转。Relative rotation of the collider, relative to the agent's rotation.
`GridRegisterMode`	`EGridRegisterMode`	`SingleCell`	如何将碰撞体注册到空间网格:SingleCell(默认), MultipleCells(巨型单位), None(不参与空间查询)。How to register the collider to the spatial grid: SingleCell (default), MultipleCells (giant units), None (no spatial queries).
`Group`	`int32`	`1`	自身碰撞组(1-8,Clamp 1–8)。Self collision group (1-8, clamped 1–8).
`IgnoreGroupFlags`	`uint8`	`0`	不与这些组产生碰撞(位掩码:Flag1 = 组1 … Flag8 = 组8)。单向语义:被无视的一方仍会与你碰撞并自行解决重叠。Groups to not collide with (bitmask: Flag1 = Group 1 ... Flag8 = Group 8). One-directional: the ignored side still collides with you and resolves overlap by itself.
`bEnablePBD`	`bool`	`true`	启用基于位置的动力学(PBD)碰撞解决重叠。Enable Position Based Dynamics collision for hard separation.
`bCollideWithAgent`	`bool`	`true`	是否与其他 Agent 发生碰撞(仅 PBD 开启时可编辑)。Whether to collide with other agents (editable only when PBD is on).
`bCollideWithDyingAgent`	`bool`	`false`	即使对方处于死亡状态,也可以与其发生碰撞。Whether to collide with agents even when they are dying.
`bCollideWithObst`	`bool`	`true`	是否与障碍物(胶囊、线段、场景)发生碰撞(仅 PBD 开启时可编辑)。Whether to collide with obstacles (capsule, segment, scene) (editable only when PBD is on).
`bDepositToPressureField`	`bool`	`false`	启用时,此 Agent 向压力场网格沉积密度,作为把其它 Agent 推开的压力源。When enabled, this agent deposits density into the pressure field grid, acting as a pressure source that pushes other agents away.
`bPushedByPressureField`	`bool`	`false`	启用时,此 Agent 经压力场梯度受到物理推动(位置漂移 + 速度反馈)。When enabled, this agent is pushed by the pressure field gradient via physics (position drift + velocity feedback).

FPressureFieldConfig USTRUCT

压力场配置(非 fragment)。经 FPhysicsShared 在同 archetype 的 Agent 间共享,相同配置去重为每个 archetype 一份。个体 Agent 经 FCollider::bDepositToPressureField 选择沉积、经 FCollider::bPushedByPressureField 选择受力。

Pressure-field configuration (not a fragment). Shared across agents of the same archetype via FPhysicsShared so identical values dedupe to one instance per archetype. Individual agents opt into deposit via FCollider::bDepositToPressureField and into physics pushback via FCollider::bPushedByPressureField.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`BaseDeposit`	`float`	`1.0f`	每帧沉积的基础密度。越高表示越强的人群源。Base density deposited into its cell every frame. Higher = stronger crowd source.
`ObstTouchBonus`	`float`	`1.0f`	接触障碍物时额外沉积的密度(墙体源)。Extra density deposited when touching an obstacle (wall sources).
`PressureBiasStrength`	`float`	`50000.0f`	压力物理漂移强度(cm / 梯度单位 / 秒)。越高位置推力越强。Pressure physics drift strength (cm per gradient unit per second). Higher = stronger position push.
`PressureBiasMaxFraction`	`float`	`0.3f`	压力漂移上限,为 MoveSpeed 的该比例。Cap the pressure drift to this fraction of MoveSpeed.

FPhysicsShared USTRUCT

物理共享配置 fragment(FA_MassBattleBaseSharedFragment 派生,可变)。集中存放原 FCollider 中 bEnablePBD 之后的 PBD / 摩擦 / 空气阻力 / 压力场参数;以可修改的共享片段分发,相同配置在同 archetype 间去重(镜像 FTrafficShared / FAnimShared 模式),运行时仍可经 GetMutableSharedFragment 修改。

Physics shared config fragment (derived from FA_MassBattleBaseSharedFragment, mutable). Collects the PBD / friction / air-drag / pressure-field knobs that used to live on FCollider after bEnablePBD; distributed as a mutable shared fragment so identical values dedupe per archetype (mirrors the FTrafficShared / FAnimShared pattern), still runtime-tweakable via GetMutableSharedFragment.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`ColliderMult`	`float`	`1.0f`	仅用于 PBD 的碰撞体缩放系数:解决 Agent 与邻居的 PBD 碰撞时虚拟放大胶囊半径(不放大轴高),让接触提前触发,但不改变 trace 与视觉形状。候选检测与 per-pair 求解都使用放大后的半径,轴高保持真实;Trace-for-agents 仍读取未放大的 Radius/Height。PBD-only collider scale multiplier: virtually inflates the capsule radius (NOT shaft height) when resolving agent-vs-neighbor PBD collisions, making contacts trigger sooner without changing the trace/visual shape. Both the candidacy gather and the per-pair solver use the inflated radius; shaft height stays real; trace-for-agents still reads the un-multiplied Radius/Height.
`ExtraExtent`	`FVector2f`	`(0, 0)`	自己侧的 PBD 邻居采集盒额外扩展(可选,编辑器显示名 "Extra Neighbor Extent (XY, Z)",ClampMin=0)。本单位采集盒默认为 max(RVO 臂长, SelfPBDRadius);X 扩展水平(XY)搜索距离,Y 扩展垂直(Z)。在 PBD 接触触达(自身放大半径 + 常见对手包围)可能超出默认盒的单位上设置——如大型 SingleCell 单位,使接触在距离上即被捕获而非深重叠后弹开(消除接触闪烁/抖动)。采集由单位自己完成,无任何全场协调;高瘦单位可只声明 Y,让身高不再毒化水平盒。默认 (0,0) = 旧版搜索盒。Self-side extra PBD neighbor-gather box extent, opt-in (editor display name "Extra Neighbor Extent (XY, Z)", ClampMin=0). This unit's gather box defaults to max(RVO arm, SelfPBDRadius); X extends the horizontal (XY) search distance, Y the vertical (Z). Set it on units whose PBD contact reach (own inflated radius + typical partner bound) can exceed the default box — e.g. large SingleCell units — so contacts are acquired at range instead of after deep overlap (removing contact flicker/jitter). The searching unit finds the pair itself, so no scene-wide coordination exists; tall units may declare Y only so height stops poisoning the horizontal box. Default (0,0) = legacy box.
`Friction_Lateral`	`float`	`8.f`	横向(侧滑)动摩擦系数。帧末对速度的横向分量(垂直于摩擦帧)做 exp(-k·dt) 衰减,始终开启。值越大单位越具抓地感。车辆位置层的横向抓地力用 `StaticFriction_Lateral`(库仑模型)。Lateral (sideslip) dynamic friction baseline. Applied as exp(-k*dt) decay on the lateral velocity component at end of frame; always-on. High values make crowds grippy. For position-layer lateral grip on vehicles, use `StaticFriction_Lateral` (Coulomb model).
`StaticFriction_Lateral`	`float`	`0.f`	库仑静摩擦(cm/s),作用于横向 PBD 推动;> 0 时对所有移动模型生效(含 Creature);0 = 关闭(完全被推——旧默认)。每帧预算 = 值 × dt(cm),低于预算的侧向 PBD 位置修正被完全吸收——Agent 保持原位(如攻击者站定射击);高于预算时仅应用超出部分。前向推动不受影响。预算作用于 `PositionRelaxation_Agent` 缩放后的净侧向修正。解决缓慢侧向漂移问题,无需 exp(-k·dt) 位置层补丁。Coulomb static friction (cm/s) for lateral PBD pushes; when > 0 it applies to ALL movement models incl. Creature (0 = disabled, full lateral pushes — legacy default). Budget = Value × dt (cm); lateral PBD corrections below it are fully absorbed — the agent holds its ground (e.g. attackers standing while shooting); above it only the excess applies. Forward pushes pass through. The budget tests the NET lateral correction after `PositionRelaxation_Agent` scaling. Solves slow sideways drift without an exp(-k*dt) position hack.
`StaticFriction_Longitudinal`	`float`	`0.f`	库仑静摩擦(cm/s),作用于前向轴的 PBD 推动,所有移动模型。仅当 Agent 无前向意图时(\|期望·朝向\| ≤ 1 cm/s——站定/瞄准/静止)生效:预算 = 值 × dt(cm),低于预算的前向修正被完全吸收——站定单位不被前向推挤。有前向意图时跳过预算,绝不吞掉自身移动。朝向轴双向吸收。0 = 关闭。Coulomb static friction (cm/s) for FORWARD-AXIS PBD pushes, all movement models. Only while the agent has NO forward intent (\|Desired·Fwd\| ≤ 1 cm/s — planted/aiming/idle): budget = Value × dt (cm); forward PBD corrections below it are fully absorbed, so planted agents hold their ground against forward shoves. With forward intent the budget is skipped so it never fights self-movement. Both signs along the facing axis are absorbed. 0 = disabled.
`Friction_Longitudinal`	`float`	`0.f`	纵向(刹车)摩擦系数,0 = 无前进阻力。仅用于刹车:当 Agent 有前向意图时跳过前向衰减,保证持续输入可达 MoveSpeed,与 CMC 地面摩擦行为一致。适用于载具/飞行器;生物类留 0(靠作者定义的减速度停下)。Longitudinal (braking) friction baseline; 0 = no forward drag. Brake-only: forward decay is skipped when the agent has forward intent so sustained input reaches MoveSpeed, mirroring CMC ground friction. For vehicles/aircraft; leave 0 for creatures.
`FrictionMult_OnStop`	`float`	`2.f`	停止意图摩擦乘数:Agent 想要停下(沿摩擦帧的期望速度 ≤ 1 cm/s)时作用于 Friction_Lateral / Friction_Longitudinal,让 idle/已到达的 Agent 更快定在原地,不影响主动移动。1.0 = 不改变。Multiplier applied to Friction_Lateral / Friction_Longitudinal while the agent WANTS to stop (desired velocity along the friction frame ≤ 1 cm/s). Lets idle/arrived agents pin in place faster without affecting active movement. 1.0 = unchanged.
`AirDrag`	`float`	`0.05f`	空中阻力系数,仅在空中(下落/抛射)时作用于 XY 速度:v = exp(-AirDrag·dt)——精确指数积分,帧率无关且无条件稳定(与 Friction_Lateral/Longitudinal 同一积分器),大值只会让空中 XY 更快归零、绝不反号。默认 0.05 有物理依据:≈ 真实空气对人形单位在 ~10 m/s 时的阻力(每秒保留 ~95% 速度,弹道保持抛物线)。0 = 真空(动量不衰减);0.1~0.3 = 明显魔法阻力;1.0 ≈ 每秒损失 63%。空中状态下地面摩擦被跳过,本项是 XY 唯一的衰减来源。Air drag coefficient applied to XY velocity while airborne (falling/launching): v = exp(-AirDrag*dt) — an exact exponential integrator, frame-rate independent and unconditionally stable (same integrator as Friction_Lateral/Longitudinal); large values only zero out aerial XY faster, never flip its sign. Default 0.05 is physically grounded: real-air drag on a human-scale body at ~10 m/s (retains ~95% velocity per second, ballistic arcs stay parabolic). 0 = vacuum (carry momentum forever); 0.1–0.3 = heavy magical drag; 1.0 = ~63% loss/s. Surface friction is bypassed mid-air, so this is the ONLY XY decay during freefall.
`MassDominanceRatio`	`float`	`1.f`	质量优势比:SelfMass > NeighborMass × Ratio 时 self 变为静态障碍物(SelfShare=0)。1.0 = 关闭(纯质量加权分配)。已摘除编辑器/BP 暴露(无任何配置启用过):现为仅 `UPROPERTY()` 字段,固定默认 1 = 优势门控关闭;求解路径仍读取该字段。用比值而非原始质量,避免 81kg 对 80kg 也变成不可推动的墙。连续性质量加权在避障层单独处理(`FTrafficShared::MassWeighting`)。Mass dominance ratio: when SelfMass > NeighborMass × Ratio, self acts as a static obstacle (SelfShare=0). 1.0 = disabled (pure mass-weighted split). Editor/BP exposure retired (no authored config ever used it): now a bare `UPROPERTY()` field fixed at the default 1 = dominance gate disabled; solver paths still read the field. Ratio (not raw mass) avoids an 81kg agent being immovable against an 80kg neighbor. Continuous mass weighting lives in the avoidance layer (`FTrafficShared::MassWeighting`).
`PositionRelaxation_Agent`	`float`	`1.0f`	Agent 间 PBD 位置修正刚度(1.0=硬, 0.1=软)。Agent 对障碍物始终使用 1.0(硬墙)。Stiffness of agent-vs-agent PBD position corrections (1.0 = hard, 0.1 = soft). Agent-vs-obstacle is hardcoded to 1.0 (obstacles are always hard walls).
`VelocityRelaxation_Agent`	`float`	`1.0f`	Agent 间 PBD 位置修正反馈到速度的程度(1.0 = 速度完全反映推动;更低 = 重叠 Agent 保留意图速度,人群更顺滑地穿插)。障碍物方向始终使用 1.0。How much of the agent-vs-agent PBD position correction feeds into velocity (1.0 = fully reflected; lower = overlapping agents retain intended velocity). Obstacle feedback is hardcoded to 1.0.
`PressureField`	`FPressureFieldConfig`	—	压力场沉积配置(基础密度与接触障碍加成)。同 archetype 共享;按 Agent 由 `FCollider::bDepositToPressureField` 门控。Pressure field deposit config (base density and obstacle-touch bonus). Shared across the archetype; gated per-agent by `FCollider::bDepositToPressureField`.
`DeterministicHash`	`int32`	`0`	确定性 CRC32 种子。模板构建时从 asset path(`GetPathName`)赋值。Deterministic CRC32 seed. Set from the asset path (`GetPathName`) at template-build.

方法 Methods

operator== FORCEINLINE bool

逐字段比较(含 PressureField 嵌套),供共享 fragment 去重判断。注意 DeterministicHash 不参与比较。

Field-by-field comparison (including nested PressureField); used for shared-fragment deduplication. Note DeterministicHash is excluded.

Input

参数 Param	类型 Type	说明 Description
`Other`	`const FPhysicsShared&`	待比较对象。The object to compare against.

Output

返回是否全部字段相等。无副作用。

Returns whether all fields are equal. No side effects.

FAgentPBDData USTRUCT

PBD 求解用的 Agent 邻居数据(非 fragment)。从 FAgentGridData 构造:收集阶段一次计算出 DeltaTime 后的预测 XY 位置(PredictedXY),PBD 求解器无需重建预测邻居数组;碰撞半径经 ColliderMult 放大,高度保持真实。

Agent-neighbor data for the PBD solver (not a fragment). Constructed from FAgentGridData: the predicted XY position after DeltaTime is computed once during gather (PredictedXY), so the solver does not rebuild a predicted-neighbor array; collider radius is inflated by ColliderMult, height stays real.

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`EntityHandle` / `UniqueID`	`FMassEntityHandle` / `int32`	— / `-1`	邻居实体句柄与唯一 ID。Neighbor entity handle and unique ID.
`UpVector`	`FVector3f`	`UpVector`	邻居朝上向量。Neighbor up vector.
`RelativePosition`	`FVector2f`	`(0, 0)`	相对请求 Agent 的 XY 位置。XY position relative to the requesting agent.
`LocationZ`	`float`	`0.f`	邻居 Z 位置。Neighbor Z location.
`Velocity`	`FVector2f`	`(0, 0)`	邻居速度(用于预测)。Neighbor velocity (for prediction).
`PredictedXY`	`FVector2f`	`(0, 0)`	DeltaTime 后的预测绝对 XY 位置(收集时计算)。Predicted absolute XY position after DeltaTime (computed during gather).
`ColliderRadius` / `ColliderHeight`	`float`	`34.f` / `108.f`	碰撞半径(已乘 `ColliderMult`)与真实高度。Collider radius (×`ColliderMult`) and real height.
`Mass`	`float`	`1.f`	质量。Mass.
`AngularVelocity`	`float`	`0.f`	角速度(度/秒),用于旋转扫掠膨胀。Angular velocity (deg/s), for rotational sweep inflation.
`bIsTouchingObst` / `bIsImmovable`	`uint8 : 1`	0	该邻居本帧正接触障碍物 / 邻居为不可推动体(PBD 关或关 Agent 碰撞但仍注册网格)——自身承担 100% 位移。Neighbor in obstacle contact this frame / neighbor is an immovable body (PBD off or agent-collision off while grid-registered) — self takes 100% displacement.

FCapsulePBDData USTRUCT

PBD 求解用的胶囊障碍邻居数据(非 fragment)。从 FCapsuleObstGridData 构造(轴高 = (半高−半径)×2,仅圆柱轴不含端盖);另有从线段障碍构造的重载(组模式内部情况——零半径垂直线段)。

Capsule-obstacle neighbor data for the PBD solver (not a fragment). Constructed from FCapsuleObstGridData (shaft height = (HalfHeight − Radius) × 2, cylinder shaft only, no caps); plus an overload constructed from segment obstacles (group-mode inside case — zero-radius vertical line).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`EntityHandle` / `UniqueID`	`FMassEntityHandle` / `int32`	— / `-1`	障碍实体句柄与唯一 ID(线段来源填入 GroupID)。Obstacle entity handle and unique ID (segment sources fill GroupID).
`UpVector` / `RelativePosition`	`FVector3f`	`UpVector` / `Zero`	障碍朝上向量与相对请求 Agent 的位置。Obstacle up vector and position relative to the requesting agent.
`ColliderRadius` / `ColliderHeight`	`float`	`34.f` / `108.f`	障碍半径与轴高(构造时按数据覆写)。Obstacle radius and shaft height (overwritten at construction).
`Speed`	`float`	`0.f`	障碍速度大小。Obstacle speed magnitude.
`bOverrideSpeedLimit` / `bIsCylinder`	`uint8 : 1`	0	可覆盖限速 / 是否圆柱体。Overrides speed limit / is cylinder.

FSegmentPBDData USTRUCT

PBD 求解用的线段障碍数据(非 fragment)。从 FSegmentObstGridData 字段直拷(Point/NextPoint/PointZ/Height)。

Segment-obstacle data for the PBD solver (not a fragment). Straight field copy from FSegmentObstGridData (Point/NextPoint/PointZ/Height).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`EntityHandle` / `GroupID` / `Index`	`FMassEntityHandle` / `uint32` / `int32`	— / `0` / `0`	实体句柄、组 ID 与组内索引。Entity handle, group ID and in-group index.
`Point` / `NextPoint`	`FVector2f`	`(0, 0)`	线段两端点(XY)。Segment endpoints (XY).
`PointZ` / `Height`	`float`	`0.f`	基准高度 Z 与线段高度。Base height Z and segment height.

FBoxObstPBDData USTRUCT

PBD 求解用的盒子障碍数据(非 fragment)。从 FBoxObstGridData 构造,HalfExtents(FVector3f→FVector)与 Orientation(FQuat4f→FQuat)做类型转换。

Box-obstacle data for the PBD solver (not a fragment). Constructed from FBoxObstGridData, casting HalfExtents (FVector3f→FVector) and Orientation (FQuat4f→FQuat).

成员变量 Members

名称 Name	类型 Type	默认值	说明 Description
`EntityHandle` / `UniqueID`	`FMassEntityHandle` / `int32`	— / `-1`	障碍实体句柄与唯一 ID。Obstacle entity handle and unique ID.
`RelativeCenter`	`FVector3f`	`Zero`	OBB 中心相对请求 Agent 的位置。OBB center relative to the requesting agent.
`Orientation`	`FQuat`	`Identity`	OBB 朝向。OBB orientation.
`HalfExtents`	`FVector`	`(50, 50, 50)`	OBB 半尺寸。OBB half extents.
`bInsideOut` / `bOverrideSpeedLimit`	`uint8 : 1`	0	反向构造(面内朝外) / 可覆盖限速。Inside-out construction / overrides speed limit.

管线角色 Pipeline Role

FCollider / FPhysicsShared 由移动与网格处理器消费:FAgentGridData / FAgentPBDData 等载体在网格收集阶段从 FCollider 形状与 FPhysicsShared 参数(ColliderMult)构造,供 PBD 求解与避障使用。压力场沉积/受力由 FCollider 的两个开关门控(头注释声明:避障层压力耦合已于 2026-08 移除(36a44902——锁步发散);压力格寻路兜底同月尝试后亦已移除;压力场如今只喂 bPushedByPressureField 物理漂移,跑在 FFix64 场地基上)。

FCollider / FPhysicsShared are consumed by movement and grid processors: carriers like FAgentGridData / FAgentPBDData are built at the grid-gather phase from the FCollider shape and FPhysicsShared knobs (ColliderMult) for the PBD solver and avoidance. Pressure-field deposit/pushback is gated by the two FCollider switches (per the header comments: the avoidance-layer pressure coupling was removed 2026-08 (36a44902 — lockstep divergence); a pressure-grid pathfinding fallback was tried and removed again later the same month; the field now feeds ONLY the bPushedByPressureField physics drift, on the FFix64 field foundation).

补充说明 Notes

文件中的 PBD 数据载体均提供按 EntityHandle 的 operator== 与 GetTypeHash,支持按实体去重与查找。

All PBD data carriers provide operator== and GetTypeHash based on EntityHandle, supporting per-entity deduplication and lookup.