Custom Data ABI v1
行为与约束
仅 Manifest v5,customData.abiVersion=1。variable 的 id/type/frequency/default/onError/expression 为显式合同;unit/space 在适用时标注并与输入一致。类型为 bool、int、uint、float、vec2/3/4、mat3/4。所有浮点 lane 必须有限;int/uint 保留 32-bit 精确 words,不经过 float;bool 为 0/1,矩阵为 9/16 个 column-major float32 lane。
expression 的七类形状由完整 Schema 展开:带 type 的 literal、ref、input/version、option/as/map、materialProperty/material、call/args、select/whenTrue/whenFalse。只允许公开输入与函数名/arity,见 Catalog。ref 的依赖不能有环,类型/单位/空间与频率须兼容。generation/frame/view 不能低于依赖最低频率;隐式类型转换、矩阵逐分量乘与 matrixMultiply 不可混同。
所有分支和未消费变量先参与原始 AST、引用深度及预算校验,再做常量折叠。固定上限包含 256 variables、4096 AST nodes、64 AST/reference depth、128 custom bindings/command;加权 operations 为 generation 32768、frame/view 各 8192。materials 还限制 4096 definitions、32 properties、64 tags、1024 groups、4096 mappings。不能通过包配置放大宿主预算。
首版 onError 仅 useDefault,default 必须类型精确且有限。customBindings 的 symbol/variable 连接已有变量,required 缺省语义以 Loader 为准;required=false 只允许驱动优化掉声明,不允许类型错误、数组或跨 owner symbol/location 冲突。offline runtimeEvaluated=false 表示计划分析,不是求值结果。
当前固定 completion 注册 23 个 version 1 输入,旧指南列出的 11 个不是完整列表。逻辑 projection_matrix 与实际 render_projection_matrix 分开;previous_* 只来自同主 view 的成功提交。history_valid 不替代 GPU history 有效性;unavailable 与 available+invalid 不同。render delta 最大有效间隔 0.25 秒,需同时检查 valid;完整 temporal history 与该旧 delta 也不是同一合同。机器 temporal 文档保留早期 runtimeReady=false,而当前 completion/后续接入文档已记录 Provider,须按时间与证据域解释。
主 view 的 temporal extent 是物理像素,jitter 也以像素计,未 opt-in jitter 时偏移为零。position 使用 world blocks,矩阵源/目标空间逐项见 Catalog;辅助 camera、分屏和 VR 不借用主 view timeline。本参考不新增时序实机或性能验收。
自动生成的 v5 结构
必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。
customData · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
abiVersion | required | const=1 |
variables | optional here | type="array"; maxItems=256; items=#/$defs/customVariable |
完整结构规则: #/$defs/customData
{
"additionalProperties": false,
"properties": {
"abiVersion": {
"const": 1
},
"variables": {
"items": {
"$ref": "#/$defs/customVariable"
},
"maxItems": 256,
"type": "array"
}
},
"required": [
"abiVersion"
],
"type": "object"
}customVariable · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
default | required | — |
expression | required | $ref="#/$defs/dataExpression" |
frequency | required | enum=["generation","frame","view"] |
id | required | $ref="#/$defs/dataId" |
onError | required | const="useDefault" |
space | optional here | $ref="#/$defs/nonEmptyString" |
type | required | enum=["bool","int","uint","float","vec2","vec3","vec4","mat3","mat4"] |
unit | optional here | $ref="#/$defs/nonEmptyString" |
完整结构规则: #/$defs/customVariable
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "bool"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"type": "boolean"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "int"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"maximum": 2147483647,
"minimum": -2147483648,
"type": "integer"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "uint"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"maximum": 4294967295,
"minimum": 0,
"type": "integer"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "float"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "vec2"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 2,
"minItems": 2,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "vec3"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 3,
"minItems": 3,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "vec4"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 4,
"minItems": 4,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "mat3"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 9,
"minItems": 9,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "mat4"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"default": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 16,
"minItems": 16,
"type": "array"
}
}
}
}
],
"properties": {
"default": {},
"expression": {
"$ref": "#/$defs/dataExpression"
},
"frequency": {
"enum": [
"generation",
"frame",
"view"
]
},
"id": {
"$ref": "#/$defs/dataId"
},
"onError": {
"const": "useDefault"
},
"space": {
"$ref": "#/$defs/nonEmptyString"
},
"type": {
"enum": [
"bool",
"int",
"uint",
"float",
"vec2",
"vec3",
"vec4",
"mat3",
"mat4"
]
},
"unit": {
"$ref": "#/$defs/nonEmptyString"
}
},
"required": [
"id",
"type",
"frequency",
"default",
"onError",
"expression"
],
"type": "object"
}dataExpression · v5
| 字段 / 分支 | 本对象必需性 | 结构约束 |
|---|---|---|
oneOf[0].literal | required | — |
oneOf[0].type | required | enum=["bool","int","uint","float","vec2","vec3","vec4","mat3","mat4"] |
oneOf[1].ref | required | $ref="#/$defs/dataId" |
oneOf[2].as | required | enum=["bool","int","uint","float"] |
oneOf[2].map | optional here | type="object" |
oneOf[2].option | required | $ref="#/$defs/dataId" |
oneOf[3].input | required | $ref="#/$defs/dataId" |
oneOf[3].version | required | $ref="#/$defs/positiveVersion" |
oneOf[4].material | required | $ref="#/$defs/dataId" |
oneOf[4].materialProperty | required | $ref="#/$defs/dataId" |
oneOf[5].args | required | type="array"; maxItems=16; items=#/$defs/dataExpression |
oneOf[5].call | required | enum=["length","vec3","greaterEqual","cos","float","mat3","safeNormalize","sin","less","equal","vec4","bool","clamp","matrixMultiply","greater","uint","vec2","div","int","notEqual","sub","or","componentMultiply","sqrt","min","abs","lessEqual","mix","and","add","mat4","dot","not","max","mul"] |
oneOf[6].select | required | $ref="#/$defs/dataExpression" |
oneOf[6].whenFalse | required | $ref="#/$defs/dataExpression" |
oneOf[6].whenTrue | required | $ref="#/$defs/dataExpression" |
完整结构规则: #/$defs/dataExpression
{
"oneOf": [
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "bool"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"type": "boolean"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "int"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"maximum": 2147483647,
"minimum": -2147483648,
"type": "integer"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "uint"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"maximum": 4294967295,
"minimum": 0,
"type": "integer"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "float"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "vec2"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 2,
"minItems": 2,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "vec3"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 3,
"minItems": 3,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "vec4"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 4,
"minItems": 4,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "mat3"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 9,
"minItems": 9,
"type": "array"
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "mat4"
}
},
"required": [
"type"
]
},
"then": {
"properties": {
"literal": {
"items": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
},
"maxItems": 16,
"minItems": 16,
"type": "array"
}
}
}
}
],
"properties": {
"literal": {},
"type": {
"enum": [
"bool",
"int",
"uint",
"float",
"vec2",
"vec3",
"vec4",
"mat3",
"mat4"
]
}
},
"required": [
"literal",
"type"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"ref": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"ref"
],
"type": "object"
},
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"as": {
"const": "bool"
}
},
"required": [
"as"
]
},
"then": {
"properties": {
"map": {
"additionalProperties": {
"type": "boolean"
}
}
}
}
},
{
"if": {
"properties": {
"as": {
"const": "int"
}
},
"required": [
"as"
]
},
"then": {
"properties": {
"map": {
"additionalProperties": {
"maximum": 2147483647,
"minimum": -2147483648,
"type": "integer"
}
}
}
}
},
{
"if": {
"properties": {
"as": {
"const": "uint"
}
},
"required": [
"as"
]
},
"then": {
"properties": {
"map": {
"additionalProperties": {
"maximum": 4294967295,
"minimum": 0,
"type": "integer"
}
}
}
}
},
{
"if": {
"properties": {
"as": {
"const": "float"
}
},
"required": [
"as"
]
},
"then": {
"properties": {
"map": {
"additionalProperties": {
"maximum": 3.4028234663852886e+38,
"minimum": -3.4028234663852886e+38,
"type": "number"
}
}
}
}
},
{
"if": {
"properties": {
"as": {
"const": "uint"
}
},
"required": [
"as"
]
},
"then": {
"required": [
"map"
]
}
}
],
"properties": {
"as": {
"enum": [
"bool",
"int",
"uint",
"float"
]
},
"map": {
"maxProperties": 256,
"minProperties": 1,
"type": "object"
},
"option": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"option",
"as"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"input": {
"$ref": "#/$defs/dataId"
},
"version": {
"$ref": "#/$defs/positiveVersion"
}
},
"required": [
"input",
"version"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"material": {
"$ref": "#/$defs/dataId"
},
"materialProperty": {
"$ref": "#/$defs/dataId"
}
},
"required": [
"materialProperty",
"material"
],
"type": "object"
},
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"call": {
"const": "length"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "vec3"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 3,
"minItems": 3
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "greaterEqual"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "cos"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "float"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "mat3"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 9,
"minItems": 9
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "safeNormalize"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "sin"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "less"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "equal"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "vec4"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 4,
"minItems": 4
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "bool"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "clamp"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 3,
"minItems": 3
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "matrixMultiply"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "greater"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "uint"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "vec2"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "div"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "int"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "notEqual"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "sub"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "or"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "componentMultiply"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "sqrt"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "min"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "abs"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "lessEqual"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "mix"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 3,
"minItems": 3
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "and"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "add"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "mat4"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 16,
"minItems": 16
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "dot"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "not"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 1,
"minItems": 1
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "max"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
},
{
"if": {
"properties": {
"call": {
"const": "mul"
}
},
"required": [
"call"
]
},
"then": {
"properties": {
"args": {
"maxItems": 2,
"minItems": 2
}
}
}
}
],
"properties": {
"args": {
"items": {
"$ref": "#/$defs/dataExpression"
},
"maxItems": 16,
"type": "array"
},
"call": {
"enum": [
"length",
"vec3",
"greaterEqual",
"cos",
"float",
"mat3",
"safeNormalize",
"sin",
"less",
"equal",
"vec4",
"bool",
"clamp",
"matrixMultiply",
"greater",
"uint",
"vec2",
"div",
"int",
"notEqual",
"sub",
"or",
"componentMultiply",
"sqrt",
"min",
"abs",
"lessEqual",
"mix",
"and",
"add",
"mat4",
"dot",
"not",
"max",
"mul"
]
}
},
"required": [
"call",
"args"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"select": {
"$ref": "#/$defs/dataExpression"
},
"whenFalse": {
"$ref": "#/$defs/dataExpression"
},
"whenTrue": {
"$ref": "#/$defs/dataExpression"
}
},
"required": [
"select",
"whenTrue",
"whenFalse"
],
"type": "object"
}
]
}dataId · v5
type="string"; maxLength=512; pattern="^[a-z0-9][a-z0-9_.-]*:[a-z0-9][a-z0-9_./-]*$"
完整结构规则: #/$defs/dataId
{
"maxLength": 512,
"pattern": "^[a-z0-9][a-z0-9_.-]*:[a-z0-9][a-z0-9_./-]*$",
"type": "string"
}完整示例
来源与机器记录
字段归属清单 · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·