# 完整 halo 路径的标量场构造

本记录是 Windows Build `23966345`、EXE SHA-256 `af2f5a1227911d8aa06b3908d6bd0211838211cae14ea91099cb57d0df990781` 的静态调查。没有运行游戏，没有把反编译结果当作原始 C++ 源码。邻域计算说明它构造了一个供零等值面提取使用的标量场，**不能证明它是严格有符号距离场**。

## 证据链

| 函数 | Evidence ID | 本记录使用范围 |
| --- | --- | --- |
| `FUN_140e88d80` | `ev_8f452f477c0038ce8be6bb09779b23b0b216ed2556d341baa80917750be91792` | u16 邻域到 float 场的公式 |
| 同函数汇编 | `ev_5a106976a0e7913a0870086a3f49d386501aa9f2f840a3c86c6bc5513a7bd32f` | 快路径六轴 min/max、分支和 fallback 奇偶条件 |
| `FUN_1401a9470` | `ev_1d2f0eb2b4d1c3f9d177c2b742628157be5adec6f24d13b031795cd2358d4c3a` | 世界相关任务调用、halo=2、模式和四个采样描述符 |
| `FUN_1401b0a70` | `ev_a426a35f64dc533e236928391bea146a19fd026915fc386fcd49c47b90f198f1` | 从 byte 输入构造材料场、halo=3 的另一条调用 |
| `FUN_1400cf2f0` | `ev_ef9428f6c257a743d7b6390afde5188c7a6b2d52018b349c53c139d303b6c881` | 非空输入时构建 meshing 对象的调度入口 |

## 输入、坐标与完整邻域

材料样本是 u16：记低字节为 `m`，高字节为 `d`。这里“材料样本”描述的是该 Mesh 路径看到的**中间输入**，不意味着资源文件每个体素原样存两个字节。

对每个输出采样点，函数把输出 origin 减去输入 origin，再减 `(1,1,1)`，得到 3×3×3 邻域的起点；中心是这个起点加 `(1,1,1)`。输入/输出数组都是 x 最快。这里的 origin 实参会被函数原地修改；原创参考实现用显式 `centerOffset` 表达该坐标关系，不复制这一接口副作用。

快路径收集：

- 27 个样本的高字节之和 `S`，包含中心。
- 六个轴邻居 `(-1,0,0),(1,0,0),(0,-1,0),(0,1,0),(0,0,-1),(0,0,1)` 的高字节最小值 `dmin` 与最大值 `dmax`。
- 中心高字节 `dc` 和中心低字节 `mc`。

六轴样本读取与 min/max 对照可定位到 `0x140e88fb2–0x140e89110`。27 项累加 `S` 的最大值是 6885，不存在该局部整数和的溢出问题。

## 原创数学重述

以下为实数表达；代码 `scalar-field-reference.mjs` 在每一步显式采用 `Math.fround` 模拟测得的 float32 运算顺序。

```text
c = dc / 255
b = 0.5 - c

if b <= 0:
    gate = clamp(2 * dmin / 255, 0, 1)
else:
    gate = clamp(2 * (1 - dmax / 255), 0, 1)

a = b * (1 + 0.732 * gate)
s = 3 * (0.5 - S / (255 * 27))
if mc < 128:
    a = a + 0.5 * (a - s)

t = sqrt(1 - (2*c - 1)^2)
mixed = (1 - t) * s + t * a
if a <= 0:
    output = min(mixed, 0.75 * a)
else:
    output = max(mixed, 0.75 * a)
```

公式对应 `0x140e89379–0x140e89497`。这不是简单的 `0.5 - d/255`，也不是单纯 3×3×3 平均：它有六轴极值门控、按中心低字节划分的校正、中心密度相关的平方根混合以及保持一定幅度的最后钳制。

高字节 `dc` 是参与算术的连续强度；低字节并非只用于着色，它也决定是否执行 `a += 0.5*(a-s)`。但此处只能确认 `<128` 与 `>=128` 两类分支，不能据此给它们强加“地形/水/建筑”的全部语义。

### 常量的原始字节

从同一哈希 EXE 按 PE 节表映射直接读取；这是文件字节观察，不是新增 REA Evidence。

| 地址 | 文件偏移 | 小端字节 | float32 |
| --- | ---: | --- | ---: |
| `0x141cfaa0c` | 30380044 | `5a643b3f` | `0.7319999933242798` |
| `0x141cd44a0` | 30223008 | `0000d841` | `27` |
| `0x1412ae488` | 19581576 | `00004040` | `3` |
| `0x1412ab06c` | 19568236 | `0000403f` | `0.75` |

## 两个调用者如何提供 halo

`FUN_1401a9470` 的当前模式 `L` 决定初始输出边长：若 `L<7`，工作 extent 加 4，origin 减 2；否则 extent 加 2，origin 减 1。材料采样立方体在输出边长基础上再加 4，origin 比输出 origin 再小 2。driver 收到的偏移 `h=2`，边界退半单位开关为 `L<7`。

它为采样接口准备四个描述符，随后调用 `FUN_140e81920`。一般逐次降低模式、origin 整除 2、边长 `floor(N/2)+1`；但第二轮当前模式为 5 时额外降到 4，因此初始模式 6 可出现 `6,4,3,2` 的序列。这是局部准备过程，尚不能直接认定为资源七层的完整映射。

`FUN_1401b0a70` 的光滑分支从输入尺寸 `(nx,ny,nz)` 构造材料尺寸 `input+7`，输入写在偏移 `(4,4,4)`；其声明 origin 为 `(-4,-4,-4)`。输出 float 场尺寸为 `input+3`，origin 为 `(-1,-1,-1)`。driver 使用 `h=3`、模式值 6；边界开关实参低字节为 0。相邻另一条分支转向 `FUN_1401ace10`，不能把该函数的全部功能都称作同一个光滑 Mesher。

上述两种尺寸关系都让整个输出区域拥有完整 3×3×3 邻域，因而本参考实现可以明确限定快路径。

### a 路径在标量转换前怎样处理 u16

以下规则仅观察于 `FUN_1401a9470`（证据 `ev_1d2f0eb2b4d1c3f9d177c2b742628157be5adec6f24d13b031795cd2358d4c3a`）准备转换输入的循环。它不能推广成所有体素资源的解码器；b 路径 `FUN_1401b0a70` 从 byte 输入构造数据，准备方式不同。

设原样本为 `(m,d)`：

| 中心低字节 | 高字节预处理 |
| --- | --- |
| `m=0` | 强制 `d=0` |
| `1<=m<=127` | 原样保留 `d` |
| `128<=m<=255` | 先取 `d=(d & 15)*17`，再检查正 Y 邻居 |

最后一种将原高字节低四位扩展到八位：例如 `0x01→0x11`、`0x0F→0xFF`、`0x10→0x00`，原高四位被丢弃。若正 Y 邻居存在，且其低字节在 `1..127`、原高字节 `dn>128`、`dn>d`，再执行：

```text
d = d + floor((dn-d)/2)
```

它只提高当前特殊类样本的高字节，不降低它；正 X、正 Z 不是这里检查的方向。`dn=128` 不满足门槛，`dn=129` 才可能满足。差值为奇数时整数除法向下，例如当前 17、邻居 254 得到 135。邻居使用**原输入**，输出写入另一数组，低字节 `m` 保持不变。

因此，即便后面的标量函数统一读取高字节，进入它的数值也可能经过类别相关的四位扩展和邻接修正。不能把资源中所有高字节都笼统解释为相同的原始八位密度。

## 刻意未实现的 clipped fallback

当邻域超出输入范围，原函数裁剪 3×3×3 盒子与有效输入的交集，仅对交集求高字节和，但仍除以 **27**。min/max 的筛选条件与快路径不同：汇编 `0x140e89271` 是 `CMP EAX,0x1`，逐轴奇偶初始化在 `0x140e891d1–0x140e891e7`、`0x140e89228–0x140e89233`。因此按当前机器码，它选择相对邻域起点恰有一个奇数坐标的子集，即完整盒子中相对中心有两轴 ±1 的 12 点，而非快路径的六轴邻居。

这个差异不应悄悄抹平成统一的“六邻域边界延拓”。参考实现**拒绝缺少完整 halo 的输入**，没有冒称复刻 fallback，也没有改变原始游戏行为。

## 校验与局限

`scalar-field-checks.json` 记录合成断言：a 路径的 ID `0/127/128` 边界、四位扩展、严格正 Y 门槛及奇差取整；全空/全满分别得到 `+1.5/-1.5`；256 个均匀高字节值的符号补集；中心低字节门槛；六轴与对角样本的差异；轴排列对称；两个调用者的尺寸覆盖；打包密度阶跃经 float 场转换后进入原创拓扑参考，得到平面 9 个 quad、16 个缓存顶点。准确断言数以 JSON 为准。

这些是合成数据验证，不是对游戏运行时采样的捕获或逐位差分。本模块不包含资源列解码（同批附件的 terraform-codec-reference.mjs 另行实现），也未恢复跨 LOD 连接、编辑更新调度；运行时 FTZ/DAZ 模式未观测。上游高字节的含义仍需逐条构建/修改路径核对。