跳到主要内容

VoxelKit

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

API 一览​

方法返回值用途
VoxelKit.version()string读取 HAR 的公开 SDK 版本。
VoxelKit.createVfpReader()VfpPackageReader创建无渲染依赖的 VFP 解析器。
VoxelKit.createVfpCompiler()VfpCompiler创建异步 Native VFP 编译器。
VoxelKit.createGltiExporter()VoxelGltiExporter创建 VFP → GLTI MP4 导出器。
VoxelKit.createGltiReader()GltiPackageReader创建只读 GLTI → 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 编译能力');
}

createGltiExporter()​

static createGltiExporter(): VoxelGltiExporter

创建一个无状态的 GLTI 导出器。真正的 VFP 解析、GLB 重建、H.264 编码和 MP4 封装发生在 export() 被 await 时；创建对象本身不读取文件、不创建 ArkGraphics 场景。

const exporter = VoxelKit.createGltiExporter();
const gltiBytes = await exporter.export(vfpBytes);

GLTI 是交付容器：默认输出包含可播放的 H.264 转台视频、可互操作 GLB，以及保持原字节的可编辑 VFP。embedEditableVfp 用于独立控制是否保留编辑源；它不决定文件应保存到相册、发送还是进入项目空间。 任务步骤见 导出到相册与分享，完整字段见 VoxelGltiExporter API。

createGltiReader()​

static createGltiReader(): GltiPackageReader

创建 GLTI 的只读恢复器。它只接受 VoxelKit 写出的、带 CHARACTECH_voxel_vfp 原始 VFP 扩展的 可编辑 GLTI。普通 MP4、普通 GLB，以及明确不嵌入工程源的展示专用 GLTI 都会失败；不会从视频或 网格猜测、重建近似体素。

const reader = VoxelKit.createGltiReader();
const originalVfp = await reader.extractVfp(gltiBytes);

请在业务侧决定从 Picker URI 读取哪份文件、将恢复字节保存到哪里，以及是否再交给 Viewer 或编辑器。

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 即可。