three-base 2.0.169 → 2.0.172

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;

package/pass/ssao_pass.js

@@ -1,7 +1,7 @@
 import { Color, DataTexture, DoubleSide, LinearFilter, MeshBasicMaterial, NoBlending, RGBAFormat, RawShaderMaterial, RepeatWrapping, Vector2, Vector3, WebGLRenderTarget, Matrix4, MultiplyBlending, PerspectiveCamera, OrthographicCamera } from "three";
 import fsQuad from "./fsQuad";
 /**
- * 判断是否为「可透视的半透明表面」——这类物体不该在世界空间 AO 里充当实体。
+ * 判断是否为「可透视的半透明表面」——这类表面不该在世界空间 AO 里充当实体。
  * 让它进入深度/法线图，被它遮挡的区域会发黑，成因分两种：
  *   a) transparent:true + opacity<1（毛玻璃、透明装饰）：深度图与法线图都落在半透明表面上，
  *      GTAO 在其表面算自遮蔽（褶皱、紧贴其它几何的窄缝）→ 这份 AO 被乘到「透过它看到的
@@ -9,67 +9,50 @@ import fsQuad from "./fsQuad";
  *   b) transparent:true + depthWrite:false（霓虹灯管、光晕、叠加面）：深度图保留身后几何（远），
  *      但法线 pass 用 overrideMaterial（MeshNormalMaterial 默认 depthWrite:true）会强行把它的
  *      法线写进去（近）→ 深度与法线指的不是同一个点 → GTAO 几乎必然算错发黑。
- * 故深度 pass 与法线 pass 统一隐藏：该像素的深度/法线即身后不透明几何，AO 由真实可见几何
- * 决定；身后是背景时深度为 1.0，shader 守卫直接判「无遮蔽」(=1)，不会发黑。
+ * 故 AO 那一趟统一隐藏这些面：该像素的法线即身后不透明几何，AO 由真实可见几何决定；
+ * 身后是背景时深度为 1.0，shader 守卫直接判「无遮蔽」(=1)，不会发黑。
  *
  * 判据只看 material.transparent 本身，不再依赖 opacity / depthWrite（2026-08-30 修正）：
  * 大量半透明是自定义 ShaderMaterial，alpha 由 shader 算出来，而材质的 opacity 仍是默认 1、
- * depthWrite 仍是 true —— 典型如 Ground1 地板（mapColor.a 径向渐变）、聚光灯光斑、
- * effectMaterial1，靠材质属性完全读不出来，会被漏判并继续污染 AO。
+ * depthWrite 仍是 true —— 典型如聚光灯光斑、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 计算。
+ * @param excludeTransparent 两道 pass 的唯一差别，取值就是它名字的含义：
+ *   - false（可见深度 / 描边/辉光/毛玻璃/覆盖色遮挡判定）：透明面**当实体**参与遮挡。
+ *     ⚠️ 关键（2026-09-06 回归根因）：three-base 大量面（玻璃、特效载体、alpha 贴图实体、
+ *     半透明墙）都标了 transparent:true；若在此排除，它们就不再遮挡身后特效，所有依赖
+ *     baseDepthTexture 的深度测试全部失效、一律显示在前面。
+ *   - true（AO 深度 + 法线）：透明面排除，避免 GTAO 在其上算错发黑。
+ *   ⚠️ 2026-10-11 起此参数原名 includeFloor（地板特例已整条拆除，见文件头），别再当"地板开关"读。
  */
-/**
- * 可见深度图的运行时开关：**标了 `userData.aoFloor` 的地板是否参与遮挡判定**。
- *
- * 默认 false = 保持原设计（可透视地板：透过地板看到的物体照常显示，不被地板挡住）。
- * 置 true 后，地板会写进 baseDepthTexture，于是**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
- * 面板「深度调试 → 地板参与遮挡」可一键切换，用于排查"挡不住"是不是地板（如 Ground1）造成的。
- *
- * 只影响 aoFloor 地板这一类；transparent 面的处理不受影响（见 isSeeThroughSurface）。
- */
-export const visibleDepthOptions = { includeFloor: false };
-const isSeeThroughSurface = (obj, includeFloor = false) => {
+const isSeeThroughSurface = (obj, excludeTransparent = false) => {
     const o = obj;
     const userData = o.userData;
     if (userData && userData.aoOpaque === true)
         return false;
     if (userData && userData.aoTransparent === true)
         return true;
-    // 地板类半透明：可见深度（includeFloor=false，描边/辉光/毛玻璃/覆盖色遮挡判定用）里排除
-    // → 可透视，透过地板看到的物体照常显示；AO 深度（includeFloor=true）里保留 → 接触 AO。
-    // ⚠️ 例外：visibleDepthOptions.includeFloor=true 时，可见深度里也保留地板 → 地板能挡住特效。
-    if (userData && userData.aoFloor === true) {
-        return includeFloor ? false : !visibleDepthOptions.includeFloor;
-    }
     const mat = o.material;
     if (!mat)
         return false;
     const list = Array.isArray(mat) ? mat : [mat];
     const transparent = list.some((m) => m !== null && m.transparent === true);
-    // ⚠️ 关键修复（2026-09-06 回归根因）：可见深度（includeFloor=false）必须把"标了
-    // transparent 但实为实心/不透明"的面当作实体参与遮挡——three-base 大量面（玻璃、特效载体、
-    // alpha 贴图实体、半透明墙）都标了 transparent:true；若在此排除，它们就不再遮挡身后特效，
-    // 所有依赖 baseDepthTexture 的深度测试（描边/辉光/毛玻璃/覆盖色）全部失效、一律显示在前面。
-    // 仅 AO 深度（includeFloor=true）需要排除透明面，避免 GTAO 在半透明面上算错发黑（保留原 AO 修复）。
-    return includeFloor && transparent;
+    return excludeTransparent && transparent;
 };
-const isNonSurface = (obj, includeFloor = false) => {
+const isNonSurface = (obj, excludeTransparent = false) => {
     const o = obj;
     if (o.isSprite === true || o.isLine === true || o.isLine2 === true || o.isLineSegments2 === true || o.isPoints === true) {
         return true;
     }
-    return isSeeThroughSurface(obj, includeFloor);
+    return isSeeThroughSurface(obj, excludeTransparent);
 };
-const hideNonSurface = (scene, includeFloor = false) => {
+const hideNonSurface = (scene, excludeTransparent = false) => {
     const list = [];
     scene.traverse((obj) => {
-        if (isNonSurface(obj, includeFloor)) {
+        if (isNonSurface(obj, excludeTransparent)) {
             list.push({ obj, prev: obj.visible });
             obj.visible = false;
         }
@@ -80,18 +63,21 @@ const restoreVisibility = (list) => {
     list.forEach(({ obj, prev }) => (obj.visible = prev));
 };
 /**
- * 深度 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 function renderAoDepthPass(renderer, camera, scene, depthRenderTarget, includeFloor = false) {
-    const hidden = hideNonSurface(scene, includeFloor);
+export function renderVisibleDepthPass(renderer, camera, scene, depthRenderTarget, excludeTransparent = false) {
+    const hidden = hideNonSurface(scene, excludeTransparent);
     // ⚠️ 深度预通道铁律：必须让所有「未被排除」的可见表面都写入深度，深度图才有真实的几何遮挡信息。
     // 透明材质（特效载体、半透明墙、alpha 贴图实体等）大多 transparent:true 且 depthWrite:false，
     // 若不强转，它们不会写进 baseDepthTexture → 深度图只剩不透明几何 → 描边/辉光/毛玻璃/覆盖色
     // 依赖 baseDepthTexture 的遮挡判定全部失效、一律显示在前（即本次回归根因）。
-    // 被排除的半透明面（aoTransparent / aoFloor / Mirror-aoOpaque 等）已在 hideNonSurface 中隐藏，
+    // 被显式标记的面（userData.aoTransparent）已在 hideNonSurface 中隐藏，
     // 此处根本不会触及，故不影响 see-through 设计；其余透明面强制写深度 = 作为实体参与遮挡，符合预期。
     const depthWriteRestore = [];
     scene.traverse((obj) => {
@@ -118,16 +104,16 @@ export function renderAoDepthPass(renderer, camera, scene, depthRenderTarget, in
 /**
  * 调试用：把「被排除出可见深度图」的表面单独渲成红色 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 function renderExcludedMaskPass(renderer, camera, scene, maskRenderTarget, includeFloor = false) {
+export function renderExcludedMaskPass(renderer, camera, scene, maskRenderTarget, excludeTransparent = false) {
     const maskMaterial = new MeshBasicMaterial({
         color: 0xff0000,
         depthTest: false,
@@ -139,7 +125,7 @@ export function renderExcludedMaskPass(renderer, camera, scene, maskRenderTarget
         const isMesh = obj.isMesh === true;
         prevVisible.push({ obj, prev: obj.visible });
         // 只显示「被排除的 Mesh」：其余一律隐藏，得到纯黑底 + 红面的 mask
-        obj.visible = isMesh && isNonSurface(obj, includeFloor);
+        obj.visible = isMesh && isNonSurface(obj, excludeTransparent);
     });
     const prevOverride = scene.overrideMaterial;
     const prevTarget = renderer.getRenderTarget();
@@ -161,25 +147,16 @@ export function renderExcludedMaskPass(renderer, camera, scene, maskRenderTarget
  * 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 function renderAoNormalPass(renderer, camera, scene, normalRenderTarget, normalMaterial, includeFloor = false) {
-    const hidden = hideNonSurface(scene, includeFloor);
-    // ⚠️ 与 renderAoDepthPass 同款「强制写深度」：本 pass 的深度会被当作含地板 AO 深度使用
-    // （normalRenderTarget.depthTexture）。透明面若因 depthWrite:false 不写深度，AO 深度就会漏掉它们，
-    // 与被本 pass 取代的那次独立深度 pass 内容不一致。pass 结束后立即还原。
-    const depthWriteRestore = [];
-    scene.traverse((obj) => {
-        const mesh = obj;
-        if (!mesh.isMesh || !mesh.material)
-            return;
-        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
-        list.forEach((m) => {
-            if (m && m.depthWrite === false) {
-                depthWriteRestore.push({ mat: m, val: false });
-                m.depthWrite = true;
-            }
-        });
-    });
+export function renderAoNormalPass(renderer, camera, scene, normalRenderTarget, normalMaterial, excludeTransparent = false) {
+    const hidden = hideNonSurface(scene, excludeTransparent);
+    // ⚠️ 2026-10-11 删掉了这里原有的「强制 depthWrite=true」整段遍历：scene.overrideMaterial 生效后，
+    // three 用的是 **override 材质**的渲染状态（WebGLRenderer.renderObjects：
+    // `material = overrideMaterial === null ? renderItem.material : overrideMaterial`，setDepthState 吃它），
+    // 物体自己材质的 depthWrite 根本读不到 ⇒ 那段是空转。需要强转的是用自身材质渲染的
+    // renderVisibleDepthPass（那边保留）。
     const prevRenderTarget = renderer.getRenderTarget();
     const prevClearColor = new Color();
     renderer.getClearColor(prevClearColor);
@@ -191,7 +168,6 @@ export function renderAoNormalPass(renderer, camera, scene, normalRenderTarget,
     renderer.render(scene, camera);
     scene.overrideMaterial = null;
     restoreVisibility(hidden);
-    depthWriteRestore.forEach(({ mat, val }) => { mat.depthWrite = val; });
     renderer.setClearColor(prevClearColor, prevClearAlpha);
     renderer.setRenderTarget(prevRenderTarget);
 }
@@ -658,9 +634,9 @@ const outputShader = new RawShaderMaterial({
         ssaoTexture: { value: null },
         ssaoStrength: { value: 1.0 },
         debug: { value: 0.0 },
-        // 可见深度（排除地板，= baseDepthTexture）：代表"真实可见表面"的深度。
+        // 可见深度（用自身材质渲染，含地板）= baseDepthTexture：代表"真实可见表面"的深度。
         tColorDepth: { value: null },
-        // AO 深度（含地板，= normalRenderTarget.depthTexture，法线 pass 顺带写入）：GTAO 实际采样的深度。
+        // AO 深度（= normalRenderTarget.depthTexture，法线 pass 顺带写入）。
         tAoDepth: { value: null },
     },
     vertexShader: `
@@ -687,10 +663,13 @@ const outputShader = new RawShaderMaterial({
     void main() {
       float ssao = texture2D(ssaoTexture, vUv).r;
 
-      // 复合守卫：对数深度越小越近。若"含地板的 AO 深度"比"可见深度"更近，
-      // 说明该像素的真实可见表面位于半透明地板之后（典型的从下方透视地板看身后实体），
-      // 地板算出的接触 AO 不该乘到它身上 → 视为无遮蔽(=1)，即"被遮挡的部分就不要 ssao"。
-      // 仅在最终合成时生效；debug 模式直接看 GTAO 原始 AO 图（含地板接触 AO），便于排查。
+      // 复合守卫：对数深度越小越近。若"AO 深度"比"可见深度"更近，说明该像素上法线趟
+      // （override 材质：DoubleSide、不做物体自己的 alpha discard）记到一个**屏幕上根本不可见**的面
+      // —— 典型如树叶抠图的空隙、单面墙的背面。此时深度与法线指的不是人眼看到的那个点，
+      // GTAO 算出的 AO 不可信 → 视为无遮蔽(=1)。
+      // ⚠️ 2026-10-11：本守卫原本主要防「可透视地板挡住身后实体」，那条特例已随地板进深度图而作废，
+      //   现在它守的是上面这类 override/自身材质两套渲染结果的错位，别当死代码删。
+      // 仅在最终合成时生效；debug 模式直接看 GTAO 原始 AO 图，便于排查。
       float dColor = texture2D(tColorDepth, vUv).r;
       float dAo = texture2D(tAoDepth, vUv).r;
       if (debug < 0.5 && dAo < dColor - 0.0001) {
@@ -722,16 +701,19 @@ export default function ssao_pass(renderer, camera, scene, depthRenderTarget, no
     // 故 AO 直接乘进 base，描边/发光/覆盖/磨砂都叠在 AO 之上不被压暗；末尾统一 FXAA 输出到屏幕，
     // 覆盖 SSAO 自身的硬边。改动调用顺序时，本 pass 无需修改（输出到"绑定的那个目标"即可）。
     const originRenderTarget = renderer.getRenderTarget();
-    // 法线 pass：地板保留（includeFloor=true），接触 AO 需要地板的视图空间法线。
+    // 法线 pass（excludeTransparent=true）：隐式透明面不参与 AO，免得 GTAO 在其上算自遮蔽把
+    // 身后实体乘黑；地板/其它不透明面照常保留 —— 接触 AO 需要地板的视图空间法线。
     // ⭐ 深度白拿（2026-09-14 优化）：normalRenderTarget 挂着 aoDepthTexture 作 depth attachment，
-    // 这一次渲染的深度由光栅器顺带写入 → 直接就是「含地板」的 AO 深度，**不再单独渲一遍深度 pass**。
-    // （原先法线 pass 之后还要再渲一遍「含地板深度」——它与法线 pass 的排除集完全相同，
+    // 这一次渲染的深度由光栅器顺带写入 → 直接就是 AO 深度，**不再单独渲一遍深度 pass**。
+    // （原先法线 pass 之后还要再渲一遍「AO 深度」——它与法线 pass 的排除集完全相同，
     //   属于重复遍历全场景，2026-09-14 已删。）
-    // 前提：renderAoNormalPass 内部已把 depthWrite=false 的透明材质强转 true，保证写入面集合一致。
+    // ⚠️ 这一趟的深度是 override 材质写的（DoubleSide、不做物体自己的 alpha discard），
+    //   所以只能给 AO 用；特效遮挡吃的是下面那张「用自身材质渲染」的可见深度。
     renderAoNormalPass(renderer, camera, scene, normalRenderTarget, normalMaterial, true);
-    // 可见深度（地板排除）= baseDepthTexture，既是描边/辉光/毛玻璃的遮挡参考，也是"真实可见表面"参考。
+    // 可见深度（用各物体自身材质渲染，含地板）= baseDepthTexture：描边/辉光/毛玻璃/覆盖色的遮挡参考，
+    // 也是复合守卫里「真实可见表面」的参考。
     const colorDepthTexture = depthRenderTarget.depthTexture;
-    // AO 深度（含地板）：GTAO 与去噪采样它，能算出物体落在地板上的接触 AO。
+    // AO 深度：GTAO 与去噪采样它（与上面的法线同一次光栅化，深度-法线永远同源）。
     const aoDepthTexture = normalRenderTarget.depthTexture;
     const normalTexture = normalRenderTarget.texture;
     renderer.getSize(size);
@@ -796,8 +778,8 @@ export default function ssao_pass(renderer, camera, scene, depthRenderTarget, no
     fsQuad.render(renderer, poissonDenoiseShader);
     renderer.setRenderTarget(originRenderTarget);
     outputShader.uniforms.ssaoTexture.value = blurTextureTarget.texture;
-    // 复合守卫：可见深度（地板排除）与 AO 深度（含地板）两图比对，
-    // 地板挡在真实可见表面之前时作废地板的接触 AO（见 outputShader 注释）。
+    // 复合守卫：可见深度（自身材质渲染）与 AO 深度（override 渲染）两图比对，
+    // AO 侧更近 = 那像素记到屏幕上不可见的面（抠图空隙/单面墙背面）→ 作废该像素 AO（见 outputShader 注释）。
     outputShader.uniforms.tColorDepth.value = colorDepthTexture;
     outputShader.uniforms.tAoDepth.value = aoDepthTexture;
     // 叠加强度：finalOcclusion = mix(1.0, ao, strength)，0 = 完全不叠加 AO，1 = 原始强度，>1 外插加深。