跳转到正文

Scene ABI 与 Terrain ​

行为与约束 ​

主线 Scene ABI v2 为四类 Terrain 显式声明 route:opaque、alpha_tested、transparent、sorted_translucent。category 的精确 id/version、target/phase 和允许 mode 见 Catalog;每类必须有唯一合法归属。override 指向活动 pack-owned Stage 与兼容 sceneProvider,builtin 物化该类别的内置 recipe,disabled 仅在类别允许时可用,并可能让相应世界内容不可见。

Provider v1/v2 不是 Scene ABI 数字的简单别名;选择完整 id/version 对,并核对其 category、vertexAbi、targetCapability、stateCapability、systemBindings、required/permittedServices。四类不能因为同属 Terrain 而共用任意 provider。包自有 Program 使用 shaderRoot,内置 fallback 保持 BuiltIn source owner;不能复制或重定向文件名来混合两个 owner。

公开 terrain_chunk 顶点是 stream 0 stride 20、stream 1 stride 8,location 0~7 的类型、offset、integerInput、normalized 与 coordinateSpace 见 顶点表。location 3 的 identifier 为整数输入;location 4 是未归一化的 oct 编码三字节,不是 XYZ 法线。符号、语义注释、origin 与矩阵约定必须与实际 shader 一致。

frameTarget 拥有整帧目标,所以天空、模型与后续世界输出仍需考察;声明四条 Terrain 不构成所有场景 renderer 已验证。opaque 深度清理和颜色 load 遵循当前 ABI,内置 fallback 当前只写 RT0,即便 named topology 有多附件。材质/法线教学编码与宿主正式 ABI 分开;覆盖不足的辅助图不能称作完整可见表面 G-buffer。

世界位置单位为 blocks。Engine 行向量矩阵原始数据上传后,GLSL 使用 Projection × View × world,不再次手工转置。OPENGL_POSITION_FIX 调整 clip z;采样深度仍保留 host 的 [0,1],重建时不能再做 2d−1。时序 view 的逻辑/实际投影、辅助 camera 和 VR 边界见 Custom data 的时序说明。

自动生成的 v5 结构 ​

必需性只针对所展示的对象/分支。Schema 没写 default 不表示运行时没有默认值。完整定义保留条件规则;Loader 另行解析 ID、所有权、预算及设备约束。

sceneRoute · v5 ​

字段 / 分支本对象必需性结构约束
idrequired$ref="#/$defs/identifier"
moderequiredenum=["override","builtin","disabled"]
stageoptional here$ref="#/$defs/identifier"
versionrequired$ref="#/$defs/positiveVersion"
完整结构规则: #/$defs/sceneRoute
json
{
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "mode": {
            "const": "override"
          }
        },
        "required": [
          "mode"
        ]
      },
      "then": {
        "required": [
          "stage"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "mode": {
            "enum": [
              "builtin",
              "disabled"
            ]
          }
        }
      },
      "then": {
        "not": {
          "anyOf": [
            {
              "required": [
                "stage"
              ]
            }
          ]
        }
      }
    }
  ],
  "properties": {
    "id": {
      "$ref": "#/$defs/identifier"
    },
    "mode": {
      "enum": [
        "override",
        "builtin",
        "disabled"
      ]
    },
    "stage": {
      "$ref": "#/$defs/identifier"
    },
    "version": {
      "$ref": "#/$defs/positiveVersion"
    }
  },
  "required": [
    "id",
    "version",
    "mode"
  ],
  "type": "object"
}

frameTarget · v5 ​

字段 / 分支本对象必需性结构约束
targetsrequired$ref="#/$defs/targets"
完整结构规则: #/$defs/frameTarget
json
{
  "additionalProperties": false,
  "properties": {
    "targets": {
      "$ref": "#/$defs/targets"
    }
  },
  "required": [
    "targets"
  ],
  "type": "object"
}

完整示例 ​

来源与机器记录 ​

字段归属清单 · Schema v5 · Catalog v2 · Completion v2

schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·

ShaderPackManifestLoader.cs

作者文档 · Manifest v5 / Scene ABI v2