MassBattleFixedPoint.h

转换族。FromFloat/FromDouble(非内联,ensureMsgf 只编译一次):数值 × 2³² 后检查 ±2³²·2³¹(=2^63)边界——超出即 ensureMsgf 警告并饱和到 MaxValue/MinValue((double)INT64_MAX 会舍入到 2^63,直接比较会把 Scaled==2^63 误判为合法,故用精确的 2^63 常量比较);FromInt 内联直乘;ToInt 向零截断。

Conversion family. FromFloat/FromDouble (non-inline so ensureMsgf compiles once): scales by 2³² and checks the ±2^63 boundary — out of range triggers an ensureMsgf warning and saturates to MaxValue/MinValue (since (double)INT64_MAX rounds UP to 2^63, the comparison uses the exact 2^63 constant to avoid accepting the UB cast); FromInt is an inline multiply; ToInt truncates toward zero.

算术族:加减直接操作 RawValue;乘除经 Mul64 / Div64;% 复用 Fmod 的除零保护。

Arithmetic family: add/sub operate on RawValue directly; mul/div go through Mul64 / Div64; % reuses Fmod's divide-by-zero guard.

跨平台 64×64→128→64 乘法:MSVC 用 _mul128 取高 64 位并移位(先转 uint64 再移位,避免有符号右移符号扩展);其它平台用 __int128 中间值右移 32。

Cross-platform 64×64→128→64 multiply: MSVC uses _mul128 with the high 64 bits shifted (cast to uint64 before shifting to avoid sign-extension); other platforms use a __int128 intermediate shifted right by 32.

跨平台 64/64→128/64→64 除法,带商溢出保护:MSVC 的 _div128 在商超出 int64 时触发 #DE 硬件异常(进程崩溃)——溢出 ⇔ trunc(|A|/|B|) ≥ 2³¹,用纯 64 位比较判定(|B|×2³¹ 自身会溢出);溢出与除零一律饱和到 MaxValue/MinValue,替代崩溃/UB。128 位中间保持原始位模式(含符号),商与旧实现完全一致。

Cross-platform 64/64→128/64→64 divide with quotient-overflow guard: MSVC's _div128 raises a #DE hardware exception (process crash) when the quotient exceeds int64 — overflow ⇔ trunc(|A|/|B|) ≥ 2³¹, checked with pure 64-bit compares (|B|×2³¹ itself would overflow); overflow and divide-by-zero both saturate to MaxValue/MinValue instead of crashing/UB. The 128-bit intermediate keeps the original bit pattern (sign included), so the quotient matches the old implementation exactly.

Sqrt:牛顿-拉弗森法开方——double sqrt 做初始猜测,8 次迭代,收敛提前退出;≤0 返回 0。InvSqrt:牛顿迭代(仅 Mul64,无除法);种子守卫——y > 46340 时 y² 溢出 Q31.32(V < ~4.66e-10),直接回退 1/sqrt(V)(回退除数 ≥ 65536 raw,Div64 恒安全)。

Sqrt: Newton-Raphson square root — double sqrt seeds the guess, up to 8 iterations with early exit on convergence; ≤0 returns 0. InvSqrt: Newton iteration (Mul64 only, no division); seed guard — when y > 46340, y² overflows Q31.32 (V < ~4.66e-10), falling straight back to 1/sqrt(V) (the fallback divisor ≥ 65536 raw keeps Div64 safe).

Floor:清低 32 位(向 -∞ 取整);Fraction:取低 32 位(小数部分);Abs:绝对值——注意 Abs(INT64_MIN) 回绕为自身(负值,与普通 int64 一致),能见到 INT64_MIN 的热点守卫(Atan/Atan2/Asin)已显式特判,此处加饱和会让每次 Length() 守卫多 3 个分支(实测向量长度吞吐 -34%);Sign:符号(-1/0/1)。

Floor: clears the low 32 bits (floor toward -inf); Fraction: keeps the low 32 bits (fractional part); Abs: absolute value — note Abs(INT64_MIN) wraps to itself (negative, same as plain int64); hot guards that can see INT64_MIN (Atan/Atan2/Asin) special-case it explicitly, and adding saturation here would cost 3 extra branches in every Length() guard (measured -34% vector-length throughput); Sign: sign (-1/0/1).

三角函数(查表,确定性):2048 条目正弦表 + 正切表(引擎启动时 InitializeLUT 生成一次;±π/2 处 tan 钳制到最大可表示值)。角度先归一化到 [0, 2π),索引线性插值(128 位中间避免余数×ONE_RAW 溢出)。Cos = Sin(x + π/2) 移相;SinCos 同时输出两者。

Trig functions (LUT-based, deterministic): 2048-entry sine and tangent tables (generated once by InitializeLUT at engine startup; tan clamps to the max representable value near ±π/2). Angles normalize to [0, 2π) first, then index with linear interpolation (a 128-bit intermediate avoids remainder×ONE_RAW overflow). Cos = Sin(x + π/2) phase shift; SinCos outputs both.

反三角函数(确定性级数):Atan 用欧拉级数(|X|>1 时 π/2 - atan(1/x) 变换,12 项收敛);Atan2 按象限组合;X=0 时 ±π/2,atan2(0,0)=0;Asin = atan(x/√(1-x²)),|x|>1 返回 0,分母为零时 ±π/2;Acos = π/2 - asin。

Inverse trig (deterministic series): Atan uses the Euler series (π/2 - atan(1/x) transform for |X|>1, up to 12 terms); Atan2 composes quadrants; X=0 gives ±π/2, atan2(0,0)=0; Asin = atan(x/√(1-x²)), returns 0 for |x|>1, ±π/2 when the denominator is zero; Acos = π/2 - asin.

Fmod:C 风格取模——结果符号与 A 相同、向零截断;除零返回 0。Exp:e^x 泰勒级数——|x|>2 时先折半(e^x = e^(x/2)²)再平方还原,16 项收敛,项 < Epsilon 提前退出。

Fmod: C-style modulo — same sign as A, truncated toward zero; divide-by-zero returns 0. Exp: e^x Taylor series — halves the argument for |x|>2 (e^x = e^(x/2)²) and squares back, up to 16 terms with early exit when a term < Epsilon.

LWC 瓦片原点对齐:返回不大于 WorldCoord 的最大瓦片对齐值(向 -∞ 取整)。C++ 整数除法向 0 截断,负值修正确保始终对齐到下方瓦片边界。瓦片大小应为 Q31.32 可表示的正倍数(如 1000.0)。

LWC tile-origin snapping: returns the greatest tile-aligned value ≤ WorldCoord (floor toward -inf). C++ integer division truncates toward 0, so negative values are adjusted to always snap to the tile boundary below. Tile size should be a positive Q31.32-representable multiple (e.g. 1000.0).

引擎启动时调用一次的查表初始化(幂等):按 2π/2048 步进预计算正弦表与正切表(±π/2 处 tan 用最大可表示值)。三角函数的调用会惰性触发它。

One-time idempotent LUT initialization at engine startup: precomputes the sine and tangent tables at 2π/2048 steps (tan clamps to the max representable value at ±π/2). Trig calls trigger it lazily.

FMath::GetMappedRangeValueClamped 的 FFix64 替代:输入区间 [InA, InB] 映射到输出区间 [OutA, OutB],Alpha 钳制到 [0,1];InB == InA 时返回 OutA。

FFix64 replacement for FMath::GetMappedRangeValueClamped: maps [InA, InB] to [OutA, OutB] with Alpha clamped to [0,1]; returns OutA when InB == InA.

FMath::ClosestPointOnSegment 的 FFixVector3 替代:P 在线段 A→B 上的投影,t 钳制到 [0,1];零长线段返回 A。

FFixVector3 replacement for FMath::ClosestPointOnSegment: projection of P onto segment A→B with t clamped to [0,1]; returns A for a zero-length segment.

FMath::SegmentDistToSegmentSafe 的 FFixVector3 替代:标准线段-线段最近点算法(Real-Time Collision Detection §5.1.9),退化情况(点线段 / 平行)逐分支处理。

FFixVector3 replacement for FMath::SegmentDistToSegmentSafe: the standard segment-segment closest-point algorithm (Real-Time Collision Detection §5.1.9) with per-branch degenerate cases (point segments / parallel).