three-base 2.0.142 → 2.0.166

package/pass/ssao_pass.js

@@ -1,808 +1,808 @@
-import { Color, DataTexture, DoubleSide, LinearFilter, MeshBasicMaterial, NoBlending, RGBAFormat, RawShaderMaterial, RepeatWrapping, Vector2, Vector3, WebGLRenderTarget, Matrix4, MultiplyBlending, PerspectiveCamera, OrthographicCamera } from "three";
-import fsQuad from "./fsQuad";
-/**
- * 判断是否为「可透视的半透明表面」——这类物体不该在世界空间 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 const visibleDepthOptions = { includeFloor: false };
-const isSeeThroughSurface = (obj, includeFloor = 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;
-};
-const isNonSurface = (obj, includeFloor = 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);
-};
-const hideNonSurface = (scene, includeFloor = false) => {
-    const list = [];
-    scene.traverse((obj) => {
-        if (isNonSurface(obj, includeFloor)) {
-            list.push({ obj, prev: obj.visible });
-            obj.visible = false;
-        }
-    });
-    return list;
-};
-const restoreVisibility = (list) => {
-    list.forEach(({ obj, prev }) => (obj.visible = prev));
-};
-/**
- * 深度 pass：固定排除非实体表面后，将场景深度渲染到 depthRenderTarget。
- * depthRenderTarget.depthTexture 即 baseDepthTexture，供 SSAO / 描边 / 发光等后续 pass 复用。
- * 排除的非实体对象（sprite/线条/点）在深度图保留 clear 深度(1.0=远)，与背景一致；排除的
- * 半透明对象则保留其身后不透明几何的深度（身后无几何时同样为 1.0）。均不影响颜色通道渲染。
- */
-export function renderAoDepthPass(renderer, camera, scene, depthRenderTarget, includeFloor = false) {
-    const hidden = hideNonSurface(scene, includeFloor);
-    // ⚠️ 深度预通道铁律：必须让所有「未被排除」的可见表面都写入深度，深度图才有真实的几何遮挡信息。
-    // 透明材质（特效载体、半透明墙、alpha 贴图实体等）大多 transparent:true 且 depthWrite:false，
-    // 若不强转，它们不会写进 baseDepthTexture → 深度图只剩不透明几何 → 描边/辉光/毛玻璃/覆盖色
-    // 依赖 baseDepthTexture 的遮挡判定全部失效、一律显示在前（即本次回归根因）。
-    // 被排除的半透明面（aoTransparent / aoFloor / Mirror-aoOpaque 等）已在 hideNonSurface 中隐藏，
-    // 此处根本不会触及，故不影响 see-through 设计；其余透明面强制写深度 = 作为实体参与遮挡，符合预期。
-    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;
-            }
-        });
-    });
-    const prevRenderTarget = renderer.getRenderTarget();
-    renderer.setRenderTarget(depthRenderTarget);
-    renderer.clear();
-    renderer.render(scene, camera);
-    // 还原 depthWrite，避免污染后续颜色通道渲染的透明混合
-    depthWriteRestore.forEach(({ mat, val }) => { mat.depthWrite = val; });
-    restoreVisibility(hidden);
-    renderer.setRenderTarget(prevRenderTarget);
-}
-/**
- * 调试用：把「被排除出可见深度图」的表面单独渲成红色 mask。
- *
- * 这些面在 renderAoDepthPass 里被 hideNonSurface 隐藏，因此**不会写进 baseDepthTexture**，
- * 也就永远挡不住描边/辉光/毛玻璃/覆盖色 —— 这正是"深度测试看起来失效"最常见的成因
- * （用户以为是 bug，其实是该面被设计成可透视：sprite/线条/点、userData.aoTransparent、
- * 以及标了 userData.aoFloor 的地板 Ground1）。
- * 面板「深度调试 → 排除面标记」叠加显示：灰=能挡住的真实遮挡面，红=被排除、挡不住任何东西。
- *
- * 只渲染 Mesh：sprite / Line2 / Points 在 MeshBasicMaterial override 下渲染异常（见文件头注释），
- * 且它们数量少、用户关心的遮挡体基本都是 Mesh，故跳过。
- */
-export function renderExcludedMaskPass(renderer, camera, scene, maskRenderTarget, includeFloor = false) {
-    const maskMaterial = new MeshBasicMaterial({
-        color: 0xff0000,
-        depthTest: false,
-        depthWrite: false,
-        side: DoubleSide,
-    });
-    const prevVisible = [];
-    scene.traverse((obj) => {
-        const isMesh = obj.isMesh === true;
-        prevVisible.push({ obj, prev: obj.visible });
-        // 只显示「被排除的 Mesh」：其余一律隐藏，得到纯黑底 + 红面的 mask
-        obj.visible = isMesh && isNonSurface(obj, includeFloor);
-    });
-    const prevOverride = scene.overrideMaterial;
-    const prevTarget = renderer.getRenderTarget();
-    const prevClear = renderer.getClearColor(new Color());
-    const prevAlpha = renderer.getClearAlpha();
-    scene.overrideMaterial = maskMaterial;
-    renderer.setRenderTarget(maskRenderTarget);
-    renderer.setClearColor(0x000000, 1);
-    renderer.clear();
-    renderer.render(scene, camera);
-    renderer.setClearColor(prevClear, prevAlpha);
-    renderer.setRenderTarget(prevTarget);
-    scene.overrideMaterial = prevOverride;
-    restoreVisibility(prevVisible);
-    maskMaterial.dispose();
-}
-/**
- * 法线 pass（仅 SSAO 开启时需要）：固定排除非实体表面后，以中性灰清屏 + normalMaterial
- * override 将视图空间法线渲染到 normalRenderTarget，供 GTAO 风格 SSAO 使用。
- * 排除对象在法线图保留中性灰清屏色 → unpackRGBToNormal(0.5,0.5,0.5)=(0,0,0) →
- * SSAO 退化法线守卫判"无遮蔽"(=1)，避免精灵弹窗被 AO 乘黑。清屏色用后即还原。
- */
-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;
-            }
-        });
-    });
-    const prevRenderTarget = renderer.getRenderTarget();
-    const prevClearColor = new Color();
-    renderer.getClearColor(prevClearColor);
-    const prevClearAlpha = renderer.getClearAlpha();
-    renderer.setClearColor(new Color(0.5, 0.5, 0.5), 1);
-    renderer.setRenderTarget(normalRenderTarget);
-    renderer.clear();
-    scene.overrideMaterial = normalMaterial;
-    renderer.render(scene, camera);
-    scene.overrideMaterial = null;
-    restoreVisibility(hidden);
-    depthWriteRestore.forEach(({ mat, val }) => { mat.depthWrite = val; });
-    renderer.setClearColor(prevClearColor, prevClearAlpha);
-    renderer.setRenderTarget(prevRenderTarget);
-}
-// 噪声贴图尺寸（奇数，magic square 要求奇数）。越大 → 旋转/半径抖动越细，
-// GTAO 各向异性（转视角时 AO 范围"呼吸"）越弱。17×17=289 种独立样本远多于默认的 5×5=25。
-const NOISE_SIZE = 17;
-// ---------------------------------------------------------------------------
-// GTAO 风格 SSAO（地平线积分）
-// 相对旧版手写 SSAO 的两点关键改进：
-//   1. 法线直接来自视图空间法线纹理（MeshNormalMaterial 渲染），不再用深度差分重建，
-//      从根本上消除噪声与边缘抖动。
-//   2. 采样采用 Ground Truth Ambient Occlusion 的地平线积分（horizon-based），
-//      几乎无 halo（光晕）与漏光。
-// 深度仍使用项目的对数深度（logarithmicDepthBuffer: true），通过 linearizeLogDepth
-// 还原 viewZ，与旧版保持一致；法线纹理来自 ThreeBase 的 normalRenderTarget。
-// 参考：three/examples/jsm/shaders/GTAOShader.js 的 horizon-based 积分核心。
-// 去噪：GTAO 计算的 AO 仍带高频噪声，这里用 Poisson 边缘保持去噪（双边去噪，
-// 依赖 normalTexture + baseDepthTexture）取代旧版 separable 高斯模糊，能在去噪的同时
-// 严格守住几何边缘。参考 three/examples/jsm/shaders/PoissonDenoiseShader.js。
-// ---------------------------------------------------------------------------
-const ssaoTextureTarget = new WebGLRenderTarget(512, 512, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-});
-const blurTextureTarget = new WebGLRenderTarget(512, 512, {
-    minFilter: LinearFilter,
-    magFilter: LinearFilter,
-    format: RGBAFormat,
-});
-const size = new Vector2();
-const projectionMatrix = new Matrix4();
-const inverseProjectionMatrix = new Matrix4();
-// 低差异方向旋转噪声（magic square noise），用于旋转每个像素的采样核，避免带状瑕疵
-function generateMagicSquare(size) {
-    const noiseSize = Math.floor(size) % 2 === 0 ? Math.floor(size) + 1 : Math.floor(size);
-    const noiseSquareSize = noiseSize * noiseSize;
-    const magicSquare = new Array(noiseSquareSize).fill(0);
-    let i = Math.floor(noiseSize / 2);
-    let j = noiseSize - 1;
-    for (let num = 1; num <= noiseSquareSize;) {
-        if (i === -1 && j === noiseSize) {
-            j = noiseSize - 2;
-            i = 0;
-        }
-        else {
-            if (j === noiseSize) {
-                j = 0;
-            }
-            if (i < 0) {
-                i = noiseSize - 1;
-            }
-        }
-        if (magicSquare[i * noiseSize + j] !== 0) {
-            j -= 2;
-            i++;
-            continue;
-        }
-        else {
-            magicSquare[i * noiseSize + j] = num++;
-        }
-        j++;
-        i--;
-    }
-    return magicSquare;
-}
-function generateMagicSquareNoise(size = NOISE_SIZE) {
-    const noiseSize = Math.floor(size) % 2 === 0 ? Math.floor(size) + 1 : Math.floor(size);
-    const magicSquare = generateMagicSquare(noiseSize);
-    const noiseSquareSize = magicSquare.length;
-    const data = new Uint8Array(noiseSquareSize * 4);
-    // 用确定性伪随机给每个像素一个 [0,1] 的 w 通道（用于采样半径抖动 sampleDir.w），
-    // 同时 xy 仍由 magic square 角度决定（保证方向分布均匀无聚集）。
-    // ⚠️ 旧实现把 w 通道写死 255（=1.0），导致 sampleDir.w 恒等于 1.0，
-    // 半径抖动完全失效、旋转方向只有 25 种 → GTAO 各向异性明显（转视角 AO 范围"呼吸"）。
-    for (let inx = 0; inx < noiseSquareSize; ++inx) {
-        const iAng = magicSquare[inx];
-        const angle = (2 * Math.PI * iAng) / noiseSquareSize;
-        const randomVec = new Vector3(Math.cos(angle), Math.sin(angle), 0).normalize();
-        // 每像素独立伪随机种子（基于行列索引），避免 w 通道规律化
-        const row = Math.floor(inx / noiseSize);
-        const col = inx % noiseSize;
-        const rnd = ((row * 73856093) ^ (col * 19349663) ^ (inx * 83492791)) >>> 0;
-        const wRand = (rnd % 1000) / 1000; // [0,1)
-        data[inx * 4] = (randomVec.x * 0.5 + 0.5) * 255;
-        data[inx * 4 + 1] = (randomVec.y * 0.5 + 0.5) * 255;
-        data[inx * 4 + 2] = 127;
-        data[inx * 4 + 3] = Math.floor(wRand * 255); // 半径抖动真正生效
-    }
-    const noiseTexture = new DataTexture(data, noiseSize, noiseSize);
-    noiseTexture.wrapS = RepeatWrapping;
-    noiseTexture.wrapT = RepeatWrapping;
-    noiseTexture.needsUpdate = true;
-    return noiseTexture;
-}
-const noiseTexture = generateMagicSquareNoise();
-const ssaoShader = new RawShaderMaterial({
-    defines: {
-        SAMPLES: 32,
-    },
-    uniforms: {
-        depthTexture: { value: null },
-        normalTexture: { value: null },
-        tNoise: { value: noiseTexture },
-        resolution: { value: new Vector2(1 / 512, 1 / 512) },
-        noiseResolution: { value: new Vector2(NOISE_SIZE, NOISE_SIZE) },
-        projectionMatrix: { value: new Matrix4() },
-        inverseProjectionMatrix: { value: new Matrix4() },
-        ssaoRadius: { value: 5.0 },
-        ssaoFalloff: { value: 5.0 },
-        ssaoBias: { value: 0.01 },
-        scale: { value: 1.0 },
-        cameraNear: { value: 0.1 },
-        cameraFar: { value: 20000 },
-        distanceExponent: { value: 1.0 },
-        distanceFallOff: { value: 1.0 },
-    },
-    vertexShader: `
-    attribute vec3 position;
-    attribute vec2 uv;
-    varying vec2 vUv;
-    void main() {
-      vUv = uv;
-      gl_Position = vec4(position, 1.0);
-    }`,
-    fragmentShader: `
-    #ifdef GL_ES
-      precision highp float;
-    #endif
-
-    uniform sampler2D depthTexture;
-    uniform sampler2D normalTexture;
-    uniform sampler2D tNoise;
-    uniform vec2 resolution;
-    uniform vec2 noiseResolution;
-    uniform mat4 projectionMatrix;
-    uniform mat4 inverseProjectionMatrix;
-    uniform float ssaoRadius;
-    uniform float ssaoFalloff;
-    uniform float ssaoBias;
-    uniform float scale;
-    uniform float cameraNear;
-    uniform float cameraFar;
-    uniform float distanceExponent;
-    uniform float distanceFallOff;
-
-    varying vec2 vUv;
-
-    const float PI = 3.141592653589793;
-
-    // ⚠️ 关键：本项目渲染器 logarithmicDepthBuffer:true，baseDepthTexture 存的是「对数编码」的 gl_FragDepth。
-    // three.js r167 写深度（logdepthbuf_fragment，透视下 gl_Position.w = -viewZ）：
-    //   gl_FragDepth = log2(1.0 - viewZ) / log2(cameraFar + 1.0)
-    // 反解得真实视图空间 Z（负值 = 相机前方）：
-    //   viewZ = 1.0 - 2^(logDepth * log2(cameraFar + 1.0))
-    // 注：three.js 的 perspectiveDepthToViewZ() 期望的是「常规透视非线性深度」(gl_FragCoord.z)，
-    // 与这里的对数编码是完全不同的两套，不能直接套用——对数深度必须显式解指数。
-    // （Python 数值复算验证：该公式对任意距离还原误差 = 0，perspectiveDepthToViewZ 误差高达数米级。）
-    float viewZFromLogDepth(float logDepth) {
-      return 1.0 - pow(2.0, logDepth * log2(cameraFar + 1.0));
-    }
-
-    // MeshNormalMaterial 把视图空间法线 pack 到 [0,1]，这里解回 [-1,1]
-    vec3 unpackRGBToNormal(vec3 rgb) {
-      return rgb * 2.0 - 1.0;
-    }
-
-    // 由 uv + 真实 viewZ 重建视图空间位置。
-    // 透视投影下：ndc.xy = clip.xy/clip.w，clip.xy = (f/aspect * X, f * Y)，clip.w = -viewZ
-    // 反解得 X = ndc.x * (-viewZ) / (f/aspect)，Y = ndc.y * (-viewZ) / f，Z = viewZ。
-    // 注意：旧写法用 inverseProjectionMatrix 反投影 ndc.z=0 取「方向」再乘 viewZ/(-dir.z)，
-    // 会把方向翻到相机背后（z/y 反号），导致平地重建到天顶方向 → GTAO 把开阔地面误判遮蔽压黑。
-    // 这里直接由 viewZ 解析构造，无符号陷阱，且对数深度已在外层 viewZFromLogDepth 还原成真实 viewZ，
-    // 与本函数无关（不再依赖 projectionMatrix 的逆，故 inverseProjectionMatrix uniform 可保留也可移除）。
-    vec3 reconstructPosition(vec2 uv, float viewZ) {
-      // 透视投影：projectionMatrix[0][0] = f/aspect，projectionMatrix[1][1] = f，clip.w = -viewZ
-      float fDivAspect = projectionMatrix[0][0];
-      float f = projectionMatrix[1][1];
-      vec2 ndc = uv * 2.0 - 1.0;
-      float negZ = -viewZ;
-      vec3 pos;
-      pos.x = ndc.x * negZ / fDivAspect;
-      pos.y = ndc.y * negZ / f;
-      pos.z = viewZ;
-      return pos;
-    }
-
-    float getLogDepth(vec2 uv) {
-      return texture2D(depthTexture, uv).r;
+import { Color, DataTexture, DoubleSide, LinearFilter, MeshBasicMaterial, NoBlending, RGBAFormat, RawShaderMaterial, RepeatWrapping, Vector2, Vector3, WebGLRenderTarget, Matrix4, MultiplyBlending, PerspectiveCamera, OrthographicCamera } from "three";
+import fsQuad from "./fsQuad";
+/**
+ * 判断是否为「可透视的半透明表面」——这类物体不该在世界空间 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 const visibleDepthOptions = { includeFloor: false };
+const isSeeThroughSurface = (obj, includeFloor = 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;
     }
-
-    // 由 uv 直接得到真实视图空间位置（对数深度反解 viewZ 后再重建）
-    vec3 getViewPosition(vec2 uv) {
-      return reconstructPosition(uv, viewZFromLogDepth(getLogDepth(uv)));
+    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;
+};
+const isNonSurface = (obj, includeFloor = false) => {
+    const o = obj;
+    if (o.isSprite === true || o.isLine === true || o.isLine2 === true || o.isLineSegments2 === true || o.isPoints === true) {
+        return true;
     }
-
-    vec3 getViewNormal(vec2 uv) {
-      return unpackRGBToNormal(texture2D(normalTexture, uv).rgb);
-    }
-
-    // 采样点的 uv：直接读该 uv 处的「真实对数深度」，不再走常规投影（投影会把对数深度当线性算错）。
-    // 这里只返回 uv，深度由 getViewPosition(sampleUv) 内部用对数反解。
-    vec2 getSceneUv(vec3 sampleViewPos) {
-      // sampleViewPos 已是真实视图空间坐标，用常规投影求屏幕 uv（投影矩阵本身对位置是对的，
-      // 错只错在「深度纹理的编码」上，所以位置的投影反算没问题，只需读取采样点的真实对数深度）。
-      vec4 sampleClipPos = projectionMatrix * vec4(sampleViewPos, 1.0);
-      return sampleClipPos.xy / sampleClipPos.w * 0.5 + 0.5;
-    }
-
-    void main() {
-      float logDepth = getLogDepth(vUv);
-      if (logDepth >= 1.0) {
-        gl_FragColor = vec4(1.0);
-        return;
-      }
-      vec3 viewPos = getViewPosition(vUv);
-      vec3 viewNormal = getViewNormal(vUv);
-
-      // 退化/非法法线（长度为 0 或含 NaN，常见于缺法线的模型）无法做地平线积分，
-      // 按"无遮蔽"处理，避免整片被乘黑。NaN 检测用 x != x（GLSL ES 1.0 无 isnan）。
-      float normalLen2 = dot(viewNormal, viewNormal);
-      if (normalLen2 < 1e-4 || normalLen2 != normalLen2) {
-        gl_FragColor = vec4(1.0);
-        return;
-      }
-
-      float radiusToUse = ssaoRadius;
-      float thicknessToUse = ssaoFalloff;
-
-      vec2 noiseUv = vUv * resolution / noiseResolution;
-      vec4 noiseTexel = texture2D(tNoise, noiseUv);
-      vec3 randomVec = noiseTexel.xyz * 2.0 - 1.0;
-      vec3 tangent = normalize(vec3(randomVec.xy, 0.0));
-      vec3 bitangent = vec3(-tangent.y, tangent.x, 0.0);
-      mat3 kernelMatrix = mat3(tangent, bitangent, vec3(0.0, 0.0, 1.0));
-
-      // SAMPLES 为编译期常量（defines），由此推导 DIRECTIONS / STEPS
-      const int DIRECTIONS = SAMPLES < 30 ? 3 : 5;
-      const int STEPS = (SAMPLES + DIRECTIONS - 1) / DIRECTIONS;
-      float ao = 0.0;
-
-      for (int i = 0; i < DIRECTIONS; ++i) {
-        float angle = float(i) / float(DIRECTIONS) * PI;
-        vec4 sampleDir = vec4(cos(angle), sin(angle), 0.0, 0.5 + 0.5 * noiseTexel.w);
-        sampleDir.xyz = normalize(kernelMatrix * sampleDir.xyz);
-
-        vec3 viewDir = normalize(-viewPos.xyz);
-        vec3 sliceBitangent = normalize(cross(sampleDir.xyz, viewDir));
-        vec3 sliceTangent = cross(sliceBitangent, viewDir);
-        vec3 normalInSlice = normalize(viewNormal - sliceBitangent * dot(viewNormal, sliceBitangent));
-
-        vec3 tangentToNormalInSlice = cross(normalInSlice, sliceBitangent);
-        vec2 cosHorizons = vec2(dot(viewDir, tangentToNormalInSlice), dot(viewDir, -tangentToNormalInSlice));
-
-        for (int j = 0; j < STEPS; ++j) {
-          vec3 sampleViewOffset = sampleDir.xyz * radiusToUse * sampleDir.w * pow(float(j + 1) / float(STEPS), distanceExponent);
-
-          vec2 sampleUv0 = getSceneUv(viewPos + sampleViewOffset);
-          vec3 sampleSceneViewPos = getViewPosition(sampleUv0);
-          vec3 viewDelta = sampleSceneViewPos - viewPos;
-          // 切面阈值（bias）：只接受"沿法线方向有明显高度突起"的采样点；
-          // 大平面上同平面远采样点 sampleHeight≈0，低于 bias 即跳过，避免平地自身被误判遮蔽压黑。
-          float sampleHeight0 = dot(viewDelta, viewNormal);
-          if (abs(viewDelta.z) < thicknessToUse && sampleHeight0 > ssaoBias) {
-            float sampleCosHorizon = dot(viewDir, normalize(viewDelta));
-            cosHorizons.x += max(0.0, (sampleCosHorizon - cosHorizons.x) * mix(1.0, 2.0 / float(j + 2), distanceFallOff));
-          }
-
-          vec2 sampleUv1 = getSceneUv(viewPos - sampleViewOffset);
-          sampleSceneViewPos = getViewPosition(sampleUv1);
-          viewDelta = sampleSceneViewPos - viewPos;
-          float sampleHeight1 = dot(viewDelta, viewNormal);
-          if (abs(viewDelta.z) < thicknessToUse && sampleHeight1 > ssaoBias) {
-            float sampleCosHorizon = dot(viewDir, normalize(viewDelta));
-            cosHorizons.y += max(0.0, (sampleCosHorizon - cosHorizons.y) * mix(1.0, 2.0 / float(j + 2), distanceFallOff));
-          }
+    return isSeeThroughSurface(obj, includeFloor);
+};
+const hideNonSurface = (scene, includeFloor = false) => {
+    const list = [];
+    scene.traverse((obj) => {
+        if (isNonSurface(obj, includeFloor)) {
+            list.push({ obj, prev: obj.visible });
+            obj.visible = false;
         }
-
-        vec2 sinHorizons = sqrt(1.0 - cosHorizons * cosHorizons);
-        float nx = dot(normalInSlice, sliceTangent);
-        float ny = dot(normalInSlice, viewDir);
-        float nxb = 1.0 / 2.0 * (acos(cosHorizons.y) - acos(cosHorizons.x) + sinHorizons.x * cosHorizons.x - sinHorizons.y * cosHorizons.y);
-        float nyb = 1.0 / 2.0 * (2.0 - cosHorizons.x * cosHorizons.x - cosHorizons.y * cosHorizons.y);
-        float occlusion = nx * nxb + ny * nyb;
-        ao += occlusion;
-      }
-
-      ao = clamp(ao / float(DIRECTIONS), 0.0, 1.0);
-      ao = pow(ao, scale);
-
-      gl_FragColor = vec4(vec3(ao), 1.0);
-    }`,
-    blending: NoBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-// ---------------------------------------------------------------------------
-// Poisson 边缘保持去噪（双边去噪）
-// 取代旧版的 separable blur（仅用深度权重的高斯模糊）。这里同时依赖
-//   1) 法线（normalTexture，视图空间 RGB 法线，unpackRGBToNormal 解码）
-//   2) 深度（baseDepthTexture，对数深度，linearizeLogDepth 还原 viewZ）
-// 做双边权重：只有法线相近 + 沿法线方向深度相近的邻域样本才会被加权平均，
-// 因此能在去除 GTAO 噪点的同时，严格保住几何边缘，避免边缘被糊成一团。
-// 参考：three/examples/jsm/shaders/PoissonDenoiseShader.js（移植到 RawShaderMaterial /
-// GLSL ES 1.0，并把深度重建适配本项目的对数深度管线）。
-// ---------------------------------------------------------------------------
-// Poisson 采样点不再用预编译 GLSL 数组字面量（vec3[N](...) 是 GLSL ES 3.00 语法，
-// 本项目 RawShaderMaterial 默认 GLSL ES 1.00 不支持，会导致 shader 编译失败、
-// 去噪目标停留在清屏黑 → 整屏被 AO 乘法混合成全黑）。改为在 shader 内按
-// 官方 generateDenoiseSamples(samples, rings, radiusExponent) 的公式逐点程序化计算，
-// 与原来的数组完全等价，且兼容 GLSL ES 1.00。
-const poissonDenoiseShader = new RawShaderMaterial({
-    defines: {
-        SAMPLES: 32,
-        POISSON_RINGS: 2,
-        POISSON_RADIUS_EXP: 1,
-    },
-    uniforms: {
-        tDiffuse: { value: null },
-        tNormal: { value: null },
-        tDepth: { value: null },
-        tNoise: { value: noiseTexture },
-        resolution: { value: new Vector2(1 / 512, 1 / 512) },
-        noiseResolution: { value: new Vector2(NOISE_SIZE, NOISE_SIZE) },
-        inverseProjectionMatrix: { value: new Matrix4() },
-        projectionMatrix: { value: new Matrix4() },
-        cameraNear: { value: 0.1 },
-        cameraFar: { value: 20000 },
-        lumaPhi: { value: 5.0 },
-        depthPhi: { value: 5.0 },
-        normalPhi: { value: 5.0 },
-        radius: { value: 4.0 },
-    },
-    vertexShader: `
-    attribute vec3 position;
-    attribute vec2 uv;
-    varying vec2 vUv;
-    void main() {
-      vUv = uv;
-      gl_Position = vec4(position, 1.0);
-    }`,
-    fragmentShader: `
-    #ifdef GL_ES
-      precision highp float;
-    #endif
-
-    uniform sampler2D tDiffuse;
-    uniform sampler2D tNormal;
-    uniform sampler2D tDepth;
-    uniform sampler2D tNoise;
-    uniform vec2 resolution;
-    uniform vec2 noiseResolution;
-    uniform mat4 inverseProjectionMatrix;
-    uniform mat4 projectionMatrix;
-    uniform float cameraNear;
-    uniform float cameraFar;
-    uniform float lumaPhi;
-    uniform float depthPhi;
-    uniform float normalPhi;
-    uniform float radius;
-
-    varying vec2 vUv;
-
-    const float PI = 3.141592653589793;
-
-    // 复用与 GTAO 主 pass 完全一致的对数深度还原（logarithmicDepthBuffer 兼容）
-    // gl_FragDepth = log2(1.0 - viewZ) / log2(cameraFar + 1.0) → 反解 viewZ = 1.0 - 2^(logDepth*log2(far+1))
-    float viewZFromLogDepth(float logDepth) {
-      return 1.0 - pow(2.0, logDepth * log2(cameraFar + 1.0));
-    }
-    vec3 unpackRGBToNormal(vec3 rgb) {
-      return rgb * 2.0 - 1.0;
-    }
-    vec3 reconstructPosition(vec2 uv, float viewZ) {
-      // 与主 GTAO pass 同款解析构造（避免 inverseProjectionMatrix 反投影 ndc.z=0 的方向符号陷阱）
-      float fDivAspect = projectionMatrix[0][0];
-      float f = projectionMatrix[1][1];
-      vec2 ndc = uv * 2.0 - 1.0;
-      float negZ = -viewZ;
-      vec3 pos;
-      pos.x = ndc.x * negZ / fDivAspect;
-      pos.y = ndc.y * negZ / f;
-      pos.z = viewZ;
-      return pos;
-    }
-    float getLogDepth(vec2 uv) {
-      return texture2D(tDepth, uv).r;
-    }
-    vec3 getViewPosition(vec2 uv) {
-      return reconstructPosition(uv, viewZFromLogDepth(getLogDepth(uv)));
-    }
-    vec3 getViewNormal(vec2 uv) {
-      return unpackRGBToNormal(texture2D(tNormal, uv).rgb);
+    });
+    return list;
+};
+const restoreVisibility = (list) => {
+    list.forEach(({ obj, prev }) => (obj.visible = prev));
+};
+/**
+ * 深度 pass：固定排除非实体表面后，将场景深度渲染到 depthRenderTarget。
+ * depthRenderTarget.depthTexture 即 baseDepthTexture，供 SSAO / 描边 / 发光等后续 pass 复用。
+ * 排除的非实体对象（sprite/线条/点）在深度图保留 clear 深度(1.0=远)，与背景一致；排除的
+ * 半透明对象则保留其身后不透明几何的深度（身后无几何时同样为 1.0）。均不影响颜色通道渲染。
+ */
+export function renderAoDepthPass(renderer, camera, scene, depthRenderTarget, includeFloor = false) {
+    const hidden = hideNonSurface(scene, includeFloor);
+    // ⚠️ 深度预通道铁律：必须让所有「未被排除」的可见表面都写入深度，深度图才有真实的几何遮挡信息。
+    // 透明材质（特效载体、半透明墙、alpha 贴图实体等）大多 transparent:true 且 depthWrite:false，
+    // 若不强转，它们不会写进 baseDepthTexture → 深度图只剩不透明几何 → 描边/辉光/毛玻璃/覆盖色
+    // 依赖 baseDepthTexture 的遮挡判定全部失效、一律显示在前（即本次回归根因）。
+    // 被排除的半透明面（aoTransparent / aoFloor / Mirror-aoOpaque 等）已在 hideNonSurface 中隐藏，
+    // 此处根本不会触及，故不影响 see-through 设计；其余透明面强制写深度 = 作为实体参与遮挡，符合预期。
+    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;
+            }
+        });
+    });
+    const prevRenderTarget = renderer.getRenderTarget();
+    renderer.setRenderTarget(depthRenderTarget);
+    renderer.clear();
+    renderer.render(scene, camera);
+    // 还原 depthWrite，避免污染后续颜色通道渲染的透明混合
+    depthWriteRestore.forEach(({ mat, val }) => { mat.depthWrite = val; });
+    restoreVisibility(hidden);
+    renderer.setRenderTarget(prevRenderTarget);
+}
+/**
+ * 调试用：把「被排除出可见深度图」的表面单独渲成红色 mask。
+ *
+ * 这些面在 renderAoDepthPass 里被 hideNonSurface 隐藏，因此**不会写进 baseDepthTexture**，
+ * 也就永远挡不住描边/辉光/毛玻璃/覆盖色 —— 这正是"深度测试看起来失效"最常见的成因
+ * （用户以为是 bug，其实是该面被设计成可透视：sprite/线条/点、userData.aoTransparent、
+ * 以及标了 userData.aoFloor 的地板 Ground1）。
+ * 面板「深度调试 → 排除面标记」叠加显示：灰=能挡住的真实遮挡面，红=被排除、挡不住任何东西。
+ *
+ * 只渲染 Mesh：sprite / Line2 / Points 在 MeshBasicMaterial override 下渲染异常（见文件头注释），
+ * 且它们数量少、用户关心的遮挡体基本都是 Mesh，故跳过。
+ */
+export function renderExcludedMaskPass(renderer, camera, scene, maskRenderTarget, includeFloor = false) {
+    const maskMaterial = new MeshBasicMaterial({
+        color: 0xff0000,
+        depthTest: false,
+        depthWrite: false,
+        side: DoubleSide,
+    });
+    const prevVisible = [];
+    scene.traverse((obj) => {
+        const isMesh = obj.isMesh === true;
+        prevVisible.push({ obj, prev: obj.visible });
+        // 只显示「被排除的 Mesh」：其余一律隐藏，得到纯黑底 + 红面的 mask
+        obj.visible = isMesh && isNonSurface(obj, includeFloor);
+    });
+    const prevOverride = scene.overrideMaterial;
+    const prevTarget = renderer.getRenderTarget();
+    const prevClear = renderer.getClearColor(new Color());
+    const prevAlpha = renderer.getClearAlpha();
+    scene.overrideMaterial = maskMaterial;
+    renderer.setRenderTarget(maskRenderTarget);
+    renderer.setClearColor(0x000000, 1);
+    renderer.clear();
+    renderer.render(scene, camera);
+    renderer.setClearColor(prevClear, prevAlpha);
+    renderer.setRenderTarget(prevTarget);
+    scene.overrideMaterial = prevOverride;
+    restoreVisibility(prevVisible);
+    maskMaterial.dispose();
+}
+/**
+ * 法线 pass（仅 SSAO 开启时需要）：固定排除非实体表面后，以中性灰清屏 + normalMaterial
+ * override 将视图空间法线渲染到 normalRenderTarget，供 GTAO 风格 SSAO 使用。
+ * 排除对象在法线图保留中性灰清屏色 → unpackRGBToNormal(0.5,0.5,0.5)=(0,0,0) →
+ * SSAO 退化法线守卫判"无遮蔽"(=1)，避免精灵弹窗被 AO 乘黑。清屏色用后即还原。
+ */
+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;
+            }
+        });
+    });
+    const prevRenderTarget = renderer.getRenderTarget();
+    const prevClearColor = new Color();
+    renderer.getClearColor(prevClearColor);
+    const prevClearAlpha = renderer.getClearAlpha();
+    renderer.setClearColor(new Color(0.5, 0.5, 0.5), 1);
+    renderer.setRenderTarget(normalRenderTarget);
+    renderer.clear();
+    scene.overrideMaterial = normalMaterial;
+    renderer.render(scene, camera);
+    scene.overrideMaterial = null;
+    restoreVisibility(hidden);
+    depthWriteRestore.forEach(({ mat, val }) => { mat.depthWrite = val; });
+    renderer.setClearColor(prevClearColor, prevClearAlpha);
+    renderer.setRenderTarget(prevRenderTarget);
+}
+// 噪声贴图尺寸（奇数，magic square 要求奇数）。越大 → 旋转/半径抖动越细，
+// GTAO 各向异性（转视角时 AO 范围"呼吸"）越弱。17×17=289 种独立样本远多于默认的 5×5=25。
+const NOISE_SIZE = 17;
+// ---------------------------------------------------------------------------
+// GTAO 风格 SSAO（地平线积分）
+// 相对旧版手写 SSAO 的两点关键改进：
+//   1. 法线直接来自视图空间法线纹理（MeshNormalMaterial 渲染），不再用深度差分重建，
+//      从根本上消除噪声与边缘抖动。
+//   2. 采样采用 Ground Truth Ambient Occlusion 的地平线积分（horizon-based），
+//      几乎无 halo（光晕）与漏光。
+// 深度仍使用项目的对数深度（logarithmicDepthBuffer: true），通过 linearizeLogDepth
+// 还原 viewZ，与旧版保持一致；法线纹理来自 ThreeBase 的 normalRenderTarget。
+// 参考：three/examples/jsm/shaders/GTAOShader.js 的 horizon-based 积分核心。
+// 去噪：GTAO 计算的 AO 仍带高频噪声，这里用 Poisson 边缘保持去噪（双边去噪，
+// 依赖 normalTexture + baseDepthTexture）取代旧版 separable 高斯模糊，能在去噪的同时
+// 严格守住几何边缘。参考 three/examples/jsm/shaders/PoissonDenoiseShader.js。
+// ---------------------------------------------------------------------------
+const ssaoTextureTarget = new WebGLRenderTarget(512, 512, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+});
+const blurTextureTarget = new WebGLRenderTarget(512, 512, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    format: RGBAFormat,
+});
+const size = new Vector2();
+const projectionMatrix = new Matrix4();
+const inverseProjectionMatrix = new Matrix4();
+// 低差异方向旋转噪声（magic square noise），用于旋转每个像素的采样核，避免带状瑕疵
+function generateMagicSquare(size) {
+    const noiseSize = Math.floor(size) % 2 === 0 ? Math.floor(size) + 1 : Math.floor(size);
+    const noiseSquareSize = noiseSize * noiseSize;
+    const magicSquare = new Array(noiseSquareSize).fill(0);
+    let i = Math.floor(noiseSize / 2);
+    let j = noiseSize - 1;
+    for (let num = 1; num <= noiseSquareSize;) {
+        if (i === -1 && j === noiseSize) {
+            j = noiseSize - 2;
+            i = 0;
+        }
+        else {
+            if (j === noiseSize) {
+                j = 0;
+            }
+            if (i < 0) {
+                i = noiseSize - 1;
+            }
+        }
+        if (magicSquare[i * noiseSize + j] !== 0) {
+            j -= 2;
+            i++;
+            continue;
+        }
+        else {
+            magicSquare[i * noiseSize + j] = num++;
+        }
+        j++;
+        i--;
     }
-
-    // 双边去噪的单次样本加权：luma（AO 灰度，恒近似相等）+ 法线相似度 + 沿法线深度差
-    // 三者相乘得到权重；AO 是灰度图，luma 项近似为 1，主要靠法线 + 深度做边缘保持。
-    void denoiseSample(in vec3 center, in vec3 viewNormal, in vec3 viewPos, in vec2 sampleUv, inout vec3 denoised, inout float totalWeight) {
-      vec3 neighborColor = texture2D(tDiffuse, sampleUv).rgb;
-      vec3 sampleNormal = getViewNormal(sampleUv);
-      vec3 viewPosSample = getViewPosition(sampleUv);
-
-      float normalDiff = dot(viewNormal, sampleNormal);
-      float normalSimilarity = pow(max(normalDiff, 0.0), normalPhi);
-      float lumaDiff = abs(length(neighborColor) - length(center));
-      float lumaSimilarity = max(1.0 - lumaDiff / lumaPhi, 0.0);
-      float depthDiff = abs(dot(viewPos - viewPosSample, viewNormal));
-      float depthSimilarity = max(1.0 - depthDiff / depthPhi, 0.0);
-      float w = lumaSimilarity * depthSimilarity * normalSimilarity;
-
-      denoised += w * neighborColor;
-      totalWeight += w;
+    return magicSquare;
+}
+function generateMagicSquareNoise(size = NOISE_SIZE) {
+    const noiseSize = Math.floor(size) % 2 === 0 ? Math.floor(size) + 1 : Math.floor(size);
+    const magicSquare = generateMagicSquare(noiseSize);
+    const noiseSquareSize = magicSquare.length;
+    const data = new Uint8Array(noiseSquareSize * 4);
+    // 用确定性伪随机给每个像素一个 [0,1] 的 w 通道（用于采样半径抖动 sampleDir.w），
+    // 同时 xy 仍由 magic square 角度决定（保证方向分布均匀无聚集）。
+    // ⚠️ 旧实现把 w 通道写死 255（=1.0），导致 sampleDir.w 恒等于 1.0，
+    // 半径抖动完全失效、旋转方向只有 25 种 → GTAO 各向异性明显（转视角 AO 范围"呼吸"）。
+    for (let inx = 0; inx < noiseSquareSize; ++inx) {
+        const iAng = magicSquare[inx];
+        const angle = (2 * Math.PI * iAng) / noiseSquareSize;
+        const randomVec = new Vector3(Math.cos(angle), Math.sin(angle), 0).normalize();
+        // 每像素独立伪随机种子（基于行列索引），避免 w 通道规律化
+        const row = Math.floor(inx / noiseSize);
+        const col = inx % noiseSize;
+        const rnd = ((row * 73856093) ^ (col * 19349663) ^ (inx * 83492791)) >>> 0;
+        const wRand = (rnd % 1000) / 1000; // [0,1)
+        data[inx * 4] = (randomVec.x * 0.5 + 0.5) * 255;
+        data[inx * 4 + 1] = (randomVec.y * 0.5 + 0.5) * 255;
+        data[inx * 4 + 2] = 127;
+        data[inx * 4 + 3] = Math.floor(wRand * 255); // 半径抖动真正生效
     }
-
-    void main() {
-      float depth = getLogDepth(vUv);
-      vec4 texel = texture2D(tDiffuse, vUv);
-      // 背景（无几何）：直接透传原 AO（白），不做去噪
-      if (depth >= 1.0) {
-        gl_FragColor = texel;
-        return;
-      }
-      vec3 viewNormal = getViewNormal(vUv);
-      // 退化/非法法线（含 NaN）按原 AO 透传，避免双边去噪把整片刷黑
-      float nLen2 = dot(viewNormal, viewNormal);
-      if (nLen2 == 0.0 || nLen2 != nLen2) {
-        gl_FragColor = texel;
-        return;
-      }
-      vec3 center = texel.rgb;
-      vec3 viewPos = getViewPosition(vUv);
-
-      vec2 noiseUv = vUv * resolution / noiseResolution;
-      vec4 noiseTexel = texture2D(tNoise, noiseUv);
-      vec2 noiseVec = vec2(sin(noiseTexel.x * 2.0 * PI), cos(noiseTexel.x * 2.0 * PI));
-      mat2 rotationMatrix = mat2(noiseVec.x, -noiseVec.y, noiseVec.x, noiseVec.y);
-
-      float totalWeight = 1.0;
-      vec3 denoised = texel.rgb;
-      for (int i = 0; i < SAMPLES; i++) {
-        // 与官方 generateDenoiseSamples(samples, POISSON_RINGS, POISSON_RADIUS_EXP) 完全等价的逐点计算
-        float fi = float(i);
-        float angle = 2.0 * PI * float(POISSON_RINGS) * fi / float(SAMPLES);
-        float radiusF = pow(fi / float(SAMPLES - 1), float(POISSON_RADIUS_EXP));
-        vec3 sampleDir = vec3(cos(angle), sin(angle), radiusF);
-        vec2 offset = rotationMatrix * (sampleDir.xy * (1.0 + sampleDir.z * (radius - 1.0)) / resolution);
-        vec2 sampleUv = vUv + offset;
-        denoiseSample(center, viewNormal, viewPos, sampleUv, denoised, totalWeight);
-      }
-
-      if (totalWeight > 0.0) {
-        denoised /= totalWeight;
-      }
-      gl_FragColor = vec4(denoised, 1.0);
-    }`,
-    blending: NoBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-const outputShader = new RawShaderMaterial({
-    uniforms: {
-        ssaoTexture: { value: null },
-        ssaoStrength: { value: 1.0 },
-        debug: { value: 0.0 },
-        // 可见深度（排除地板，= baseDepthTexture）：代表"真实可见表面"的深度。
-        tColorDepth: { value: null },
-        // AO 深度（含地板，= normalRenderTarget.depthTexture，法线 pass 顺带写入）：GTAO 实际采样的深度。
-        tAoDepth: { value: null },
-    },
-    vertexShader: `
-    attribute vec3 position;
-    attribute vec2 uv;
-    varying vec2 vUv;
-    void main() {
-      vUv = uv;
-      gl_Position = vec4(position, 1.0);
-    }`,
-    fragmentShader: `
-    #ifdef GL_ES
-      precision highp float;
-    #endif
-
-    uniform sampler2D ssaoTexture;
-    uniform float ssaoStrength;
-    uniform float debug;
-    uniform sampler2D tColorDepth;
-    uniform sampler2D tAoDepth;
-
-    varying vec2 vUv;
-
-    void main() {
-      float ssao = texture2D(ssaoTexture, vUv).r;
-
-      // 复合守卫：对数深度越小越近。若"含地板的 AO 深度"比"可见深度"更近，
-      // 说明该像素的真实可见表面位于半透明地板之后（典型的从下方透视地板看身后实体），
-      // 地板算出的接触 AO 不该乘到它身上 → 视为无遮蔽(=1)，即"被遮挡的部分就不要 ssao"。
-      // 仅在最终合成时生效；debug 模式直接看 GTAO 原始 AO 图（含地板接触 AO），便于排查。
-      float dColor = texture2D(tColorDepth, vUv).r;
-      float dAo = texture2D(tAoDepth, vUv).r;
-      if (debug < 0.5 && dAo < dColor - 0.0001) {
-        ssao = 1.0;
-      }
-
-      float finalOcclusion = mix(1.0, ssao, ssaoStrength);
-
-      if (debug > 0.5) {
-        gl_FragColor = vec4(vec3(ssao), 1.0);
-      } else {
-        gl_FragColor = vec4(vec3(finalOcclusion), 1.0);
-      }
-    }`,
-    blending: MultiplyBlending,
-    depthTest: false,
-    depthWrite: false,
-    transparent: true,
-});
-export default function ssao_pass(renderer, camera, scene, depthRenderTarget, normalRenderTarget, normalMaterial, devicePixelRatio, options) {
-    // ⚠️ 早退只看 enable：strength/intensity 是"叠加强度"，0 表示"不叠加 AO"而不是"关掉这个 pass"。
-    // 旧代码写成 `!options.enable || !options.strength`，强度调到 0 会跳过整条 pass（连法线准备也停），
-    // debug 模式下就再也看不到 AO 图，语义也和"强度 = 0"混在一起。
-    if (!options.enable) {
+    const noiseTexture = new DataTexture(data, noiseSize, noiseSize);
+    noiseTexture.wrapS = RepeatWrapping;
+    noiseTexture.wrapT = RepeatWrapping;
+    noiseTexture.needsUpdate = true;
+    return noiseTexture;
+}
+const noiseTexture = generateMagicSquareNoise();
+const ssaoShader = new RawShaderMaterial({
+    defines: {
+        SAMPLES: 32,
+    },
+    uniforms: {
+        depthTexture: { value: null },
+        normalTexture: { value: null },
+        tNoise: { value: noiseTexture },
+        resolution: { value: new Vector2(1 / 512, 1 / 512) },
+        noiseResolution: { value: new Vector2(NOISE_SIZE, NOISE_SIZE) },
+        projectionMatrix: { value: new Matrix4() },
+        inverseProjectionMatrix: { value: new Matrix4() },
+        ssaoRadius: { value: 5.0 },
+        ssaoFalloff: { value: 5.0 },
+        ssaoBias: { value: 0.01 },
+        scale: { value: 1.0 },
+        cameraNear: { value: 0.1 },
+        cameraFar: { value: 20000 },
+        distanceExponent: { value: 1.0 },
+        distanceFallOff: { value: 1.0 },
+    },
+    vertexShader: `
+    attribute vec3 position;
+    attribute vec2 uv;
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = vec4(position, 1.0);
+    }`,
+    fragmentShader: `
+    #ifdef GL_ES
+      precision highp float;
+    #endif
+
+    uniform sampler2D depthTexture;
+    uniform sampler2D normalTexture;
+    uniform sampler2D tNoise;
+    uniform vec2 resolution;
+    uniform vec2 noiseResolution;
+    uniform mat4 projectionMatrix;
+    uniform mat4 inverseProjectionMatrix;
+    uniform float ssaoRadius;
+    uniform float ssaoFalloff;
+    uniform float ssaoBias;
+    uniform float scale;
+    uniform float cameraNear;
+    uniform float cameraFar;
+    uniform float distanceExponent;
+    uniform float distanceFallOff;
+
+    varying vec2 vUv;
+
+    const float PI = 3.141592653589793;
+
+    // ⚠️ 关键：本项目渲染器 logarithmicDepthBuffer:true，baseDepthTexture 存的是「对数编码」的 gl_FragDepth。
+    // three.js r167 写深度（logdepthbuf_fragment，透视下 gl_Position.w = -viewZ）：
+    //   gl_FragDepth = log2(1.0 - viewZ) / log2(cameraFar + 1.0)
+    // 反解得真实视图空间 Z（负值 = 相机前方）：
+    //   viewZ = 1.0 - 2^(logDepth * log2(cameraFar + 1.0))
+    // 注：three.js 的 perspectiveDepthToViewZ() 期望的是「常规透视非线性深度」(gl_FragCoord.z)，
+    // 与这里的对数编码是完全不同的两套，不能直接套用——对数深度必须显式解指数。
+    // （Python 数值复算验证：该公式对任意距离还原误差 = 0，perspectiveDepthToViewZ 误差高达数米级。）
+    float viewZFromLogDepth(float logDepth) {
+      return 1.0 - pow(2.0, logDepth * log2(cameraFar + 1.0));
+    }
+
+    // MeshNormalMaterial 把视图空间法线 pack 到 [0,1]，这里解回 [-1,1]
+    vec3 unpackRGBToNormal(vec3 rgb) {
+      return rgb * 2.0 - 1.0;
+    }
+
+    // 由 uv + 真实 viewZ 重建视图空间位置。
+    // 透视投影下：ndc.xy = clip.xy/clip.w，clip.xy = (f/aspect * X, f * Y)，clip.w = -viewZ
+    // 反解得 X = ndc.x * (-viewZ) / (f/aspect)，Y = ndc.y * (-viewZ) / f，Z = viewZ。
+    // 注意：旧写法用 inverseProjectionMatrix 反投影 ndc.z=0 取「方向」再乘 viewZ/(-dir.z)，
+    // 会把方向翻到相机背后（z/y 反号），导致平地重建到天顶方向 → GTAO 把开阔地面误判遮蔽压黑。
+    // 这里直接由 viewZ 解析构造，无符号陷阱，且对数深度已在外层 viewZFromLogDepth 还原成真实 viewZ，
+    // 与本函数无关（不再依赖 projectionMatrix 的逆，故 inverseProjectionMatrix uniform 可保留也可移除）。
+    vec3 reconstructPosition(vec2 uv, float viewZ) {
+      // 透视投影：projectionMatrix[0][0] = f/aspect，projectionMatrix[1][1] = f，clip.w = -viewZ
+      float fDivAspect = projectionMatrix[0][0];
+      float f = projectionMatrix[1][1];
+      vec2 ndc = uv * 2.0 - 1.0;
+      float negZ = -viewZ;
+      vec3 pos;
+      pos.x = ndc.x * negZ / fDivAspect;
+      pos.y = ndc.y * negZ / f;
+      pos.z = viewZ;
+      return pos;
+    }
+
+    float getLogDepth(vec2 uv) {
+      return texture2D(depthTexture, uv).r;
+    }
+
+    // 由 uv 直接得到真实视图空间位置（对数深度反解 viewZ 后再重建）
+    vec3 getViewPosition(vec2 uv) {
+      return reconstructPosition(uv, viewZFromLogDepth(getLogDepth(uv)));
+    }
+
+    vec3 getViewNormal(vec2 uv) {
+      return unpackRGBToNormal(texture2D(normalTexture, uv).rgb);
+    }
+
+    // 采样点的 uv：直接读该 uv 处的「真实对数深度」，不再走常规投影（投影会把对数深度当线性算错）。
+    // 这里只返回 uv，深度由 getViewPosition(sampleUv) 内部用对数反解。
+    vec2 getSceneUv(vec3 sampleViewPos) {
+      // sampleViewPos 已是真实视图空间坐标，用常规投影求屏幕 uv（投影矩阵本身对位置是对的，
+      // 错只错在「深度纹理的编码」上，所以位置的投影反算没问题，只需读取采样点的真实对数深度）。
+      vec4 sampleClipPos = projectionMatrix * vec4(sampleViewPos, 1.0);
+      return sampleClipPos.xy / sampleClipPos.w * 0.5 + 0.5;
+    }
+
+    void main() {
+      float logDepth = getLogDepth(vUv);
+      if (logDepth >= 1.0) {
+        gl_FragColor = vec4(1.0);
+        return;
+      }
+      vec3 viewPos = getViewPosition(vUv);
+      vec3 viewNormal = getViewNormal(vUv);
+
+      // 退化/非法法线（长度为 0 或含 NaN，常见于缺法线的模型）无法做地平线积分，
+      // 按"无遮蔽"处理，避免整片被乘黑。NaN 检测用 x != x（GLSL ES 1.0 无 isnan）。
+      float normalLen2 = dot(viewNormal, viewNormal);
+      if (normalLen2 < 1e-4 || normalLen2 != normalLen2) {
+        gl_FragColor = vec4(1.0);
         return;
+      }
+
+      float radiusToUse = ssaoRadius;
+      float thicknessToUse = ssaoFalloff;
+
+      vec2 noiseUv = vUv * resolution / noiseResolution;
+      vec4 noiseTexel = texture2D(tNoise, noiseUv);
+      vec3 randomVec = noiseTexel.xyz * 2.0 - 1.0;
+      vec3 tangent = normalize(vec3(randomVec.xy, 0.0));
+      vec3 bitangent = vec3(-tangent.y, tangent.x, 0.0);
+      mat3 kernelMatrix = mat3(tangent, bitangent, vec3(0.0, 0.0, 1.0));
+
+      // SAMPLES 为编译期常量（defines），由此推导 DIRECTIONS / STEPS
+      const int DIRECTIONS = SAMPLES < 30 ? 3 : 5;
+      const int STEPS = (SAMPLES + DIRECTIONS - 1) / DIRECTIONS;
+      float ao = 0.0;
+
+      for (int i = 0; i < DIRECTIONS; ++i) {
+        float angle = float(i) / float(DIRECTIONS) * PI;
+        vec4 sampleDir = vec4(cos(angle), sin(angle), 0.0, 0.5 + 0.5 * noiseTexel.w);
+        sampleDir.xyz = normalize(kernelMatrix * sampleDir.xyz);
+
+        vec3 viewDir = normalize(-viewPos.xyz);
+        vec3 sliceBitangent = normalize(cross(sampleDir.xyz, viewDir));
+        vec3 sliceTangent = cross(sliceBitangent, viewDir);
+        vec3 normalInSlice = normalize(viewNormal - sliceBitangent * dot(viewNormal, sliceBitangent));
+
+        vec3 tangentToNormalInSlice = cross(normalInSlice, sliceBitangent);
+        vec2 cosHorizons = vec2(dot(viewDir, tangentToNormalInSlice), dot(viewDir, -tangentToNormalInSlice));
+
+        for (int j = 0; j < STEPS; ++j) {
+          vec3 sampleViewOffset = sampleDir.xyz * radiusToUse * sampleDir.w * pow(float(j + 1) / float(STEPS), distanceExponent);
+
+          vec2 sampleUv0 = getSceneUv(viewPos + sampleViewOffset);
+          vec3 sampleSceneViewPos = getViewPosition(sampleUv0);
+          vec3 viewDelta = sampleSceneViewPos - viewPos;
+          // 切面阈值（bias）：只接受"沿法线方向有明显高度突起"的采样点；
+          // 大平面上同平面远采样点 sampleHeight≈0，低于 bias 即跳过，避免平地自身被误判遮蔽压黑。
+          float sampleHeight0 = dot(viewDelta, viewNormal);
+          if (abs(viewDelta.z) < thicknessToUse && sampleHeight0 > ssaoBias) {
+            float sampleCosHorizon = dot(viewDir, normalize(viewDelta));
+            cosHorizons.x += max(0.0, (sampleCosHorizon - cosHorizons.x) * mix(1.0, 2.0 / float(j + 2), distanceFallOff));
+          }
+
+          vec2 sampleUv1 = getSceneUv(viewPos - sampleViewOffset);
+          sampleSceneViewPos = getViewPosition(sampleUv1);
+          viewDelta = sampleSceneViewPos - viewPos;
+          float sampleHeight1 = dot(viewDelta, viewNormal);
+          if (abs(viewDelta.z) < thicknessToUse && sampleHeight1 > ssaoBias) {
+            float sampleCosHorizon = dot(viewDir, normalize(viewDelta));
+            cosHorizons.y += max(0.0, (sampleCosHorizon - cosHorizons.y) * mix(1.0, 2.0 / float(j + 2), distanceFallOff));
+          }
+        }
+
+        vec2 sinHorizons = sqrt(1.0 - cosHorizons * cosHorizons);
+        float nx = dot(normalInSlice, sliceTangent);
+        float ny = dot(normalInSlice, viewDir);
+        float nxb = 1.0 / 2.0 * (acos(cosHorizons.y) - acos(cosHorizons.x) + sinHorizons.x * cosHorizons.x - sinHorizons.y * cosHorizons.y);
+        float nyb = 1.0 / 2.0 * (2.0 - cosHorizons.x * cosHorizons.x - cosHorizons.y * cosHorizons.y);
+        float occlusion = nx * nxb + ny * nyb;
+        ao += occlusion;
+      }
+
+      ao = clamp(ao / float(DIRECTIONS), 0.0, 1.0);
+      ao = pow(ao, scale);
+
+      gl_FragColor = vec4(vec3(ao), 1.0);
+    }`,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+// ---------------------------------------------------------------------------
+// Poisson 边缘保持去噪（双边去噪）
+// 取代旧版的 separable blur（仅用深度权重的高斯模糊）。这里同时依赖
+//   1) 法线（normalTexture，视图空间 RGB 法线，unpackRGBToNormal 解码）
+//   2) 深度（baseDepthTexture，对数深度，linearizeLogDepth 还原 viewZ）
+// 做双边权重：只有法线相近 + 沿法线方向深度相近的邻域样本才会被加权平均，
+// 因此能在去除 GTAO 噪点的同时，严格保住几何边缘，避免边缘被糊成一团。
+// 参考：three/examples/jsm/shaders/PoissonDenoiseShader.js（移植到 RawShaderMaterial /
+// GLSL ES 1.0，并把深度重建适配本项目的对数深度管线）。
+// ---------------------------------------------------------------------------
+// Poisson 采样点不再用预编译 GLSL 数组字面量（vec3[N](...) 是 GLSL ES 3.00 语法，
+// 本项目 RawShaderMaterial 默认 GLSL ES 1.00 不支持，会导致 shader 编译失败、
+// 去噪目标停留在清屏黑 → 整屏被 AO 乘法混合成全黑）。改为在 shader 内按
+// 官方 generateDenoiseSamples(samples, rings, radiusExponent) 的公式逐点程序化计算，
+// 与原来的数组完全等价，且兼容 GLSL ES 1.00。
+const poissonDenoiseShader = new RawShaderMaterial({
+    defines: {
+        SAMPLES: 32,
+        POISSON_RINGS: 2,
+        POISSON_RADIUS_EXP: 1,
+    },
+    uniforms: {
+        tDiffuse: { value: null },
+        tNormal: { value: null },
+        tDepth: { value: null },
+        tNoise: { value: noiseTexture },
+        resolution: { value: new Vector2(1 / 512, 1 / 512) },
+        noiseResolution: { value: new Vector2(NOISE_SIZE, NOISE_SIZE) },
+        inverseProjectionMatrix: { value: new Matrix4() },
+        projectionMatrix: { value: new Matrix4() },
+        cameraNear: { value: 0.1 },
+        cameraFar: { value: 20000 },
+        lumaPhi: { value: 5.0 },
+        depthPhi: { value: 5.0 },
+        normalPhi: { value: 5.0 },
+        radius: { value: 4.0 },
+    },
+    vertexShader: `
+    attribute vec3 position;
+    attribute vec2 uv;
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = vec4(position, 1.0);
+    }`,
+    fragmentShader: `
+    #ifdef GL_ES
+      precision highp float;
+    #endif
+
+    uniform sampler2D tDiffuse;
+    uniform sampler2D tNormal;
+    uniform sampler2D tDepth;
+    uniform sampler2D tNoise;
+    uniform vec2 resolution;
+    uniform vec2 noiseResolution;
+    uniform mat4 inverseProjectionMatrix;
+    uniform mat4 projectionMatrix;
+    uniform float cameraNear;
+    uniform float cameraFar;
+    uniform float lumaPhi;
+    uniform float depthPhi;
+    uniform float normalPhi;
+    uniform float radius;
+
+    varying vec2 vUv;
+
+    const float PI = 3.141592653589793;
+
+    // 复用与 GTAO 主 pass 完全一致的对数深度还原（logarithmicDepthBuffer 兼容）
+    // gl_FragDepth = log2(1.0 - viewZ) / log2(cameraFar + 1.0) → 反解 viewZ = 1.0 - 2^(logDepth*log2(far+1))
+    float viewZFromLogDepth(float logDepth) {
+      return 1.0 - pow(2.0, logDepth * log2(cameraFar + 1.0));
+    }
+    vec3 unpackRGBToNormal(vec3 rgb) {
+      return rgb * 2.0 - 1.0;
+    }
+    vec3 reconstructPosition(vec2 uv, float viewZ) {
+      // 与主 GTAO pass 同款解析构造（避免 inverseProjectionMatrix 反投影 ndc.z=0 的方向符号陷阱）
+      float fDivAspect = projectionMatrix[0][0];
+      float f = projectionMatrix[1][1];
+      vec2 ndc = uv * 2.0 - 1.0;
+      float negZ = -viewZ;
+      vec3 pos;
+      pos.x = ndc.x * negZ / fDivAspect;
+      pos.y = ndc.y * negZ / f;
+      pos.z = viewZ;
+      return pos;
     }
-    // 记录当前渲染目标，最终 SSAO 乘法叠加到它上面。⚠️ 调用方决定输出目标——
-    // ThreeBase（2026-09-14 起）在深度 pass 之后、对象级特效之前调用，此时绑定的是 baseRenderTarget，
-    // 故 AO 直接乘进 base，描边/发光/覆盖/磨砂都叠在 AO 之上不被压暗；末尾统一 FXAA 输出到屏幕，
-    // 覆盖 SSAO 自身的硬边。改动调用顺序时，本 pass 无需修改（输出到"绑定的那个目标"即可）。
-    const originRenderTarget = renderer.getRenderTarget();
-    // 法线 pass：地板保留（includeFloor=true），接触 AO 需要地板的视图空间法线。
-    // ⭐ 深度白拿（2026-09-14 优化）：normalRenderTarget 挂着 aoDepthTexture 作 depth attachment，
-    // 这一次渲染的深度由光栅器顺带写入 → 直接就是「含地板」的 AO 深度，**不再单独渲一遍深度 pass**。
-    // （原先法线 pass 之后还要再渲一遍「含地板深度」——它与法线 pass 的排除集完全相同，
-    //   属于重复遍历全场景，2026-09-14 已删。）
-    // 前提：renderAoNormalPass 内部已把 depthWrite=false 的透明材质强转 true，保证写入面集合一致。
-    renderAoNormalPass(renderer, camera, scene, normalRenderTarget, normalMaterial, true);
-    // 可见深度（地板排除）= baseDepthTexture，既是描边/辉光/毛玻璃的遮挡参考，也是"真实可见表面"参考。
-    const colorDepthTexture = depthRenderTarget.depthTexture;
-    // AO 深度（含地板）：GTAO 与去噪采样它，能算出物体落在地板上的接触 AO。
-    const aoDepthTexture = normalRenderTarget.depthTexture;
-    const normalTexture = normalRenderTarget.texture;
-    renderer.getSize(size);
-    const resScale = options.resolutionScale ?? 0.5;
-    const ssaoW = Math.round(size.x * devicePixelRatio * resScale);
-    const ssaoH = Math.round(size.y * devicePixelRatio * resScale);
-    ssaoTextureTarget.setSize(ssaoW, ssaoH);
-    blurTextureTarget.setSize(ssaoW, ssaoH);
-    projectionMatrix.copy(camera.projectionMatrix);
-    inverseProjectionMatrix.copy(projectionMatrix).invert();
-    // SAMPLES 由 sampleCount 决定（编译期常量，改变需重新编译 shader）
-    const samples = options.sampleCount || 32;
-    if (ssaoShader.defines.SAMPLES !== samples) {
-        ssaoShader.defines.SAMPLES = samples;
-        ssaoShader.needsUpdate = true;
+    float getLogDepth(vec2 uv) {
+      return texture2D(tDepth, uv).r;
     }
-    ssaoShader.uniforms.depthTexture.value = aoDepthTexture;
-    ssaoShader.uniforms.normalTexture.value = normalTexture;
-    // resolution 传像素尺寸：供 GTAO 噪声按屏幕平铺（与官方 GTAOPass 一致）
-    ssaoShader.uniforms.resolution.value.set(ssaoW, ssaoH);
-    ssaoShader.uniforms.projectionMatrix.value = projectionMatrix;
-    ssaoShader.uniforms.inverseProjectionMatrix.value = inverseProjectionMatrix;
-    ssaoShader.uniforms.ssaoRadius.value = options.radius ?? 5.0;
-    ssaoShader.uniforms.ssaoFalloff.value = options.falloff ?? 5.0;
-    ssaoShader.uniforms.ssaoBias.value = options.bias ?? 0.01;
-    // scale = AO 次幂（gamma 校正），只由 options.scale 控制；intensity 是"叠加强度"，走下面 outputShader 的 mix。
-    // ⚠️ 用 ?? 而非 ||：0 是合法值，用 || 会被吞掉退回默认值。
-    ssaoShader.uniforms.scale.value = options.scale ?? 1.0;
-    const camFar = options.cameraFar ||
-        ((camera instanceof PerspectiveCamera || camera instanceof OrthographicCamera) ? camera.far : 20000);
-    ssaoShader.uniforms.cameraFar.value = camFar;
-    ssaoShader.uniforms.cameraNear.value = (camera instanceof PerspectiveCamera || camera instanceof OrthographicCamera)
-        ? camera.near
-        : 0.1;
-    ssaoShader.uniforms.distanceExponent.value = options.distanceExponent ?? 1.0;
-    ssaoShader.uniforms.distanceFallOff.value = options.distanceFallOff ?? 1.0;
-    renderer.setRenderTarget(ssaoTextureTarget);
-    renderer.clear();
-    fsQuad.render(renderer, ssaoShader);
-    // Poisson 边缘保持去噪：单 pass 完成（替代旧版 separable blur 双 pass）。
-    // resolution 传像素尺寸，供噪声平铺与采样偏移缩放（与 GTAO 主 pass 一致）。
-    const denoiseRes = new Vector2(ssaoW, ssaoH);
-    // 去噪最大采样半径，单位 = 像素（官方 Poisson 公式里 radius 就是像素倍率）。
-    // 兜底 1 像素：radius=0 会让 32 个采样点全部落在中心，等于完全不去噪，保留 1px 更符合"最小模糊"。
-    const denoiseRadius = Math.max(1.0, options.blurRadius ?? 4.0);
-    // SAMPLES 由 sampleCount 决定（编译期常量，改变需重新编译 shader）
-    if (poissonDenoiseShader.defines.SAMPLES !== samples) {
-        poissonDenoiseShader.defines.SAMPLES = samples;
-        poissonDenoiseShader.needsUpdate = true;
+    vec3 getViewPosition(vec2 uv) {
+      return reconstructPosition(uv, viewZFromLogDepth(getLogDepth(uv)));
     }
-    poissonDenoiseShader.uniforms.tDiffuse.value = ssaoTextureTarget.texture;
-    poissonDenoiseShader.uniforms.tNormal.value = normalTexture;
-    poissonDenoiseShader.uniforms.tDepth.value = aoDepthTexture;
-    poissonDenoiseShader.uniforms.resolution.value.copy(denoiseRes);
-    poissonDenoiseShader.uniforms.noiseResolution.value.set(NOISE_SIZE, NOISE_SIZE);
-    poissonDenoiseShader.uniforms.inverseProjectionMatrix.value = inverseProjectionMatrix;
-    poissonDenoiseShader.uniforms.cameraFar.value = ssaoShader.uniforms.cameraFar.value;
-    poissonDenoiseShader.uniforms.cameraNear.value = ssaoShader.uniforms.cameraNear.value;
-    poissonDenoiseShader.uniforms.radius.value = denoiseRadius;
-    renderer.setRenderTarget(blurTextureTarget);
-    renderer.clear();
-    fsQuad.render(renderer, poissonDenoiseShader);
-    renderer.setRenderTarget(originRenderTarget);
-    outputShader.uniforms.ssaoTexture.value = blurTextureTarget.texture;
-    // 复合守卫：可见深度（地板排除）与 AO 深度（含地板）两图比对，
-    // 地板挡在真实可见表面之前时作废地板的接触 AO（见 outputShader 注释）。
-    outputShader.uniforms.tColorDepth.value = colorDepthTexture;
-    outputShader.uniforms.tAoDepth.value = aoDepthTexture;
-    // 叠加强度：finalOcclusion = mix(1.0, ao, strength)，0 = 完全不叠加 AO，1 = 原始强度，>1 外插加深。
-    // intensity 与 strength 同义，便于调用方只设 intensity；同样用 ?? 保证 0 生效。
-    outputShader.uniforms.ssaoStrength.value = options.strength ?? options.intensity ?? 1.0;
-    outputShader.uniforms.debug.value = options.debug ? 1.0 : 0.0;
-    fsQuad.render(renderer, outputShader);
-}
+    vec3 getViewNormal(vec2 uv) {
+      return unpackRGBToNormal(texture2D(tNormal, uv).rgb);
+    }
+
+    // 双边去噪的单次样本加权：luma（AO 灰度，恒近似相等）+ 法线相似度 + 沿法线深度差
+    // 三者相乘得到权重；AO 是灰度图，luma 项近似为 1，主要靠法线 + 深度做边缘保持。
+    void denoiseSample(in vec3 center, in vec3 viewNormal, in vec3 viewPos, in vec2 sampleUv, inout vec3 denoised, inout float totalWeight) {
+      vec3 neighborColor = texture2D(tDiffuse, sampleUv).rgb;
+      vec3 sampleNormal = getViewNormal(sampleUv);
+      vec3 viewPosSample = getViewPosition(sampleUv);
+
+      float normalDiff = dot(viewNormal, sampleNormal);
+      float normalSimilarity = pow(max(normalDiff, 0.0), normalPhi);
+      float lumaDiff = abs(length(neighborColor) - length(center));
+      float lumaSimilarity = max(1.0 - lumaDiff / lumaPhi, 0.0);
+      float depthDiff = abs(dot(viewPos - viewPosSample, viewNormal));
+      float depthSimilarity = max(1.0 - depthDiff / depthPhi, 0.0);
+      float w = lumaSimilarity * depthSimilarity * normalSimilarity;
+
+      denoised += w * neighborColor;
+      totalWeight += w;
+    }
+
+    void main() {
+      float depth = getLogDepth(vUv);
+      vec4 texel = texture2D(tDiffuse, vUv);
+      // 背景（无几何）：直接透传原 AO（白），不做去噪
+      if (depth >= 1.0) {
+        gl_FragColor = texel;
+        return;
+      }
+      vec3 viewNormal = getViewNormal(vUv);
+      // 退化/非法法线（含 NaN）按原 AO 透传，避免双边去噪把整片刷黑
+      float nLen2 = dot(viewNormal, viewNormal);
+      if (nLen2 == 0.0 || nLen2 != nLen2) {
+        gl_FragColor = texel;
+        return;
+      }
+      vec3 center = texel.rgb;
+      vec3 viewPos = getViewPosition(vUv);
+
+      vec2 noiseUv = vUv * resolution / noiseResolution;
+      vec4 noiseTexel = texture2D(tNoise, noiseUv);
+      vec2 noiseVec = vec2(sin(noiseTexel.x * 2.0 * PI), cos(noiseTexel.x * 2.0 * PI));
+      mat2 rotationMatrix = mat2(noiseVec.x, -noiseVec.y, noiseVec.x, noiseVec.y);
+
+      float totalWeight = 1.0;
+      vec3 denoised = texel.rgb;
+      for (int i = 0; i < SAMPLES; i++) {
+        // 与官方 generateDenoiseSamples(samples, POISSON_RINGS, POISSON_RADIUS_EXP) 完全等价的逐点计算
+        float fi = float(i);
+        float angle = 2.0 * PI * float(POISSON_RINGS) * fi / float(SAMPLES);
+        float radiusF = pow(fi / float(SAMPLES - 1), float(POISSON_RADIUS_EXP));
+        vec3 sampleDir = vec3(cos(angle), sin(angle), radiusF);
+        vec2 offset = rotationMatrix * (sampleDir.xy * (1.0 + sampleDir.z * (radius - 1.0)) / resolution);
+        vec2 sampleUv = vUv + offset;
+        denoiseSample(center, viewNormal, viewPos, sampleUv, denoised, totalWeight);
+      }
+
+      if (totalWeight > 0.0) {
+        denoised /= totalWeight;
+      }
+      gl_FragColor = vec4(denoised, 1.0);
+    }`,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+const outputShader = new RawShaderMaterial({
+    uniforms: {
+        ssaoTexture: { value: null },
+        ssaoStrength: { value: 1.0 },
+        debug: { value: 0.0 },
+        // 可见深度（排除地板，= baseDepthTexture）：代表"真实可见表面"的深度。
+        tColorDepth: { value: null },
+        // AO 深度（含地板，= normalRenderTarget.depthTexture，法线 pass 顺带写入）：GTAO 实际采样的深度。
+        tAoDepth: { value: null },
+    },
+    vertexShader: `
+    attribute vec3 position;
+    attribute vec2 uv;
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = vec4(position, 1.0);
+    }`,
+    fragmentShader: `
+    #ifdef GL_ES
+      precision highp float;
+    #endif
+
+    uniform sampler2D ssaoTexture;
+    uniform float ssaoStrength;
+    uniform float debug;
+    uniform sampler2D tColorDepth;
+    uniform sampler2D tAoDepth;
+
+    varying vec2 vUv;
+
+    void main() {
+      float ssao = texture2D(ssaoTexture, vUv).r;
+
+      // 复合守卫：对数深度越小越近。若"含地板的 AO 深度"比"可见深度"更近，
+      // 说明该像素的真实可见表面位于半透明地板之后（典型的从下方透视地板看身后实体），
+      // 地板算出的接触 AO 不该乘到它身上 → 视为无遮蔽(=1)，即"被遮挡的部分就不要 ssao"。
+      // 仅在最终合成时生效；debug 模式直接看 GTAO 原始 AO 图（含地板接触 AO），便于排查。
+      float dColor = texture2D(tColorDepth, vUv).r;
+      float dAo = texture2D(tAoDepth, vUv).r;
+      if (debug < 0.5 && dAo < dColor - 0.0001) {
+        ssao = 1.0;
+      }
+
+      float finalOcclusion = mix(1.0, ssao, ssaoStrength);
+
+      if (debug > 0.5) {
+        gl_FragColor = vec4(vec3(ssao), 1.0);
+      } else {
+        gl_FragColor = vec4(vec3(finalOcclusion), 1.0);
+      }
+    }`,
+    blending: MultiplyBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default function ssao_pass(renderer, camera, scene, depthRenderTarget, normalRenderTarget, normalMaterial, devicePixelRatio, options) {
+    // ⚠️ 早退只看 enable：strength/intensity 是"叠加强度"，0 表示"不叠加 AO"而不是"关掉这个 pass"。
+    // 旧代码写成 `!options.enable || !options.strength`，强度调到 0 会跳过整条 pass（连法线准备也停），
+    // debug 模式下就再也看不到 AO 图，语义也和"强度 = 0"混在一起。
+    if (!options.enable) {
+        return;
+    }
+    // 记录当前渲染目标，最终 SSAO 乘法叠加到它上面。⚠️ 调用方决定输出目标——
+    // ThreeBase（2026-09-14 起）在深度 pass 之后、对象级特效之前调用，此时绑定的是 baseRenderTarget，
+    // 故 AO 直接乘进 base，描边/发光/覆盖/磨砂都叠在 AO 之上不被压暗；末尾统一 FXAA 输出到屏幕，
+    // 覆盖 SSAO 自身的硬边。改动调用顺序时，本 pass 无需修改（输出到"绑定的那个目标"即可）。
+    const originRenderTarget = renderer.getRenderTarget();
+    // 法线 pass：地板保留（includeFloor=true），接触 AO 需要地板的视图空间法线。
+    // ⭐ 深度白拿（2026-09-14 优化）：normalRenderTarget 挂着 aoDepthTexture 作 depth attachment，
+    // 这一次渲染的深度由光栅器顺带写入 → 直接就是「含地板」的 AO 深度，**不再单独渲一遍深度 pass**。
+    // （原先法线 pass 之后还要再渲一遍「含地板深度」——它与法线 pass 的排除集完全相同，
+    //   属于重复遍历全场景，2026-09-14 已删。）
+    // 前提：renderAoNormalPass 内部已把 depthWrite=false 的透明材质强转 true，保证写入面集合一致。
+    renderAoNormalPass(renderer, camera, scene, normalRenderTarget, normalMaterial, true);
+    // 可见深度（地板排除）= baseDepthTexture，既是描边/辉光/毛玻璃的遮挡参考，也是"真实可见表面"参考。
+    const colorDepthTexture = depthRenderTarget.depthTexture;
+    // AO 深度（含地板）：GTAO 与去噪采样它，能算出物体落在地板上的接触 AO。
+    const aoDepthTexture = normalRenderTarget.depthTexture;
+    const normalTexture = normalRenderTarget.texture;
+    renderer.getSize(size);
+    const resScale = options.resolutionScale ?? 0.5;
+    const ssaoW = Math.round(size.x * devicePixelRatio * resScale);
+    const ssaoH = Math.round(size.y * devicePixelRatio * resScale);
+    ssaoTextureTarget.setSize(ssaoW, ssaoH);
+    blurTextureTarget.setSize(ssaoW, ssaoH);
+    projectionMatrix.copy(camera.projectionMatrix);
+    inverseProjectionMatrix.copy(projectionMatrix).invert();
+    // SAMPLES 由 sampleCount 决定（编译期常量，改变需重新编译 shader）
+    const samples = options.sampleCount || 32;
+    if (ssaoShader.defines.SAMPLES !== samples) {
+        ssaoShader.defines.SAMPLES = samples;
+        ssaoShader.needsUpdate = true;
+    }
+    ssaoShader.uniforms.depthTexture.value = aoDepthTexture;
+    ssaoShader.uniforms.normalTexture.value = normalTexture;
+    // resolution 传像素尺寸：供 GTAO 噪声按屏幕平铺（与官方 GTAOPass 一致）
+    ssaoShader.uniforms.resolution.value.set(ssaoW, ssaoH);
+    ssaoShader.uniforms.projectionMatrix.value = projectionMatrix;
+    ssaoShader.uniforms.inverseProjectionMatrix.value = inverseProjectionMatrix;
+    ssaoShader.uniforms.ssaoRadius.value = options.radius ?? 5.0;
+    ssaoShader.uniforms.ssaoFalloff.value = options.falloff ?? 5.0;
+    ssaoShader.uniforms.ssaoBias.value = options.bias ?? 0.01;
+    // scale = AO 次幂（gamma 校正），只由 options.scale 控制；intensity 是"叠加强度"，走下面 outputShader 的 mix。
+    // ⚠️ 用 ?? 而非 ||：0 是合法值，用 || 会被吞掉退回默认值。
+    ssaoShader.uniforms.scale.value = options.scale ?? 1.0;
+    const camFar = options.cameraFar ||
+        ((camera instanceof PerspectiveCamera || camera instanceof OrthographicCamera) ? camera.far : 20000);
+    ssaoShader.uniforms.cameraFar.value = camFar;
+    ssaoShader.uniforms.cameraNear.value = (camera instanceof PerspectiveCamera || camera instanceof OrthographicCamera)
+        ? camera.near
+        : 0.1;
+    ssaoShader.uniforms.distanceExponent.value = options.distanceExponent ?? 1.0;
+    ssaoShader.uniforms.distanceFallOff.value = options.distanceFallOff ?? 1.0;
+    renderer.setRenderTarget(ssaoTextureTarget);
+    renderer.clear();
+    fsQuad.render(renderer, ssaoShader);
+    // Poisson 边缘保持去噪：单 pass 完成（替代旧版 separable blur 双 pass）。
+    // resolution 传像素尺寸，供噪声平铺与采样偏移缩放（与 GTAO 主 pass 一致）。
+    const denoiseRes = new Vector2(ssaoW, ssaoH);
+    // 去噪最大采样半径，单位 = 像素（官方 Poisson 公式里 radius 就是像素倍率）。
+    // 兜底 1 像素：radius=0 会让 32 个采样点全部落在中心，等于完全不去噪，保留 1px 更符合"最小模糊"。
+    const denoiseRadius = Math.max(1.0, options.blurRadius ?? 4.0);
+    // SAMPLES 由 sampleCount 决定（编译期常量，改变需重新编译 shader）
+    if (poissonDenoiseShader.defines.SAMPLES !== samples) {
+        poissonDenoiseShader.defines.SAMPLES = samples;
+        poissonDenoiseShader.needsUpdate = true;
+    }
+    poissonDenoiseShader.uniforms.tDiffuse.value = ssaoTextureTarget.texture;
+    poissonDenoiseShader.uniforms.tNormal.value = normalTexture;
+    poissonDenoiseShader.uniforms.tDepth.value = aoDepthTexture;
+    poissonDenoiseShader.uniforms.resolution.value.copy(denoiseRes);
+    poissonDenoiseShader.uniforms.noiseResolution.value.set(NOISE_SIZE, NOISE_SIZE);
+    poissonDenoiseShader.uniforms.inverseProjectionMatrix.value = inverseProjectionMatrix;
+    poissonDenoiseShader.uniforms.cameraFar.value = ssaoShader.uniforms.cameraFar.value;
+    poissonDenoiseShader.uniforms.cameraNear.value = ssaoShader.uniforms.cameraNear.value;
+    poissonDenoiseShader.uniforms.radius.value = denoiseRadius;
+    renderer.setRenderTarget(blurTextureTarget);
+    renderer.clear();
+    fsQuad.render(renderer, poissonDenoiseShader);
+    renderer.setRenderTarget(originRenderTarget);
+    outputShader.uniforms.ssaoTexture.value = blurTextureTarget.texture;
+    // 复合守卫：可见深度（地板排除）与 AO 深度（含地板）两图比对，
+    // 地板挡在真实可见表面之前时作废地板的接触 AO（见 outputShader 注释）。
+    outputShader.uniforms.tColorDepth.value = colorDepthTexture;
+    outputShader.uniforms.tAoDepth.value = aoDepthTexture;
+    // 叠加强度：finalOcclusion = mix(1.0, ao, strength)，0 = 完全不叠加 AO，1 = 原始强度，>1 外插加深。
+    // intensity 与 strength 同义，便于调用方只设 intensity；同样用 ?? 保证 0 生效。
+    outputShader.uniforms.ssaoStrength.value = options.strength ?? options.intensity ?? 1.0;
+    outputShader.uniforms.debug.value = options.debug ? 1.0 : 0.0;
+    fsQuad.render(renderer, outputShader);
+}