附录 A：完整 Binary Layout
本附录汇总 VFP 1.3 已定义的固定结构。所有多字节数值使用 Little-endian；所有未定义的保留字段必须为零。可变长度数组的长度由同一结构中的 count、size 或 offset 字段确定。
A.1 容器结构
| 结构 | 固定大小 | 格式摘要 |
|---|---|---|
| Header | 64 | VFPK、主/次版本、Header Size、Feature Flags、Asset UUID、保留 |
| Footer | 64 | VFPF、版本、Footer Size、Directory Offset/Length/CRC、File Length、保留 |
| DIR0 Header | 32 | DIR0、目录版本、Entry Count/Size、Flags、保留 |
| Directory Entry | 48 | Tag、Codec、Chunk ID、Flags、Offset、Length、Raw Length、CRC32、保留 |
Header（64 bytes）
char[4] magic、uint16 majorVersion、uint16 minorVersion、uint32 headerSize、uint32 featureFlags、uint8[16] assetUuid、uint8[32] reserved。
Footer（64 bytes）
char[4] magic、uint16 majorVersion、uint16 minorVersion、uint32 footerSize、uint64 directoryOffset、uint64 directoryLength、uint32 directoryCrc32、uint32 footerFlags、uint64 fileLength、uint8[20] reserved。
Directory Entry（48 bytes）
char[4] tag、uint32 codec、int32 chunkId、uint32 flags、uint64 offset、uint64 length、uint64 rawLength、uint32 crc32、uint32 reserved。
A.2 权威区段
| Tag | Scope | Payload 结构 | 固定部分 |
|---|---|---|---|
| META | Global | META v1 | 128 |
| PAL0 | Global | Header + 8-byte Palette Entries | 16 |
| CHIX | Global | Header + 32-byte Chunk Entries | 32 |
| VOX0 | Per Chunk | Header + encoded voxel data | 32 |
META v1（128 bytes）
| Offset | Field | Type |
|---|---|---|
| 0 | metaVersion / metaSize | uint16 / uint16 |
| 4 | metaFlags | uint32 |
| 8 | coordinateSystem / voxelUnit / chunkSizeX/Y/Z / reserved | uint8[6] |
| 14 | reserved | uint16 |
| 16 | gridSizeX/Y/Z / reserved | uint8[4] |
| 20 | voxelCount / chunkCount / paletteEntryCount | uint32[3] |
| 32 | anchor / pivot | float32[6] |
| 56 | sourceRevision / reserved | uint32[2] |
| 64 | sourceHash | uint8[32] |
| 96 | generatorUuid | uint8[16] |
| 112 | reserved | uint8[16] |
PAL0
Header：uint16 paletteVersion、uint16 headerSize、uint16 entryCount、uint16 entrySize、uint32 paletteFlags、uint32 reserved。
Palette Entry（8 bytes）：uint8 index、uint8 r/g/b/a、uint8 materialFlags、uint8 emission、uint8 reserved。
CHIX
Header：uint16 chixVersion、uint16 headerSize、uint32 entryCount、uint32 entrySize、uint32 chixFlags、uint8[16] reserved。
Chunk Entry（32 bytes）：int32 chunkId、uint8 chunkX/Y/Z/flags、uint8 sizeX/Y/Z/reserved、uint32 nonEmptyVoxelCount、uint32 voxelCapacity、uint32 reserved、uint8[8] reserved。
VOX0
Header（32 bytes）：uint16 voxVersion、uint16 headerSize、int32 chunkId、uint8 sizeX/Y/Z、uint8 voxelCodec、uint32 voxelCapacity、uint32 nonEmptyVoxelCount、uint32 voxelDataLength、uint32 reserved0、uint32 reserved1。
内部 voxelCodec=0 时，数据为 uint8[voxelCapacity]。voxelCodec=1 时，数据为重复的 (uint8 runLength, uint8 paletteIndex) 对。
A.3 缓存与附加区段
| Tag | Scope | Header | Record / 数据 |
|---|---|---|---|
| SCNE | Global | 128 | 固定展示场景 |
| MSH0 | Per Chunk | 48 | 16-byte Face Record |
| VBUF | Per Chunk | 64 | 20-byte Vertex + uint32 Indices |
| PMSH | Per Chunk | 48 | 16-byte Polygon Record |
| RND0 | Global | 64 | 24-byte Batch + int32 refs |
| ANM0 | Global | 32 | 32-byte Clip + 48-byte keyframes |
| BORD | Global | 48 | 8-byte Edge Record |
| PRVW | Global | 64 | Preview data bytes |
| THMB | Global | 0 | 完整 RGBA PNG 文件字节；无 VFP 私有 Header |
标准 Record 汇总
| Record | 字节 | 核心字段 |
|---|---|---|
| MSH0 / PMSH Face | 16 | axis、paletteIndex、plane、u、v、width、height、flags、reserved |
| VBUF Vertex | 20 | position float32×3、packed normal、RGBA8 |
| RND0 Batch | 24 | material class、flags、Chunk refs、index range |
| ANM0 Clip | 32 | clip ID、duration、keyframe count/offset、flags |
| ANM0 Keyframe | 48 | time、translation、rotation、scale、reserved |
| BORD Edge | 8 | x、y、z、axis、style、paletteIndex、reserved |
A.4 目录与 Tag 分配
| Tag | Required | Rebuildable | Presentation Only | Chunk ID |
|---|---|---|---|---|
| META | 是 | 否 | 否 | -1 |
| PAL0 | 是 | 否 | 否 | -1 |
| CHIX | 是 | 否 | 否 | -1 |
| VOX0 | 是 | 否 | 否 | ≥0 |
| SCNE | 否 | 是 | 是 | -1 |
| MSH0 / VBUF / PMSH | 否 | 是 | 否 | ≥0 |
| RND0 / ANM0 / BORD / PRVW / THMB | 否 | 是 | 是 | -1 |
本附录是字段尺寸汇总；冲突时以对应章节的完整字段描述为准。