第 7 章：CHIX 区段
Directory Tag： CHIX
作用范围： 全局区段，chunkId = -1
必须性： 必须存在且仅存在一次
允许 Codec： RAW8
CHIX（Chunk Index）定义资产被划分为哪些空间 Chunk，以及每个 Chunk 的稳定编号、位置、实际尺寸和非空体素统计。它是 META 与 Chunk 级 VOX0、MSH0、VBUF、PMSH 之间的权威索引桥梁。
7.1 Chunk 模型
资产逻辑网格按照 META.chunkSizeX/Y/Z 从局部原点开始切分。Chunk 的格网坐标为无符号 (chunkX, chunkY, chunkZ)，其逻辑起点为：
originX = chunkX × META.chunkSizeX
originY = chunkY × META.chunkSizeY
originZ = chunkZ × META.chunkSizeZ
Chunk 的实际尺寸为：
sizeX = min(META.chunkSizeX, META.gridSizeX - originX)
sizeY = min(META.chunkSizeY, META.gridSizeY - originY)
sizeZ = min(META.chunkSizeZ, META.gridSizeZ - originZ)
因此，处于资产边界的 Chunk 可以小于标准 Chunk 尺寸。CHIX 必须存储实际尺寸，读取器不得仅根据标准尺寸推断边缘 Chunk 的体素数量。
7.2 Binary Layout
7.2.1 CHIX Header
CHIX Payload 由固定 32 字节 Header 和 entryCount 个固定 32 字节 Chunk Entry 组成。
| Offset | Size | Type | Field | Description |
|---|---|---|---|---|
| 0 | 2 | uint16 | chixVersion | 必须为 1 |
| 2 | 2 | uint16 | headerSize | 必须为 32 |
| 4 | 4 | uint32 | entryCount | Chunk Entry 数量 |
| 8 | 4 | uint32 | entrySize | 必须为 32 |
| 12 | 4 | uint32 | chixFlags | VFP 1.3 必须为 0 |
| 16 | 16 | uint8[16] | reserved | 必须为全零 |
Payload 总长度必须满足：
32 + entryCount × 32
entryCount 必须等于 META.chunkCount。
7.2.2 Chunk Entry
| Offset | Size | Type | Field | Description |
|---|---|---|---|---|
| 0 | 4 | int32 | chunkId | 稳定 Chunk 编号，必须大于等于 0 |
| 4 | 1 | uint8 | chunkX | Chunk 格网 X 坐标 |
| 5 | 1 | uint8 | chunkY | Chunk 格网 Y 坐标 |
| 6 | 1 | uint8 | chunkZ | Chunk 格网 Z 坐标 |
| 7 | 1 | uint8 | chunkFlags | Chunk 标志 |
| 8 | 1 | uint8 | sizeX | 实际 X 尺寸 |
| 9 | 1 | uint8 | sizeY | 实际 Y 尺寸 |
| 10 | 1 | uint8 | sizeZ | 实际 Z 尺寸 |
| 11 | 1 | uint8 | reserved0 | 必须为 0 |
| 12 | 4 | uint32 | nonEmptyVoxelCount | 此 Chunk 的非空体素数量 |
| 16 | 4 | uint32 | voxelCapacity | 必须等于 sizeX × sizeY × sizeZ |
| 20 | 4 | uint32 | reserved1 | 必须为 0 |
| 24 | 8 | uint8[8] | reserved2 | 必须为全零 |
chunkFlags 定义：
| Bit | 名称 | 语义 |
|---|---|---|
| 0 | EDGE_CHUNK | 此 Chunk 位于至少一个资产边界上 |
| 1–7 | Reserved | 必须为 0 |
7.3 编号与排序规则
chunkId 是唯一稳定标识，不等同于空间坐标的线性索引。它必须在一个资产中唯一，且建议由编译器按 (chunkZ, chunkY, chunkX) 的词典序从 0 开始连续分配。
CHIX Entry 必须按 chunkId 严格升序存储。写入器不得在同一空间坐标写入两条 Entry。读取器可建立空间坐标到 Chunk ID 的索引，但不得假设 Chunk ID 必然等于其空间线性索引。
如果修改或重新切分资产导致 Chunk 集合变化，写入器可以重新分配 Chunk ID，但必须同步更新所有 Chunk 级 Directory Entry 和全部缓存关联。
7.4 与 VOX0 的关系
每一条 CHIX Entry 必须恰好对应一个 Directory Entry：
tag = VOX0
chunkId = CHIX Entry.chunkId
VOX0 Header 中的 Chunk ID、实际尺寸和非空体素数必须分别等于 CHIX Entry 的 chunkId、sizeX/Y/Z 与 nonEmptyVoxelCount。
CHIX 不允许描述没有 VOX0 的逻辑 Chunk。即使一个 Chunk 完全为空，只要它存在于 CHIX，就必须存在可验证的 VOX0；推荐写入器直接省略完全空且不承担逻辑意义的 Chunk，以减小目录和文件体积。
7.5 验证规则
验证器必须检查：
codec = RAW8，Header 与 Entry 长度分别为32；chixVersion = 1、chixFlags = 0，所有保留字段为0；entryCount == META.chunkCount，Payload 长度精确匹配；- 所有
chunkId非负、唯一并严格升序； - 所有
(chunkX, chunkY, chunkZ)唯一，并且由它们算出的 origin 位于 META 网格内； sizeX/Y/Z非零，并精确等于依据 META 计算的实际尺寸；voxelCapacity == sizeX × sizeY × sizeZ；nonEmptyVoxelCount <= voxelCapacity；EDGE_CHUNK与实际边界状态一致；- 每项均有且仅有一个对应
VOX0，且相应 VOX0 的 Header 与统计信息一致。
CHIX 是权威区段。任何编号、坐标、尺寸或 VOX0 对应关系错误都会使资产无效。
本章总结
CHIX 让 VFP 的权威体素数据可以按空间 Chunk 被定位、校验和局部更新。它不保存具体颜色，但决定每个 VOX0 在资产网格中的位置和应有体素容量。