第 0 章：文档说明
0.1 关于本文档
《Voxel Format Package Specification 1.3》定义 .vfp 文件的容器结构、权威体素数据、可重建缓存、读取与验证行为，以及从 .vf 到 .vfp 的推荐编译要求。
VFP 是面向单体体素资产的二进制包格式，服务于创作工具、编辑器、实时渲染器、游戏引擎、移动应用、云端服务和资产分发系统之间的稳定交换。它可承载角色、宠物、道具、家具、建筑组件、玩具、手办和独立展示作品等资产。
VFP 1.3 不定义大型地图、无限世界、跨区域流送、实体关系、多人协作状态或世界级空间索引。这些能力属于未来 VWFP 的规划范围，不属于本版本。
数据分层
| 数据层 | 定义 | 典型区段 | 可删除并重建 |
|---|---|---|---|
| 权威资产数据 | 决定资产真实体素内容与基础解释方式 | META、PAL0、CHIX、VOX0 | 否 |
| 编辑缓存 | 加快局部编辑、选取和网格重建 | MSH0 | 是 |
| 表现缓存 | 加快恢复、渲染、展示或兼容预览 | VBUF、PMSH、RND0、ANM0、PRVW、THMB | 是 |
| 容器索引 | 定位、校验和管理数据区段 | DIR0、Footer | 否 |
VOX0 是 VFP 1.3 唯一的权威体素源。缓存可以缺失、损坏或重新生成，但网格、渲染缓存和预览都不得替代 VOX0 判断资产真实内容。
0.1.1 目标读者
本规范面向 VFP 编译器、读取器、验证器和转换器的开发者，以及体素编辑器、运行时渲染器、游戏引擎、资产管理系统和服务端实现者。二进制章节应以字段布局、字节大小、编码方式、约束与验证规则为准，不应仅依据概念描述猜测实现。
0.1.2 规范性语言
| 关键字 | 含义 |
|---|---|
MUST / 必须 | 不满足即不符合 VFP 1.3。 |
MUST NOT / 禁止 | 明确禁止，出现时应视为格式错误或不兼容行为。 |
SHOULD / 应 | 强烈建议遵守；偏离时应有明确兼容性或性能理由。 |
SHOULD NOT / 不应 | 通常不建议，只有在明确理由下采用。 |
MAY / 可 | 可选能力；不实现不影响基础权威读取，但实现方必须按其区段规则安全处理或忽略。 |
“读取器”负责读取或解释 VFP；“写入器”负责创建或保存 VFP；“验证器”负责按本规范检查文件。一个程序可以同时承担多个角色。
0.1.3 合规性范围
| 合规性等级 | 最低要求 |
|---|---|
| 最小读取器 | 支持 Header、Footer、DIR0、JSON META、PAL0、CHIX、VOX0 与 RAW8，能拒绝结构非法或权威数据损坏的文件。 |
| 完整读取器 | 在最小读取器基础上支持所有标准区段，并对可选区段实施降级处理。 |
| 合规写入器 | 输出满足结构、长度、校验、保留字段与区段关系规则的 VFP 1.3，且至少能输出最小可读取文件。 |
| 合规验证器 | 检查容器、Directory、权威区段、Payload 边界、Codec、校验值、Source Hash 和区段依赖关系。 |
仅显示 PRVW 或 THMB 预览，或仅读取 PMSH、VBUF 等缓存而不能读取 VOX0 的程序，不属于 VFP 1.3 合规读取器。
0.1.4 不属于本规范的内容
VFP 1.3 不规定 .vf 的完整 JSON Schema、编辑器 UI、具体合面或材质算法、网络协议、CDN、数据库、DRM、AI 模型、世界地图、跨资产依赖和某一 GPU API 的私有 Buffer 格式。这些系统可以使用 VFP，但不得把私有行为写成 VFP 文件语义。
0.2 版本信息
| 项目 | 值 |
|---|---|
| 规范名称 | Voxel Format Package Specification |
| 中文名称 | VFP 技术标准 |
| 当前版本 | 1.3 |
| 文件扩展名 | .vfp |
| Header Magic | VFPK |
| Footer Magic | VFPF |
| Directory Magic | DIR0 |
| 数值字节序 | Little-endian |
| 适用资产 | 单体体素资产 |
| 当前状态 | 稳定规范 |
版本号由 major.minor 组成。主版本用于不兼容的容器、权威数据或语义改变；次版本只用于可兼容的可选区段、字段、缓存能力或规则澄清。VFP 1.3 写入器必须写入 majorVersion = 1、minorVersion = 3。
VFP 1.3 已作为当前稳定规范发布。任何会影响既有文件解释的改动都必须以新的兼容版本或新的正式格式变更表达；不得通过目录 flags、reserved 或未分配 Tag 改写既有语义。
0.3 设计目标
VFP 解决“易编辑”和“易运行”二选一的问题：源数据保留精确可编辑性，派生缓存服务快速启动和运行时性能。
| 目标 | 说明 |
|---|---|
| 可编辑性 | 保留独立、精确的体素源数据。 |
| 快速加载 | 允许内置网格、顶点和渲染缓存。 |
| 局部更新 | 通过 Chunk 索引减少编辑后的全模型重建。 |
| 可验证性 | 使用 Footer、Directory、CRC32 与 Source Hash 验证结构和一致性。 |
| 可扩展性 | 通过明确分配的可选 Tag、版本化记录与 XEXT 扩展；flags/reserved 不承载扩展语义。 |
| 跨平台性 | 固定字节序、整数宽度、坐标与编码规则。 |
| 可恢复性 | 缓存损坏或缺失时仍可由权威数据恢复。 |
| 确定性 | 相同的规范化输入与编译选项应尽可能得到一致输出。 |
VFP 1.3 不是通用三角网格、场景图、骨骼动画、开放世界数据库或任何平台私有渲染格式的替代品。它也不以支持超过 255 × 255 × 255 的单体权威体素网格为目标。
0.3.1 设计原则
- 源数据与缓存分离。
- Directory 优于物理排列顺序。
- 保守读取，明确写入。
- 支持按 Chunk 与区段按需加载。
- 所有偏移、长度、编码、Hash 和缓存依赖都必须可检查。
- 新能力优先采用可选区段与明确版本化记录；VFP 1.3 的目录 flags 必须为零。
0.4 术语定义
| 术语 | 定义 |
|---|---|
| Asset | 可独立加载、展示、编辑或引用的体素对象。 |
| Voxel | 占据单位立方体网格单元的离散元素，其存在性与颜色由 VOX0 定义。 |
| Empty Voxel | 空网格单元，在 VFP 1.3 中以 Palette Index 0 表示。 |
| Palette | 将非零颜色索引映射为颜色及附加属性的集合，由 PAL0 定义。 |
| Chunk | 网格中的固定尺寸局部区域，是按需加载、局部编辑与局部缓存的基本单位。 |
| Section | 可被 Directory 独立定位、读取与校验的一段 Payload 数据，不等同于空间 Chunk。 |
| Tag | 四字节 ASCII 区段标识，例如 VOX0、PAL0。 |
| Directory | 以 DIR0 开头的目录，记录 Tag、Codec、位置、长度、校验与属性。 |
| Authoritative Data | 决定资产真实语义、不可由其他区段可靠替代的数据。 |
| Cache | 由权威数据派生、可被忽略或重建的性能数据。 |
| Source Hash | 基于规范化权威数据计算的 SHA-256 值。 |
| Codec | Payload 的编码方式，例如 RAW8 或 RLE8。 |
| Reserved | 未来版本预留的字段或位；VFP 1.3 写入器必须写入 0。 |
下一步阅读 第 1 章：快速开始。