跳到主要内容

VfpCompiler

VfpCompiler 是随 HAR 交付的 Native .so 的稳定 ArkTS 门面。算法、压缩细节和缓存生成逻辑不暴露给应用；应用只依赖本页列出的数据契约。voxel-kit 2.4.0 的单个 HAR 已同时携带 arm64-v8a 真机与 x86_64 模拟器的 .so，接入方不需要额外复制 Native 库。

创建与版本​

const compiler = VoxelKit.createVfpCompiler();
const nativeVersion: string = compiler.version();

version() 返回随当前 HAR 打包的 Native 编译器版本，便于诊断，不等同于目标 VFP 的版本。

capabilities()​

capabilities(): VfpCompilerCapabilities

返回 vfpVersion、nativeAbi、jsonToVfp、voxToVfp、cacheRebuild、previewGeneration、runtimeCaches、renderCache、animationCache。功能必须以此运行时能力为准，不能根据方法是否存在推断 Native 二进制的功能已启用。

const caps = compiler.capabilities();
if (!caps.jsonToVfp) {
  throw new Error('当前设备上的 Native 编译器不支持 JSON → VFP');
}

compileJsonText()​

async compileJsonText(jsonText: string, chunkSize: number = 16): Promise<ArrayBuffer>
参数类型约束
jsonTextstringPixForge 单字符调色板 JSON。
chunkSizenumber1..gridSize，默认 16。

成功时返回可直接保存或传给 Reader/Viewer 的 VFP 1.3 内存字节。编译在 Native 异步任务中完成，不阻塞 ArkUI，但输入 JSON 与输出 VFP 会在内存中同时存在。

compileJson() 与 VfpCompilerOptions​

async compileJson(jsonText: string, options: VfpCompilerOptions): Promise<ArrayBuffer>
选项默认值说明
chunkSize16VOX0 分块边长。
includeRuntimeCachestrue请求生成运行时缓存。实际结果以 capabilities() 为准。
includeRenderCachefalse请求 RND0；默认关闭以控制文件体积。
includeAnimationCachetrue请求 ANM0。
includePreviewGlbtrue写入 PRVW GLB 2.0；关闭不影响 PMSH 正式预览。
includeThumbnailtrue写入 THMB 96 × 96 PNG；关闭不影响权威数据。

当前编译器始终生成权威 META、PAL0、CHIX、完整 VOX0、区段 CRC 和 source hash。任何派生缓存都是可删除的，不能代替权威数据。

完整安全流程​

async function compileJsonToVerifiedVfp(jsonText: string): Promise<ArrayBuffer> {
  const compiler = VoxelKit.createVfpCompiler();
  const options = new VfpCompilerOptions();
  options.chunkSize = 16;
  options.includeRenderCache = false;
  const vfpBytes = await compiler.compileJson(jsonText, options);

  const reader = VoxelKit.createVfpReader();
  reader.validateAuthoritative(vfpBytes);
  return vfpBytes;
}

错误处理与限制​

Promise 会因非 JSON、缺少网格/调色板、符号与网格不一致、grid 或 chunk 越界、Native 能力缺失或内存压力而拒绝。捕获后展示可读错误；不要在失败后把部分字节保存成 VFP。

compileVox()、rebuildCaches()、PRVW/THMB 生成均由 capabilities() 判断。当前 2.4.0 Native 编译器支持这些能力；如未来出现精简 ABI，应用应在能力位为 false 时禁用对应操作或交给后端/Python SDK，而非假设会自动降级。