跳到主要内容

第 6C 章：XEXT 自定义扩展

XEXT v1 由 26072802-xext-v1 引入。它让第三方应用在不占用新的四字符标准区段、也不改变体素权威数据的前提下，保存自己的附加信息。

XEXT 是数据容器，不是插件执行机制：它不能包含脚本、动态库或可执行代码，也不能改变 META、PAL0、CHIX、VOX0 和既有 sourceHash 的解释。

适用范围​

kind可保存不可保存
metadata作者、许可证、AI 提示词、审核标签、协作批注影响模型体素含义的数据。
presentationUnity 导入设置、编辑器图层状态、业务视图偏好所有 Reader 都必须实现的正式渲染语义。
cacheLOD、引擎私有网格、碰撞缓存、分析缓存未绑定 sourceHash 的可复用权威数据。

骨骼、材质、新体素编码、坐标系、加密签名等会影响跨平台理解的能力，必须使用正式 VFP 变更和标准区段，不能放入 XEXT。

目录与二进制布局​

一个文件可有多个 XEXT；每条均为：

tag     = XEXT
chunkId = -1
codec   = 0 (RAW8)
flags   = 0

XEXT v1 的 48 B Header：

version:u8 = 1
kind:u8 = 1 METADATA / 2 PRESENTATION / 3 CACHE
encoding:u8 = 1 CANONICAL_JSON / 2 OPAQUE_BYTES
flags:u8 = bit0 BIND_TO_SOURCE
schemaVersion:u16
extensionIdLength:u16
payloadLength:u64
baseSourceHash:u8[32]
extensionIdUtf8
payload

extensionId 必须是包含 . 的小写反向域名，例如 com.charactech.voxel.ai-provenance。同一文件中不可重复。单条 payload 最大 8 MiB，所有 XEXT payload 合计最大 16 MiB。

当 BIND_TO_SOURCE 未设置时，baseSourceHash 必须全为零；设置时必须与 Header sourceHash 一致。kind=CACHE 必须绑定 source。

兼容与保存规则​

情况正确行为
Reader 不认识 XEXT跳过该区段，继续读取标准 VFP / Bind Pose。
Reader 认识 ID 但不认识 schemaVersion保留原 payload 或忽略；不得猜测解释。
权威 VOX0/PAL0 修改丢弃所有绑定 source 的 XEXT，或由扩展所有者重建。
未绑定 metadata/presentation可原样透传。
Writer 无法无损保留未知扩展不修改权威数据时可复制；修改后必须丢弃已绑定扩展。

Python 编译输入​

{
  "extensions": [
    {
      "id": "com.charactech.voxel.ai-provenance",
      "version": 1,
      "kind": "metadata",
      "encoding": "json",
      "bind_to_source": true,
      "payload": {"prompt": "blue voxel", "seed": 20260728}
    },
    {
      "id": "com.unity.voxel.import-settings",
      "version": 1,
      "kind": "presentation",
      "encoding": "base64",
      "bind_to_source": false,
      "payload_base64": "AQID"
    }
  ]
}

encoding=json 会被 Writer 规范化成 canonical JSON；encoding=base64 只负责编码不解释二进制内容。Python 可通过 Vfp.extensions() 读取 ExtensionEntry，payload 始终以 bytes 返回，由 extensionId 所有者自行解析。

当前 HarmonyOS Native Compiler 不编译或写回 XEXT；它不得用于修改含 XEXT 的 VFP，以免静默丢失扩展。HarmonyOS Reader 可安全忽略这些区段并读取标准体素。