第 4 章：META 区段
规范状态： Draft
Directory Tag： META
作用范围： 全局区段，chunkId 必须为 -1
必须性： 必须存在且仅存在一次
允许 Codec： RAW8
META 定义资产的基础解释信息：逻辑网格尺寸、Chunk 尺寸、坐标约定、体素统计、资产锚点与当前权威 Source Hash。读取器必须先成功解析 META，才能安全解释 CHIX 和 VOX0。
4.1 作用
META 是资产级元数据，不保存任一具体体素的颜色或存在性。它回答的是“这个资产以什么空间、尺寸和分块规则被解释”；VOX0 回答的才是“每个位置有什么体素”。
META 必须用于：
- 限定资产逻辑网格的最大坐标范围；
- 确定所有 Chunk 的标准尺寸；
- 声明 VFP 固定的右手坐标语义；
- 提供非空体素总数和 Chunk 数量等快速统计；
- 保存由权威数据计算得到的 Source Hash；
- 提供资产根锚点，供默认展示和实例放置使用。
META 不得保存会覆盖 PAL0、CHIX 或 VOX0 内容的冗余真值。若 META 的统计信息与权威区段不一致，文件无效；不得以 META 中的统计数反向修正体素数据。
4.2 Binary Layout
4.2.1 META Payload
VFP 1.3 的 META Payload 固定为 128 字节，Directory Entry 必须使用 codec = RAW8、rawLength = 128、length = 128。
| Offset | Size | Type | Field | Description |
|---|---|---|---|---|
| 0 | 2 | uint16 | metaVersion | META 版本；必须为 1 |
| 2 | 2 | uint16 | metaSize | Payload 固定长度；必须为 128 |
| 4 | 4 | uint32 | metaFlags | 元数据标志；VFP 1.3 必须为 0 |
| 8 | 1 | uint8 | coordinateSystem | 坐标系；必须为 1（右手系，+Y 上，+Z 前） |
| 9 | 1 | uint8 | voxelUnit | 体素单位；必须为 1（一个网格单位） |
| 10 | 1 | uint8 | chunkSizeX | 标准 Chunk 的 X 尺寸 |
| 11 | 1 | uint8 | chunkSizeY | 标准 Chunk 的 Y 尺寸 |
| 12 | 1 | uint8 | chunkSizeZ | 标准 Chunk 的 Z 尺寸 |
| 13 | 1 | uint8 | reserved0 | 必须为 0 |
| 14 | 2 | uint16 | reserved1 | 必须为 0 |
| 16 | 1 | uint8 | gridSizeX | 逻辑网格 X 尺寸，范围 1..255 |
| 17 | 1 | uint8 | gridSizeY | 逻辑网格 Y 尺寸，范围 1..255 |
| 18 | 1 | uint8 | gridSizeZ | 逻辑网格 Z 尺寸，范围 1..255 |
| 19 | 1 | uint8 | reserved2 | 必须为 0 |
| 20 | 4 | uint32 | voxelCount | 全资产非空体素总数 |
| 24 | 4 | uint32 | chunkCount | CHIX 中的 Chunk 数量 |
| 28 | 4 | uint32 | paletteEntryCount | PAL0 中非空颜色条目数量 |
| 32 | 4 | float32 | anchorX | 资产根锚点 X |
| 36 | 4 | float32 | anchorY | 资产根锚点 Y |
| 40 | 4 | float32 | anchorZ | 资产根锚点 Z |
| 44 | 4 | float32 | pivotX | 默认旋转中心 X |
| 48 | 4 | float32 | pivotY | 默认旋转中心 Y |
| 52 | 4 | float32 | pivotZ | 默认旋转中心 Z |
| 56 | 4 | uint32 | sourceRevision | 权威内容修订号；首次编译为 1 |
| 60 | 4 | uint32 | reserved3 | 必须为 0 |
| 64 | 32 | uint8[32] | sourceHash | 当前权威数据的 SHA-256 Source Hash |
| 96 | 16 | uint8[16] | generatorUuid | 生成器或创作会话 UUID；全零表示未指定 |
| 112 | 16 | uint8[16] | reserved4 | 必须为全零 |
4.2.2 结构定义
META_V1 = struct.Struct("<HHIBBBBBBHBBBBIIIffffffII32s16s16s")
assert META_V1.size == 128
实现应以字段级读取方式处理该结构，不得依赖语言默认结构体对齐。
4.3 字段定义
4.3.1 空间与尺寸字段
coordinateSystem = 1 固定表示右手坐标系：+X 向右、+Y 向上、+Z 向前。voxelUnit = 1 固定表示一个体素边长为一个逻辑单位。
gridSizeX/Y/Z 定义全资产有效体素坐标范围：
0 <= x < gridSizeX
0 <= y < gridSizeY
0 <= z < gridSizeZ
chunkSizeX/Y/Z 定义规则 Chunk 的标称尺寸。边缘 Chunk 可以小于该尺寸，但不得大于它。VFP 1.3 推荐使用 16, 16, 16；写入器可以使用其他 1..255 的尺寸，前提是 CHIX、VOX0 与所有缓存保持一致。
4.3.2 统计字段
voxelCount 必须等于所有 VOX0 解码后非零 Palette Index 的总数。chunkCount 必须等于 CHIX 的 Entry 数量。paletteEntryCount 必须等于 PAL0 中索引 1..255 范围内已定义且可引用的颜色条目数量。
这些字段用于快速查询和预分配，不取代完整验证。读取器可在普通加载时延迟验证统计值，但验证器必须重新计算并比较。
4.3.3 锚点与枢轴
anchorX/Y/Z 是资产在外部场景或资源系统中放置时的推荐根锚点。pivotX/Y/Z 是默认旋转中心。二者均以资产局部网格坐标表示，可为小数和负数，但必须是有限 float32。
它们仅影响默认放置和表现，不改变任一体素坐标。缺少专门展示信息时，读取器可使用它们；SCNE 存在时，SCNE 的展示变换优先。
4.3.4 修订与身份字段
sourceRevision 是单调递增的逻辑修订号。当权威数据发生变化时，写入器必须至少将它增加 1，并重新计算 sourceHash。仅改变缓存、Directory 排列、文件 UUID 或填充字节时不得增加该值。
generatorUuid 可用于识别生成器、创作会话或资产管线来源，不是安全凭证，也不参与 Source Hash。
4.4 验证规则
合规验证器必须检查：
- Directory Entry 为全局
META，chunkId = -1，codec = RAW8，且length = rawLength = 128； metaVersion = 1、metaSize = 128、metaFlags = 0；- 所有保留字段均为
0； coordinateSystem = 1、voxelUnit = 1；gridSizeX/Y/Z与chunkSizeX/Y/Z均在1..255范围内；chunkSize不得大于对应gridSize；voxelCount不得超过gridSizeX × gridSizeY × gridSizeZ；anchor与pivot全部为有限float32；chunkCount、paletteEntryCount分别与CHIX、PAL0的实际内容一致；voxelCount与所有VOX0的实际非空体素数一致；sourceHash与第 16 章规定的规范化权威输入重新计算结果一致。
任一验证失败均属于权威数据错误，读取器必须拒绝资产。
本章总结
META 为整个资产提供稳定的空间、尺寸、统计和 Source Hash 基础。它不直接存储体素，但决定了 PAL0、CHIX、VOX0 应如何被安全解释。