compile_json()

compile_json(input_path, output_path, *, chunk_size=16, preview=False,
             thumbnail=True, thumbnail_size=256,
             thumbnail_background="transparent") -> dict[str, object]

简化的 JSON → VFP 编译入口。适合默认写入运行时缓存与 THMB、但不需要 RND0 等高级开关的业务代码。

参数	默认值	说明
input_path	必填	VF / PixForge JSON 路径。
output_path	必填	目标 .vfp 路径。
chunk_size	16	1..255 的 Chunk 边长。
preview	False	是否写入 PRVW GLB。
thumbnail	True	是否写入 THMB PNG。
thumbnail_size	256	THMB 正方形边长，范围 64..1024。
thumbnail_background	transparent	透明背景或 #RRGGBB 不透明背景。

返回编译统计，如 sourceHash、solidVoxelCount、vfpBytes、thumbnailPngBytes。JSON、网格、调色板或缩略图参数非法时抛出 VfpError；读写失败抛出 OSError。

from voxelkit import compile_json
report = compile_json("source.json", "asset.vfp", thumbnail_background="#20252D")
print(report["sourceHash"])