命令行

安装完整 wheel 后，会提供三个命令：

命令	用途
voxelkit	JSON → VFP。
vox2vfp	MagicaVoxel 单模型 VOX → VFP。
vfp2vox	VFP 权威体素 → VOX。

JSON → VFP

voxelkit model.json model.vfp \
  --chunk-size 16 \
  --no-preview \
  --thumbnail-size 256 \
  --thumbnail-background transparent \
  --verify

常用参数：--no-thumbnail 关闭 THMB；--thumbnail-background '#20252D' 写入实体背景；--render-cache 启用默认关闭的 RND0；--no-runtime-cache 与 --no-animation-cache 分别关闭基础缓存和 ANM0。

VOX 转换

vox2vfp model.vox model.vfp --no-preview --thumbnail-background '#17212B'
vfp2vox model.vfp model.vox

命令会将结果输出为 JSON，适合 CI 或脚本读取。任何格式错误会以非零退出码结束，并将诊断写入标准错误。

自动化建议

set -euo pipefail
voxelkit "$INPUT_JSON" "$OUTPUT_VFP" --no-preview --verify
python3 -c 'from voxelkit import Vfp; Vfp.parse("'"'"'$OUTPUT_VFP'"'"'").extract_thumbnail("'"'"'$OUTPUT_PNG'"'"'")'

生产脚本应固定 wheel 版本、记录输入 source hash 与输出文件大小，并在需要可信资产时使用 --verify 或 Python validate()。不要用 THMB/PRVW 的存在代替权威验证。