ice3 0.2.1 → 0.2.2

package/dist/index.js

@@ -389,22 +389,41 @@ var ICEIndexedGeometry = class {
 };
 
 // packages/core/dist/material/ICEBasicMaterial.js
+var DEFAULT_ROUGHNESS = 0.85;
 var ICEBasicMaterial = class {
   typeId = "ice3:BasicMaterial";
   color;
   edgeColor;
   shading;
+  map;
+  normalMap;
+  ormMap;
+  metallic;
+  roughness;
+  emissive;
   constructor(options) {
     this.color = options.color;
     this.edgeColor = options.edgeColor;
     this.shading = options.shading;
+    this.map = options.map;
+    this.normalMap = options.normalMap;
+    this.ormMap = options.ormMap;
+    this.metallic = options.metallic ?? 0;
+    this.roughness = options.roughness ?? DEFAULT_ROUGHNESS;
+    this.emissive = options.emissive;
   }
   toJSON() {
     return {
       typeId: this.typeId,
       color: this.color,
       ...this.edgeColor ? { edgeColor: this.edgeColor } : {},
-      ...this.shading ? { shading: this.shading } : {}
+      ...this.shading ? { shading: this.shading } : {},
+      ...this.map ? { map: this.map } : {},
+      ...this.normalMap ? { normalMap: this.normalMap } : {},
+      ...this.ormMap ? { ormMap: this.ormMap } : {},
+      ...this.metallic !== 0 ? { metallic: this.metallic } : {},
+      ...this.roughness !== DEFAULT_ROUGHNESS ? { roughness: this.roughness } : {},
+      ...this.emissive ? { emissive: this.emissive } : {}
     };
   }
 };
@@ -450,10 +469,17 @@ var ICEPerspectiveCamera = class {
   getTarget() {
     return this.lookTarget;
   }
+  /**
+   * 投影矩阵。屏幕空间效果要从深度重建视空间坐标，光有 viewProjection 不够。
+   */
+  getProjectionMatrix(aspect) {
+    return new ICEMatrix4().perspective(this.fov, aspect, this.near, this.far);
+  }
+  getViewMatrix() {
+    return new ICEMatrix4().lookAt(this.eye, this.lookTarget, new ICEVector3(0, 1, 0));
+  }
   getViewProjectionMatrix(aspect) {
-    const projection = new ICEMatrix4().perspective(this.fov, aspect, this.near, this.far);
-    const view = new ICEMatrix4().lookAt(this.eye, this.lookTarget, new ICEVector3(0, 1, 0));
-    return projection.multiply(view);
+    return this.getProjectionMatrix(aspect).multiply(this.getViewMatrix());
   }
 };
 
@@ -972,6 +998,7 @@ void main() {
 var FRAGMENT_SOURCE = `#version 300 es
 precision highp float;
 uniform vec4 u_color;
+uniform vec4 u_clipPlane;
 uniform float u_pickMode;
 uniform float u_useVertexColor;
 uniform float u_useDirectionalShading;
@@ -980,11 +1007,47 @@ uniform vec3 u_cameraPosition;
 uniform sampler2D u_shadowMap;
 uniform mat4 u_lightViewProjection;
 uniform float u_shadowEnabled;
+uniform float u_shadowNormalOffset;
+uniform float u_shadowDebug;
+uniform sampler2D u_baseColorMap;
+uniform float u_useBaseColorMap;
+uniform vec2 u_uvScale;
+uniform sampler2D u_normalMap;
+uniform float u_useNormalMap;
+uniform sampler2D u_ormMap;
+uniform float u_useOrmMap;
+uniform float u_ormOcclusion;
+uniform float u_ormMetallicRoughness;
+uniform float u_normalScale;
+uniform float u_metallic;
+uniform float u_roughness;
+uniform vec3 u_emissive;
+uniform sampler2D u_sceneDepth;
+uniform float u_useSceneDepth;
+uniform mat4 u_projection;
+uniform vec2 u_viewport;
+uniform vec2 u_clipRange;
+uniform float u_aoRadius;
+uniform float u_aoStrength;
 in vec3 v_color;
 in vec3 v_worldPosition;
 out vec4 outputColor;
 
+// \u7531\u5C4F\u5E55 UV \u4E0E\u6DF1\u5EA6\u7F13\u51B2\u91CD\u5EFA\u89C6\u7A7A\u95F4\u5750\u6807\uFF08\u4E0E WebGL2DepthMath \u7684\u6362\u7B97\u4E00\u81F4\uFF09\u3002
+vec3 viewPositionAt(vec2 uv, float tanHalfFov, float aspect, float near, float far) {
+  float depth = texture(u_sceneDepth, uv).r;
+  float ndcZ = depth * 2.0 - 1.0;
+  float linear = (2.0 * near * far) / (far + near - ndcZ * (far - near));
+  vec2 ndc = uv * 2.0 - 1.0;
+  return vec3(ndc.x * tanHalfFov * aspect * linear, ndc.y * tanHalfFov * linear, -linear);
+}
+
 void main() {
+  // Section plane: discard the half-space on the negative side. A zero plane
+  // (0,0,0,0) evaluates to 0 and keeps everything, so it doubles as "off".
+  if (dot(v_worldPosition, u_clipPlane.xyz) + u_clipPlane.w < 0.0) {
+    discard;
+  }
   if (u_pickMode > 0.5) {
     outputColor = u_color;
     return;
@@ -995,19 +1058,74 @@ void main() {
     dFdx(v_worldPosition),
     dFdy(v_worldPosition)
   ));
+  // Box-projected UVs make the tangent frame analytic: the projection plane's
+  // two world axes are the tangents, so no vertex tangent channel is needed.
+  vec3 tangent = vec3(0.0);
+  vec3 bitangent = vec3(0.0);
+  vec3 axisWeight = abs(normal);
+  if (axisWeight.x >= axisWeight.y && axisWeight.x >= axisWeight.z) {
+    tangent = vec3(0.0, 0.0, -sign(normal.x));
+    bitangent = vec3(0.0, 1.0, 0.0);
+  } else if (axisWeight.y >= axisWeight.z) {
+    tangent = vec3(1.0, 0.0, 0.0);
+    bitangent = vec3(0.0, 0.0, sign(normal.y));
+  } else {
+    tangent = vec3(sign(normal.z), 0.0, 0.0);
+    bitangent = vec3(0.0, 1.0, 0.0);
+  }
+  // \u4E09\u5F20\u8D34\u56FE\u5171\u7528\u540C\u4E00\u5957\u76D2\u6295\u5F71 UV\uFF1A\u6CD5\u7EBF\u4E3B\u5BFC\u8F74\u51B3\u5B9A\u6295\u5F71\u5E73\u9762\uFF0C\u5355\u4F4D\u662F\u7C73\u3002
+  // \u5199\u4E00\u6B21\u5C31\u591F\u4E86\u2014\u2014\u5E95\u56FE\u3001\u6CD5\u7EBF\u56FE\u3001ORM \u5404\u5199\u4E00\u904D\u8FDF\u65E9\u4F1A\u6F02\u3002
+  vec2 surfaceUv;
+  if (axisWeight.x >= axisWeight.y && axisWeight.x >= axisWeight.z) {
+    surfaceUv = vec2(-sign(normal.x) * v_worldPosition.z, v_worldPosition.y);
+  } else if (axisWeight.y >= axisWeight.z) {
+    surfaceUv = vec2(v_worldPosition.x, sign(normal.y) * v_worldPosition.z);
+  } else {
+    surfaceUv = vec2(sign(normal.z) * v_worldPosition.x, v_worldPosition.y);
+  }
+  surfaceUv *= u_uvScale;
+  if (u_useNormalMap > 0.5) {
+    vec3 sampled = texture(u_normalMap, surfaceUv).xyz * 2.0 - 1.0;
+    sampled.xy *= u_normalScale;
+    normal = normalize(
+      normalize(tangent) * sampled.x
+      + normalize(bitangent) * sampled.y
+      + normal * sampled.z
+    );
+  }
   // \u4E3B\u5149 + \u534A\u7403\u5929\u5149\u3002\u6CD5\u7EBF\u7531\u5C4F\u5E55\u7A7A\u95F4\u5BFC\u6570\u6C42\u51FA\uFF0C\u671D\u5411\u4E0E\u7ED5\u5E8F\u4E00\u81F4\uFF1A
   // \u8FCE\u7740\u5149\u7684\u4E00\u9762\u5403\u6EE1\u76F4\u5C04\uFF0C\u80CC\u5149\u9762\u53EA\u7559 35% \u7684\u53CD\u5F39\u5149\uFF0C\u6697\u90E8\u4E0D\u81F3\u4E8E\u7CCA\u6210\u4E00\u7247\u3002
   vec3 lightDirection = normalize(vec3(${LIGHT_DIRECTION.join(", ")}));
   float ndl = dot(normal, lightDirection);
   float key = max(ndl, 0.0) + 0.35 * max(-ndl, 0.0);
   float sky = 0.5 + 0.5 * normal.y;
+  // ORM\uFF1AR \u906E\u853D\u3001G \u7C97\u7CD9\u5EA6\u3001B \u91D1\u5C5E\u5EA6\uFF0C\u548C glTF \u7684\u6253\u5305\u7EA6\u5B9A\u4E00\u81F4\u3002
+  // \u906E\u853D\u53EA\u538B\u95F4\u63A5\u5149\uFF08\u73AF\u5883\u4E0E\u5929\u5149\uFF09\uFF0C\u76F4\u5C04\u7167\u5EA6\u4E0D\u53D7\u5F71\u54CD\u2014\u2014\u5426\u5219\u9634\u5F71\u548C\u8D34\u56FE\u4F1A\u4E92\u76F8\u6253\u67B6\u3002
+  float surfaceOcclusion = 1.0;
+  float surfaceMetallic = u_metallic;
+  float surfaceRoughness = clamp(u_roughness, 0.04, 1.0);
+  if (u_useOrmMap > 0.5) {
+    vec3 orm = texture(u_ormMap, surfaceUv).rgb;
+    if (u_ormOcclusion > 0.5) surfaceOcclusion = clamp(orm.r, 0.0, 1.0);
+    if (u_ormMetallicRoughness > 0.5) {
+      surfaceRoughness = clamp(surfaceRoughness * orm.g, 0.04, 1.0);
+      surfaceMetallic = clamp(surfaceMetallic * orm.b, 0.0, 1.0);
+    }
+  }
   // \u76F4\u5C04\u5149\u5F3A\u5EA6\u6309\u771F\u5B9E\u65E5\u7167\u7ED9\uFF1A\u671D\u4E0A\u7684\u9762\u4F1A\u8D85\u8FC7 1\uFF0C\u8FC7\u66DD\u5230\u63A5\u8FD1\u767D\u8272\u662F\u5BF9\u7684\uFF0C
   // \u4E4B\u524D\u4E0A\u9650\u538B\u5230 1 \u9644\u8FD1\uFF0C\u6574\u4E2A\u5382\u533A\u5C31\u6C38\u8FDC\u6652\u4E0D\u5230\u592A\u9633\uFF0C\u770B\u7740\u53D1\u95F7\u53D1\u6697\u3002
   float shade = clamp(
-    ${LIGHTING.ambient} + ${LIGHTING.direct} * key + ${LIGHTING.sky} * sky,
+    (${LIGHTING.ambient} + ${LIGHTING.sky} * sky) * surfaceOcclusion
+      + ${LIGHTING.direct} * key,
     ${LIGHTING.minimum},
     ${LIGHTING.maximum}
   );
+  // Base-colour texture. There is no UV vertex channel: the projection is
+  // derived from the surface normal's dominant axis, in metres, which matches
+  // the coordinates Studio writes into exported glTF.
+  if (u_useBaseColorMap > 0.5) {
+    color *= texture(u_baseColorMap, surfaceUv).rgb;
+  }
   vec3 lit = color * mix(1.0, shade, u_useDirectionalShading);
 
   // \u8868\u9762\u9897\u7C92\uFF1A\u6309\u4E16\u754C\u5750\u6807\u53D6\u4E24\u5C42\u54C8\u5E0C\uFF0C\u6253\u6563\u6574\u7247\u7EAF\u8272\u5E26\u6765\u7684\u5851\u6599\u611F\u3002
@@ -1052,20 +1170,108 @@ void main() {
       + vec3(0.42, 0.52, 0.54) * sparkle * 0.55;
   }
 
+  // \u5C4F\u5E55\u7A7A\u95F4\u906E\u853D\uFF1A\u5148\u628A\u6DF1\u5EA6\u8FD8\u539F\u6210\u89C6\u7A7A\u95F4\u5750\u6807\uFF0C\u518D\u6309**\u4E16\u754C\u534A\u5F84**\u53D6\u6837\u3002
+  // \u76F4\u63A5\u6BD4\u8F83 NDC \u6DF1\u5EA6\u5DEE\u8868\u8FBE\u4E0D\u4E86"1 \u7C73"\u8FD9\u79CD\u91CF\uFF08\u8FDC\u7AEF\u5343\u5206\u4E4B\u51E0\u5C31\u8DE8\u4E86\u5341\u7C73\uFF09\uFF0C
+  // \u8FD9\u4E5F\u662F SPEC-007 \u524D\u4E09\u8F6E\u5931\u8D25\u7684\u539F\u56E0\u3002
+  if (u_useSceneDepth > 0.5) {
+    vec2 screenUv = gl_FragCoord.xy / u_viewport;
+    float tanHalfFov = 1.0 / u_projection[1][1];
+    float aspect = u_projection[1][1] / u_projection[0][0];
+    float near = u_clipRange.x;
+    float far = u_clipRange.y;
+
+    vec3 centre = viewPositionAt(screenUv, tanHalfFov, aspect, near, far);
+    // \u6CD5\u7EBF\u7531\u89C6\u7A7A\u95F4\u4F4D\u7F6E\u7684\u5C4F\u5E55\u5BFC\u6570\u6C42\u51FA\uFF1A\u51E0\u4F55\u6CA1\u6709\u6CD5\u7EBF\u5C5E\u6027\uFF0C\u4E5F\u4E0D\u9700\u8981\u3002
+    vec3 viewNormal = normalize(cross(dFdx(centre), dFdy(centre)));
+    float centreDepth = -centre.z;
+
+    // \u4E16\u754C\u534A\u5F84\u6362\u7B97\u6210\u50CF\u7D20\u534A\u5F84\uFF1A\u8D8A\u8FDC\u8D8A\u5C0F\uFF0C\u8FD1\u666F\u8FDC\u666F\u624D\u90FD\u6709\u610F\u4E49\u3002
+    float pixelRadius = (u_aoRadius / max(1e-4, centreDepth * tanHalfFov)) * (u_viewport.y * 0.5);
+    // \u4EA4\u9519\u68AF\u5EA6\u566A\u58F0\uFF08IGN\uFF09\u4EE3\u66FF sin \u54C8\u5E0C\uFF1A\u540C\u6837\u662F\u9010\u50CF\u7D20\u6270\u52A8\uFF0C\u4F46\u5B83\u5728\u76F8\u90BB\u50CF\u7D20\u95F4\u662F
+    // \u6E10\u53D8\u800C\u975E\u8DF3\u53D8\uFF0C\u91C7\u6837\u7F3A\u53E3\u770B\u8D77\u6765\u50CF\u7EC6\u5BC6\u6296\u52A8\uFF0C\u4E0D\u50CF\u6912\u76D0\u566A\u70B9\u3002
+    float rotation = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715)))) * 6.2831853;
+
+    // \u4E09\u5708\u53D6\u6837\uFF1A0.35 / 0.65 / 1.0 \u500D\u534A\u5F84\uFF0C\u6743\u91CD 1.0 / 0.7 / 0.45\uFF0C\u5206\u522B\u8D1F\u8D23
+    // \u8D34\u5730\u63A5\u89E6\u3001\u7F1D\u9699\u4E2D\u90E8\u3001\u5927\u9762\u79EF\u5939\u89D2\u3002\u6837\u672C\u6309\u4E0E\u6CD5\u7EBF\u7684\u5939\u89D2\u52A0\u6743\u2014\u2014\u6B63\u5BF9\u7740\u7684\u5E73\u9762
+    // \u4E0D\u8BE5\u88AB\u5468\u56F4\u540C\u6837\u5E73\u7684\u4E1C\u897F\u538B\u6697\uFF0C\u53EA\u6709"\u7ACB\u8D77\u6765\u6321\u4F4F\u6211"\u7684\u624D\u7B97\u6CD5\u3002
+    float occlusion = 0.0;
+    float weightSum = 0.0;
+    for (int ring = 0; ring < 3; ring++) {
+      // \u4E09\u5708\uFF1A\u8D34\u5730\u63A5\u89E6 / \u7F1D\u9699\u4E2D\u90E8 / \u5927\u9762\u79EF\u5939\u89D2\u3002\u6CA1\u6709\u6A21\u7CCA\u901A\u9053\u65F6\uFF0C\u9760\u5708\u5C42\u5206\u644A
+      // \u91C7\u6837\u5BC6\u5EA6\u662F\u538B\u566A\u70B9\u6700\u76F4\u63A5\u7684\u529E\u6CD5\uFF08\u6A21\u7CCA\u8981\u989D\u5916\u7684 FBO \u4E0E\u5168\u5C4F\u901A\u9053\uFF09\u3002
+      float ringScale = ring == 0 ? 0.35 : (ring == 1 ? 0.65 : 1.0);
+      float ringWeight = ring == 0 ? 1.0 : (ring == 1 ? 0.7 : 0.45);
+      for (int i = 0; i < 8; i++) {
+        float angle = rotation + float(i) * 0.7853982 + float(ring) * 0.2618;
+        vec2 offset = vec2(cos(angle), sin(angle)) * pixelRadius * ringScale;
+        vec2 sampleUv = screenUv + offset / u_viewport;
+        if (sampleUv.x < 0.0 || sampleUv.x > 1.0 || sampleUv.y < 0.0 || sampleUv.y > 1.0) continue;
+        vec3 delta = viewPositionAt(sampleUv, tanHalfFov, aspect, near, far) - centre;
+        float distance = length(delta);
+        if (distance < 0.0001 || distance > u_aoRadius) continue;
+        float alignment = dot(delta, viewNormal) / distance;
+        if (alignment <= 0.15) continue;
+        occlusion += ringWeight * alignment;
+        weightSum += ringWeight;
+      }
+    }
+    if (weightSum > 0.0) {
+      occlusion /= weightSum;
+      lit *= 1.0 - clamp(occlusion, 0.0, 1.0) * u_aoStrength;
+    }
+  }
+
+  // \u91D1\u5C5E\u6CA1\u6709\u6F2B\u53CD\u5C04\uFF1A\u5B83\u7684\u989C\u8272\u5168\u90E8\u6765\u81EA\u53CD\u5C04\u3002\u5148\u628A\u6F2B\u53CD\u5C04\u6309 metallic \u6536\u6389\uFF0C
+  // \u518D\u7528\u53CD\u5C04\u9879\u8865\u56DE\u6765\uFF0C\u5426\u5219\u91D1\u5C5E\u548C\u5851\u6599\u5728\u540C\u4E00\u4E2A\u592A\u9633\u4E0B\u53EA\u662F"\u989C\u8272\u4E0D\u540C"\u3002
+  {
+    vec3 viewDirection = normalize(u_cameraPosition - v_worldPosition);
+    vec3 halfVector = normalize(lightDirection + viewDirection);
+    float metallic = clamp(surfaceMetallic, 0.0, 1.0);
+    float roughness = clamp(surfaceRoughness, 0.04, 1.0);
+    vec3 reflectance = mix(vec3(0.04), color, metallic);
+
+    float diffuseGain = 1.0 - metallic * 0.85;
+    float facing = max(dot(normal, lightDirection), 0.0);
+
+    // \u9AD8\u5149\uFF1A\u7C97\u7CD9\u5EA6\u51B3\u5B9A\u53F6\u74E3\u5BBD\u5EA6\u4E0E\u5F3A\u5EA6\uFF08\u6307\u6570 96 \u2192 4\uFF0C\u589E\u76CA 1.0 \u2192 0.18\uFF09\u3002
+    float shininess = mix(96.0, 4.0, roughness * roughness);
+    float highlight = pow(max(dot(normal, halfVector), 0.0), shininess);
+    float specularGain = mix(1.0, 0.18, roughness);
+
+    // \u73AF\u5883\u53CD\u5C04\uFF1A\u6309\u53CD\u5C04\u65B9\u5411\u53D6\u5929\u7A7A/\u5730\u9762\u8272\uFF0C\u63A0\u5C04\u89D2\u518D\u53E0\u4E00\u5C42 Fresnel\u3002
+    // \u53EA\u770B\u6CD5\u7EBF\u7684\u8BDD\uFF0C\u5E73\u8EBA\u7684\u91D1\u5C5E\u4F1A\u548C\u7ACB\u7740\u7684\u91D1\u5C5E\u4E00\u4E2A\u989C\u8272\u2014\u2014\u73B0\u5B9E\u91CC\u524D\u8005\u53CD\u5C04\u5929\u9876\u3001
+    // \u540E\u8005\u53CD\u5C04\u5730\u5E73\u7EBF\uFF0C\u6070\u6070\u662F\u91D1\u5C5E\u6700\u5BB9\u6613\u8FA8\u8BA4\u7684\u7279\u5F81\u3002
+    vec3 reflected = reflect(-viewDirection, normal);
+    float skyMix = clamp(reflected.y * 0.9 + 0.35, 0.0, 1.0);
+    vec3 skyColor = mix(vec3(0.15, 0.16, 0.17), vec3(0.62, 0.72, 0.84), skyMix);
+    float fresnel = pow(1.0 - clamp(dot(normal, viewDirection), 0.0, 1.0), 4.0);
+    float envGain = (0.22 + 0.55 * fresnel) * mix(0.4, 1.0, metallic);
+
+    float litScale = diffuseGain;
+    lit *= litScale;
+    lit += reflectance * (highlight * specularGain * mix(0.35, 1.0, facing)
+      + skyColor * envGain);
+    lit += u_emissive;
+  }
+
   // \u9634\u5F71\uFF1A\u628A\u4E16\u754C\u5750\u6807\u6295\u5230\u5149\u6E90\u7A7A\u95F4\uFF0C\u4E0E\u6DF1\u5EA6\u56FE\u6BD4\u8F83\u3002\u53D6 3\xD73 \u91C7\u6837\u7684\u5E73\u5747\u505A\u8F7B\u5FAE\u67D4\u5316\u3002
+  // shadowLit \u5728\u8C03\u8BD5\u901A\u9053\u91CC\u76F4\u63A5\u8F93\u51FA\uFF1A1 = \u53D7\u5149\uFF0C0 = \u88AB\u906E\u3002
+  float shadowLit = 1.0;
   if (u_shadowEnabled > 0.5) {
-    vec4 lightSpace = u_lightViewProjection * vec4(v_worldPosition, 1.0);
+    // \u91C7\u6837\u70B9\u6CBF\u6CD5\u7EBF\u63A8\u51FA 1.5 \u4E2A\u7EB9\u7D20\uFF1A\u5E73\u8EBA\u5728\u5149\u91CC\u7684\u9762\uFF08\u5C4B\u9876\u3001\u5730\u9762\uFF09\u5728\u6BCF\u4E2A\u7EB9\u7D20\u5185
+    // \u672C\u8EAB\u5C31\u6709\u6DF1\u5EA6\u5DEE\uFF0C\u9760\u6DF1\u5EA6\u504F\u5DEE\u53BB\u8FFD\u8FD9\u4E2A\u5DEE\u53EA\u4F1A\u8BA9\u5F71\u5B50\u8131\u79BB\u7269\u4F53\uFF08peter-panning\uFF09\u3002
+    // \u628A\u6BD4\u8F83\u70B9\u62AC\u79BB\u8868\u9762\u624D\u662F\u6B63\u89E3\uFF0C\u504F\u79FB\u91CF\u6309\u7EB9\u7D20\u6362\u7B97\uFF0C\u548C\u8D34\u56FE\u5206\u8FA8\u7387\u89E3\u8026\u3002
+    vec3 shadowPosition = v_worldPosition + normal * u_shadowNormalOffset;
+    vec4 lightSpace = u_lightViewProjection * vec4(shadowPosition, 1.0);
     vec3 projected = lightSpace.xyz / max(lightSpace.w, 1e-5) * 0.5 + 0.5;
     if (projected.x > 0.002 && projected.x < 0.998
         && projected.y > 0.002 && projected.y < 0.998
         && projected.z > 0.0 && projected.z < 1.0) {
-      // \u659C\u9762\u5BF9\u6DF1\u5EA6\u7684\u8BEF\u5DEE\u6700\u654F\u611F\uFF0C\u6309 N\xB7L \u653E\u5927\u504F\u79FB\uFF1A
-      // \u56FA\u5B9A\u5C0F\u504F\u79FB\u5728\u8FD9\u5957 960 \u7C73\u6DF1\u7684\u5149\u9525\u91CC\u7B49\u4E8E\u51E0\u7C73\uFF0C\u5899\u9762\u4F1A\u81EA\u5DF1\u628A\u81EA\u5DF1\u906E\u4F4F\uFF08\u9634\u5F71\u75E4\u75AE\uFF09\u3002
+      // \u89C6\u9525\u8D34\u5408\u573A\u666F\u540E\u6DF1\u5EA6\u8DE8\u5EA6\u53EA\u6709\u767E\u7C73\u91CF\u7EA7\uFF0C\u504F\u5DEE\u4E5F\u5C31\u53EF\u4EE5\u6309\u7EB9\u7406\u5355\u5143\u7ED9\u3002
+      // \u9634\u5F71 pass \u53EA\u753B\u80CC\u9762\uFF08cull FRONT\uFF09\uFF0C\u53D7\u5149\u9762\u548C\u6DF1\u5EA6\u56FE\u5929\u7136\u9519\u5F00\uFF0C\u57FA\u6570\u53EF\u4EE5\u5F88\u5C0F\uFF1B
+      // \u659C\u9762\u6700\u654F\u611F\uFF0C\u4ECD\u6309 N\xB7L \u653E\u5927\uFF08\u9634\u5F71\u75E4\u75AE\u4E0E\u9634\u5F71\u8131\u79BB\u4E4B\u95F4\u7684\u90A3\u6761\u7A84\u7F1D\uFF09\u3002
       float ndlShadow = max(dot(normal, lightDirection), 0.0);
-      // \u504F\u79FB\u6309\u5149\u9525\u6DF1\u5EA6\uFF08\u8FD1 -260 / \u8FDC 700\uFF0C\u5171 960 \u7C73\uFF09\u6362\u7B97\uFF1A
-      // 0.006 \u5BF9\u5E94\u7EA6 5.8 \u7C73\uFF0C\u6B63\u597D\u538B\u6389\u6DF1\u5EA6\u56FE\u4E0E\u9010\u50CF\u7D20\u6295\u5F71\u4E4B\u95F4\u7684\u7CFB\u7EDF\u8BEF\u5DEE\uFF0C
-      // \u540C\u65F6\u8FD8\u80FD\u7559\u4F4F\u5341\u51E0\u7C73\u9AD8\u6784\u7B51\u7269\u7684\u6295\u5F71\u3002
-      float bias = 0.0015 + 0.0025 * (1.0 - ndlShadow);
+      float bias = 0.0006 + 0.0012 * (1.0 - ndlShadow);
       float lit2 = 0.0;
       vec2 texel = vec2(1.0 / 2048.0);
       for (int dx = -1; dx <= 1; dx++) {
@@ -1074,10 +1280,21 @@ void main() {
           lit2 += projected.z - bias > depth ? 0.0 : 1.0;
         }
       }
-      lit *= mix(0.68, 1.0, lit2 / 9.0);
+      shadowLit = lit2 / 9.0;
+      lit *= mix(0.68, 1.0, shadowLit);
 
     }
   }
+  // \u8C03\u8BD5\u901A\u9053\uFF1A?shadowdebug=1 \u770B\u906E\u853D\u5224\u5B9A\uFF0C=2 \u770B\u6DF1\u5EA6\u56FE\u672C\u8EAB\u3002
+  if (u_shadowDebug > 0.5) {
+    if (u_shadowDebug < 1.5) {
+      outputColor = vec4(shadowLit, 0.12, 0.12, 1.0);
+    } else {
+      float stored = texture(u_shadowMap, gl_FragCoord.xy / u_viewport).r;
+      outputColor = vec4(vec3(stored), 1.0);
+    }
+    return;
+  }
   // \u753B\u5E03\u6309 sRGB \u89E3\u91CA\u5199\u5165\u503C\uFF0C\u800C\u6750\u8D28\u662F\u7EBF\u6027\u7A7A\u95F4\u7684\u5206\u91CF\uFF0C\u5FC5\u987B\u505A\u4E00\u6B21\u7F16\u7801\u3002
   // \u4E0D\u505A\u7684\u8BDD\u7EBF\u6027 0.017 \u4F1A\u5F53\u4F5C sRGB 0.017 \u663E\u793A\uFF0C\u6DF1\u8272\u6750\u8D28\u5168\u90E8\u584C\u6210\u9ED1\u8272\u3002
   outputColor = vec4(
@@ -1103,8 +1320,31 @@ var WebGL2Program = class _WebGL2Program {
   shadowMapLocation;
   lightMatrixLocation;
   shadowEnabledLocation;
+  shadowNormalOffsetLocation;
+  shadowDebugLocation;
   instancingLocation;
   pickModeLocation;
+  clipPlaneLocation;
+  baseColorMapLocation;
+  useBaseColorMapLocation;
+  uvScaleLocation;
+  normalMapLocation;
+  ormMapLocation;
+  useOrmMapLocation;
+  ormOcclusionLocation;
+  ormMetallicRoughnessLocation;
+  useNormalMapLocation;
+  normalScaleLocation;
+  metallicLocation;
+  roughnessLocation;
+  emissiveLocation;
+  sceneDepthLocation;
+  useSceneDepthLocation;
+  projectionLocation;
+  viewportLocation;
+  clipRangeLocation;
+  aoRadiusLocation;
+  aoStrengthLocation;
   constructor(gl) {
     this.gl = gl;
     const program = this.createProgram(VERTEX_SOURCE, FRAGMENT_SOURCE);
@@ -1117,9 +1357,32 @@ var WebGL2Program = class _WebGL2Program {
     const cameraPositionLocation = gl.getUniformLocation(program, "u_cameraPosition");
     const instancingLocation = gl.getUniformLocation(program, "u_useInstancing");
     const pickModeLocation = gl.getUniformLocation(program, "u_pickMode");
+    const clipPlaneLocation = gl.getUniformLocation(program, "u_clipPlane");
+    const baseColorMapLocation = gl.getUniformLocation(program, "u_baseColorMap");
+    const useBaseColorMapLocation = gl.getUniformLocation(program, "u_useBaseColorMap");
+    const uvScaleLocation = gl.getUniformLocation(program, "u_uvScale");
+    const normalMapLocation = gl.getUniformLocation(program, "u_normalMap");
+    const ormMapLocation = gl.getUniformLocation(program, "u_ormMap");
+    const useOrmMapLocation = gl.getUniformLocation(program, "u_useOrmMap");
+    const ormOcclusionLocation = gl.getUniformLocation(program, "u_ormOcclusion");
+    const ormMetallicRoughnessLocation = gl.getUniformLocation(program, "u_ormMetallicRoughness");
+    const useNormalMapLocation = gl.getUniformLocation(program, "u_useNormalMap");
+    const normalScaleLocation = gl.getUniformLocation(program, "u_normalScale");
+    const metallicLocation = gl.getUniformLocation(program, "u_metallic");
+    const roughnessLocation = gl.getUniformLocation(program, "u_roughness");
+    const emissiveLocation = gl.getUniformLocation(program, "u_emissive");
+    const sceneDepthLocation = gl.getUniformLocation(program, "u_sceneDepth");
+    const useSceneDepthLocation = gl.getUniformLocation(program, "u_useSceneDepth");
+    const projectionLocation = gl.getUniformLocation(program, "u_projection");
+    const viewportLocation = gl.getUniformLocation(program, "u_viewport");
+    const clipRangeLocation = gl.getUniformLocation(program, "u_clipRange");
+    const aoRadiusLocation = gl.getUniformLocation(program, "u_aoRadius");
+    const aoStrengthLocation = gl.getUniformLocation(program, "u_aoStrength");
     const shadowMapLocation = gl.getUniformLocation(program, "u_shadowMap");
     const lightMatrixLocation = gl.getUniformLocation(program, "u_lightViewProjection");
     const shadowEnabledLocation = gl.getUniformLocation(program, "u_shadowEnabled");
+    const shadowNormalOffsetLocation = gl.getUniformLocation(program, "u_shadowNormalOffset");
+    const shadowDebugLocation = gl.getUniformLocation(program, "u_shadowDebug");
     if (!matrixLocation || !colorLocation || !clipOffsetLocation || !vertexColorLocation || !directionalShadingLocation || !waterShadingLocation || !cameraPositionLocation || !instancingLocation || !pickModeLocation) {
       gl.deleteProgram(program);
       throw new ICEEngineError("ICE3_SHADER_LINK_FAILED", "ICE3_SHADER_LINK_FAILED: shader uniforms are missing");
@@ -1135,11 +1398,71 @@ var WebGL2Program = class _WebGL2Program {
     this.shadowMapLocation = shadowMapLocation;
     this.lightMatrixLocation = lightMatrixLocation;
     this.shadowEnabledLocation = shadowEnabledLocation;
-    this.shadowMapLocation = shadowMapLocation;
-    this.lightMatrixLocation = lightMatrixLocation;
-    this.shadowEnabledLocation = shadowEnabledLocation;
+    this.shadowNormalOffsetLocation = shadowNormalOffsetLocation;
+    this.shadowDebugLocation = shadowDebugLocation;
     this.instancingLocation = instancingLocation;
     this.pickModeLocation = pickModeLocation;
+    this.clipPlaneLocation = clipPlaneLocation;
+    this.baseColorMapLocation = baseColorMapLocation;
+    this.useBaseColorMapLocation = useBaseColorMapLocation;
+    this.uvScaleLocation = uvScaleLocation;
+    this.normalMapLocation = normalMapLocation;
+    this.ormMapLocation = ormMapLocation;
+    this.useOrmMapLocation = useOrmMapLocation;
+    this.ormOcclusionLocation = ormOcclusionLocation;
+    this.ormMetallicRoughnessLocation = ormMetallicRoughnessLocation;
+    this.useNormalMapLocation = useNormalMapLocation;
+    this.normalScaleLocation = normalScaleLocation;
+    this.metallicLocation = metallicLocation;
+    this.roughnessLocation = roughnessLocation;
+    this.emissiveLocation = emissiveLocation;
+    this.sceneDepthLocation = sceneDepthLocation;
+    this.useSceneDepthLocation = useSceneDepthLocation;
+    this.projectionLocation = projectionLocation;
+    this.viewportLocation = viewportLocation;
+    this.clipRangeLocation = clipRangeLocation;
+    this.aoRadiusLocation = aoRadiusLocation;
+    this.aoStrengthLocation = aoStrengthLocation;
+    if (sceneDepthLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(sceneDepthLocation, 2);
+    }
+    if (useSceneDepthLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(useSceneDepthLocation, 0);
+    }
+    if (aoRadiusLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(aoRadiusLocation, 2.5);
+    }
+    if (emissiveLocation) {
+      gl.useProgram(program);
+      gl.uniform3f(emissiveLocation, 0, 0, 0);
+    }
+    if (normalMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(normalMapLocation, 1);
+    }
+    if (ormMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(ormMapLocation, 4);
+    }
+    if (useNormalMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(useNormalMapLocation, 0);
+    }
+    if (baseColorMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(baseColorMapLocation, 0);
+    }
+    if (useBaseColorMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(useBaseColorMapLocation, 0);
+    }
+    if (clipPlaneLocation) {
+      gl.useProgram(program);
+      gl.uniform4f(clipPlaneLocation, 0, 0, 0, 0);
+    }
     if (shadowMapLocation) {
       gl.useProgram(program);
       gl.uniform1i(shadowMapLocation, 3);
@@ -1154,14 +1477,120 @@ var WebGL2Program = class _WebGL2Program {
   setColor(color) {
     this.gl.uniform4f(this.colorLocation, ...color);
   }
+  /**
+   * Bind a base-colour texture to unit 0 and enable sampling. Passing `null`
+   * restores flat shading without touching the bound texture.
+   */
+  setBaseColorMap(texture, scale) {
+    const gl = this.gl;
+    if (!this.useBaseColorMapLocation)
+      return;
+    if (!texture) {
+      gl.uniform1f(this.useBaseColorMapLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useBaseColorMapLocation, 1);
+    if (this.uvScaleLocation) {
+      gl.uniform2f(this.uvScaleLocation, scale[0], scale[1]);
+    }
+  }
+  /** Bind a tangent-space normal map to unit 1; `null` disables perturbation. */
+  setNormalMap(texture, strength) {
+    const gl = this.gl;
+    if (!this.useNormalMapLocation)
+      return;
+    if (!texture) {
+      gl.uniform1f(this.useNormalMapLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useNormalMapLocation, 1);
+    if (this.normalScaleLocation) {
+      gl.uniform1f(this.normalScaleLocation, strength);
+    }
+  }
+  /**
+   * Bind the packed ORM map. `occlusion` / `metallicRoughness` describe which
+   * halves of the image are meaningful; both false disables sampling.
+   */
+  setOrmMap(texture, occlusion, metallicRoughness) {
+    const gl = this.gl;
+    if (!this.useOrmMapLocation)
+      return;
+    if (!texture || !occlusion && !metallicRoughness) {
+      gl.uniform1f(this.useOrmMapLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE4);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useOrmMapLocation, 1);
+    if (this.ormOcclusionLocation) {
+      gl.uniform1f(this.ormOcclusionLocation, occlusion ? 1 : 0);
+    }
+    if (this.ormMetallicRoughnessLocation) {
+      gl.uniform1f(this.ormMetallicRoughnessLocation, metallicRoughness ? 1 : 0);
+    }
+  }
+  /** Metallic-roughness factors plus emission for the current draw. */
+  setSurface(metallic, roughness, emissive) {
+    const gl = this.gl;
+    if (this.metallicLocation)
+      gl.uniform1f(this.metallicLocation, metallic);
+    if (this.roughnessLocation)
+      gl.uniform1f(this.roughnessLocation, roughness);
+    if (this.emissiveLocation) {
+      if (emissive)
+        gl.uniform3f(this.emissiveLocation, emissive[0], emissive[1], emissive[2]);
+      else
+        gl.uniform3f(this.emissiveLocation, 0, 0, 0);
+    }
+  }
+  /** 绑定相机深度纹理（unit 2）并传入重建视空间所需的相机参数。 */
+  setSceneDepth(texture, projection, near, far, deviceWidth, deviceHeight) {
+    const gl = this.gl;
+    if (!this.useSceneDepthLocation)
+      return;
+    if (!texture || !projection) {
+      gl.uniform1f(this.useSceneDepthLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE2);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useSceneDepthLocation, 1);
+    if (this.projectionLocation) {
+      gl.uniformMatrix4fv(this.projectionLocation, false, projection.elements);
+    }
+    if (this.viewportLocation) {
+      gl.uniform2f(this.viewportLocation, deviceWidth, deviceHeight);
+    }
+    if (this.clipRangeLocation) {
+      gl.uniform2f(this.clipRangeLocation, near, far);
+    }
+  }
+  /** 遮蔽半径（米）与强度，供运行时调节。强度 0 等于关闭。 */
+  setOcclusion(radius, strength) {
+    const gl = this.gl;
+    if (this.aoRadiusLocation)
+      gl.uniform1f(this.aoRadiusLocation, radius);
+    if (this.aoStrengthLocation)
+      gl.uniform1f(this.aoStrengthLocation, strength);
+  }
   setClipOffset(x, y) {
     this.gl.uniform2f(this.clipOffsetLocation, x, y);
   }
+  setClipPlane(plane) {
+    if (!this.clipPlaneLocation)
+      return;
+    this.gl.uniform4f(this.clipPlaneLocation, plane[0], plane[1], plane[2], plane[3]);
+  }
   setVertexColors(enabled) {
     this.gl.uniform1f(this.vertexColorLocation, enabled ? 1 : 0);
   }
   /** 绑定阴影贴图与光源矩阵；关闭时着色器跳过采样。 */
-  setShadow(enabled, texture, matrix, unit = 3) {
+  setShadow(enabled, texture, matrix, normalOffset = 0, unit = 3) {
     const gl = this.gl;
     gl.uniform1f(this.shadowEnabledLocation, enabled && texture && matrix ? 1 : 0);
     if (!enabled || !texture || !matrix)
@@ -1172,8 +1601,17 @@ var WebGL2Program = class _WebGL2Program {
       gl.uniform1i(this.shadowMapLocation, unit);
     if (this.lightMatrixLocation)
       gl.uniformMatrix4fv(this.lightMatrixLocation, false, matrix);
+    if (this.shadowNormalOffsetLocation) {
+      gl.uniform1f(this.shadowNormalOffsetLocation, normalOffset);
+    }
     gl.activeTexture(gl.TEXTURE0);
   }
+  /** 阴影调试通道：0 关闭，1 输出遮蔽判定，2 输出深度图。 */
+  setShadowDebug(mode) {
+    if (!this.shadowDebugLocation)
+      return;
+    this.gl.uniform1f(this.shadowDebugLocation, mode);
+  }
   setDirectionalShading(enabled) {
     this.gl.uniform1f(this.directionalShadingLocation, enabled ? 1 : 0);
   }
@@ -1275,6 +1713,14 @@ function collectInstanceBatches(renderables, output = []) {
   }
   return output;
 }
+function renderablesOutsideInstanceBatches(renderables, batches) {
+  const batched = /* @__PURE__ */ new Set();
+  for (const batch of batches) {
+    for (const id of batch.meshIds)
+      batched.add(id);
+  }
+  return renderables.filter((renderable) => !batched.has(renderable.id));
+}
 
 // packages/renderer/dist/WebGL2InstanceBatch.js
 var WebGL2InstanceCache = class {
@@ -1319,10 +1765,10 @@ var WebGL2InstanceCache = class {
     gl.bindBuffer(gl.ARRAY_BUFFER, matrixBuffer);
     gl.bufferData(gl.ARRAY_BUFFER, batch.instanceMatrices, gl.DYNAMIC_DRAW);
     for (let column = 0; column < 4; column += 1) {
-      const location = WebGL2Program.INSTANCE_MATRIX_ATTRIBUTE + column;
-      gl.enableVertexAttribArray(location);
-      gl.vertexAttribPointer(location, 4, gl.FLOAT, false, 64, column * 16);
-      gl.vertexAttribDivisor(location, 1);
+      const location2 = WebGL2Program.INSTANCE_MATRIX_ATTRIBUTE + column;
+      gl.enableVertexAttribArray(location2);
+      gl.vertexAttribPointer(location2, 4, gl.FLOAT, false, 64, column * 16);
+      gl.vertexAttribDivisor(location2, 1);
     }
     gl.bindBuffer(gl.ARRAY_BUFFER, semanticBuffer);
     gl.bufferData(gl.ARRAY_BUFFER, batch.semanticIndices, gl.DYNAMIC_DRAW);
@@ -2018,14 +2464,136 @@ var WebGL2Picker = class {
   }
 };
 
+// packages/renderer/dist/WebGL2Shader.js
+function createShaderProgram(gl, vertexSource, fragmentSource, label) {
+  const vertex = compileShader(gl, gl.VERTEX_SHADER, vertexSource, `${label}:vertex`);
+  const fragment = compileShader(gl, gl.FRAGMENT_SHADER, fragmentSource, `${label}:fragment`);
+  const program = gl.createProgram();
+  if (!program) {
+    throw new ICEEngineError("ICE3_SHADER_LINK_FAILED", `ICE3_SHADER_LINK_FAILED: ${label}: program allocation failed`);
+  }
+  gl.attachShader(program, vertex);
+  gl.attachShader(program, fragment);
+  gl.linkProgram(program);
+  gl.deleteShader(vertex);
+  gl.deleteShader(fragment);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    const log = gl.getProgramInfoLog(program) ?? "unknown link error";
+    gl.deleteProgram(program);
+    throw new ICEEngineError("ICE3_SHADER_LINK_FAILED", `ICE3_SHADER_LINK_FAILED: ${label}: ${log}`);
+  }
+  return program;
+}
+function compileShader(gl, type, source, label) {
+  const shader = gl.createShader(type);
+  if (!shader) {
+    throw new ICEEngineError("ICE3_SHADER_COMPILE_FAILED", `ICE3_SHADER_COMPILE_FAILED: ${label}: allocation failed`);
+  }
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(shader) ?? "unknown compile error";
+    gl.deleteShader(shader);
+    throw new ICEEngineError("ICE3_SHADER_COMPILE_FAILED", `ICE3_SHADER_COMPILE_FAILED: ${label}: ${log}`);
+  }
+  return shader;
+}
+
+// packages/renderer/dist/ShadowFrustum.js
+var SHADOW_LIGHT_DIRECTION = [-0.35, 0.85, 0.4];
+var BOUNDS_PADDING = 0.08;
+function shadowFrustum(bounds, mapSize = 2048) {
+  const box = bounds ?? { min: [-50, -5, -50], max: [650, 60, 650] };
+  const centre = [
+    (box.min[0] + box.max[0]) / 2,
+    (box.min[1] + box.max[1]) / 2,
+    (box.min[2] + box.max[2]) / 2
+  ];
+  const radius = Math.max(1, 0.5 * Math.hypot(box.max[0] - box.min[0], box.max[1] - box.min[1], box.max[2] - box.min[2]));
+  const pad = radius * BOUNDS_PADDING;
+  const direction = normalize2(SHADOW_LIGHT_DIRECTION);
+  const distance2 = radius * 2 + pad * 2;
+  const eye = [
+    centre[0] + direction[0] * distance2,
+    centre[1] + direction[1] * distance2,
+    centre[2] + direction[2] * distance2
+  ];
+  const view = new ICEMatrix4().lookAt(new ICEVector3(eye[0], eye[1], eye[2]), new ICEVector3(centre[0], centre[1], centre[2]), new ICEVector3(0, 1, 0));
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  let minZ = Infinity;
+  let maxZ = -Infinity;
+  for (let corner = 0; corner < 8; corner += 1) {
+    const point = new ICEVector3(corner & 1 ? box.max[0] : box.min[0], corner & 2 ? box.max[1] : box.min[1], corner & 4 ? box.max[2] : box.min[2]);
+    const projected = view.transformPoint(point);
+    minX = Math.min(minX, projected[0]);
+    maxX = Math.max(maxX, projected[0]);
+    minY = Math.min(minY, projected[1]);
+    maxY = Math.max(maxY, projected[1]);
+    minZ = Math.min(minZ, projected[2]);
+    maxZ = Math.max(maxZ, projected[2]);
+  }
+  const projection = orthographic(minX - pad, maxX + pad, minY - pad, maxY + pad, -maxZ - pad, -minZ + pad);
+  const width = maxX - minX + pad * 2;
+  const height = maxY - minY + pad * 2;
+  return {
+    matrix: multiply(projection, view.elements),
+    texelWorld: Math.max(width, height) / mapSize
+  };
+}
+function normalize2(value) {
+  const length = Math.hypot(value[0], value[1], value[2]) || 1;
+  return [value[0] / length, value[1] / length, value[2] / length];
+}
+function orthographic(left, right, bottom, top, near, far) {
+  const lr = 1 / (left - right);
+  const bt = 1 / (bottom - top);
+  const nf = 1 / (near - far);
+  return [
+    -2 * lr,
+    0,
+    0,
+    0,
+    0,
+    -2 * bt,
+    0,
+    0,
+    0,
+    0,
+    2 * nf,
+    0,
+    (left + right) * lr,
+    (top + bottom) * bt,
+    (far + near) * nf,
+    1
+  ];
+}
+function multiply(a, b) {
+  const out = new Float32Array(16);
+  for (let column = 0; column < 4; column += 1) {
+    for (let row = 0; row < 4; row += 1) {
+      let sum = 0;
+      for (let k = 0; k < 4; k += 1) {
+        sum += (a[k * 4 + row] ?? 0) * (b[column * 4 + k] ?? 0);
+      }
+      out[column * 4 + row] = sum;
+    }
+  }
+  return out;
+}
+
 // packages/renderer/dist/WebGL2ShadowMap.js
 var VERTEX_SOURCE3 = `#version 300 es
 layout(location = 0) in vec3 a_position;
 layout(location = 3) in mat4 a_instanceMatrix;
-uniform mat4 u_lightViewProjection;
+uniform mat4 u_matrix;
+uniform float u_useInstancing;
 void main() {
-  vec4 world = a_instanceMatrix * vec4(a_position, 1.0);
-  gl_Position = u_lightViewProjection * world;
+  vec4 local = vec4(a_position, 1.0);
+  vec4 world = mix(local, a_instanceMatrix * local, u_useInstancing);
+  gl_Position = u_matrix * world;
 }
 `;
 var FRAGMENT_SOURCE3 = `#version 300 es
@@ -2034,18 +2602,18 @@ void main() {
   // \u53EA\u5199\u6DF1\u5EA6\uFF0C\u989C\u8272\u4E0D\u9700\u8981\u3002
 }
 `;
-var LIGHT_DIRECTION2 = [-0.35, 0.85, 0.4];
 var SHADOW_SIZE = 2048;
-var ORTHO_EXTENT = 430;
-var ORTHO_NEAR = -260;
-var ORTHO_FAR = 700;
 var WebGL2ShadowMap = class {
   gl;
+  /** 最近一次着色器编译/链接失败的原因，供诊断读取。 */
+  lastError = null;
   framebuffer = null;
   depthTexture = null;
   program = null;
-  lightMatrixLocation = null;
+  matrixLocation = null;
+  instancingLocation = null;
   matrixScratch = new Float32Array(16);
+  texelWorldValue = 1;
   constructor(gl) {
     this.gl = gl;
     this.createResources();
@@ -2057,6 +2625,19 @@ var WebGL2ShadowMap = class {
   get matrix() {
     return this.matrixScratch;
   }
+  /** 一个深度纹素在世界空间的边长（米）。法线偏移按它换算，别用魔数。 */
+  get texelWorld() {
+    return this.texelWorldValue;
+  }
+  /**
+   * 按场景包围盒拟合视锥。每帧调用没有意义——场景内容不变时矩阵也不会变，
+   * 所以由调用方决定何时重算（包围盒变化或首帧）。
+   */
+  setBounds(bounds) {
+    const frustum = shadowFrustum(bounds, SHADOW_SIZE);
+    this.matrixScratch.set(frustum.matrix);
+    this.texelWorldValue = frustum.texelWorld;
+  }
   /** 绑定阴影帧缓冲，返回是否成功。 */
   begin() {
     const gl = this.gl;
@@ -2067,12 +2648,24 @@ var WebGL2ShadowMap = class {
     gl.disable(gl.POLYGON_OFFSET_FILL);
     gl.clear(gl.DEPTH_BUFFER_BIT);
     gl.enable(gl.DEPTH_TEST);
-    gl.enable(gl.CULL_FACE);
-    gl.cullFace(gl.FRONT);
+    gl.disable(gl.CULL_FACE);
     gl.useProgram(this.program);
-    gl.uniformMatrix4fv(this.lightMatrixLocation, false, this.matrixScratch);
+    gl.uniformMatrix4fv(this.matrixLocation, false, this.matrixScratch);
+    gl.uniform1f(this.instancingLocation, 1);
     return true;
   }
+  /**
+   * 非实例化绘制：矩阵换成 `lightViewProjection × world`，顶点位置直接当世界坐标用。
+   *
+   * 阴影通道原先只会画实例化批次，瓦片（渲染批次）与落单网格因此完全不投影。
+   * 补这两条路径靠的就是这个入口——和 `WebGL2SceneDepth` 同一套写法。
+   */
+  setMatrix(matrix) {
+    this.gl.uniformMatrix4fv(this.matrixLocation, false, matrix);
+  }
+  setInstancing(enabled) {
+    this.gl.uniform1f(this.instancingLocation, enabled ? 1 : 0);
+  }
   /** 解绑，恢复默认帧缓冲。 */
   end(width, height) {
     const gl = this.gl;
@@ -2109,130 +2702,283 @@ var WebGL2ShadowMap = class {
     gl.readBuffer(gl.NONE);
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     this.program = this.createProgram(VERTEX_SOURCE3, FRAGMENT_SOURCE3);
-    this.lightMatrixLocation = this.program ? gl.getUniformLocation(this.program, "u_lightViewProjection") : null;
-    this.updateLightMatrix();
-  }
-  /** 正交光源矩阵：覆盖整片场地，与主着色器的光方向一致。 */
-  updateLightMatrix() {
-    const direction = normalize2(LIGHT_DIRECTION2);
-    const target = [300, 0, 0];
-    const eye = [
-      target[0] + direction[0] * 400,
-      target[1] + direction[1] * 400,
-      target[2] + direction[2] * 400
-    ];
-    const view = lookAt(eye, target, [0, 1, 0]);
-    const projection = orthographic(-ORTHO_EXTENT, ORTHO_EXTENT, -ORTHO_EXTENT, ORTHO_EXTENT, ORTHO_NEAR, ORTHO_FAR);
-    this.matrixScratch.set(multiply(projection, view));
+    this.matrixLocation = this.program ? gl.getUniformLocation(this.program, "u_matrix") : null;
+    this.instancingLocation = this.program ? gl.getUniformLocation(this.program, "u_useInstancing") : null;
+    this.setBounds(null);
   }
   createProgram(vertex, fragment) {
-    const gl = this.gl;
-    const vertexShader = this.compile(gl.VERTEX_SHADER, vertex);
-    const fragmentShader = this.compile(gl.FRAGMENT_SHADER, fragment);
-    if (!vertexShader || !fragmentShader)
-      return null;
-    const program = gl.createProgram();
-    gl.attachShader(program, vertexShader);
-    gl.attachShader(program, fragmentShader);
-    gl.linkProgram(program);
-    gl.deleteShader(vertexShader);
-    gl.deleteShader(fragmentShader);
-    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
-      gl.deleteProgram(program);
+    try {
+      return createShaderProgram(this.gl, vertex, fragment, "shadow");
+    } catch (error) {
+      this.lastError = error instanceof Error ? error.message : String(error);
       return null;
     }
-    return program;
   }
-  compile(type, source) {
+};
+
+// packages/renderer/dist/SceneBounds.js
+var localBoundsCache = /* @__PURE__ */ new WeakMap();
+function geometryLocalBounds(geometry) {
+  const cached = localBoundsCache.get(geometry);
+  if (cached)
+    return cached;
+  const positions = geometry.positions;
+  if (!positions || positions.length < 3)
+    return null;
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (let index = 0; index + 2 < positions.length; index += 3) {
+    const x = positions[index];
+    const y = positions[index + 1];
+    const z = positions[index + 2];
+    if (x < minX)
+      minX = x;
+    if (y < minY)
+      minY = y;
+    if (z < minZ)
+      minZ = z;
+    if (x > maxX)
+      maxX = x;
+    if (y > maxY)
+      maxY = y;
+    if (z > maxZ)
+      maxZ = z;
+  }
+  const bounds = { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+  localBoundsCache.set(geometry, bounds);
+  return bounds;
+}
+function accumulateSceneBounds(renderables) {
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  let seen = false;
+  for (const renderable of renderables) {
+    const local = geometryLocalBounds(renderable.mesh.geometry);
+    if (!local)
+      continue;
+    const matrix = renderable.worldMatrix;
+    for (let corner = 0; corner < 8; corner += 1) {
+      const x = corner & 1 ? local.max[0] : local.min[0];
+      const y = corner & 2 ? local.max[1] : local.min[1];
+      const z = corner & 4 ? local.max[2] : local.min[2];
+      const worldX = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
+      const worldY = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
+      const worldZ = matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14];
+      if (worldX < minX)
+        minX = worldX;
+      if (worldY < minY)
+        minY = worldY;
+      if (worldZ < minZ)
+        minZ = worldZ;
+      if (worldX > maxX)
+        maxX = worldX;
+      if (worldY > maxY)
+        maxY = worldY;
+      if (worldZ > maxZ)
+        maxZ = worldZ;
+      seen = true;
+    }
+  }
+  return seen ? { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] } : null;
+}
+
+// packages/renderer/dist/WebGL2SceneDepth.js
+var VERTEX_SOURCE4 = `#version 300 es
+layout(location = 0) in vec3 a_position;
+layout(location = 3) in mat4 a_instanceMatrix;
+uniform mat4 u_matrix;
+uniform float u_useInstancing;
+void main() {
+  vec4 local = vec4(a_position, 1.0);
+  vec4 world = mix(local, a_instanceMatrix * local, u_useInstancing);
+  gl_Position = u_matrix * world;
+}
+`;
+var FRAGMENT_SOURCE4 = `#version 300 es
+precision highp float;
+void main() {}
+`;
+var WebGL2SceneDepth = class {
+  gl;
+  framebuffer;
+  depthTexture = null;
+  program;
+  matrixLocation;
+  instancingLocation;
+  width = 0;
+  height = 0;
+  constructor(gl) {
+    this.gl = gl;
+    this.program = createShaderProgram(gl, VERTEX_SOURCE4, FRAGMENT_SOURCE4, "scene-depth");
+    this.matrixLocation = gl.getUniformLocation(this.program, "u_matrix");
+    this.instancingLocation = gl.getUniformLocation(this.program, "u_useInstancing");
+    const framebuffer = gl.createFramebuffer();
+    if (!framebuffer)
+      throw new Error("ICE3_FRAMEBUFFER_FAILED: scene depth");
+    this.framebuffer = framebuffer;
+  }
+  get texture() {
+    return this.depthTexture;
+  }
+  begin(viewProjection, width, height) {
     const gl = this.gl;
-    const shader = gl.createShader(type);
-    if (!shader)
-      return null;
-    gl.shaderSource(shader, source);
-    gl.compileShader(shader);
-    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
-      gl.deleteShader(shader);
-      return null;
+    this.ensureTexture(Math.max(1, width), Math.max(1, height));
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, this.width, this.height);
+    gl.disable(gl.POLYGON_OFFSET_FILL);
+    gl.disable(gl.BLEND);
+    gl.depthMask(true);
+    gl.clear(gl.DEPTH_BUFFER_BIT);
+    gl.enable(gl.DEPTH_TEST);
+    gl.useProgram(this.program);
+    gl.uniformMatrix4fv(this.matrixLocation, false, viewProjection);
+    gl.uniform1f(this.instancingLocation, 0);
+  }
+  setMatrix(matrix) {
+    this.gl.uniformMatrix4fv(this.matrixLocation, false, matrix);
+  }
+  setInstancing(enabled) {
+    this.gl.uniform1f(this.instancingLocation, enabled ? 1 : 0);
+  }
+  end(width, height) {
+    const gl = this.gl;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.enable(gl.POLYGON_OFFSET_FILL);
+    gl.viewport(0, 0, width, height);
+  }
+  dispose() {
+    const gl = this.gl;
+    if (this.depthTexture)
+      gl.deleteTexture(this.depthTexture);
+    gl.deleteFramebuffer(this.framebuffer);
+    gl.deleteProgram(this.program);
+    this.depthTexture = null;
+  }
+  ensureTexture(width, height) {
+    const gl = this.gl;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    if (this.depthTexture && this.width === width && this.height === height) {
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, this.depthTexture, 0);
+      return;
     }
-    return shader;
+    if (this.depthTexture)
+      gl.deleteTexture(this.depthTexture);
+    this.width = width;
+    this.height = height;
+    const texture = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.DEPTH_COMPONENT24, width, height, 0, gl.DEPTH_COMPONENT, gl.UNSIGNED_INT, null);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, texture, 0);
+    gl.drawBuffers([gl.NONE]);
+    gl.readBuffer(gl.NONE);
+    this.depthTexture = texture;
   }
 };
-function normalize2(value) {
-  const length = Math.hypot(value[0], value[1], value[2]) || 1;
-  return [value[0] / length, value[1] / length, value[2] / length];
-}
-function subtract2(a, b) {
-  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
-}
-function cross2(a, b) {
-  return [
-    a[1] * b[2] - a[2] * b[1],
-    a[2] * b[0] - a[0] * b[2],
-    a[0] * b[1] - a[1] * b[0]
-  ];
-}
-function dot2(a, b) {
-  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
-}
-function lookAt(eye, target, up) {
-  const forward = normalize2(subtract2(eye, target));
-  const right = normalize2(cross2(up, forward));
-  const cameraUp = cross2(forward, right);
-  return [
-    right[0],
-    right[1],
-    right[2],
-    0,
-    cameraUp[0],
-    cameraUp[1],
-    cameraUp[2],
-    0,
-    forward[0],
-    forward[1],
-    forward[2],
-    0,
-    -dot2(right, eye),
-    -dot2(cameraUp, eye),
-    -dot2(forward, eye),
-    1
-  ];
-}
-function orthographic(left, right, bottom, top, near, far) {
-  const lr = 1 / (left - right);
-  const bt = 1 / (bottom - top);
-  const nf = 1 / (near - far);
-  return [
-    -2 * lr,
-    0,
-    0,
-    0,
-    0,
-    -2 * bt,
-    0,
-    0,
-    0,
-    0,
-    2 * nf,
-    0,
-    (left + right) * lr,
-    (top + bottom) * bt,
-    (far + near) * nf,
-    1
-  ];
-}
-function multiply(a, b) {
-  const out = new Array(16).fill(0);
-  for (let column = 0; column < 4; column += 1) {
-    for (let row = 0; row < 4; row += 1) {
-      let sum = 0;
-      for (let k = 0; k < 4; k += 1) {
-        sum += (a[k * 4 + row] ?? 0) * (b[column * 4 + k] ?? 0);
+
+// packages/renderer/dist/WebGL2TextureCache.js
+var REPEAT = 10497;
+var fetchImageLoader = async (url) => {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`ICE3_TEXTURE_FETCH_FAILED: ${response.status} ${url}`);
+  }
+  return createImageBitmap(await response.blob());
+};
+var WebGL2TextureCache = class {
+  gl;
+  load;
+  onUpload;
+  entries = /* @__PURE__ */ new Map();
+  disposed = false;
+  constructor(gl, load = fetchImageLoader, onUpload) {
+    this.gl = gl;
+    this.load = load;
+    this.onUpload = onUpload;
+  }
+  /** Texture for `url`, or `null` while it is still loading (or after failure). */
+  texture(url) {
+    if (this.disposed)
+      return null;
+    const existing = this.entries.get(url);
+    if (existing) {
+      return existing.state === "ready" ? existing.texture : null;
+    }
+    this.entries.set(url, { state: "pending" });
+    void this.load(url).then((image) => {
+      if (this.disposed) {
+        image.close?.();
+        return;
       }
-      out[column * 4 + row] = sum;
+      const texture = this.upload(image);
+      if (this.disposed) {
+        this.gl.deleteTexture(texture);
+        return;
+      }
+      this.entries.set(url, { state: "ready", texture });
+      this.onUpload?.();
+    }).catch(() => {
+      if (!this.disposed)
+        this.entries.set(url, { state: "failed" });
+    });
+    return null;
+  }
+  stats() {
+    let loaded = 0;
+    let pending = 0;
+    let failed2 = 0;
+    for (const entry of this.entries.values()) {
+      if (entry.state === "ready")
+        loaded += 1;
+      else if (entry.state === "pending")
+        pending += 1;
+      else
+        failed2 += 1;
     }
+    return { loaded, pending, failed: failed2 };
   }
-  return out;
-}
+  dispose() {
+    if (this.disposed)
+      return;
+    this.disposed = true;
+    for (const entry of this.entries.values()) {
+      if (entry.state === "ready")
+        this.gl.deleteTexture(entry.texture);
+    }
+    this.entries.clear();
+  }
+  upload(image) {
+    const gl = this.gl;
+    const texture = gl.createTexture();
+    if (!texture) {
+      throw new Error("ICE3_TEXTURE_CREATE_FAILED");
+    }
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, REPEAT);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, REPEAT);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.generateMipmap(gl.TEXTURE_2D);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    image.close?.();
+    return texture;
+  }
+};
+
+// packages/renderer/dist/WebGL2Uv.js
+var DEFAULT_UV_SCALE = [1, 1];
 
 // packages/renderer/dist/Color.js
 var COLOR_CACHE_LIMIT = 128;
@@ -2325,9 +3071,12 @@ var WebGL2RendererBackend = class {
   onContextLost;
   onContextRestored;
   program = null;
+  clipPlane = [0, 0, 0, 0];
   shadowMap = null;
-  // 阴影采样开关。定位掉深度偏差之前保持关闭，避免把错误的明暗关系画出来。
+  /** 方向光阴影开关：默认关闭，由 `initialize({ shadows })` 或页面地址 `?shadows=` 打开。 */
   shadowEnabled = false;
+  /** `?shadowdebug=1` 输出遮蔽判定，`=2` 输出深度图；排查阴影问题的唯一可信手段。 */
+  shadowDebug = 0;
   semanticProgram = null;
   geometryCache = null;
   instanceCache = null;
@@ -2355,10 +3104,106 @@ var WebGL2RendererBackend = class {
     gpuEvictions: 0,
     gpuBytes: 0
   };
+  textures = null;
+  sceneDepth = null;
+  occlusionRadius = 2.5;
+  /**
+   * 三圈采样比双圈多找到约 1.7 个亮度点的遮蔽（同参数 96.36 → 94.65），原样沿用到
+   * 默认值就把厂区压得发闷。0.30 是回调后的值：整帧 95.70（无遮蔽 99.59），
+   * 高光像素 878（无遮蔽 1088），接触暗部仍看得见。详见 SPEC-007 第 5.5 节。
+   */
+  occlusionStrength = 0.3;
+  options = null;
+  /**
+   * Bind the material's colour and (if it has one) its base-colour texture.
+   * Called for every opaque/shaded draw so a batched draw and a single mesh draw
+   * cannot drift apart.
+   */
+  applyMaterial(material) {
+    const program = this.program;
+    if (!program)
+      return;
+    program.setColor(colorToRgba(material.color));
+    const map = material.map;
+    const texture = map && this.textures ? this.textures.texture(map.url) : null;
+    program.setBaseColorMap(texture, map?.scale ?? material.ormMap?.scale ?? DEFAULT_UV_SCALE);
+    const normalMap = material.normalMap;
+    const normalTexture = normalMap && this.textures ? this.textures.texture(normalMap.url) : null;
+    program.setNormalMap(normalTexture, normalMap?.strength ?? 1);
+    const ormMap = material.ormMap;
+    const ormTexture = ormMap && this.textures ? this.textures.texture(ormMap.url) : null;
+    program.setOrmMap(ormTexture, ormMap?.occlusion !== false, ormMap?.metallicRoughness !== false);
+    program.setSurface(material.metallic, material.roughness, material.emissive);
+  }
+  /** Edge overlays are line work: never sampled, always flat. */
+  applyEdgeMaterial(material) {
+    const program = this.program;
+    if (!program)
+      return;
+    program.setColor(colorToRgba(material.edgeColor ?? material.color));
+    program.setBaseColorMap(null, DEFAULT_UV_SCALE);
+    program.setNormalMap(null, 1);
+    program.setOrmMap(null, false, false);
+    program.setSurface(0, 0.85, void 0);
+  }
+  /**
+   * `?ao=<radius>,<strength>` 覆盖遮蔽参数（`ao=off` 关闭）。
+   *
+   * 屏幕空间遮蔽的合适参数与场景尺度强相关，靠改代码重编译来找太慢。这里只读一次
+   * 页面地址，纯属调参通道，不参与渲染决策。
+   */
+  readOcclusionOverride() {
+    if (typeof location === "undefined")
+      return;
+    const value = new URLSearchParams(location.search).get("ao");
+    if (!value)
+      return;
+    if (value === "off") {
+      this.occlusionStrength = 0;
+      return;
+    }
+    const parts = value.split(",").map(Number);
+    const radius = parts[0];
+    const strength = parts[1];
+    if (radius !== void 0 && Number.isFinite(radius) && radius > 0) {
+      this.occlusionRadius = radius;
+    }
+    if (strength !== void 0 && Number.isFinite(strength) && strength >= 0) {
+      this.occlusionStrength = strength;
+    }
+  }
+  /**
+   * `?shadows=1` / `?shadows=0` 覆盖阴影开关，与 `?ao` 同属调参通道。
+   *
+   * 阴影是一次额外全场景 pass，默认不开；演示与对比时靠地址栏切换，
+   * 不必为看清"有影子/没影子"重编译一次。
+   */
+  readShadowOverride() {
+    if (typeof location === "undefined")
+      return;
+    const params = new URLSearchParams(location.search);
+    const value = params.get("shadows");
+    if (value !== null) {
+      this.shadowEnabled = value !== "0" && value !== "off";
+    }
+    const debug = Number(params.get("shadowdebug"));
+    this.shadowDebug = Number.isFinite(debug) ? Math.max(0, Math.min(2, Math.trunc(debug))) : 0;
+    if (this.shadowDebug > 0)
+      this.shadowEnabled = true;
+  }
+  ensureTextureCache() {
+    if (this.textures || !this.gl)
+      return;
+    this.textures = new WebGL2TextureCache(this.gl, void 0, () => {
+      this.options?.onUploadReady?.();
+    });
+  }
   handleContextLost = (event) => {
     event.preventDefault();
     this.picker = null;
     this.program = null;
+    this.sceneDepth?.dispose();
+    this.sceneDepth = null;
     this.shadowMap?.dispose();
     this.shadowMap = null;
     this.geometryCache?.clear();
@@ -2379,6 +3224,7 @@ var WebGL2RendererBackend = class {
     this.onContextRestored?.();
   };
   initialize(options) {
+    this.options = options;
     const gl = options.canvas.getContext("webgl2", {
       alpha: true,
       antialias: true,
@@ -2402,6 +3248,11 @@ var WebGL2RendererBackend = class {
     gl.enable(gl.POLYGON_OFFSET_FILL);
     gl.polygonOffset(2, 4);
     this.createProgram(gl);
+    this.ensureTextureCache();
+    this.sceneDepth = new WebGL2SceneDepth(gl);
+    this.readOcclusionOverride();
+    this.shadowEnabled = options.shadows ?? false;
+    this.readShadowOverride();
     this.canvas.addEventListener("webglcontextlost", this.handleContextLost);
     this.canvas.addEventListener("webglcontextrestored", this.handleContextRestored);
   }
@@ -2436,6 +3287,9 @@ var WebGL2RendererBackend = class {
   releaseBatchGeometry(geometry) {
     this.geometryCache?.unpin(geometry);
   }
+  setClipPlane(plane) {
+    this.clipPlane = plane ? [plane[0], plane[1], plane[2], plane[3]] : [0, 0, 0, 0];
+  }
   render(frame) {
     if (!this.gl || !this.program || !this.geometryCache) {
       throw new ICEEngineError("ICE3_ENGINE_NOT_READY", "Renderer is not initialized");
@@ -2458,6 +3312,7 @@ var WebGL2RendererBackend = class {
       gpuBytes: 0
     };
     this.program.use();
+    this.program.setClipPlane(this.clipPlane);
     this.program.setClipOffset(0, 0);
     this.program.setDirectionalShading(false);
     this.program.setWaterShading(false);
@@ -2472,8 +3327,58 @@ var WebGL2RendererBackend = class {
     const renderables = collectRenderables(frame.scene, this.renderablesScratch);
     const instances = collectInstanceBatches(renderables, this.instancesScratch);
     const batches = collectRenderBatches(frame.scene, this.batchesScratch);
+    const standalone = renderablesOutsideInstanceBatches(renderables, instances);
     this.profiler.mark("collect");
+    let aoReady = false;
+    if (this.sceneDepth) {
+      const deviceWidth = Math.max(1, Math.round(frame.viewport.width * this.dpr));
+      const deviceHeight = Math.max(1, Math.round(frame.viewport.height * this.dpr));
+      this.sceneDepth.begin(viewProjection.elements, deviceWidth, deviceHeight);
+      this.sceneDepth.setInstancing(true);
+      for (const batch of instances) {
+        if (isTransparentColor(batch.material.color))
+          continue;
+        const instance = this.instanceCache.retain(gl, this.geometryCache, batch);
+        if (!instance)
+          continue;
+        gl.bindVertexArray(instance.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.triangleIndexBuffer);
+        gl.drawElementsInstanced(gl.TRIANGLES, instance.triangleCount, batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
+      }
+      this.sceneDepth.setInstancing(false);
+      for (const draw of batches) {
+        if (isTransparentColor(draw.batch.material.color))
+          continue;
+        world.elements.set(draw.worldMatrix);
+        mvp.elements.set(viewProjection.elements);
+        mvp.multiply(world);
+        this.sceneDepth.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, draw.batch.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, draw.batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+      }
+      for (const renderable of standalone) {
+        if (isTransparentColor(renderable.mesh.material.color))
+          continue;
+        world.elements.set(renderable.worldMatrix);
+        mvp.elements.set(viewProjection.elements);
+        mvp.multiply(world);
+        this.sceneDepth.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, renderable.mesh.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, renderable.mesh.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+      }
+      this.sceneDepth.end(deviceWidth, deviceHeight);
+      aoReady = true;
+      this.program.use();
+    }
+    if (this.shadowEnabled && this.shadowMap) {
+      this.shadowMap.setBounds(accumulateSceneBounds(renderables));
+    }
     if (this.shadowEnabled && this.shadowMap?.begin()) {
+      const lightViewProjection = this.shadowMap.matrix;
       for (const batch of instances) {
         if (isTransparentColor(batch.material.color))
           continue;
@@ -2484,10 +3389,47 @@ var WebGL2RendererBackend = class {
         gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.triangleIndexBuffer);
         gl.drawElementsInstanced(gl.TRIANGLES, instance.triangleCount, batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
       }
+      this.shadowMap.setInstancing(false);
+      for (const draw of batches) {
+        if (isTransparentColor(draw.batch.material.color))
+          continue;
+        world.elements.set(draw.worldMatrix);
+        mvp.elements.set(lightViewProjection);
+        mvp.multiply(world);
+        this.shadowMap.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, draw.batch.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, draw.batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+      }
+      for (const renderable of standalone) {
+        if (isTransparentColor(renderable.mesh.material.color))
+          continue;
+        world.elements.set(renderable.worldMatrix);
+        mvp.elements.set(lightViewProjection);
+        mvp.multiply(world);
+        this.shadowMap.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, renderable.mesh.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, renderable.mesh.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+      }
       this.shadowMap.end(frame.viewport.width * this.dpr, frame.viewport.height * this.dpr);
       this.program.use();
-      this.program.setShadow(this.shadowEnabled, this.shadowMap.texture, this.shadowMap.matrix);
     }
+    if (this.shadowMap) {
+      this.program.use();
+      this.program.setShadow(
+        this.shadowEnabled,
+        this.shadowMap.texture,
+        this.shadowMap.matrix,
+        // 1.5 个纹素：够把平躺在光里的面抬离自身深度，又不会让影子明显离开物体。
+        this.shadowMap.texelWorld * 1.5
+      );
+      this.program.setShadowDebug(this.shadowDebug);
+    }
+    this.program.setSceneDepth(aoReady ? this.sceneDepth.texture : null, frame.camera.getProjectionMatrix(aspect), frame.camera.near, frame.camera.far, Math.max(1, frame.viewport.width * this.dpr), Math.max(1, frame.viewport.height * this.dpr));
+    this.program.setOcclusion(this.occlusionRadius, this.occlusionStrength);
     for (const transparentPass of [false, true]) {
       if (transparentPass) {
         gl.enable(gl.BLEND);
@@ -2509,7 +3451,7 @@ var WebGL2RendererBackend = class {
           this.instancedMeshIds.add(id);
         mvp.elements.set(viewProjection.elements);
         this.program.setMatrix(mvp);
-        this.program.setColor(colorToRgba(batch.material.color));
+        this.applyMaterial(batch.material);
         this.program.setVertexColors(Boolean(batch.geometry.colors));
         this.program.setDirectionalShading(batch.material.shading !== "flat");
         this.program.setWaterShading(batch.material.shading === "water");
@@ -2521,7 +3463,7 @@ var WebGL2RendererBackend = class {
           this.program.setVertexColors(false);
           this.program.setDirectionalShading(false);
           this.program.setWaterShading(false);
-          this.program.setColor(colorToRgba(batch.material.edgeColor));
+          this.applyEdgeMaterial(batch.material);
           gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.edgeIndexBuffer);
           for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
             this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
@@ -2540,7 +3482,7 @@ var WebGL2RendererBackend = class {
         world.elements.set(draw.worldMatrix);
         mvp.multiply(world);
         this.program.setMatrix(mvp);
-        this.program.setColor(colorToRgba(draw.batch.material.color));
+        this.applyMaterial(draw.batch.material);
         const geometry = this.geometryCache.retain(gl, draw.batch.geometry);
         this.program.setVertexColors(Boolean(draw.batch.geometry.colors));
         this.program.setDirectionalShading(draw.batch.material.shading !== "flat");
@@ -2554,7 +3496,7 @@ var WebGL2RendererBackend = class {
           this.program.setVertexColors(false);
           this.program.setDirectionalShading(false);
           this.program.setWaterShading(false);
-          this.program.setColor(colorToRgba(draw.batch.material.edgeColor));
+          this.applyEdgeMaterial(draw.batch.material);
           gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.edgeIndexBuffer);
           for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
             this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
@@ -2573,7 +3515,7 @@ var WebGL2RendererBackend = class {
         world.elements.set(renderable.worldMatrix);
         mvp.multiply(world);
         this.program.setMatrix(mvp);
-        this.program.setColor(colorToRgba(renderable.mesh.material.color));
+        this.applyMaterial(renderable.mesh.material);
         const geometry = this.geometryCache.retain(gl, renderable.mesh.geometry);
         this.program.setVertexColors(Boolean(renderable.mesh.geometry.colors));
         this.program.setDirectionalShading(renderable.mesh.material.shading !== "flat");
@@ -2586,7 +3528,7 @@ var WebGL2RendererBackend = class {
           this.program.setVertexColors(false);
           this.program.setDirectionalShading(false);
           this.program.setWaterShading(false);
-          this.program.setColor(colorToRgba(renderable.mesh.material.edgeColor));
+          this.applyEdgeMaterial(renderable.mesh.material);
           gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.edgeIndexBuffer);
           for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
             this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
@@ -6263,8 +7205,8 @@ function pickSceneNode(scene, camera, viewport, point) {
     target.y - eye.y,
     target.z - eye.z
   ]);
-  const right = normalize3(cross3(forward, [0, 1, 0]));
-  const up = normalize3(cross3(right, forward));
+  const right = normalize3(cross2(forward, [0, 1, 0]));
+  const up = normalize3(cross2(right, forward));
   const aspect = viewport.width / Math.max(viewport.height, 1);
   const tangent = Math.tan(camera.fov * Math.PI / 360);
   const ndcX = point.x / viewport.width * 2 - 1;
@@ -6306,7 +7248,7 @@ var normalize3 = (value) => {
   const length = Math.hypot(...value);
   return length > 0 ? [value[0] / length, value[1] / length, value[2] / length] : [0, 0, 0];
 };
-var cross3 = (left, right) => [
+var cross2 = (left, right) => [
   left[1] * right[2] - left[2] * right[1],
   left[2] * right[0] - left[0] * right[2],
   left[0] * right[1] - left[1] * right[0]
@@ -6612,6 +7554,7 @@ var ICE3 = class extends ICEEventDispatcher {
   generatedOverlayCanvas = false;
   scene = null;
   camera = null;
+  clipPlane = [0, 0, 0, 0];
   viewport = { x: 0, y: 0, width: 1, height: 1 };
   dpr = 1;
   frameId = 0;
@@ -6707,6 +7650,10 @@ var ICE3 = class extends ICEEventDispatcher {
           if (this.state === "destroyed")
             return;
           this.recordDiagnostic(error.code, error.message, "error");
+        },
+        onUploadReady: () => {
+          if (this.state === "running")
+            this.requestRender("upload-ready");
         }
       });
       window.addEventListener("resize", this.handleWindowResize);
@@ -6751,6 +7698,17 @@ var ICE3 = class extends ICEEventDispatcher {
     this.requestRender("background-color");
     return this;
   }
+  /**
+   * Section plane `[nx, ny, nz, d]`: fragments with `dot(world, n) + d < 0`
+   * are discarded. `null` (or a zero plane) disables clipping.
+   */
+  setClipPlane(plane) {
+    this.assertActive();
+    this.clipPlane = plane ? [plane[0], plane[1], plane[2], plane[3]] : [0, 0, 0, 0];
+    this.backend.setClipPlane?.(this.clipPlane);
+    this.requestRender("clip-plane");
+    return this;
+  }
   prepareRenderBatchGeometry(geometry) {
     if (!this.backend.prepareBatchGeometry) {
       throw new ICEEngineError("ICE3_RENDER_BATCH_ADAPTER_UNAVAILABLE", "The active renderer cannot stage adaptive batch geometry");
@@ -7544,7 +8502,13 @@ function buildAssetScene(snapshot) {
   const materials = snapshot.materials.map((material) => new ICEBasicMaterial({
     color: material.baseColor,
     ...material.edgeColor ? { edgeColor: material.edgeColor } : {},
-    ...material.shading ? { shading: material.shading } : {}
+    ...material.shading ? { shading: material.shading } : {},
+    ...material.map ? { map: material.map } : {},
+    ...material.normalMap ? { normalMap: material.normalMap } : {},
+    ...material.ormMap ? { ormMap: material.ormMap } : {},
+    ...material.metallic !== void 0 ? { metallic: material.metallic } : {},
+    ...material.roughness !== void 0 ? { roughness: material.roughness } : {},
+    ...material.emissive ? { emissive: material.emissive } : {}
   }));
   const meshesByNode = /* @__PURE__ */ new Map();
   for (const mesh of snapshot.meshes) {
@@ -7697,6 +8661,45 @@ function colorHex(color) {
 }
 
 // packages/assets/dist/ICEProfileValidator.js
+function validateTextures(json) {
+  const images = records(json.images);
+  const textures = records(json.textures);
+  const samplers = records(json.samplers);
+  for (const image of images) {
+    const uri = image.uri;
+    if (typeof uri !== "string" || !uri || uri.startsWith("/") || uri.includes("..") || uri.includes("://") || image.bufferView !== void 0) {
+      throw assetError("ICE3_ASSET_UNSUPPORTED_FEATURE", "images must reference a relative file path");
+    }
+  }
+  for (const texture of textures) {
+    const source = Number(texture.source);
+    if (!Number.isInteger(source) || source < 0 || source >= images.length) {
+      throw assetError("ICE3_ASSET_INVALID_GLB", "texture source is out of range");
+    }
+    if (texture.sampler !== void 0) {
+      const sampler = Number(texture.sampler);
+      if (!Number.isInteger(sampler) || sampler < 0 || sampler >= samplers.length) {
+        throw assetError("ICE3_ASSET_INVALID_GLB", "texture sampler is out of range");
+      }
+    }
+  }
+  for (const material of records(json.materials)) {
+    const slots = [
+      ["baseColorTexture", record(record(material.pbrMetallicRoughness)?.baseColorTexture)],
+      ["normalTexture", record(material.normalTexture)],
+      ["metallicRoughnessTexture", record(record(material.pbrMetallicRoughness)?.metallicRoughnessTexture)],
+      ["occlusionTexture", record(material.occlusionTexture)]
+    ];
+    for (const [slot, reference] of slots) {
+      if (!reference)
+        continue;
+      const index = Number(reference.index);
+      if (!Number.isInteger(index) || index < 0 || index >= textures.length) {
+        throw assetError("ICE3_ASSET_INVALID_GLB", `${slot} index is out of range`);
+      }
+    }
+  }
+}
 function validatePreparedProfile(json, binary) {
   const asset = record(json.asset);
   const profile = record(record(asset?.extras)?.ice3);
@@ -7724,15 +8727,13 @@ function validatePreparedProfile(json, binary) {
     "animations",
     "skins",
     "cameras",
-    "textures",
-    "images",
-    "samplers",
     "lights"
   ]) {
     if (Array.isArray(json[field]) && json[field].length > 0) {
       throw assetError("ICE3_ASSET_UNSUPPORTED_FEATURE", `${field} are unsupported by the M1 profile`);
     }
   }
+  validateTextures(json);
   if (records(json.scenes).length !== 1 || json.scene !== 0 || records(json.buffers).length !== 1 || records(json.buffers)[0]?.uri !== void 0 || Number(records(json.buffers)[0]?.byteLength) > binary.byteLength) {
     throw assetError("ICE3_ASSET_INVALID_GLB", "profile container fields are invalid");
   }
@@ -7890,13 +8891,15 @@ function assetError(code, message) {
 }
 
 // packages/assets/dist/ICEGLBReader.js
-function readPreparedGLB(bytes) {
+function readPreparedGLB(bytes, options = {}) {
   const { json, binary, profile } = parseGLB(bytes);
   const accessors = records(json.accessors);
   const views = records(json.bufferViews);
   const sourceNodes = records(json.nodes);
   const sourceMeshes = records(json.meshes);
   const sourceMaterials = records(json.materials);
+  const sourceTextures = records(json.textures);
+  const sourceImages = records(json.images);
   const activeScene = records(json.scenes)[Number(json.scene ?? 0)];
   const sceneRoots = integers(activeScene?.nodes);
   const parents = new Array(sourceNodes.length).fill(null);
@@ -7979,11 +8982,18 @@ function readPreparedGLB(bytes) {
       const edgeMaterial = edgePrimitive ? sourceMaterials[Number(edgePrimitive.material)] : void 0;
       const shading = record(record(baseMaterial?.extras)?.ice3)?.shading;
       const materialIndex = materials.length;
+      const map = materialMap(baseMaterial, sourceTextures, sourceImages, options.baseUrl);
+      const normalMap = normalMaterialMap(baseMaterial, sourceTextures, sourceImages, options.baseUrl);
+      const ormMap = ormMaterialMap(baseMaterial, sourceTextures, sourceImages, options.baseUrl);
       materials.push({
         id: `${meshId}/material/${primitiveIndex}`,
         baseColor: materialColor(baseMaterial),
         ...edgeMaterial ? { edgeColor: materialColor(edgeMaterial) } : {},
-        ...shading === "directional" || shading === "water" ? { shading } : {}
+        ...shading === "directional" || shading === "water" ? { shading } : {},
+        ...map ? { map } : {},
+        ...normalMap ? { normalMap } : {},
+        ...ormMap ? { ormMap } : {},
+        ...surfaceFactors(baseMaterial)
       });
       const bounds = boundsFromAccessor(accessors[positionIndex]);
       const geometryIndex = geometries.length;
@@ -8293,6 +9303,93 @@ function boundsFromProfile(value) {
     max: [Number(max[0]), Number(max[1]), Number(max[2])]
   };
 }
+function materialMap(material, textures, images, baseUrl) {
+  const reference = record(record(material?.pbrMetallicRoughness)?.baseColorTexture);
+  if (!reference)
+    return void 0;
+  const texture = textures[Number(reference.index)];
+  const uri = record(images[Number(record(texture)?.source)])?.uri;
+  if (typeof uri !== "string" || uri.length === 0)
+    return void 0;
+  const transform = record(record(reference.extensions)?.KHR_texture_transform);
+  const scale = numbers(transform?.scale, 2);
+  const su = scale?.[0];
+  const sv = scale?.[1];
+  return {
+    url: resolveTextureUrl(uri, baseUrl),
+    ...typeof su === "number" && typeof sv === "number" && su > 0 && sv > 0 ? { scale: [su, sv] } : {}
+  };
+}
+function surfaceFactors(material) {
+  const pbr = record(material?.pbrMetallicRoughness);
+  const metallic = unitOrUndefined(pbr?.metallicFactor);
+  const roughness = unitOrUndefined(pbr?.roughnessFactor);
+  const emissive = numbers(material?.emissiveFactor, 3);
+  return {
+    ...metallic !== void 0 ? { metallic } : {},
+    ...roughness !== void 0 ? { roughness } : {},
+    ...emissive && emissive.some((value) => value > 0) ? { emissive: [emissive[0], emissive[1], emissive[2]] } : {}
+  };
+}
+function unitOrUndefined(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed))
+    return void 0;
+  return Math.min(1, Math.max(0, parsed));
+}
+function normalMaterialMap(material, textures, images, baseUrl) {
+  const reference = record(material?.normalTexture);
+  if (!reference)
+    return void 0;
+  const texture = textures[Number(reference.index)];
+  const uri = record(images[Number(record(texture)?.source)])?.uri;
+  if (typeof uri !== "string" || uri.length === 0)
+    return void 0;
+  const strength = Number(reference.scale);
+  return {
+    url: resolveTextureUrl(uri, baseUrl),
+    ...Number.isFinite(strength) && strength >= 0 ? { strength } : {}
+  };
+}
+function ormMaterialMap(material, textures, images, baseUrl) {
+  const metallicRoughness = textureReference(record(record(material?.pbrMetallicRoughness)?.metallicRoughnessTexture), textures, images, baseUrl);
+  const occlusion = textureReference(record(material?.occlusionTexture), textures, images, baseUrl);
+  if (!metallicRoughness && !occlusion)
+    return void 0;
+  const url = metallicRoughness?.url ?? occlusion.url;
+  const scale = metallicRoughness?.scale ?? occlusion?.scale;
+  return {
+    url,
+    ...scale ? { scale } : {},
+    occlusion: occlusion?.url === url,
+    metallicRoughness: metallicRoughness !== void 0
+  };
+}
+function textureReference(reference, textures, images, baseUrl) {
+  if (!reference)
+    return void 0;
+  const texture = textures[Number(reference.index)];
+  const uri = record(images[Number(record(texture)?.source)])?.uri;
+  if (typeof uri !== "string" || uri.length === 0)
+    return void 0;
+  const transform = record(record(reference.extensions)?.KHR_texture_transform);
+  const scale = numbers(transform?.scale, 2);
+  const su = scale?.[0];
+  const sv = scale?.[1];
+  return {
+    url: resolveTextureUrl(uri, baseUrl),
+    ...typeof su === "number" && typeof sv === "number" && su > 0 && sv > 0 ? { scale: [su, sv] } : {}
+  };
+}
+function resolveTextureUrl(uri, baseUrl) {
+  if (!baseUrl)
+    return uri;
+  try {
+    return new URL(uri, baseUrl).href;
+  } catch {
+    return uri;
+  }
+}
 function materialColor(material) {
   if (!material)
     return "#808080";
@@ -9193,7 +10290,7 @@ var ICEAssetLoader = class {
       throw new Error(`ICE3_ASSET_FETCH_FAILED: HTTP ${response.status}`);
     }
     const bytes = await response.arrayBuffer();
-    const snapshot = readPreparedGLB(bytes);
+    const snapshot = readPreparedGLB(bytes, { baseUrl: url });
     return { bytes, snapshot };
   }
 };
@@ -9983,7 +11080,7 @@ var ICETilesetHandle = class extends ICEEventDispatcher {
   adaptivePlanningSignature = "";
   renderBatchingMode;
   visibleCoverageIds = /* @__PURE__ */ new Set();
-  constructor(engine, snapshot, camera, scheduler, fetch, maxConcurrentTiles, maxCommitsPerFrame, maxScreenSpaceErrorPixels, lodSettleDelayMs, renderBatching, callerSignal) {
+  constructor(engine, snapshot, camera, scheduler, fetch2, maxConcurrentTiles, maxCommitsPerFrame, maxScreenSpaceErrorPixels, lodSettleDelayMs, renderBatching, callerSignal) {
     super();
     this.engine = engine;
     this.snapshot = snapshot;
@@ -10014,7 +11111,7 @@ var ICETilesetHandle = class extends ICEEventDispatcher {
       });
     }
     this.assetLoader = new ICEAssetLoader(engine, {
-      fetch: (input, init) => fetch(input, {
+      fetch: (input, init) => fetch2(input, {
         ...init ?? {},
         signal: this.abortController.signal
       })
@@ -11174,8 +12271,20 @@ export {
   deserializeScene,
   serializeScene
 };
-//! 方向光阴影贴图。
+//! 阴影视锥：按场景包围盒拟合方向光的正交投影。
 //!
+//! 早期实现把光照视锥写死成 860 米见方、960 米深。两个后果都很贵：
+//! 2048 的深度图摊到 860 米是每纹素 0.42 米（薄墙的影子直接消失），
+//! 而深度偏差 0.0015 在 960 米的跨度上等于 1.4 米，短影子被整段吃掉。
+//! 视锥贴合场景后，偏差回到"厘米"量级，贴图分辨率也才有意义。
+//! 方向光阴影贴图。
 //! 一次深度 pass 把场景从光源方向渲染进深度纹理，主 pass 再按世界坐标比较深度。
-//! 只处理单方向光、单张贴图，够覆盖当前查看器的需要；级联与软阴影留给后续。
+//! 只处理单方向光、单张贴图；视锥按场景包围盒拟合（见 ShadowFrustum）。
+//! 场景包围盒：给阴影视锥用。
+//! 引擎里没有现成的场景 bounds，而阴影视锥必须贴合实际内容——写死范围会让
+//! 深度精度和贴图分辨率一起浪费（见 ShadowFrustum）。这里按"几何局部包围盒
+//! 缓存 + 世界矩阵变换"累加，避免每帧扫描几十万个顶点。
+//! 相机深度通道：屏幕空间遮蔽的来源。
+//! 从**相机**方向渲染一遍深度。必须覆盖全部几何路径——瓦片走渲染批次，其余走实例化
+//! 批次；只画一条会让深度图大半是空的（SPEC-007）。
 //# sourceMappingURL=index.js.map