编译 VFP

JSON → VFP

compile_json() 是最简入口；Vfp.compile() 会返回已解析的对象，适合紧接着检查或导出。

from voxelkit import Vfp, compile_json

result = compile_json(
    "model.json",
    "model.vfp",
    chunk_size=16,
    preview=False,
    thumbnail=True,
    thumbnail_size=256,
    thumbnail_background="transparent",
)

asset = Vfp.compile(
    "model.json",
    "model-with-preview.vfp",
    include_preview=True,
    include_render_cache=False,
)

compile_json() 参数

参数	类型 / 默认值	说明
input_path	str / Path	输入 JSON 路径。
output_path	str / Path	输出 .vfp 路径。
chunk_size	int = 16	可编辑 Chunk 的边长。
preview	bool = False	是否写入 PRVW GLB。
thumbnail	bool = True	是否写入 THMB PNG。
thumbnail_size	int = 256	正方形缩略图边长，范围 64..1024。
thumbnail_background	"transparent"	透明背景，或不透明 #RRGGBB。

Vfp.compile() 使用同一能力，但参数名与 VFP 区段对应：include_preview、include_runtime_caches、 include_render_cache、include_animation_cache、include_thumbnail、thumbnail_size、thumbnail_background。 RND0 默认关闭，应仅在运行时确实能直接消费该缓存时开启。

VOX → VFP

from voxelkit import Vfp

asset = Vfp.from_vox(
    "model.vox",
    "model.vfp",
    include_preview=True,
    thumbnail_background="#17212B",
)

当前互操作 Profile 支持 MagicaVoxel 单模型 MAIN/SIZE/XYZI[/RGBA]。含 PACK、场景图或对象变换的 文件会明确拒绝，避免静默压平导致语义丢失。

THMB 与 PRVW 的选择

• THMB：小型 RGBA PNG，适合文件列表。默认生成、默认透明，使用 extract_thumbnail() 导出。
• PRVW：GLB 预览，适合通用 3D 展示；只有启用 preview=True / include_preview=True 才会写入。
• 两者均为派生内容，不改变 VOX0 权威数据或 source hash。

CLI

voxelkit model.json model.vfp --no-preview --thumbnail-background '#20252D' --verify
vox2vfp model.vox model.vfp --no-preview --thumbnail-size 512

完整参数说明见 命令行。