MassBattleHashFold.h

共享的确定性 hash 折叠原语,是实体 fragment hash 管线(UMassBattleNetworkSubsystem)与 LockstepVarStore 折叠的单一来源。双端必须逐位一致折叠(锁步),所有函数为 inline,保证只有一份实现、不存在漂移。核心问题:含 float/double 叶的结构中 -0.0 == 0.0 相等但字节不同,哈希会不同——因此折叠前先规范化为临时缓冲(memzero padding + -0.0 → 0.0 + 反规格化数冲零),绝不修改 live 状态。所有混合经 CityHash64 系列完成。另提供写入点冲零助手 SanitizeSyncFloat 与数组路径指纹 MakePathFingerprint(数组无法进入反射驱动的哈希注册表,用滚动指纹让路径折线分叉当 tick 即报)。

Shared deterministic hash folding primitives — the single source of truth for both the per-entity fragment hash pipeline (UMassBattleNetworkSubsystem) and the LockstepVarStore fold. Both peers must fold bit-identically (lockstep), so the functions are inline: exactly one implementation to drift. Core problem: in structs with float/double leaves, -0.0 == 0.0 compares equal but hashes differently — so structs are canonicalized into a temp buffer before folding (memzero padding + -0.0 → 0.0 + subnormals flushed to 0.0), never mutating live state. All mixing goes through the CityHash64 family. The header also provides the write-site flush helper SanitizeSyncFloat and the array path fingerprint MakePathFingerprint (arrays cannot enter the reflection-driven hash registry; the rolling fingerprint makes a diverged path polyline visible at its tick).

描述结构体内一个 float/double 叶的偏移。由 BuildHashFloatLeaves 预计算,供 FoldCanonicalizedFloatStruct 折叠时定位并规范化。

Describes the offset of one float/double leaf inside a struct. Precomputed by BuildHashFloatLeaves, consumed by FoldCanonicalizedFloatStruct to locate and canonicalize leaves during folding.

本文件无反射类型、无 .cpp,全部为 inline,被两处消费: ① LockstepVarStore 折叠管线(LockstepVarStore.cpp):ClassifyProperty 用 ContainsFloatOrDoubleLeaves 判定 CanonicalizeFloatStruct 分类并用 BuildHashFloatLeaves 预计算叶(85-89 行);FoldInto 的 CanonicalizeFloatStruct 分支调 FoldCanonicalizedFloatStruct、其余分支调 MixBytesInto(348-404 行)。 ② 实体 fragment hash 管线(MassBattleNetworkSubsystem.cpp):GetHashFieldPolicy 用 ContainsFloatOrDoubleLeaves 判定字段分类(565 行),hash 布局折叠体 using namespace MassBattleHashFold(576 行)。UMassBattleSubsystem::FoldVarStoresIntoHash 用 MixBytesInto 对模板键作盐(612 行)。实体 hash 的逐字段折叠宏亦引用 BuildHashFloatLeaves(MassBattleMacros.h 144 行)。 hash 管线总体由 UMassBattleNetworkProcessor 每 tick 折叠、UMassBattleNetworkSubsystem 逐 tick 广播对比(失步检测)并参与快照捕获/恢复校验——见 MassBattleNetworkSubsystem.html。 ③ MakePathFingerprint / SanitizeSyncFloat 在写位消费:两个移动处理器(MassBattleAgentMoveProcessor.cpp / MassBattleAgentMoveProcessorFP.cpp)在写入/清空 FNavigating::PathPoints 时调 MakePathFingerprint,在写 FMoving::CurrentVelocity / CurrentAngularVelocity 与 tilt Slerp 结果时调 SanitizeSyncFloat;UMassBattleAgentSubsystem.cpp 清空路径时刷新指纹;MassBattleNetworkSubsystem.cpp 在恢复校验折叠前从 blob 重建的数组现算指纹。

No reflected types and no .cpp — everything is inline, consumed by two pipelines: ① The LockstepVarStore fold pipeline (LockstepVarStore.cpp): ClassifyProperty uses ContainsFloatOrDoubleLeaves to decide the CanonicalizeFloatStruct category and BuildHashFloatLeaves for precomputed leaves (lines 85-89); FoldInto's CanonicalizeFloatStruct branch calls FoldCanonicalizedFloatStruct, all others MixBytesInto (lines 348-404). ② The entity fragment hash pipeline (MassBattleNetworkSubsystem.cpp): GetHashFieldPolicy uses ContainsFloatOrDoubleLeaves to classify fields (line 565); the hash layout fold body does using namespace MassBattleHashFold (line 576). UMassBattleSubsystem::FoldVarStoresIntoHash salts template keys with MixBytesInto (line 612). The per-field fold macros also reference BuildHashFloatLeaves (MassBattleMacros.h line 144). The overall hash pipeline is folded per tick by UMassBattleNetworkProcessor, broadcast and compared per tick by UMassBattleNetworkSubsystem (desync detection), and participates in snapshot capture/restore validation — see MassBattleNetworkSubsystem.html. ③ MakePathFingerprint / SanitizeSyncFloat are consumed at write sites: both move processors (MassBattleAgentMoveProcessor.cpp / MassBattleAgentMoveProcessorFP.cpp) call MakePathFingerprint whenever they write or clear FNavigating::PathPoints, and call SanitizeSyncFloat when writing FMoving::CurrentVelocity / CurrentAngularVelocity and the tilt Slerp result; UMassBattleAgentSubsystem.cpp refreshes the fingerprint on path clear; MassBattleNetworkSubsystem.cpp recomputes it from the blob-restored array before the restore-validation fold.