VoxelKit

VoxelKit 是不持有文件、页面或 ArkGraphics 场景的静态门面。它只负责创建功能对象，因此可在服务、Ability 和组件外层安全使用。

API 一览

方法	返回值	用途
VoxelKit.version()	string	读取 HAR 的公开 SDK 版本。
VoxelKit.createVfpReader()	VfpPackageReader	创建无渲染依赖的 VFP 解析器。
VoxelKit.createVfpCompiler()	VfpCompiler	创建异步 Native VFP 编译器。

version()

static version(): string

无参数、无 I/O。它返回的是 ArkTS SDK 版本，不能用来推断一个 VFP 文件的格式版本；文件版本请使用 reader.parse(bytes).majorVersion 与 minorVersion。

const sdkVersion: string = VoxelKit.version();
console.info('Voxel Kit SDK: ' + sdkVersion);

createVfpReader()

static createVfpReader(): VfpPackageReader

返回一个新的、无状态 Reader。Reader 不缓存上一次文件，因此同一个实例可以顺序处理多个 ArrayBuffer；涉及同一个文件的 parse、decodePalette、validateAuthoritative 可共用该实例。

const reader = VoxelKit.createVfpReader();
const document = reader.parse(vfpBytes);
console.info('sections: ' + document.sectionTags().join(', '));

createVfpCompiler()

static createVfpCompiler(): VfpCompiler

返回 Native 编译器的 ArkTS 门面。创建本身不执行编译、不会读取文件；真正的 CPU 工作仅在 compileJsonText() 或 compileJson() 被 await 时发生。

const compiler = VoxelKit.createVfpCompiler();
console.info('native compiler: ' + compiler.version());
const capability = compiler.capabilities();
if (!capability.jsonToVfp) {
  throw new Error('当前 HAR 不包含 JSON 编译能力');
}

Reader 与 Compiler 的组合

下面示例把 JSON 编译为内存中的 VFP，再做权威验证。它不写入文件系统，适用于先验证后由宿主决定保存位置的流程。

async function compileAndCheck(jsonText: string): Promise<number> {
  const compiler = VoxelKit.createVfpCompiler();
  const bytes = await compiler.compileJsonText(jsonText, 16);
  const reader = VoxelKit.createVfpReader();
  const result = reader.validateAuthoritative(bytes);
  return result.solidVoxelCount;
}

不要将 VoxelKit 当作全局可变配置中心；每个页面各自保存其 Controller、Reader 或 Compiler 即可。