跳到主要内容

Vfp.validate()

asset.validate() -> dict[str, object]

执行 SDK 的完整 VFP 1.3 校验。它验证容器、目录、每个存储 payload CRC、META/PAL0/CHIX/VOX0 结构，恢复权威线性体素并重算 source hash；存在的标准缓存也会按其版本、长度、hash 和布局规则检查。

何时必须调用​

  • 用户上传后进入资产库前。
  • 作为 JSON/VOX 导出、缓存重建或服务端处理的前置步骤。
  • 比较两个资产 source_hash 前，至少对外部来源调用一次。

示例：可信导出​

from voxelkit import Vfp, VfpError

asset = Vfp.parse("incoming/castle.vfp")
try:
    report = asset.validate()
except VfpError as error:
    print("拒绝损坏或不一致的资产:", error)
    raise

print(report["sourceHash"])
asset.export_json("exports/castle.json")

成功报告​

报告至少包含 gridSize、chunkSize、solidVoxelCount、paletteCount、chunkCount、sourceHash、vfpBytes 与缓存存在性/字节数。所有字段都对应刚刚验证的文件状态；它不是持续监视对象，文件随后被替换时必须重新验证。

成本​

完整校验会读取全部 VOX0，并在存在缓存时额外检查它们。它适合后台任务、CLI、导入队列和发布流程，不适合每次列表刷新。仅展示信息使用 inspect()，仅检查容器可读使用 Vfp.parse()。

失败语义​

任何一项失败都会抛出 VfpError，没有“警告后返回部分报告”的模式。常见失败包括 CRC、RLE、chunk 目录、PAL0 index、META 统计、Header/META source hash、PRVW GLB、THMB PNG 或派生缓存 hash 不一致。不要捕获后继续导出或覆盖原文件。