跳到主要内容

第 18 章：编译器规范

编译器负责将 VF、编辑器内部模型或其他输入转换为合规 VFP。它的首要职责不是生成缓存，而是生成可被独立读取器无歧义恢复的权威资产。

18.1 VF 输入​

VF 是推荐输入格式，通常为 JSON，但不是 VFP 的唯一来源。无论输入形式如何，编译器在进入 VFP 管线前必须得到下列规范化信息：

  • 逻辑网格尺寸 gridSizeX/Y/Z；
  • 每个非空体素的整数坐标与颜色；
  • 坐标系，或可转换为 VFP 右手坐标系的映射；
  • 可选的资产 UUID、锚点、枢轴和展示建议。

编译器必须拒绝或明确修正：越界坐标、重复坐标、非有限数值、超过 255 的单轴尺寸、超过 255 种可引用颜色、无法确定的透明/空体素语义。不得静默截断、取模或依赖输入对象遍历顺序。

18.2 编译流程​

合规编译器必须按逻辑依赖顺序完成：

  1. 解析输入并验证语义；
  2. 标准化坐标、空体素和颜色；
  3. 构建稳定 PAL0，保留索引 0 为空；
  4. 根据 META Chunk Size 切分网格并分配稳定 Chunk ID；
  5. 生成 CHIX 和每个 VOX0；
  6. 计算体素统计、META 和 Source Hash；
  7. 可选生成 SCNE、MSH0、VBUF、PMSH、RND0、ANM0、BORD、PRVW、THMB；
  8. 写入所有 Payload 并计算每个存储区段 CRC32；
  9. 写入 DIR0；
  10. 最后写入 Footer。

写入器应在写入完成后以独立读取逻辑重新验证 Header、Footer、Directory、权威区段、CRC32 和 Source Hash。

18.3 确定性生成​

给定相同的规范化输入和编译选项，编译器应生成相同的权威区段字节和 Source Hash。至少必须固定：

  • Palette 条目顺序；
  • Chunk 切分和 Chunk ID 分配；
  • CHIX Entry 排序；
  • VOX0 线性顺序与 RAW8/RLE8 选择策略；
  • Source Hash 输入；
  • Directory Entry 排序（建议按 Payload Offset，再按 Tag/Chunk ID）。

资产 UUID、generator UUID、生成时间、缓存压缩实现和文件物理排列可不确定，但不得影响权威 Source Hash。若产品需要字节级可复现文件，应将这些字段固定或归零，并使用确定性缓存生成器。

18.4 输出要求​

每个合规编译器必须至少输出 Header、META、PAL0、CHIX、全部 VOX0、DIR0 和 Footer。它必须：

  • 将所有必需区段标记为 REQUIRED；
  • 按第 2 章执行 8 字节对齐；
  • 为每个 Payload 与 Directory 写入正确 CRC32；
  • 在 META 中写入与权威数据一致的统计和 Source Hash；
  • 不引用未写入的区段或不存在的 Chunk；
  • 在 Footer 中写入实际文件长度和当前 Directory 的精确位置。

输出缓存是可选的；输出任何缓存时，编译器必须写入适当的 Source Hash 关联并遵循对应区段规范。

本章总结​

VFP 编译器把“可创作的体素描述”转为“可验证的体素资产包”。其最低成功标准是权威数据完整、可独立加载且可重建全部缓存。