three-base 2.0.168 → 2.0.172

package/WaterFlow/WaterFlow.js

@@ -25,7 +25,7 @@ import { ScreenSpaceFluidPass } from './ScreenSpaceFluidPass';
  *     depthMode: 'logarithmic',
  *   });
  *   // 每帧：先 renderer.setRenderTarget(baseRenderTarget); renderer.render(scene, camera);
- *   //       再 renderAoDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
+ *   //       再 renderVisibleDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
  *   //       然后 water.update(dt, elapsed);
  *   //       最后 setRenderTarget(screenRT); fsQuad.render(renderer, pass.material);
  *   // 注意：WaterFlow 的 composite 是纯消费 base 纹理的 fsQuad，可直接放进你的链。

package/WaterFlow/WaterFlow.ts

@@ -36,7 +36,7 @@ import type {
  *     depthMode: 'logarithmic',
  *   });
  *   // 每帧：先 renderer.setRenderTarget(baseRenderTarget); renderer.render(scene, camera);
- *   //       再 renderAoDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
+ *   //       再 renderVisibleDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
  *   //       然后 water.update(dt, elapsed);
  *   //       最后 setRenderTarget(screenRT); fsQuad.render(renderer, pass.material);
  *   // 注意：WaterFlow 的 composite 是纯消费 base 纹理的 fsQuad，可直接放进你的链。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.168",
+  "version": "2.0.172",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {

package/pass/bloom_pass.js

@@ -15,23 +15,18 @@ const selectDepthTexture = (() => {
     baseDepthTexture.anisotropy = 16;
     return baseDepthTexture;
 })();
+// ⭐ 2026-10-11 皇上旨「简化渲染」：selectDepthTexture 挂在本目标上当 depth attachment，
+// mask 那一趟光栅化顺带写出本体深度 ⇒ 原来为同一对象再渲一趟「只出深度」整条删除。
 const selectTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTest 判定边界与 mask 视觉边缘错位，bloom 边缘锯齿/摩尔纹。
     // 边缘抗锯齿统一由终处理 FXAA 兜底。
 });
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
 const selectDepthTestTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -117,7 +112,6 @@ export default function bloom_pass(renderer, camera, object3d, baseRenderTarget,
     size.multiplyScalar(devicePixelRatio);
     bloomPass.setSize(size.x, size.y);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷②修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 的尺寸与全屏 baseDepth 对齐，否则深度比例错位导致 bloom 被全部 discard
     selectDepthTexture.image.width = size.x;
@@ -168,13 +162,12 @@ export default function bloom_pass(renderer, camera, object3d, baseRenderTarget,
         }
     });
     try {
+        // ⭐ mask 这一趟顺带把本体深度写进 selectDepthTexture（挂在 selectTextureTarget 的 depth
+        //   attachment 上）；原先紧随其后的「只渲深度」第二趟（同材质/同相机/同几何 ⇒ 深度逐位相同）
+        //   已在 2026-10-11 皇上旨简化时删除。与材质/父节点还原同生命周期。
         renderer.setRenderTarget(selectTextureTarget);
         renderer.clear();
         renderer.render(scene, camera);
-        // 单独渲染对象深度到无 MSAA 目标，供 depthTestShader 做遮挡判定（与材质/父节点还原同生命周期）
-        renderer.setRenderTarget(selectDepthTextureTarget);
-        renderer.clear();
-        renderer.render(scene, camera);
     }
     finally {
         // 还原材质 emissive

package/pass/bloom_pass.ts

@@ -18,25 +18,19 @@ const selectDepthTexture: DepthTexture = (() => {
     return baseDepthTexture;
 })();
 
+// ⭐ 2026-10-11 皇上旨「简化渲染」：selectDepthTexture 挂在本目标上当 depth attachment，
+// mask 那一趟光栅化顺带写出本体深度 ⇒ 原来为同一对象再渲一趟「只出深度」整条删除。
 const selectTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTest 判定边界与 mask 视觉边缘错位，bloom 边缘锯齿/摩尔纹。
     // 边缘抗锯齿统一由终处理 FXAA 兜底。
 });
 
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
-
 const selectDepthTestTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -145,7 +139,6 @@ export default function bloom_pass(
     size.multiplyScalar(devicePixelRatio);
     bloomPass.setSize(size.x, size.y);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷②修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 的尺寸与全屏 baseDepth 对齐，否则深度比例错位导致 bloom 被全部 discard
     selectDepthTexture.image.width = size.x;
@@ -198,14 +191,12 @@ export default function bloom_pass(
     });
 
     try {
+        // ⭐ mask 这一趟顺带把本体深度写进 selectDepthTexture（挂在 selectTextureTarget 的 depth
+        //   attachment 上）；原先紧随其后的「只渲深度」第二趟（同材质/同相机/同几何 ⇒ 深度逐位相同）
+        //   已在 2026-10-11 皇上旨简化时删除。与材质/父节点还原同生命周期。
         renderer.setRenderTarget(selectTextureTarget);
         renderer.clear();
         renderer.render(scene, camera);
-
-        // 单独渲染对象深度到无 MSAA 目标，供 depthTestShader 做遮挡判定（与材质/父节点还原同生命周期）
-        renderer.setRenderTarget(selectDepthTextureTarget);
-        renderer.clear();
-        renderer.render(scene, camera);
     } finally {
         // 还原材质 emissive
         emissiveBackup.forEach(({ material, emissive, emissiveIntensity }) => {

package/pass/cover_pass.js

@@ -20,23 +20,18 @@ const selectDepthTexture = (() => {
     baseDepthTexture.anisotropy = 16;
     return baseDepthTexture;
 })();
+// ⭐ 2026-10-11 皇上旨「简化渲染」：selectDepthTexture 挂在本目标上当 depth attachment，
+// mask 那一趟光栅化顺带写出本体深度 ⇒ 原来为同一对象再渲一趟「只出深度」整条删除。
 const selectTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTestShader 判定边界与 mask 视觉边缘错位，覆盖边缘锯齿。
     // 边缘抗锯齿统一由终处理 FXAA 兜底。
 });
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
 const selectDepthTestTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -125,7 +120,6 @@ export default function cover_pass(renderer, camera, object3d, baseDepthTexture,
     renderer.getSize(size);
     size.multiplyScalar(devicePixelRatio);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 尺寸与全屏 baseDepth 对齐，否则深度比例错位导致颜色覆盖被错误 discard
     selectDepthTexture.image.width = size.x;
@@ -133,15 +127,13 @@ export default function cover_pass(renderer, camera, object3d, baseDepthTexture,
     selectDepthTexture.needsUpdate = true;
     selectDepthTestTextureTarget.setSize(size.x, size.y);
     blur1TextureTarget.setSize(size.x, size.y);
+    // ⭐ mask 那一趟光栅化顺带把本体深度写进 selectDepthTexture（挂在 selectTextureTarget 的
+    //   depth attachment 上）；原先紧随其后的「只渲深度」第二趟（同材质/同相机/同几何 ⇒ 深度逐位相同）
+    //   已在 2026-10-11 皇上旨简化时删除。
     renderer.setRenderTarget(selectTextureTarget);
     scene.children = [object3d];
     renderer.clear();
     renderer.render(scene, camera);
-    // 单独渲染对象深度到无 MSAA 目标，供 depthTestShader 做遮挡判定
-    renderer.setRenderTarget(selectDepthTextureTarget);
-    scene.children = [object3d];
-    renderer.clear();
-    renderer.render(scene, camera);
     // 调试：记录选区深度，供面板「深度判定图 / 辉光深度比对」排查 cover 的遮挡判定
     debugDepthState.lastSelectDepth = selectDepthTexture;
     renderer.setRenderTarget(originRenderTarget);

package/pass/cover_pass.ts

@@ -23,25 +23,19 @@ const selectDepthTexture: DepthTexture = (() => {
     return baseDepthTexture;
 })();
 
+// ⭐ 2026-10-11 皇上旨「简化渲染」：selectDepthTexture 挂在本目标上当 depth attachment，
+// mask 那一趟光栅化顺带写出本体深度 ⇒ 原来为同一对象再渲一趟「只出深度」整条删除。
 const selectTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTestShader 判定边界与 mask 视觉边缘错位，覆盖边缘锯齿。
     // 边缘抗锯齿统一由终处理 FXAA 兜底。
 });
 
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
-
 const selectDepthTestTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -149,7 +143,6 @@ export default function cover_pass(
     renderer.getSize(size);
     size.multiplyScalar(devicePixelRatio);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 尺寸与全屏 baseDepth 对齐，否则深度比例错位导致颜色覆盖被错误 discard
     selectDepthTexture.image.width = size.x;
@@ -157,16 +150,13 @@ export default function cover_pass(
     selectDepthTexture.needsUpdate = true;
     selectDepthTestTextureTarget.setSize(size.x, size.y);
     blur1TextureTarget.setSize(size.x, size.y);
+    // ⭐ mask 那一趟光栅化顺带把本体深度写进 selectDepthTexture（挂在 selectTextureTarget 的
+    //   depth attachment 上）；原先紧随其后的「只渲深度」第二趟（同材质/同相机/同几何 ⇒ 深度逐位相同）
+    //   已在 2026-10-11 皇上旨简化时删除。
     renderer.setRenderTarget(selectTextureTarget);
     scene.children = [object3d];
     renderer.clear();
     renderer.render(scene, camera);
-
-    // 单独渲染对象深度到无 MSAA 目标，供 depthTestShader 做遮挡判定
-    renderer.setRenderTarget(selectDepthTextureTarget);
-    scene.children = [object3d];
-    renderer.clear();
-    renderer.render(scene, camera);
     // 调试：记录选区深度，供面板「深度判定图 / 辉光深度比对」排查 cover 的遮挡判定
     debugDepthState.lastSelectDepth = selectDepthTexture;
 

package/pass/debugDepthState.d.ts

@@ -2,8 +2,8 @@ import type { DepthTexture } from "three";
 /**
  * 深度调试预览模式（面板按钮与控制台 `window.__TB_DEBUG_DEPTH` 共用同一枚举）：
  *   - "none"    ：正常渲染（默认）
- *   - "global"  ：全局深度图（baseDepthTexture，排除地板）
- *   - "ao"      ：AO 深度图（aoDepthTexture，含地板）
+ *   - "global"  ：可见深度图（baseDepthTexture，各物体自身材质渲染，含地板）
+ *   - "ao"      ：AO 深度图（aoDepthTexture，法线 pass 顺带写入，override 渲染）
  *   - "compare" ：R=base 深度、G=选区 select 深度（对数反解后归一化）
  *   - "judge"   ：R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)
  *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=挡不住任何后处理）

package/pass/debugDepthState.ts

@@ -3,8 +3,8 @@ import type { DepthTexture } from "three";
 /**
  * 深度调试预览模式（面板按钮与控制台 `window.__TB_DEBUG_DEPTH` 共用同一枚举）：
  *   - "none"    ：正常渲染（默认）
- *   - "global"  ：全局深度图（baseDepthTexture，排除地板）
- *   - "ao"      ：AO 深度图（aoDepthTexture，含地板）
+ *   - "global"  ：可见深度图（baseDepthTexture，各物体自身材质渲染，含地板）
+ *   - "ao"      ：AO 深度图（aoDepthTexture，法线 pass 顺带写入，override 渲染）
  *   - "compare" ：R=base 深度、G=选区 select 深度（对数反解后归一化）
  *   - "judge"   ：R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)
  *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=挡不住任何后处理）

package/pass/glow_pass.js

@@ -14,23 +14,18 @@ const selectDepthTexture = (() => {
     baseDepthTexture.anisotropy = 16;
     return baseDepthTexture;
 })();
+// ⭐ 2026-10-11 皇上旨「简化渲染」：selectDepthTexture 挂在本目标上当 depth attachment，
+// mask 那一趟光栅化顺带写出本体深度 ⇒ 原来为同一对象再渲一趟「只出深度」整条删除。
 const selectTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTestShader 判定边界与 mask 视觉边缘错位，辉光边缘锯齿。
     // 边缘抗锯齿统一由 mask 内部 FXAA + 终处理 FXAA 兜底。
 });
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
 const selectDepthTestTextureTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -483,7 +478,6 @@ export default function glow_pass(renderer, camera, object3d, baseDepthTexture,
     renderer.getSize(size);
     size.multiplyScalar(devicePixelRatio);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 尺寸与全屏 baseDepth 对齐，否则深度比例错位导致辉光被错误 discard
     selectDepthTexture.image.width = size.x;
@@ -495,16 +489,14 @@ export default function glow_pass(renderer, camera, object3d, baseDepthTexture,
     selectDepthBlurTmpTextureTarget.setSize(size.x, size.y);
     selectDepthBlurTextureTarget.setSize(size.x, size.y);
     blurDepthTestTextureTarget.setSize(size.x, size.y);
-    // 1. 渲染物体本体 mask（灰度）
+    // 1. 渲染物体本体 mask（灰度）。⭐ 本体深度由同一趟光栅化顺带写进 selectDepthTexture
+    //   （挂在 selectTextureTarget 的 depth attachment 上）；原先的第 2 趟「只渲深度」（供 min-blur
+    //   外扩用）与这趟同材质/同相机/同几何 ⇒ 深度逐位相同，2026-10-11 皇上旨简化时删除。
+    //   （下面的步骤编号保留 3/4/5…，别处注释按号交叉引用，不随之重排。）
     renderer.setRenderTarget(selectTextureTarget);
     scene.children = [object3d];
     renderer.clear();
     renderer.render(scene, camera);
-    // 2. 渲染物体本体深度（无 MSAA，供 min-blur 外扩用）
-    renderer.setRenderTarget(selectDepthTextureTarget);
-    scene.children = [object3d];
-    renderer.clear();
-    renderer.render(scene, camera);
     // 调试：把本次渲染的选区深度记到全局调试状态，供面板「辉光深度比对」读取
     debugDepthState.lastSelectDepth = selectDepthTexture;
     // 3. 深度测试（用本体 mask）：被真实更近物体挡住的「本体辉光」部分 discard。

package/pass/glow_pass.ts

@@ -17,25 +17,19 @@ const selectDepthTexture: DepthTexture = (() => {
     return baseDepthTexture;
 })();
 
+// ⭐ 2026-10-11 皇上旨「简化渲染」：selectDepthTexture 挂在本目标上当 depth attachment，
+// mask 那一趟光栅化顺带写出本体深度 ⇒ 原来为同一对象再渲一趟「只出深度」整条删除。
 const selectTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
     format: RGBAFormat,
+    depthTexture: selectDepthTexture,
     anisotropy: 16,
-    // 无 MSAA：mask 颜色与下方 selectDepthTextureTarget（深度）必须同为硬边缘，
+    // 无 MSAA：mask 颜色与它顺带写入的深度必须同为硬边缘，
     // 否则 mask 边缘平滑而深度硬 → depthTestShader 判定边界与 mask 视觉边缘错位，辉光边缘锯齿。
     // 边缘抗锯齿统一由 mask 内部 FXAA + 终处理 FXAA 兜底。
 });
 
-// 无 MSAA 的深度专用目标：仅用于导出对象深度，供 depthTestShader 做遮挡判定（深度无需抗锯齿）
-const selectDepthTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-    depthTexture: selectDepthTexture,
-    anisotropy: 16,
-});
-
 const selectDepthTestTextureTarget: WebGLRenderTarget = new WebGLRenderTarget(1024, 1024, {
     minFilter: LinearFilter,
     magFilter: LinearFilter,
@@ -521,7 +515,6 @@ export default function glow_pass(
     renderer.getSize(size);
     size.multiplyScalar(devicePixelRatio);
     selectTextureTarget.setSize(size.x, size.y);
-    selectDepthTextureTarget.setSize(size.x, size.y);
     // 缺陷修复：three r167 的 WebGLRenderTarget.setSize 不会同步 depthTexture，
     // 需手动把 selectDepthTexture 尺寸与全屏 baseDepth 对齐，否则深度比例错位导致辉光被错误 discard
     selectDepthTexture.image.width = size.x;
@@ -534,17 +527,14 @@ export default function glow_pass(
     selectDepthBlurTextureTarget.setSize(size.x, size.y);
     blurDepthTestTextureTarget.setSize(size.x, size.y);
 
-    // 1. 渲染物体本体 mask（灰度）
+    // 1. 渲染物体本体 mask（灰度）。⭐ 本体深度由同一趟光栅化顺带写进 selectDepthTexture
+    //   （挂在 selectTextureTarget 的 depth attachment 上）；原先的第 2 趟「只渲深度」（供 min-blur
+    //   外扩用）与这趟同材质/同相机/同几何 ⇒ 深度逐位相同，2026-10-11 皇上旨简化时删除。
+    //   （下面的步骤编号保留 3/4/5…，别处注释按号交叉引用，不随之重排。）
     renderer.setRenderTarget(selectTextureTarget);
     scene.children = [object3d];
     renderer.clear();
     renderer.render(scene, camera);
-
-    // 2. 渲染物体本体深度（无 MSAA，供 min-blur 外扩用）
-    renderer.setRenderTarget(selectDepthTextureTarget);
-    scene.children = [object3d];
-    renderer.clear();
-    renderer.render(scene, camera);
     // 调试：把本次渲染的选区深度记到全局调试状态，供面板「辉光深度比对」读取
     debugDepthState.lastSelectDepth = selectDepthTexture;
 

package/pass/ssao_pass.d.ts

@@ -1,67 +1,36 @@
 import { MeshNormalMaterial, Scene, WebGLRenderTarget, WebGLRenderer, Camera } from "three";
 /**
- * 判断是否为「可透视的半透明表面」——这类物体不该在世界空间 AO 里充当实体。
- * 让它进入深度/法线图，被它遮挡的区域会发黑，成因分两种：
- *   a) transparent:true + opacity<1（毛玻璃、透明装饰）：深度图与法线图都落在半透明表面上，
- *      GTAO 在其表面算自遮蔽（褶皱、紧贴其它几何的窄缝）→ 这份 AO 被乘到「透过它看到的
- *      实体」上 → 该区域发黑。
- *   b) transparent:true + depthWrite:false（霓虹灯管、光晕、叠加面）：深度图保留身后几何（远），
- *      但法线 pass 用 overrideMaterial（MeshNormalMaterial 默认 depthWrite:true）会强行把它的
- *      法线写进去（近）→ 深度与法线指的不是同一个点 → GTAO 几乎必然算错发黑。
- * 故深度 pass 与法线 pass 统一隐藏：该像素的深度/法线即身后不透明几何，AO 由真实可见几何
- * 决定；身后是背景时深度为 1.0，shader 守卫直接判「无遮蔽」(=1)，不会发黑。
- *
- * 判据只看 material.transparent 本身，不再依赖 opacity / depthWrite（2026-08-30 修正）：
- * 大量半透明是自定义 ShaderMaterial，alpha 由 shader 算出来，而材质的 opacity 仍是默认 1、
- * depthWrite 仍是 true —— 典型如 Ground1 地板（mapColor.a 径向渐变）、聚光灯光斑、
- * effectMaterial1，靠材质属性完全读不出来，会被漏判并继续污染 AO。
- * 代价：Mirror 这类「标了 transparent 但 shader 实际输出 alpha=1.0」的实心反射面会被误排除，
- * 故 Mirror 在构造函数里显式标记 userData.aoOpaque = true 保留（见各 Mirror 实现）。
- * 其余特例同样可用 userData.aoTransparent=true 强制排除 / userData.aoOpaque=true 强制保留。
- *
- * @param includeFloor 是否为「含地板」的 AO 数据准备（GTAO 深度/法线）。
- *   - false（默认，可见深度 / 描边/辉光/毛玻璃遮挡判定）：地板按普通半透明排除。
- *   - true（AO 深度）：标了 userData.aoFloor 的地板保留为实体，参与接触 AO 计算。
- */
-/**
- * 可见深度图的运行时开关：**标了 `userData.aoFloor` 的地板是否参与遮挡判定**。
- *
- * 默认 false = 保持原设计（可透视地板：透过地板看到的物体照常显示，不被地板挡住）。
- * 置 true 后，地板会写进 baseDepthTexture，于是**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
- * 面板「深度调试 → 地板参与遮挡」可一键切换，用于排查"挡不住"是不是地板（如 Ground1）造成的。
- *
- * 只影响 aoFloor 地板这一类；transparent 面的处理不受影响（见 isSeeThroughSurface）。
- */
-export declare const visibleDepthOptions: {
-    includeFloor: boolean;
-};
-/**
- * 深度 pass：固定排除非实体表面后，将场景深度渲染到 depthRenderTarget。
- * depthRenderTarget.depthTexture 即 baseDepthTexture，供 SSAO / 描边 / 发光等后续 pass 复用。
+ * 可见深度 pass：固定排除非实体表面后，用**各物体自身的材质**把场景深度渲染到 depthRenderTarget。
+ * depthRenderTarget.depthTexture 即 baseDepthTexture，供描边 / 发光 / 覆盖 / 磨砂的遮挡判定，
+ * 也是 SSAO 合成时「真实可见表面」的参考。
  * 排除的非实体对象（sprite/线条/点）在深度图保留 clear 深度(1.0=远)，与背景一致；排除的
  * 半透明对象则保留其身后不透明几何的深度（身后无几何时同样为 1.0）。均不影响颜色通道渲染。
+ * ⚠️ 名字里的 ao 已不适用（2026-10-11 改名自 renderAoDepthPass）：它产出的是**可见深度**，
+ *   AO 自己的深度挂在法线 pass 上（见 renderAoNormalPass），两者只差 excludeTransparent 一个开关。
  */
-export declare function renderAoDepthPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, depthRenderTarget: WebGLRenderTarget, includeFloor?: boolean): void;
+export declare function renderVisibleDepthPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, depthRenderTarget: WebGLRenderTarget, excludeTransparent?: boolean): void;
 /**
  * 调试用：把「被排除出可见深度图」的表面单独渲成红色 mask。
  *
- * 这些面在 renderAoDepthPass 里被 hideNonSurface 隐藏，因此**不会写进 baseDepthTexture**，
+ * 这些面在 renderVisibleDepthPass 里被 hideNonSurface 隐藏，因此**不会写进 baseDepthTexture**，
  * 也就永远挡不住描边/辉光/毛玻璃/覆盖色 —— 这正是"深度测试看起来失效"最常见的成因
- * （用户以为是 bug，其实是该面被设计成可透视：sprite/线条/点、userData.aoTransparent、
- * 以及标了 userData.aoFloor 的地板 Ground1）。
+ * （用户以为是 bug，其实是该面被设计成可透视：sprite/线条/点、userData.aoTransparent）。
+ * ⚠️ 地板不在此列：2026-10-11 起 Ground1 是实心不透明面，正常写进可见深度图。
  * 面板「深度调试 → 排除面标记」叠加显示：灰=能挡住的真实遮挡面，红=被排除、挡不住任何东西。
  *
  * 只渲染 Mesh：sprite / Line2 / Points 在 MeshBasicMaterial override 下渲染异常（见文件头注释），
  * 且它们数量少、用户关心的遮挡体基本都是 Mesh，故跳过。
  */
-export declare function renderExcludedMaskPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, maskRenderTarget: WebGLRenderTarget, includeFloor?: boolean): void;
+export declare function renderExcludedMaskPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, maskRenderTarget: WebGLRenderTarget, excludeTransparent?: boolean): void;
 /**
  * 法线 pass（仅 SSAO 开启时需要）：固定排除非实体表面后，以中性灰清屏 + normalMaterial
  * override 将视图空间法线渲染到 normalRenderTarget，供 GTAO 风格 SSAO 使用。
  * 排除对象在法线图保留中性灰清屏色 → unpackRGBToNormal(0.5,0.5,0.5)=(0,0,0) →
  * SSAO 退化法线守卫判"无遮蔽"(=1)，避免精灵弹窗被 AO 乘黑。清屏色用后即还原。
+ * 深度白拿：normalRenderTarget 挂着 aoDepthTexture 作 depth attachment，这一趟的深度由光栅器
+ * 顺带写入 → 就是 AO 用的深度，无需再单独渲一遍（2026-09-14）。
  */
-export declare function renderAoNormalPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, normalRenderTarget: WebGLRenderTarget, normalMaterial: MeshNormalMaterial, includeFloor?: boolean): void;
+export declare function renderAoNormalPass(renderer: WebGLRenderer, camera: Camera, scene: Scene, normalRenderTarget: WebGLRenderTarget, normalMaterial: MeshNormalMaterial, excludeTransparent?: boolean): void;
 export interface SsaoOptions {
     enable: boolean;
     debug?: boolean;