VFP Compiler API

VfpCompiler 是随 voxel-kit HAR 一起发布的闭源 Native NAPI 编译器。它在后台线程完成 JSON/VOX 解析、RLE、贪心面、CRC、source hash 和 VFP 写入；ArkTS 只接触稳定的参数对象与 Promise<ArrayBuffer>，不会接触 C++ 指针、Mesh 或 ArkGraphics 对象。

从 voxel-kit 2.4.0 起，编译器除写入权威体素数据和标准缓存外，还会默认生成可选的 PRVW GLB 与 THMB PNG。它们是方便预览和列表展示的派生资源，不是权威数据，也不会改变 source hash。

创建与能力探测

import {
  VoxelKit,
  VfpCompiler,
  VfpCompilerOptions,
  VfpPackageReader
} from 'voxel-kit';

const compiler: VfpCompiler = VoxelKit.createVfpCompiler();
const reader: VfpPackageReader = VoxelKit.createVfpReader();
console.info('compiler=' + compiler.version());

const caps = compiler.capabilities();
if (!caps.jsonToVfp || !caps.previewGeneration) {
  throw new Error('当前 HAR 的 Native 编译能力不完整');
}

createVfpCompiler() 无参数、无文件句柄且不创建 3D 场景；VfpCompiler 无 dispose()，可在页面字段或业务服务中长期复用。每次调用都创建独立的 Native 异步任务，因此多个 Promise 的完成顺序不保证等于发起顺序。

capabilities() 返回以下能力位：

字段	含义
`vfpVersion` / `nativeAbi`	Writer 的目标 VFP 版本和当前 Native ABI 标识。
`jsonToVfp` / `voxToVfp`	JSON、单模型 MagicaVoxel VOX 编译是否可用。
`cacheRebuild`	是否可从权威 `VOX0/PAL0` 重建缓存。
`previewGeneration`	是否可生成 `PRVW` 与 `THMB`。
`runtimeCaches` / `renderCache` / `animationCache`	`VBUF/PMSH`、`RND0`、`ANM0` 的支持状态。

version() 返回 Native 编译器版本（当前为 0.3.0），不是 HAR 版本或 VFP 文件版本。

能力与产物

能力	状态	说明
PixForge JSON → VFP	支持	严格读取单 ASCII 调色板 JSON。
单模型 MagicaVoxel VOX → VFP	支持	接受 `MAIN/SIZE/XYZI[/RGBA]`；拒绝场景图与多模型。
权威源	默认写入	`META`、`PAL0`、`SCNE`、`CHIX`、完整 `VOX0`、每 Chunk `MSH0`。
运行时缓存	默认写入	`VBUF`、`PMSH` 与 `ANM0`。
展开渲染缓存	可选	`RND0` 默认关闭，以避免大模型包体膨胀。
GLB 通用预览	默认写入	`PRVW` GLB 2.0，含位置、法线、顶点色和索引。
PNG 缩略图	默认写入	`THMB`，96 × 96 直接 RGBA PNG，适合资源卡片。
缓存重建	支持	先恢复并验证 `VOX0/PAL0/source hash`，再生成新 generation 0 VFP。

VOX0 + PAL0 + source hash 才是权威数据边界。MSH0、PMSH、RND0、ANM0、PRVW 与 THMB 都可以被安全删除或重新生成，不能用于编辑正确性或资产可信性判断。

`compileJsonText()`：默认编译

async compileJsonText(jsonText: string, chunkSize: number = 16): Promise<ArrayBuffer>

适用于只需要默认策略的场景。它默认写入运行时缓存、动画缓存、PRVW 和 THMB，不写 RND0。

参数	类型	默认值	约束
`jsonText`	`string`	无	完整 PixForge JSON 文本；不是 URI、路径或 `ArrayBuffer`。
`chunkSize`	`number`	`16`	整数，范围 `1..grid_size`。

JSON 必须使用 data[z][y][x]；grid_size 为 1..255，调色板符号为单个 ASCII 字符，. 为保留空体素，颜色为 #RRGGBB。空模型、多字符/Unicode 符号、颜色 alpha、尾逗号和未定义调色板引用会 reject。

async function compileAndVerify(jsonText: string): Promise<ArrayBuffer> {
  const compiler = VoxelKit.createVfpCompiler();
  const reader = VoxelKit.createVfpReader();
  const bytes = await compiler.compileJsonText(jsonText, 16);
  const validation = reader.validateAuthoritative(bytes);
  console.info('sourceHash=' + validation.sourceHash);
  return bytes;
}

`compileJson()`：控制输出体积与缓存

async compileJson(jsonText: string, options: VfpCompilerOptions): Promise<ArrayBuffer>

选项	默认值	作用
`chunkSize`	`16`	`VOX0`/`MSH0` 的块边长。
`includeRuntimeCaches`	`true`	写入 `VBUF` 与 `PMSH`，供 VoxelViewer 快速预览。
`includeRenderCache`	`false`	写入展开顶点/索引缓存 `RND0`。
`includeAnimationCache`	`true`	写入 `ANM0` 载入动画批次。
`includePreviewGlb`	`true`	写入 `PRVW`。关闭不会影响 Viewer 的 PMSH 正式预览。
`includeThumbnail`	`true`	写入 `THMB`。关闭适合不需要资源列表封面的中间产物。

const options = new VfpCompilerOptions();
options.chunkSize = 16;
options.includeRenderCache = false;
options.includePreviewGlb = true;
options.includeThumbnail = true;

const vfpBytes = await compiler.compileJson(jsonText, options);

关闭 PRVW 或 THMB 只减少派生资源的生成时间和输出体积；不会改变权威 VOX0、source hash、PMSH 预览或体素的颜色/坐标。

`compileVox()`：单模型 MagicaVoxel 输入

async compileVox(voxBytes: ArrayBuffer, chunkSize: number = 16): Promise<ArrayBuffer>

该入口接受 MagicaVoxel 150+ 的单模型 MAIN/SIZE/XYZI[/RGBA]。PACK、nTRN、nGRP、nSHP、LAYR 和多模型 VOX 会被拒绝，避免把场景层级静默丢失后仍声称转换成功。输出使用与 JSON 编译相同的默认缓存和派生资源策略。

`rebuildCaches()`：从可信权威源重建

async rebuildCaches(vfpBytes: ArrayBuffer,
  options?: VfpCacheRebuildOptions): Promise<ArrayBuffer>

重建前会恢复 VOX0、检查 PAL0、区段 CRC、RLE、chunk 一致性并重算 source hash。任何权威数据损坏都会 reject；不会把旧 PMSH、RND0 或 PRVW 当作重建源。

VfpCacheRebuildOptions 与 VfpCompilerOptions 使用相同的缓存/预览开关，另有 chunkSize：默认 0 表示保持输入 VFP 的 chunk 大小。默认会重新生成 PRVW、THMB；如果资产服务只要权威数据，可将二者设为 false。

异步、内存与错误处理

调用立即返回 Promise；解析、贪心面、GLB、PNG、CRC 和写入均在 Native 后台线程完成，不阻塞 ArkUI。
编译期间输入 JSON/VOX、体素缓冲、派生缓存和输出 VFP 可能同时在内存中存在。大模型应串行编译，并在结果被保存或交给下一步后释放业务侧的输入引用。
Promise resolve 只代表字节已生成；对上传、分享或用户文件，仍应调用 reader.validateAuthoritative() 再将其视为可信资产。

reject 类别	常见原因	建议
`grid_size must be between 1 and 255`	网格越界。	规范化源文件。
`chunkSize must be between 1 and grid_size`	chunkSize 无效。	使用默认 16。
`missing JSON key` / `invalid JSON`	JSON 缺少结构或格式非法。	使用 PixForge 标准导出。
`palette ...` / `undefined palette symbol`	调色板符号或颜色不符合约束。	使用单 ASCII 符号和 `#RRGGBB`。
`voxel source has no solid voxels`	模型为空。	至少保留一个实体体素。

不要直接 import libvoxelkit_compiler.so，也不要把 PRVW/THMB 当作可编辑源。公开兼容契约是 VoxelKit.createVfpCompiler()、VfpCompiler 和它的 Options 类型。

创建与能力探测​

能力与产物​

compileJsonText()：默认编译​

compileJson()：控制输出体积与缓存​

compileVox()：单模型 MagicaVoxel 输入​

rebuildCaches()：从可信权威源重建​

异步、内存与错误处理​