编译 VFP

输入是 PixForge 体素 JSON：grid_size、colors 和 data[z][y][x]。当前 Python SDK 不公开 MagicaVoxel VOX → VFP 编译 API。

from pathlib import Path
from voxelkit import Vfp, compile_json, compile_vfp

# 简化入口：chunk 与 PRVW 开关
summary = compile_json("model.json", "model.vfp", chunk_size=16, preview=False)

# 完整缓存控制
summary = compile_vfp(
    Path("model.json"), Path("model-full.vfp"),
    chunk_size=16,
    include_preview=True,
    include_runtime_caches=True,
    include_render_cache=False,
    include_animation_cache=True,
)

asset = Vfp.compile("model.json", "model-asset.vfp", include_preview=False)

chunk_size 必须为 1..255；实际 VFP 网格同样上限为 255。include_runtime_caches 控制 VBUF/PMSH，include_render_cache 控制默认关闭的 RND0，include_animation_cache 控制 ANM0，include_preview 控制 PRVW。它们都不改变 VOX0/PAL0/sourceHash。

编译返回统计字典，包含 gridSize、solidVoxelCount、chunkCount、sourceHash、vfpBytes 与各缓存存在性。输入不合法抛出 VfpError，路径问题抛出 OSError。