附录 D：示例文件

D.0 THMB 可选缩略图样例要求

带缩略图的样例应在活动 Directory 中含唯一 THMB[-1]，并且其载荷为可独立打开的 RGBA PNG。 读取器测试至少应覆盖：正常 THMB、缺失 THMB、payload CRC 错误、PNG signature 错误、非正方形 IHDR 和超过 1024 × 1024 的尺寸。上述错误只应让缩略图降级，不应改变同一文件的 VOX0 验证结论。

本附录定义一个最小概念资产，供编译器与读取器进行互操作测试。它是一个 1 × 1 × 1 的单红色体素资产，只有一个 Chunk，VOX0 使用 RAW8。为避免本附录因 CRC32 和 Source Hash 示例值被手工复制错误而产生误导，最终文件字节应由附录 B 的布局与第 16 章的 Hash 规则生成。

D.1 资产语义

属性	值
网格尺寸	1 × 1 × 1
Chunk 尺寸	1 × 1 × 1
Chunk 数量	1
非空体素数	1
Palette	索引 1 = RGBA(255, 0, 0, 255)
Chunk ID	0
Chunk 坐标	(0, 0, 0)
VOX0	RAW8，唯一体素的 Palette Index 为 1

D.2 规范化输入

{
  "gridSize": [1, 1, 1],
  "chunkSize": [1, 1, 1],
  "palette": {
    "1": { "rgba": [255, 0, 0, 255], "materialFlags": 0, "emission": 0 }
  },
  "voxels": [
    { "x": 0, "y": 0, "z": 0, "paletteIndex": 1 }
  ]
}

D.3 所需区段

Directory 必须含有以下四条权威 Entry：

Tag	chunkId	Codec	Payload 要点
META	-1	RAW8	grid/chunk size 均为 1，voxelCount=1，chunkCount=1，paletteEntryCount=1
PAL0	-1	RAW8	一个索引 1 的红色条目
CHIX	-1	RAW8	一个 Chunk ID 0、坐标 0/0/0、尺寸 1/1/1 的 Entry
VOX0	0	RAW8	Header 的 capacity=1、nonEmpty=1、dataLength=1，数据字节为 01

VOX0 的可变数据区只有一个字节：

01

D.4 文件写入顺序示例

以下是推荐物理布局；读取器不得依赖此排列：

Header (64)
META (128)
PAL0 (24)
CHIX (64)
VOX0 (33) + 7 bytes zero alignment padding
DIR0 (32 + 4 × 48 = 224)
Footer (64)

在此布局中，Directory Entry 的 Section Offset 分别为：META=64、PAL0=192、CHIX=216、VOX0=280、DIR0=320、Footer=544，文件总长度为 608 字节。每个 Payload 的 CRC32、DIR0 CRC32 和 META Source Hash 必须由实际字节计算后写入；不可使用占位值。

D.5 预期读取结果

合规读取器加载该文件后应得到：

asset.gridSize        = (1, 1, 1)
asset.chunkCount      = 1
asset.chunk(0).size   = (1, 1, 1)
asset.chunk(0)[0,0,0] = paletteIndex 1
asset.palette[1]      = RGBA(255, 0, 0, 255)
asset.nonEmptyCount   = 1

读取器可自行生成六个可见单位面、十二个三角形或其他等价渲染表示；这些表现结果不改变该示例的权威体素内容。