three-base 2.0.137 → 2.0.145

package/shaders/baseTextureToRenderShader.ts

@@ -0,0 +1,232 @@
+import { ShaderMaterial, Vector2, ShaderChunk, NoBlending } from "three";
+export const baseTextureToRenderShader = new ShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        resolution: { value: new Vector2(1 / 1024, 1 / 1024) },
+        /** 抖动强度：1.0 = 标准 ±0.5 LSB（总跨度 1/255），0 = 关闭（A/B 对比用） */
+        uDitherStrength: { value: 1.0 }
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        precision highp float;
+
+        uniform sampler2D tDiffuse;
+    
+        uniform vec2 resolution;
+    
+        /** 抖动强度（1.0 = ±0.5 LSB；0 = 关闭） */
+        uniform float uDitherStrength;
+    
+        varying vec2 vUv;
+    
+        /**
+         * 交错梯度噪声 Interleaved Gradient Noise，返回 [0,1)。
+         *
+         * 为什么不用 Bayer 有序矩阵（2026-09-06 皇上反馈「辉光透明度不对」后改）：
+         *   Bayer 是 8×8 块状循环图案，在大面积柔和渐变（外辉光/天空/雾）上会形成**肉眼可见的规则
+         *   网格/点阵**，把自然的透明度渐变打成"脏"的质感；辉光暗部（R 仅 16~47）一个码值就是
+         *   2%~6% 跳变，网格尤其明显。IGN 是高频交错梯度，没有块状结构，人眼几乎察觉不到。
+         *
+         * 为什么不用 sin()/大数 fract() 版哈希（如 hash12）：它依赖 fract(4531.99) 这类大数的
+         *   小数位精度，在不同 GPU / 驱动 / 精度限定符（mediump vs highp）下行为不一致，
+         *   存在退化成常数的风险（一旦退化，抖动就变成恒定偏移，色带一根没少）。
+         *   IGN 内部最大值约 52.98，精度安全边际大得多。
+         * ⚠️ 澄清：Bayer 被替换**不是**因为精度（实测大坐标下不退化），纯粹是块状网格的观感问题。
+         */
+        float ign(vec2 p) {
+            return fract(52.9829189 * fract(0.06711056 * p.x + 0.00583715 * p.y));
+        }
+    
+        #ifndef FXAA_DISCARD
+                #define FXAA_DISCARD 0
+        #endif
+    
+        /*--------------------------------------------------------------------------*/
+        #define FxaaTexTop(t, p) texture2D(t, p, -100.0)
+        #define FxaaTexOff(t, p, o, r) texture2D(t, p + (o * r), -100.0)
+        /*--------------------------------------------------------------------------*/
+    
+        #define NUM_SAMPLES 5
+    
+        float contrast( vec4 a, vec4 b ) {
+                vec4 diff = abs( a - b );
+                return max( max( max( diff.r, diff.g ), diff.b ), diff.a );
+        }
+    
+        /*============================================================================
+    
+                                        FXAA3 QUALITY - PC
+    
+        ============================================================================*/
+    
+        /*--------------------------------------------------------------------------*/
+        vec4 FxaaPixelShader(
+                vec2 posM,
+                sampler2D tex,
+                vec2 fxaaQualityRcpFrame,
+                float fxaaQualityEdgeThreshold,
+                float fxaaQualityinvEdgeThreshold
+        ) {
+                vec4 rgbaM = FxaaTexTop(tex, posM);
+                vec4 rgbaS = FxaaTexOff(tex, posM, vec2( 0.0, 1.0), fxaaQualityRcpFrame.xy);
+                vec4 rgbaE = FxaaTexOff(tex, posM, vec2( 1.0, 0.0), fxaaQualityRcpFrame.xy);
+                vec4 rgbaN = FxaaTexOff(tex, posM, vec2( 0.0,-1.0), fxaaQualityRcpFrame.xy);
+                vec4 rgbaW = FxaaTexOff(tex, posM, vec2(-1.0, 0.0), fxaaQualityRcpFrame.xy);
+    
+                bool earlyExit = max( max( max(
+                        contrast( rgbaM, rgbaN ),
+                        contrast( rgbaM, rgbaS ) ),
+                        contrast( rgbaM, rgbaE ) ),
+                        contrast( rgbaM, rgbaW ) )
+                        < fxaaQualityEdgeThreshold;
+    
+                #if (FXAA_DISCARD == 1)
+                        if(earlyExit) FxaaDiscard;
+                #else
+                        if(earlyExit) return rgbaM;
+                #endif
+    
+                float contrastN = contrast( rgbaM, rgbaN );
+                float contrastS = contrast( rgbaM, rgbaS );
+                float contrastE = contrast( rgbaM, rgbaE );
+                float contrastW = contrast( rgbaM, rgbaW );
+    
+                float relativeVContrast = ( contrastN + contrastS ) - ( contrastE + contrastW );
+                relativeVContrast *= fxaaQualityinvEdgeThreshold;
+    
+                bool horzSpan = relativeVContrast > 0.;
+    
+                if( abs( relativeVContrast ) < .3 ) {
+                        vec2 dirToEdge;
+                        dirToEdge.x = contrastE > contrastW ? 1. : -1.;
+                        dirToEdge.y = contrastS > contrastN ? 1. : -1.;
+    
+                        vec4 rgbaAlongH = FxaaTexOff(tex, posM, vec2( dirToEdge.x, -dirToEdge.y ), fxaaQualityRcpFrame.xy);
+                        float matchAlongH = contrast( rgbaM, rgbaAlongH );
+    
+                        vec4 rgbaAlongV = FxaaTexOff(tex, posM, vec2( -dirToEdge.x, dirToEdge.y ), fxaaQualityRcpFrame.xy);
+                        float matchAlongV = contrast( rgbaM, rgbaAlongV );
+    
+                        relativeVContrast = matchAlongV - matchAlongH;
+                        relativeVContrast *= fxaaQualityinvEdgeThreshold;
+    
+                        if( abs( relativeVContrast ) < .3 ) {
+                                return mix(
+                                        rgbaM,
+                                        (rgbaN + rgbaS + rgbaE + rgbaW) * .25,
+                                        .4
+                                );
+                        }
+    
+                        horzSpan = relativeVContrast > 0.;
+                }
+    
+                if(!horzSpan) rgbaN = rgbaW;
+                if(!horzSpan) rgbaS = rgbaE;
+    
+                bool pairN = contrast( rgbaM, rgbaN ) > contrast( rgbaM, rgbaS );
+                if(!pairN) rgbaN = rgbaS;
+    
+                vec2 offNP;
+                offNP.x = (!horzSpan) ? 0.0 : fxaaQualityRcpFrame.x;
+                offNP.y = ( horzSpan) ? 0.0 : fxaaQualityRcpFrame.y;
+    
+                bool doneN = false;
+                bool doneP = false;
+    
+                float nDist = 0.;
+                float pDist = 0.;
+    
+                vec2 posN = posM;
+                vec2 posP = posM;
+    
+                int iterationsUsed = 0;
+                int iterationsUsedN = 0;
+                int iterationsUsedP = 0;
+                for( int i = 0; i < NUM_SAMPLES; i++ ) {
+                        iterationsUsed = i;
+    
+                        float increment = float(i + 1);
+    
+                        if(!doneN) {
+                                nDist += increment;
+                                posN = posM + offNP * nDist;
+                                vec4 rgbaEndN = FxaaTexTop(tex, posN.xy);
+                                doneN = contrast( rgbaEndN, rgbaM ) > contrast( rgbaEndN, rgbaN );
+                                iterationsUsedN = i;
+                        }
+    
+                        if(!doneP) {
+                                pDist += increment;
+                                posP = posM - offNP * pDist;
+                                vec4 rgbaEndP = FxaaTexTop(tex, posP.xy);
+                                doneP = contrast( rgbaEndP, rgbaM ) > contrast( rgbaEndP, rgbaN );
+                                iterationsUsedP = i;
+                        }
+    
+                        if(doneN || doneP) break;
+                }
+    
+    
+                if ( !doneP && !doneN ) return rgbaM;
+    
+                float dist = min(
+                        doneN ? float( iterationsUsedN ) / float( NUM_SAMPLES - 1 ) : 1.,
+                        doneP ? float( iterationsUsedP ) / float( NUM_SAMPLES - 1 ) : 1.
+                );
+    
+                dist = pow(dist, .5);
+    
+                dist = 1. - dist;
+    
+                return mix(
+                        rgbaM,
+                        rgbaN,
+                        dist * .5
+                );
+        }
+    
+        void main() {
+                const float edgeDetectionQuality = .2;
+                const float invEdgeDetectionQuality = 1. / edgeDetectionQuality;
+    
+                vec4 srgbColor = sRGBTransferOETF(FxaaPixelShader(
+                        vUv,
+                        tDiffuse,
+                        resolution,
+                        edgeDetectionQuality,
+                        invEdgeDetectionQuality
+                ));
+    
+                // ---- 终处理抖动（dither）：消除 8bit 输出量化的色带 ----
+                // 屏幕 framebuffer 只有 8bit，柔和渐变（外辉光/天空/雾/bloom 衰减）在此被量化成
+                // 肉眼可见的"一层一层"台阶。叠加 ±0.5 LSB（总跨度 1/255）的屏幕空间随机噪声后，
+                // 台阶被打散成高频颗粒——人眼对高频噪声极不敏感，色带随即消失（2026-09-06 修）。
+                // 注意：dither 只补偿「最终 8bit 输出」这一步；中间 RT 的线性量化色带由
+                // ThreeBase 的 baseRenderTarget/screenRenderTarget 改 HalfFloatType 根治。
+                // 二者缺一不可：半浮点恢复渐变连续性，dither 消除「源数据动态范围不足」型色带
+                // （如 SpriteText3 外辉光 R 通道在源图只有 39~46 共 8 个码值，34px 上必然每 5px 一跳）。
+                float dither = (ign(gl_FragCoord.xy) - 0.5) * (1.0 / 255.0) * uDitherStrength;
+                gl_FragColor = vec4(srgbColor.rgb + dither, srgbColor.a);
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+    // 终处理：手写 sRGBTransferOETF 已是唯一一次 sRGB 编码；关闭 three 的自动 tonemap/colorspace 注入，
+    // 防止渲染到屏幕时被 three 再编码一次（本 ShaderMaterial 不写 include 块，three 本就不会注入，
+    // 这里显式置 false 仅是防御，保证颜色空间语义单一可控）。
+    toneMapped: false,
+});

package/shaders/copyShader.js

@@ -1,9 +1,8 @@
 import { ShaderChunk, ShaderMaterial } from "three";
-// 拷贝着色器
 const copyShader = new ShaderMaterial({
     uniforms: {
-        map: { value: null }, // 贴图纹理
-        opacity: { value: 1 }, // 透明度
+        map: { value: null },
+        opacity: { value: 1 },
     },
     vertexShader: `
           ${ShaderChunk.common}

package/shaders/copyShader.ts

@@ -0,0 +1,32 @@
+import { ShaderChunk, ShaderMaterial } from "three";
+const copyShader = new ShaderMaterial({
+    uniforms: {
+        map: { value: null },
+        opacity: { value: 1 },
+    },
+    vertexShader: `
+          ${ShaderChunk.common}
+          ${ShaderChunk.logdepthbuf_pars_vertex}
+          varying vec2 vUv;
+          void main() {
+              vUv = uv;
+              gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+              ${ShaderChunk.logdepthbuf_vertex}
+          }
+      `,
+    fragmentShader: `
+          ${ShaderChunk.logdepthbuf_pars_fragment}
+          uniform float opacity;
+          uniform sampler2D map;
+          varying vec2 vUv;
+          void main() {
+              gl_FragColor = texture2D(map, vUv);
+              gl_FragColor.a *= opacity;
+              ${ShaderChunk.logdepthbuf_fragment}
+          }
+      `,
+    depthTest: true,
+    depthWrite: true,
+    transparent: true,
+});
+export default copyShader;

package/shaders/debugDepthCompareShader.d.ts

@@ -0,0 +1,14 @@
+import { ShaderMaterial } from "three";
+/**
+ * 调试用：把「全局 base 深度」与「最近一次 glow/stroke 选区的 select 深度」并排显示，
+ * 用于排查"深度测试全部失效"根因：
+ *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   G = 选区自身深度（selectDepthTexture，由 glow_pass/stroke_pass 渲染后写入 debugDepthState）
+ * 两路都用 `pow(cameraFar+1, d)-1` 反推到近似线性视深再归一化（背景≈1 → 黄白）。
+ *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderAoDepthPass 失效），但选区深度正常；
+ *   - R、G 都全白       → 两路深度都没写进；
+ *   - R 有灰阶、G 全白   → 选区深度没写进（glow/stroke 自身的深度 pass 失效）；
+ *   - R、G 都有灰阶      → 深度正常，问题在 depthTestShader 比对侧。
+ */
+declare const debugDepthCompareShader: ShaderMaterial;
+export default debugDepthCompareShader;

package/shaders/debugDepthCompareShader.js

@@ -0,0 +1,49 @@
+import { ShaderChunk, ShaderMaterial } from "three";
+/**
+ * 调试用：把「全局 base 深度」与「最近一次 glow/stroke 选区的 select 深度」并排显示，
+ * 用于排查"深度测试全部失效"根因：
+ *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   G = 选区自身深度（selectDepthTexture，由 glow_pass/stroke_pass 渲染后写入 debugDepthState）
+ * 两路都用 `pow(cameraFar+1, d)-1` 反推到近似线性视深再归一化（背景≈1 → 黄白）。
+ *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderAoDepthPass 失效），但选区深度正常；
+ *   - R、G 都全白       → 两路深度都没写进；
+ *   - R 有灰阶、G 全白   → 选区深度没写进（glow/stroke 自身的深度 pass 失效）；
+ *   - R、G 都有灰阶      → 深度正常，问题在 depthTestShader 比对侧。
+ */
+const debugDepthCompareShader = new ShaderMaterial({
+    uniforms: {
+        tBase: { value: null },
+        tSelect: { value: null },
+        cameraFar: { value: 1000.0 },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        uniform sampler2D tBase;
+        uniform sampler2D tSelect;
+        uniform float cameraFar;
+        varying vec2 vUv;
+        void main() {
+            float baseD = texture2D(tBase, vUv).r;
+            float selD = texture2D(tSelect, vUv).r;
+            // 与 stroke_pass 的 __STROKE_DEPTH_VIS 同一反推公式，保证两座视图语义一致
+            float vb = pow(cameraFar + 1.0, baseD) - 1.0;
+            float vs = pow(cameraFar + 1.0, selD) - 1.0;
+            gl_FragColor = vec4(vb / cameraFar, vs / cameraFar, 0.0, 1.0);
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default debugDepthCompareShader;

package/shaders/debugDepthCompareShader.ts

@@ -0,0 +1,50 @@
+import { ShaderChunk, ShaderMaterial } from "three";
+
+/**
+ * 调试用：把「全局 base 深度」与「最近一次 glow/stroke 选区的 select 深度」并排显示，
+ * 用于排查"深度测试全部失效"根因：
+ *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   G = 选区自身深度（selectDepthTexture，由 glow_pass/stroke_pass 渲染后写入 debugDepthState）
+ * 两路都用 `pow(cameraFar+1, d)-1` 反推到近似线性视深再归一化（背景≈1 → 黄白）。
+ *   - R 全白、G 也有内容 → 全局 base 深度没写进（renderAoDepthPass 失效），但选区深度正常；
+ *   - R、G 都全白       → 两路深度都没写进；
+ *   - R 有灰阶、G 全白   → 选区深度没写进（glow/stroke 自身的深度 pass 失效）；
+ *   - R、G 都有灰阶      → 深度正常，问题在 depthTestShader 比对侧。
+ */
+const debugDepthCompareShader = new ShaderMaterial({
+    uniforms: {
+        tBase: { value: null as unknown as import("three").Texture },
+        tSelect: { value: null as unknown as import("three").Texture },
+        cameraFar: { value: 1000.0 },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        uniform sampler2D tBase;
+        uniform sampler2D tSelect;
+        uniform float cameraFar;
+        varying vec2 vUv;
+        void main() {
+            float baseD = texture2D(tBase, vUv).r;
+            float selD = texture2D(tSelect, vUv).r;
+            // 与 stroke_pass 的 __STROKE_DEPTH_VIS 同一反推公式，保证两座视图语义一致
+            float vb = pow(cameraFar + 1.0, baseD) - 1.0;
+            float vs = pow(cameraFar + 1.0, selD) - 1.0;
+            gl_FragColor = vec4(vb / cameraFar, vs / cameraFar, 0.0, 1.0);
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default debugDepthCompareShader;

package/shaders/debugDepthJudgeShader.d.ts

@@ -0,0 +1,18 @@
+import { ShaderMaterial } from "three";
+/**
+ * 调试用：把「深度测试判定」本身画出来，用于定位"后处理深度测试全部失效"。
+ *
+ * 通道语义（全部为**原始**深度值，不做对数反解，避免饱和丢信息）：
+ *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   G = 选区自身深度（selectDepthTexture，glow/stroke 渲染后写入 debugDepthState）
+ *   B = 判定结果：baseD < selD - bias ? 1 : 0
+ *       与 stroke_pass 的 depthTestShader 同一判定式（bias = 0.0006）：
+ *       1(蓝) = 判为被更近物体挡住 → 该像素应 discard；0(黑) = 不丢弃。
+ *
+ * 判读：
+ *   - 物体区域（G 明显暗于 1.0 的像素）B 全黑   → 判定从不触发，后处理必"一律显示在最前"；
+ *     再看该区域 R 与 G 谁大：R 反而比 G 大（base 比 select 还远）→ base 深度图里缺了遮挡物。
+ *   - 物体区域 B 有蓝 → 判定本身正常，问题在后续合成（叠加顺序/混合）。
+ */
+declare const debugDepthJudgeShader: ShaderMaterial;
+export default debugDepthJudgeShader;

package/shaders/debugDepthJudgeShader.js

@@ -0,0 +1,52 @@
+import { ShaderChunk, ShaderMaterial } from "three";
+import { DEPTH_TEST_BIAS } from "../pass/depthTestBias";
+/**
+ * 调试用：把「深度测试判定」本身画出来，用于定位"后处理深度测试全部失效"。
+ *
+ * 通道语义（全部为**原始**深度值，不做对数反解，避免饱和丢信息）：
+ *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   G = 选区自身深度（selectDepthTexture，glow/stroke 渲染后写入 debugDepthState）
+ *   B = 判定结果：baseD < selD - bias ? 1 : 0
+ *       与 stroke_pass 的 depthTestShader 同一判定式（bias = 0.0006）：
+ *       1(蓝) = 判为被更近物体挡住 → 该像素应 discard；0(黑) = 不丢弃。
+ *
+ * 判读：
+ *   - 物体区域（G 明显暗于 1.0 的像素）B 全黑   → 判定从不触发，后处理必"一律显示在最前"；
+ *     再看该区域 R 与 G 谁大：R 反而比 G 大（base 比 select 还远）→ base 深度图里缺了遮挡物。
+ *   - 物体区域 B 有蓝 → 判定本身正常，问题在后续合成（叠加顺序/混合）。
+ */
+const debugDepthJudgeShader = new ShaderMaterial({
+    uniforms: {
+        tBase: { value: null },
+        tSelect: { value: null },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        uniform sampler2D tBase;
+        uniform sampler2D tSelect;
+        varying vec2 vUv;
+        void main() {
+            float baseD = texture2D(tBase, vUv).r;
+            float selD = texture2D(tSelect, vUv).r;
+            // 与 depthTestShader 完全一致的判定式（同用 DEPTH_TEST_BIAS 单一常量源）：
+            // 对数深度下值越小越近，base 比 select 近过容差 → 判为被遮挡（应 discard）。
+            float judged = step(baseD, selD - ${DEPTH_TEST_BIAS});
+            gl_FragColor = vec4(baseD, selD, judged, 1.0);
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default debugDepthJudgeShader;

package/shaders/debugDepthJudgeShader.ts

@@ -0,0 +1,54 @@
+import { ShaderChunk, ShaderMaterial, Texture } from "three";
+import { DEPTH_TEST_BIAS } from "../pass/depthTestBias";
+
+/**
+ * 调试用：把「深度测试判定」本身画出来，用于定位"后处理深度测试全部失效"。
+ *
+ * 通道语义（全部为**原始**深度值，不做对数反解，避免饱和丢信息）：
+ *   R = 全局 base 深度（baseDepthTexture，排除地板）
+ *   G = 选区自身深度（selectDepthTexture，glow/stroke 渲染后写入 debugDepthState）
+ *   B = 判定结果：baseD < selD - bias ? 1 : 0
+ *       与 stroke_pass 的 depthTestShader 同一判定式（bias = 0.0006）：
+ *       1(蓝) = 判为被更近物体挡住 → 该像素应 discard；0(黑) = 不丢弃。
+ *
+ * 判读：
+ *   - 物体区域（G 明显暗于 1.0 的像素）B 全黑   → 判定从不触发，后处理必"一律显示在最前"；
+ *     再看该区域 R 与 G 谁大：R 反而比 G 大（base 比 select 还远）→ base 深度图里缺了遮挡物。
+ *   - 物体区域 B 有蓝 → 判定本身正常，问题在后续合成（叠加顺序/混合）。
+ */
+const debugDepthJudgeShader = new ShaderMaterial({
+    uniforms: {
+        tBase: { value: null as unknown as Texture },
+        tSelect: { value: null as unknown as Texture },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        uniform sampler2D tBase;
+        uniform sampler2D tSelect;
+        varying vec2 vUv;
+        void main() {
+            float baseD = texture2D(tBase, vUv).r;
+            float selD = texture2D(tSelect, vUv).r;
+            // 与 depthTestShader 完全一致的判定式（同用 DEPTH_TEST_BIAS 单一常量源）：
+            // 对数深度下值越小越近，base 比 select 近过容差 → 判为被遮挡（应 discard）。
+            float judged = step(baseD, selD - ${DEPTH_TEST_BIAS});
+            gl_FragColor = vec4(baseD, selD, judged, 1.0);
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+
+export default debugDepthJudgeShader;

package/shaders/debugExcludedShader.d.ts

@@ -0,0 +1,13 @@
+import { ShaderMaterial } from "three";
+/**
+ * 调试用：把「可见深度图」与「被排除面 mask」叠在一起看。
+ *
+ * 底色 = baseDepthTexture 灰度（近黑远白，同「全局深度图」档）；
+ * 红色 = 该像素上的表面被 renderAoDepthPass 排除（sprite/线条/点、userData.aoTransparent、
+ *        标了 userData.aoFloor 的地板 Ground1 等）→ **它写不进深度图，永远挡不住任何后处理**。
+ *
+ * 判读：挡不住你的那个面如果是红的 → 不是深度算法坏了，是它被设计成可透视；
+ *       把该对象的 userData.aoTransparent 去掉 / 不要标 aoFloor，即可让它参与遮挡。
+ */
+declare const debugExcludedShader: ShaderMaterial;
+export default debugExcludedShader;

package/shaders/debugExcludedShader.js

@@ -0,0 +1,46 @@
+import { ShaderChunk, ShaderMaterial } from "three";
+/**
+ * 调试用：把「可见深度图」与「被排除面 mask」叠在一起看。
+ *
+ * 底色 = baseDepthTexture 灰度（近黑远白，同「全局深度图」档）；
+ * 红色 = 该像素上的表面被 renderAoDepthPass 排除（sprite/线条/点、userData.aoTransparent、
+ *        标了 userData.aoFloor 的地板 Ground1 等）→ **它写不进深度图，永远挡不住任何后处理**。
+ *
+ * 判读：挡不住你的那个面如果是红的 → 不是深度算法坏了，是它被设计成可透视；
+ *       把该对象的 userData.aoTransparent 去掉 / 不要标 aoFloor，即可让它参与遮挡。
+ */
+const debugExcludedShader = new ShaderMaterial({
+    uniforms: {
+        tDepth: { value: null },
+        tMask: { value: null },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        uniform sampler2D tDepth;
+        uniform sampler2D tMask;
+        varying vec2 vUv;
+        void main() {
+            float d = texture2D(tDepth, vUv).r;
+            float mask = texture2D(tMask, vUv).r;
+            // 灰度深度 + 被排除面叠红（mask 为纯红，取 r 通道即可）
+            vec3 col = vec3(d, d, d);
+            col = mix(col, vec3(1.0, 0.15, 0.15), mask * 0.85);
+            gl_FragColor = vec4(col, 1.0);
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default debugExcludedShader;

package/shaders/debugExcludedShader.ts

@@ -0,0 +1,48 @@
+import { ShaderChunk, ShaderMaterial, Texture } from "three";
+
+/**
+ * 调试用：把「可见深度图」与「被排除面 mask」叠在一起看。
+ *
+ * 底色 = baseDepthTexture 灰度（近黑远白，同「全局深度图」档）；
+ * 红色 = 该像素上的表面被 renderAoDepthPass 排除（sprite/线条/点、userData.aoTransparent、
+ *        标了 userData.aoFloor 的地板 Ground1 等）→ **它写不进深度图，永远挡不住任何后处理**。
+ *
+ * 判读：挡不住你的那个面如果是红的 → 不是深度算法坏了，是它被设计成可透视；
+ *       把该对象的 userData.aoTransparent 去掉 / 不要标 aoFloor，即可让它参与遮挡。
+ */
+const debugExcludedShader = new ShaderMaterial({
+    uniforms: {
+        tDepth: { value: null as unknown as Texture },
+        tMask: { value: null as unknown as Texture },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        uniform sampler2D tDepth;
+        uniform sampler2D tMask;
+        varying vec2 vUv;
+        void main() {
+            float d = texture2D(tDepth, vUv).r;
+            float mask = texture2D(tMask, vUv).r;
+            // 灰度深度 + 被排除面叠红（mask 为纯红，取 r 通道即可）
+            vec3 col = vec3(d, d, d);
+            col = mix(col, vec3(1.0, 0.15, 0.15), mask * 0.85);
+            gl_FragColor = vec4(col, 1.0);
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+
+export default debugExcludedShader;