版本变更记录
本页记录 VFP 格式规范 的变更，不等同于 Python wheel、HarmonyOS HAR 或编译器的发布日志。每一次已发布的格式变更都分配一个独立、可引用的版本号；实现版本可能先于或晚于格式支持，使用某项能力前仍应同时检查文件区段、SDK API 与目标渲染器能力。
变更编号规则
格式变更号采用：
YYMMDDNN-短名称
| 部分 | 含义 | 示例 |
|---|---|---|
YYMMDD | 变更定稿日期 | 260727 表示 2026-07-27。 |
NN | 当天从 01 开始递增的两位序号 | 04 表示当天第 4 项已定稿变更。 |
短名称 | 小写 kebab-case 的稳定主题名 | matl-v1。 |
示例：26072704-matl-v1。编号一经分配不得改作其他语义；后续修正文档、实现或测试时，使用新的变更号并在本页标明其取代或补充的记录。文件 Header 的 major.minor 仍是容器兼容版本，不能用此变更号替代。
版本策略
major变化表示 Header、Footer、Directory 或权威数据解释发生不兼容变化。minor变化表示同一主版本下新增明确规则；Reader 应按该 minor 的规范判断是否支持。- 在 1.3 中新增的可选四字符区段属于扩展记录：旧 Reader 可以忽略未知的可选区段，但不得误解或猜测其内容。
- 缓存、预览和缩略图均非 VOX0 权威几何源；它们的变化不应破坏无缓存读取路径。
当前最新版本
当前正式格式版本为 VFP 1.3；截至本文档更新时，最新的独立格式变更是
26072705-matl-cache-rebuild-safety。它是对 MATL v1 缓存生命周期的补充规则，
不改变容器 Header、Directory、VOX0 或 MATL 的二进制布局。
| 项目 | 当前值 | 兼容性结论 |
|---|---|---|
| 容器版本 | 1.3 | VFP 1.3 Reader 可按既有容器规则读取。 |
| 最新变更 | 26072705-matl-cache-rebuild-safety | 与此前 VFP 1.3 文件双向兼容；只影响支持 MATL 的缓存重建器。 |
| 权威数据 | META、PAL0、CHIX、VOX0 | 仍是所有恢复、编辑和校验的唯一可信来源。 |
| 新增可选区段 | MATL | 未实现 MATL 的 Reader 可忽略区段并按 PAL0 基础色降级显示。 |
| 缓存与表现区段 | MSH0、VBUF、PMSH、RND0、ANM0、PRVW、THMB | 都可被忽略或重新生成；校验失败不能阻止权威数据读取。 |
兼容性标记说明
每条变更都必须说明以下信息，避免只写“兼容”而缺少可执行的读取策略：
| 标记 | 说明 |
|---|---|
| 向后兼容 | 新 Reader 是否能读取变更前生成的文件。 |
| 向前兼容 | 变更前 Reader 是否能安全处理变更后生成的文件；“可忽略”不代表能呈现新增效果。 |
| 升级要求 | Writer、Reader 或渲染器是否必须升级才能产生或消费该能力。 |
| 降级行为 | 不支持时应显示、忽略、回退还是拒绝，及拒绝的边界。 |
| 缓存影响 | 已有派生缓存可否继续使用、必须失效还是可以忽略并重建。 |
VFP 1.3 系列
26072705-matl-cache-rebuild-safety：材质资产的缓存重建安全规则
Native cache rebuild 必须验证并保留 MATL。若该重建器尚不能生成材质感知的 PRVW 或 THMB， 则必须省略它们，不能将含玻璃、金属或自发光语义的资产重新写成纯色预览缓存。此变更不修改 MATL 二进制布局，补充的是 Writer 与缓存生命周期规则。
| 兼容项 | 结论 |
|---|---|
| 向后兼容 | 是。新重建器可处理没有 MATL 的既有 VFP 1.3 文件。 |
| 向前兼容 | 是。旧 Reader 无需理解该规则，仍按文件中的权威数据和可选缓存读取。 |
| 升级要求 | 仅需要升级执行缓存重建的 Writer/Compiler；普通 Reader 无需升级。 |
| 降级行为 | 无材质预览生成能力时省略 PRVW/THMB，不写入错误的纯色替代缓存。 |
| 缓存影响 | 材质变更后的外观缓存必须失效；MSH0、VBUF、PMSH 等纯几何缓存可继续使用。 |
26072704-matl-v1：调色板绑定材质扩展
新增可选 MATL，由 paletteIndex 绑定金属度、粗糙度、自发光、透明模式、透射、IOR 与厚度。
MATL 不修改 PAL0 布局、不改变 VOX0，且不进入历史 sourceHash，因此旧 Reader 仍能打开文件并按基础色显示。
| 兼容项 | 结论 |
|---|---|
| 向后兼容 | 是。新 Reader 对无 MATL 的历史文件使用默认不透明材质。 |
| 向前兼容 | 是，条件是旧 Reader 能按 VFP 1.3 可选区段规则忽略未知 MATL；它不会呈现金属、玻璃或自发光效果。 |
| 升级要求 | 生成或严格校验 MATL 需要升级 Writer/Reader；材质视觉效果还需要目标渲染器单独支持。 |
| 降级行为 | 忽略 MATL，使用 PAL0 的基础色与默认不透明材质；不得将 MATL 当成未知权威区段而拒绝文件。 |
| 缓存影响 | RND0、PRVW、THMB 等外观缓存失效；几何缓存不因材质字段本身重建。 |
兼容与迁移规则：
- 新 Writer 仅在至少有一项非默认材质时写入 MATL。
- 新 Reader 必须检查 MATL CRC、Header、记录顺序、palette 引用和
baseSourceHash。 - 不满足 MATL 校验时，Reader 必须忽略 MATL 并回退到 PAL0，而不是破坏 VOX0 的权威读取。
详见 MATL 材质扩展。
26072703-preview-and-thumbnail：预览与资产列表资源
| 区段 | 变更 | 兼容影响 |
|---|---|---|
PRVW | 可选 GLB 2.0 预览。 | 非权威；不支持 GLB 的 Reader 忽略。 |
THMB | 可选全局 RAW PNG 缩略图，支持透明背景。 | 非权威；缺失仅影响资产卡片。 |
| 兼容项 | 结论 |
|---|---|
| 向后兼容 | 是。新 Reader 可读取不含预览资源的 VFP 1.3 文件。 |
| 向前兼容 | 是。旧 Reader 忽略未知的可选 PRVW 和 THMB。 |
| 升级要求 | 只有需要直接提取 GLB 或缩略图的资产浏览器需要升级。 |
| 降级行为 | 无预览时显示占位图或从 VOX0 延迟生成；不得用预览替代权威模型。 |
| 缓存影响 | 可随时删除或替换；与 VOX0/sourceHash 不匹配时直接忽略。 |
PRVW 和 THMB 不得替代 VOX0，也不得阻塞编辑模式的权威恢复。
26072702-runtime-cache-set：运行时与编辑缓存
| 区段 | 变更 | 兼容影响 |
|---|---|---|
MSH0 | Chunk 级贪心面计划。 | 可丢弃；编辑器可从 VOX0 重建。 |
VBUF | 完整线性 RAW8 体素缓冲缓存。 | 可丢弃；命中时加快恢复。 |
PMSH | 全局贪心面预览缓存。 | 可丢弃；避免端侧分 Chunk 合面。 |
RND0 | 已展开顶点/索引/顶点色缓存。 | 可选且默认可关闭；引擎仍需创建原生 Geometry。 |
ANM0 | 默认载入动画批次。 | 仅表现层，缺失不影响模型。 |
| 兼容项 | 结论 |
|---|---|
| 向后兼容 | 是。新 Reader 可读取无任一缓存区段的基线 VFP 1.3 文件。 |
| 向前兼容 | 是。旧 Reader 必须忽略它不认识的可选缓存，不得从缓存推断权威体素。 |
| 升级要求 | 只对追求更快恢复、预览或默认动画的运行时有要求。 |
| 降级行为 | 忽略缺失、损坏或不支持的缓存，从 META/PAL0/CHIX/VOX0 恢复。 |
| 缓存影响 | 各缓存均由 sourceHash、CRC、版本和语义校验绑定；任一校验失败即失效，不影响打开文件。 |
26072701-vfp13-baseline：确定性单体体素资产容器
| 范围 | 内容 |
|---|---|
| 容器 | 固定 64 B Header、最终 64 B Footer、48 B DIR0 Entry，均采用 little-endian。 |
| 权威几何 | META、PAL0、CHIX、VOX0；线性体素顺序为 X 最快、随后 Y、最后 Z。 |
| 编码 | codec=0 RAW8、codec=1 RLE8；flags 不表达编码且必须为 0。 |
| 限制 | 单轴网格与 Palette Index 均为 1..255。 |
| Hash | 基于 gridSize + PAL0 基础颜色/符号 + VOX0 的 sourceHash。 |
迁移：旧 JSON、VOX 或其他格式导入器先归一化为 palette index 和线性体素，再生成权威区段；无需依赖任何缓存。
| 兼容项 | 结论 |
|---|---|
| 向后兼容 | 不适用。此条是 VFP 1.3 的基线定义。 |
| 向前兼容 | 不保证。无法理解 VFP 1.3 Header、Directory 或权威区段规则的旧格式 Reader 必须明确拒绝，不能猜测解析。 |
| 升级要求 | 所有产生或读取 VFP 1.3 权威数据的实现都必须支持本条。 |
| 降级行为 | 不存在安全降级；读取失败时应提示需要 VFP 1.3 兼容 Reader。 |
| 缓存影响 | 无；缓存属于后续可选变更，基线恢复不依赖缓存。 |
SDK 实现记录
| 能力 | Python VoxelKit | HarmonyOS VoxelKit |
|---|---|---|
| VFP 1.3 容器/权威几何读取 | 支持 | 支持 |
| MATL 编译与读取 | 支持 | 尚未公开为 Reader API |
| MATL 严格校验 | 支持 | Native cache rebuild 内部保留/校验 |
| 材质感知 PRVW GLB | 支持 | Native rebuild 遇 MATL 时不生成纯色 PRVW |
| ArkGraphics 材质渲染 | 不适用 | 尚未支持 |
这张表用于防止“文件可存储材质”被误解为“所有端侧预览器已渲染材质”。
后续演进准则
未来若需要多个材质对象、纹理、法线贴图、真实折射、动画材质或全资产加密签名，应新增类似 YYMMDDNN-短名称 的变更记录，并视兼容性决定是否提升 minor/major 版本；不得占用 MATL v1 保留字节、复用未知 alphaMode，或通过 directory flags 猜测新编码。