数据结构与错误

BlockEntry

由 asset.entries() 返回的不可变目录项：section（4 字节 bytes tag）、chunk_id（全局为 -1）、codec（0=RAW8、1=RLE8）、flags、offset、stored_length、raw_length、crc32 与 reserved。VFP 1.3 合规目录项的 flags 与 reserved 均为 0。它只描述定位信息；读取载荷请使用 read_section()。

PaletteEntry

由 asset.palette() 返回，具有 index、symbol、red、green、blue。index 是 VOX0 中的非零字节值，RGB 范围为 0..255。

可选扩展返回值

materials()、rig()、extensions() 与 thumbnail() 没有额外的顶层导入类型；它们返回由格式定义的只读记录或字典：

方法	返回内容	缺失时
materials()	按 palette index 排序的材质记录。	空元组。
rig()	joints、defaultJointId、bindings、clips、skeletonHash 的字典。	None。
extensions(id?)	ExtensionEntry 元组，记录 extension_id、kind、encoding、schemaVersion、source hash 绑定和原始 payload。	空元组。
thumbnail()	(mime, width, height, png_bytes)。	None。

这些方法不会解释第三方扩展 payload，也不会把 THMB 或 PRVW 视为权威体素。对材质、Rig 和 XEXT 的可信绑定，请调用 validate()。

VfpError

继承 ValueError，表示 VFP/JSON/VOX 格式错误、区段缺失、CRC/hash 不一致或不支持的 Profile。文件系统问题则可能抛出 OSError。

from voxelkit import VfpError
try:
    asset.validate()
except VfpError as error:
    print(error)