MassBattlePhysicsTypes.h

独立多次子步 PBD 物理引擎的共享类型(纯 C++ struct,无 USTRUCT 反射)。按「GridUpdateProcessor + MoveProcessor 两段式模型」的评审结论组织为三段:REGISTER(注册段)遍历 agent,把每个打包为恰好一条 64 字节缓存行的 FAgentPhysicsData 记录注册进 2D 平坦哈希网格——记录本身就是网格负载(位置住在网格里,不在侧边数组);SOLVE(求解段)只遍历槽位数组(绝不碰 fragment、绝不碰 TMap):每个 body 读邻居的 Pre 记录(各一条缓存行、cell 切片连续),写自己的 Current 记录,Pre/Current 双版本规则——读只见 Pre、写只进 Current,子步之间由网格更新把 Current 提升为 Pre(零拷贝 swap),成员身份每帧注册一次、遍历余量随运行最大累计位移自适应,跨格漂移绝不丢对;WRITEBACK(写回段)再遍历 agent 一次——唯一的 fragment 写。分桶保持 2D 的原因:精确 3D 胶囊对测试负责垂直判定,2D 使遍历为 (2R/256)² 次探测而非 (2R/256)³;生产 agent 网格 Z=5000cm 实际同为 2D,同理。

Shared types for the standalone multi-substep PBD physics engine (plain C++ structs, no USTRUCT reflection). Organized per the GridUpdate + Move two-pass design review into three passes: REGISTER walks agents and packs each into ONE exactly-64-byte cache-line FAgentPhysicsData record registered into the 2D flat hash grid — the record IS the grid payload (positions live in the grid, not in side arrays). SOLVE iterates SLOT ARRAYS ONLY (never fragments, never TMap): every body reads neighbors' Pre records (one cache line each, contiguous cell slices) and writes its own Current record; the Pre/Current double-version rule — reads see only Pre, writes go only to Current; between substeps the grid update promotes Current → Pre (a zero-copy swap); membership is registered once per frame and the walk margin adapts to the running max cumulative displacement so cell-boundary drift can never drop a pair. WRITEBACK walks agents once more — the ONLY fragment writes. Bucketing stays 2D because the exact 3D capsule pair test handles verticality, and 2D keeps a walk at ~(2R/256)² probes instead of (2R/256)³; the production agent grid runs Z=5000 cm — effectively 2D — for the same reason.

通道规则:本文件全部为帧内派生数据——绝不注册进网络 hash / 快照。双端从相同同步 fragment 跑相同代码,锁步安全来自计算一致。引擎宿主为 Processors/MassBattlePhysicsProcessor.h。

Channel rule: everything here is frame-internal derived data — NEVER registered into the network hash/snapshot. Both peers run the same code from the same synced fragments; lockstep safety comes from identical computation. The engine host is Processors/MassBattlePhysicsProcessor.h.

Move 处理器 → 物理处理器的帧内交接记录。独立引擎启用时,Move 处理器在其尾部并行(TLS 直写实体索引槽位)推送;物理处理器在注册段开头串行合并消费(超容溢出部分排空)。

The per-frame handoff record from the Move processors to the physics processor. When the standalone engine is armed, the Move processors push records (parallel, direct entity-indexed writes) at their tail; the physics processor merges + consumes them (draining capacity overflow) serially at register time.

网格/槽位热记录——恰好一条 64 字节缓存行(static_assert(sizeof == 64) 强制)。每槽存在两个版本(Pre / Current):子步读邻居的 Pre、写自身 Current(整记录拷贝 + 新位置),因此每次邻居读取都是一条连续缓存行。求解全程单精度 float(Chaos 同款)。.cpp 中另有 static_assert(std::is_trivially_copyable_v<FAgentPhysicsData>)——以原始字节跨总线安全。

The grid/slot hot record — exactly one 64-byte cache line (enforced by static_assert(sizeof == 64)). Two versions exist per slot (Pre / Current): a substep reads neighbors' Pre and writes its own Current (whole-record copy + new position), so every neighbor read is one contiguous line. The whole solve runs single-precision float (Chaos-style). The .cpp adds static_assert(std::is_trivially_copyable_v<FAgentPhysicsData>) — concurrency-safe to ship as raw bytes.

一条缓存障碍候选。数据指针整帧稳定(障碍网格帧初重建、模拟阶段只读);子步对引用重算接触几何,不重扫障碍网格。每帧只采集一次(注册段内 BuildObstacleCacheForSlot 构建进 FPhysicsSlotSelf::ObstRefs)。

One cached obstacle candidate. The data pointer is stable for the whole frame (the obstacle grid is rebuilt at frame start and read-only during the sim stages); substeps recompute contact geometry against the ref without re-walking the obstacle grid. Gathered ONCE per frame (built into FPhysicsSlotSelf::ObstRefs by BuildObstacleCacheForSlot during the register pass).

仅自身可见的求解状态(配置拷贝、门控、交接输入、累积器)。邻居永远不碰它——所以它可以「胖」,不伤对遍历的缓存表现。热记录(FAgentPhysicsData)只保留邻居需要的最小字段,自身专属的一切都在这里。

Self-only solve state (config copies, gates, handoff inputs, accumulators). Neighbors never touch it — so it can be fat without hurting the pair-walk cache profile. The hot record (FAgentPhysicsData) keeps only the minimum neighbors need; everything self-specific lives here.

一条网格注册项:cell 坐标 + 槽位索引 + 偏置 UID(巨型单位发多条——多格脚印)。UID 与槽位一起打包进每格的 64 位成员字,因此逐格成员排序即得 UID 序,与槽位编号无关——槽位序本身是票号分配(依赖调度),确定性住在格子里(AgentGrid 的 SortAgentCellsByUniqueID 配方)。

One grid registration entry: cell coordinate + slot index + biased UID (giants emit several — a multi-cell footprint). The UID packs WITH the slot into each cell's 64-bit member word, so the per-cell member sort produces UID rank regardless of slot numbering — slot order itself is ticket-assigned (scheduling-dependent); determinism lives in the cells (the AgentGrid SortAgentCellsByUniqueID recipe).

全部类型只服务于 UMassBattlePhysicsProcessor(及其持久化网格宿主 UMassBattlePhysicsSubsystem),以下关系在发布树 grep 验证:FPhysicsHandoffRecord 由两个 Move 处理器(MassBattleAgentMoveProcessor.cpp 与 MassBattleAgentMoveProcessorFP.cpp)在其尾部经 UMassBattlePhysicsProcessor::PushHandoff 实体索引直写;FAgentPhysicsData / FPhysicsSlotSelf 是处理器的 PreData / CurData / Selves 三条槽位数组元素;FPhysicsObstRef 由处理器的 BuildObstacleCacheForSlot 从 UMassBattleHashGridSubsystem 的障碍网格一次性采集;FPhysicsCellEntry 被 UMassBattlePhysicsSubsystem 消费——注册波内经自旋锁追加 / Pending 收集器进入,串行 flush 后逐格按打包字做 UID 成员排序(MassBattlePhysicsSubsystem.h / .cpp)。fragment 的读写全部隔离在处理器的注册段(读)与写回段(写),求解段只见这些槽位结构。网络通道零参与——绝不进 hash / 快照。

Every type here serves only UMassBattlePhysicsProcessor (and its persistent grid host UMassBattlePhysicsSubsystem); the following relations are grep-verified in the release tree: FPhysicsHandoffRecord is written at the tails of both Move processors (MassBattleAgentMoveProcessor.cpp and MassBattleAgentMoveProcessorFP.cpp) via UMassBattlePhysicsProcessor::PushHandoff with direct entity-indexed writes; FAgentPhysicsData / FPhysicsSlotSelf are the elements of the processor's PreData / CurData / Selves slot arrays; FPhysicsObstRef is gathered once per frame by the processor's BuildObstacleCacheForSlot from the obstacle grid of UMassBattleHashGridSubsystem; FPhysicsCellEntry is consumed by UMassBattlePhysicsSubsystem — spinlock appends / the Pending gatherer during the register wave, then a serial flush and the per-cell UID-packed member sort (MassBattlePhysicsSubsystem.h / .cpp). Fragment reads/writes are fully isolated into the processor's register pass (reads) and writeback pass (writes); the solve pass sees only these slot structures. Zero network-channel involvement — never hashed, never snapshotted.

两条 static_assert 守住硬约束:sizeof(FAgentPhysicsData) == 64(恰好一条缓存行,头文件内)与 std::is_trivially_copyable_v<FAgentPhysicsData>(可平凡复制,PhysicsProcessor.cpp 内)。头文件按引擎小版本条件包含实体句年头(UE ≥ 5.8 走 Mass/EntityHandle.h,否则 MassEntityHandle.h),并包含 Fragments/GridData.h 以取三种障碍网格数据类型。AVBD 求解器状态(PairLambda / PairPenalty / PairCContact)的生命周期 = 对条目的生命周期:采集趟初始化(λ=0、ρ=ρ₀),消费趟演化,重采重置——v1 无跨帧 warmstart;完整设计见引擎源码引用的 references/avbd-solver-design.md。

Two static_asserts guard the hard constraints: sizeof(FAgentPhysicsData) == 64 (exactly one cache line, in the header) and std::is_trivially_copyable_v<FAgentPhysicsData> (trivially copyable, in PhysicsProcessor.cpp). The header conditionally includes the entity-handle header by engine minor version (UE ≥ 5.8 → Mass/EntityHandle.h, else MassEntityHandle.h) and includes Fragments/GridData.h for the three obstacle grid data types. The AVBD solver state (PairLambda / PairPenalty / PairCContact) has the lifecycle of its pair entry: gather inits (λ=0, ρ=ρ₀), consume sweeps evolve, regather resets — no cross-frame warmstart in v1; full design in references/avbd-solver-design.md cited by the engine sources.