VfpPackageReader：权威数据与导出

VFP 的权威体素来源是 PAL0 + CHIX + VOX0，而不是 PRVW、MSH0、PMSH、VBUF、RND0、ANM0 或缩略图。缓存缺失、过期或被删除时，权威数据仍可恢复模型。

decodePalette()

decodePalette(bytes: ArrayBuffer): Array<VfpPaletteEntry>

恢复 PAL0 顺序表。每条 VfpPaletteEntry 包含：

字段	说明
index、symbol	权威调色板索引与原始符号。
red、green、blue、alpha	0–255 RGBA。
metallic、roughness	材质参数。
emissiveRed/Green/Blue	自发光 RGB。
flags	调色板记录扩展标志。

decodeVoxels()

decodeVoxels(bytes: ArrayBuffer): VfpVoxelVolume

解码 CHIX 与所有 VOX0，处理 RAW8/RLE8，返回 gridSize、chunkSize、solidVoxelCount 和线性 ArrayBuffer voxels。线性索引由 SDK 固定，调用者不得根据渲染缓存猜测坐标；若需要按索引读取，请由应用创建 new Uint8Array(volume.voxels)。

const volume = reader.decodeVoxels(vfpBytes);
console.info('grid=' + volume.gridSize + ', solids=' + volume.solidVoxelCount);
const paletteIndex = new Uint8Array(volume.voxels)[0];
console.info('first palette index: ' + paletteIndex);

对 128³ 以上密集模型，此调用会分配完整线性缓冲；不要在每一帧、列表每个单元格或 UI 构建函数内反复调用。

inspect()

inspect(bytes: ArrayBuffer): VfpInspection

在恢复应用 UI 前提供资产摘要。VfpInspection 含文档、网格/Chunk 尺寸、实体数、调色板数、Chunk 数，以及 hasMeshCache、hasVoxelBuffer、hasPreviewMesh、hasRenderBuffer、hasAnimationPlan、hasPreviewGlb、hasThumbnail 等布尔值。

这些 has* 表示区段存在，不代表缓存可安全信任。

validateAuthoritative()

validateAuthoritative(bytes: ArrayBuffer): VfpAuthoritativeValidation

执行容器校验、必要权威区段恢复、source hash 重算与比对。成功才返回 document、gridSize、chunkSize、solidVoxelCount、sourceHash；任一步失败均抛错。

const verified = reader.validateAuthoritative(vfpBytes);
console.info('trusted hash: ' + verified.sourceHash);

需要“文件未被篡改、权威模型可恢复”的场景必须调用它。仅 validate() 成功说明所有已存储载荷 CRC 正确，不能说明 VOXO 与 Header hash 的语义一致。

导出交换格式

exportJsonText(bytes: ArrayBuffer): string
exportVox(bytes: ArrayBuffer): ArrayBuffer

两者都以权威数据为输入：前者返回 PixForge JSON 文本，后者返回 MagicaVoxel .vox 字节。建议先 validateAuthoritative()，再导出，以便把坏文件与格式不支持问题在用户保存前报告。

function convertToVox(vfpBytes: ArrayBuffer): ArrayBuffer {
  const reader = VoxelKit.createVfpReader();
  reader.validateAuthoritative(vfpBytes);
  return reader.exportVox(vfpBytes);
}

导出不会自动写磁盘。由宿主以用户明确选择的位置保存 ArrayBuffer，并处理文件名、覆盖确认和文件系统权限。