three-base 2.0.142 → 2.0.145

package/ThreeBase.js

@@ -1,1202 +1,1202 @@
-/*
- * @Author: xiaosihan
- * @Date: 2021-12-20 13:38:22
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2025-01-28 04:26:41
- */
-import { round } from "lodash";
-import { AxesHelper, Box3, DepthFormat, DepthTexture, DoubleSide, EventDispatcher, GridHelper, HalfFloatType, LinearFilter, Line, Mesh, MeshNormalMaterial, MOUSE, NearestFilter, NoBlending, NoColorSpace, NormalBlending, OrthographicCamera, PerspectiveCamera, Points, RGBAFormat, RGBFormat, FloatType, UnsignedByteType, NoToneMapping, Scene, SRGBColorSpace, TOUCH, UnsignedIntType, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
-import { MathUtils } from "three";
-const { degToRad, generateUUID } = MathUtils;
-import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
-import ThreeMouse from "./ThreeMouse";
-import InstancedGroup from "./instanced/InstancedGroup";
-import Transition from "./Transition";
-import bloom_pass from "./pass/bloom_pass";
-import cover_pass from "./pass/cover_pass";
-import frosted_glass_pass from "./pass/frosted_glass_pass";
-import { flushLensflareOverlays } from "./lensflare/LensFlare";
-import glow_pass from "./pass/glow_pass";
-import stroke_pass from "./pass/stroke_pass";
-import ssao_pass, { renderAoDepthPass, renderExcludedMaskPass, visibleDepthOptions } from "./pass/ssao_pass";
-import screenBloomPass from "./pass/screen_bloom_pass";
-import copyShader from "./shaders/copyShader";
-import { baseTextureToRenderShader } from "./shaders/baseTextureToRenderShader";
-import baseDepthVisShader from "./shaders/baseDepthVisShader";
-import debugDepthCompareShader from "./shaders/debugDepthCompareShader";
-import debugDepthJudgeShader from "./shaders/debugDepthJudgeShader";
-import debugExcludedShader from "./shaders/debugExcludedShader";
-import { debugDepthState } from "./pass/debugDepthState";
-import { WaterFlow } from "./WaterFlow/WaterFlow";
-import waterFlowPass from "./WaterFlow/waterFlowPass";
-import threeLoader from "./threeLoader";
-import threeUtils from "./threeUtils";
-import fsQuad from "./pass/fsQuad";
-/** OrbitControls 阻尼基准值（等价于 60fps 下的单帧衰减比例）。
- *  render 循环会按真实帧间隔把它换算成「帧率无关」的单帧衰减比例（见下方 controls.update 处）。
- *  取值历史：0.05（1826ab1 验证过"加阻尼也不晃"的正常值，配合 rotateSpeed=0.2）→
- *  a9f3ec9 把 rotateSpeed 提到 1.0 才导致"快速晃动中心点飘"，与阻尼无关；该次顺手把阻尼关成 false 诊断。
- *  本轮复原：enableDamping=true + dampingFactor=0.05（回到不飘配置），rotateSpeed 折中 0.5（0.2 跟手、
- *  1.0 易飘）。若 0.5 仍飘，降到 0.2 完全复原 1826ab1；若想更跟手，升到 0.3~0.4 之间试。 */
-const CONTROLS_DAMPING_BASE = 0.05;
-// three.js 的基础对象
-export default class ThreeBase extends EventDispatcher {
-    constructor() {
-        super();
-        // 资源加载进度有更新时, 需要渲染
-        threeLoader.addEventListener("loadding", () => {
-            this.dispatchEvent({ type: "loadding" });
-            setTimeout(() => {
-                this.needRender = true;
-            }, 100);
-        });
-        threeLoader.addEventListener("onLoad", () => {
-            this.dispatchEvent({ type: "onLoad" });
-            setTimeout(() => {
-                this.needRender = true;
-            }, 100);
-        });
-        // 固定的实例化分组器挂进场景，并注入到鼠标事件系统用于 InstancedMesh 命中路由
-        this.scene.add(this.instancedGroup);
-        this.threeMouse.instancedGroup = this.instancedGroup;
-        this.init();
-    }
-    // 设置最小分辨率
-    minDevicePixelRatio = 1;
-    // 实际帧缓冲像素比硬上限：SSAA 超采样可能把总像素比推得过高导致卡顿，
-    // 这里硬性限制 effectiveRatio 不超过该值（无论设备像素比或 renderScale 多大）。
-    // 高 dpr 屏（如 2×）下 effectiveRatio=2 会让整条后处理链在 2× 分辨率跑，快速晃动掉帧顿挫、
-    // 像素抖动（用户感知为"飘"）；收紧到 1（高 dpr 屏 base RT 最多 1×2=2× 每维）进一步压中间 RT 填充率。注意 renderer 自身
-    // setPixelRatio 仍按 dpr 输出最终屏幕，这里只压中间 RT 计算量，不影响最终清晰度。
-    maxPixelRatio = 1;
-    // 超采样倍数（SSAA）：在帧缓冲分辨率基础上再乘 renderScale 渲染，
-    // 最后由 FXAA 降采样输出到屏幕。renderScale>1 可消除"纹理缩小产生的摩尔纹"——
-    // MSAA 只处理几何边缘、管不到着色器内的纹理采样；SSAA 才是纹理摩尔纹的治本手段
-    // （纹理被欠采样时的拍频，必须靠提高实际采样率才能消除）。
-    // 1 = 关闭超采样（仅设备 pixelRatio）；2 = 2 倍超采样（质量最高，片元开销 ×4，需强 GPU）。
-    renderScale = 1;
-    // 全局超采样/分辨率倍率（SSAA）：base / 深度 / 法线 / 效果 mask / 屏幕合成 全部按
-    // effectiveRatio × resolution 内部超采样渲染，终处理 FXAA 降采样输出到屏幕。
-    // 全链路同倍率 → 各 RT 严格 1:1 对齐：几何锯齿、效果边缘锯齿、辉光漏光（深度 vs mask 错位）、
-    // mask 合成 UV 缩放错位、SSAO 深度错位变黑 一并消除。默认 2 = 每维 2×、总像素 4×；
-    // 代价全链路填充 ×4（base + 深度 + 法线 + 后处理 SSAO/cover/frosted）。要省性能整体降 1
-    // （关超采样，仅 FXAA 兜底，几何硬边锯齿回弹）。历史坑：baseRenderScale/auxRenderScale/
-    // effectRenderScale 三参各自为政，倍率不同步必错位，故统一为单参数 resolution 管全局。
-    // ⚠️ 必须用 getter/setter，不能是普通字段：所有 RT 尺寸只在 updateRenderTargetSizes()
-    // 里按 effectiveRatio × resolution 计算，而该方法过去只被 setSize()（容器尺寸变化）调用
-    // → 运行时改 resolution 不会重建任何 RT，画面毫无变化（表现为"调分辨率没感觉"）。
-    // 故 setter 里改动倍率后立刻重建全部 RT。
-    _resolution = 2;
-    get resolution() {
-        return this._resolution;
-    }
-    set resolution(value) {
-        // 夹到合理区间：0 或负值会让 RT 尺寸为 0，WebGL 报 framebuffer incomplete
-        const next = Math.min(4, Math.max(0.25, Number.isFinite(value) ? value : 2));
-        if (next === this._resolution) {
-            return;
-        }
-        this._resolution = next;
-        // 尚未布局（size 为 0）时跳过，等首次 setSize 时自然会带上新倍率
-        if (this.size.x > 0 && this.size.y > 0) {
-            this.updateRenderTargetSizes(this.size.x, this.size.y);
-        }
-    }
-    /**
-     * 终处理抖动强度（消除 8bit 输出量化的色带，见 baseTextureToRenderShader）。
-     * 1.0 = 标准 ±0.5 LSB（默认，肉眼无感但能打散色带）；0 = 完全关闭。
-     * ⚠️ 若某处柔和渐变（外辉光/天空）看着"发脏/有颗粒"，先把它设 0 做 A/B 对比：
-     *    0 时若色带回来，说明抖动是必需的，应调小到 0.5 而不是关掉。
-     */
-    get ditherStrength() {
-        return baseTextureToRenderShader.uniforms.uDitherStrength.value;
-    }
-    set ditherStrength(value) {
-        const next = Math.max(0, Number.isFinite(value) ? value : 1);
-        baseTextureToRenderShader.uniforms.uDitherStrength.value = next;
-    }
-    /**
-     * 渲染目标(RT)底层配置（运行时可调，改即重建 base / screen 两个主颜色 RT）。
-     * 皇上要的「RT 上面的配置」= type / format / colorSpace / filter；
-     * 默认与原始硬编码一致（HalfFloatType + RGBAFormat + 线性 NoColorSpace + Linear 滤波）。
-     * 调这些能直观复现/消除典型问题：
-     *   - type=UnsignedByteType(8bit 线性)：柔和渐变被压成 3~6 色阶 → 同心环色带（banding）
-     *   - colorSpace=SRGBColorSpace：RT 已按 sRGB 编码 + 终处理再编一次 → 双重编码发白
-     *   - filter=NearestFilter：颜色插值变最近邻 → 边缘像素化/糊
-     */
-    _rtOptions = {
-        type: HalfFloatType,
-        colorSpace: NoColorSpace,
-        format: RGBAFormat,
-        filter: LinearFilter,
-    };
-    /** 面板/代码里的字符串名 → THREE 常量（单一映射点，避免散落硬编码数字） */
-    static rtNameToConstant(key, name) {
-        switch (key) {
-            case "type":
-                return { HalfFloat: HalfFloatType, Byte: UnsignedByteType, Float: FloatType }[name] ?? HalfFloatType;
-            case "colorSpace":
-                return { Linear: NoColorSpace, SRGB: SRGBColorSpace }[name] ?? NoColorSpace;
-            case "format":
-                return { RGBA: RGBAFormat, RGB: RGBFormat }[name] ?? RGBAFormat;
-            case "filter":
-                return { Linear: LinearFilter, Nearest: NearestFilter }[name] ?? LinearFilter;
-        }
-    }
-    /**
-     * 运行时改 RT 底层配置：更新 _rtOptions 后重建 base / screen 两个主颜色 RT（保留当前尺寸）。
-     * 必须在已布局（size>0）后才重建；否则等下次 setSize 自然带新选项。
-     * 仅重建主颜色 RT（base/screen）；深度/法线/aoDepth 是辅助通道，其 type 由对应 depthTexture 决定，
-     * 不在面板暴露，避免破坏深度比对 / SSAO 深度黑。
-     */
-    applyRenderTargetOption(key, name) {
-        switch (key) {
-            case "type":
-                this._rtOptions.type = ThreeBase.rtNameToConstant("type", name);
-                break;
-            case "colorSpace":
-                this._rtOptions.colorSpace = ThreeBase.rtNameToConstant("colorSpace", name);
-                break;
-            case "format":
-                this._rtOptions.format = ThreeBase.rtNameToConstant("format", name);
-                break;
-            case "filter":
-                this._rtOptions.filter = ThreeBase.rtNameToConstant("filter", name);
-                break;
-        }
-        this.rebuildRenderTargets();
-    }
-    rebuildRenderTargets() {
-        if (this.size.x <= 0 || this.size.y <= 0) {
-            return;
-        }
-        const w = Math.max(1, Math.round(this.size.x * this.effectiveRatio * this._resolution));
-        const h = Math.max(1, Math.round(this.size.y * this.effectiveRatio * this._resolution));
-        const opts = {
-            minFilter: this._rtOptions.filter,
-            magFilter: this._rtOptions.filter,
-            format: this._rtOptions.format,
-            type: this._rtOptions.type,
-            stencilBuffer: false,
-            anisotropy: 16,
-        };
-        this.baseRenderTarget.dispose();
-        this.baseRenderTarget = new WebGLRenderTarget(w, h, { ...opts });
-        this.baseRenderTarget.texture.colorSpace = this._rtOptions.colorSpace;
-        this.screenRenderTarget.dispose();
-        this.screenRenderTarget = new WebGLRenderTarget(w, h, { ...opts });
-        this.screenRenderTarget.texture.colorSpace = this._rtOptions.colorSpace;
-        this.needRender = true;
-    }
-    // 效果 mask 像素比硬上限：避免高 dpr 屏（如 2×）上 effectiveRatio×resolution 爆到 4×，
-    // 让效果 mask RT（含辉光多次高斯迭代）填充量失控。经验值 2×：相对设备 dpr 输出足够平滑，
-    // 且把"效果 mask 超采样"的填充量控制在场景同级的 2× 以内（原本 3× 在高 dpr 屏是"还是卡"的高嫌疑点）。
-    effectMaxPixelRatio = 2;
-    // 超采样倍率已统一为上方 resolution 字段（base / 深度 / 法线 / mask / 屏幕全部取它）。
-    // 辅助通道（深度/法线）分辨率系数。
-    // 关键：描边/发光/辉光/毛玻璃都拿 baseDepthTexture 做遮挡比对（deathTestShader 以全分辨率
-    // UV 采样半分辨率深度，并与全分辨率物体深度做硬阈值比较）。半分辨率深度（Nearest 滤波）被
-    // 放大采样后与锐利的物体深度在边缘逐像素翻转 discard，产生边缘摩尔纹/锯齿——这是这 4 个特效
-    // 共同的摩尔纹根因。故深度必须与 mask 同分辨率（全分辨率），1:1 采样才无放大错位。
-    // 法线仅 SSAO 使用（首页默认关闭、不渲染），全分辨率无额外开销。
-    // 之前为"不卡"降到 0.5 反而引入摩尔纹，已恢复为 1。
-    // 辅助通道(深度/法线)倍率已并入 resolution，不再单独设 auxRenderScale。
-    // 实际帧缓冲像素比 = min( max(devicePixelRatio, minDevicePixelRatio) * renderScale, maxPixelRatio )
-    get effectiveRatio() {
-        return Math.min(Math.max(window.devicePixelRatio, this.minDevicePixelRatio) * this.renderScale, this.maxPixelRatio);
-    }
-    // 基础深度纹理
-    baseDepthTexture = (() => {
-        const baseDepthTexture = new DepthTexture(4096, 4096);
-        baseDepthTexture.format = DepthFormat;
-        // 升级为 24/32 位深度（UnsignedIntType），相比原 16 位（UnsignedShortType）
-        // 能显著提升对数深度在远场的精度，消除 SSAO 与深度比对的 banding 瑕疵。
-        baseDepthTexture.type = UnsignedIntType;
-        baseDepthTexture.anisotropy = 16;
-        return baseDepthTexture;
-    })();
-    // 基础纹理渲染对象（无 MSAA）：抗锯齿统一由终处理 FXAA 承担。
-    // ⚠️ 必须保持与 depthRenderTarget 同样的「无 MSAA」策略——颜色 MSAA 会让物体边缘平滑成
-    // 半透明渐入，而 baseDepth（无 MSAA 硬边缘）在相交像素仍记完整深度，二者错位会导致
-    // depthTestShader 判定边界与人眼视觉不一致，描边/辉光在遮挡边界呈现锯齿状闪缩。
-    // 统一无 MSAA 后颜色与深度边缘严格对齐，边缘抗锯齿改由最终 FXAA 兜底（见 renderRendererTarget）。
-    // ⚠️ type 必须是 HalfFloatType（16bit 浮点），不能用默认的 UnsignedByteType（8bit）：
-    //    本 RT 存的是「线性」颜色（NoColorSpace），而 8bit 线性空间在暗部码值极度稀疏
-    //    （linear 码值 0/1/2/3 对应 sRGB 0/12.7/21.7/28.2，相邻码值跨度肉眼可见），
-    //    导致柔和渐变（外辉光、天空、雾、bloom 衰减）被压成 3~6 个色阶 → 呈现"一层一层"色带。
-    //    实测（2026-09-06 SpriteText3 外辉光 42px 扫描线）：
-    //      8bit linear：R 通道 42px 内仅 3 个色阶（每 14px 一跳）、G 通道 6 个色阶
-    //      sRGB 8bit  ：B 通道 42px 内 42 个色阶（每像素一阶，完全平滑）
-    //    改半浮点后渐变不再在中间量化，终处理仍只做一次 sRGB 编码（见 baseTextureToRenderShader）。
-    baseRenderTarget = (() => {
-        const baseRenderTarget = new WebGLRenderTarget(128, 128, {
-            minFilter: LinearFilter,
-            magFilter: LinearFilter,
-            format: RGBAFormat,
-            type: HalfFloatType,
-            stencilBuffer: false,
-            anisotropy: 16,
-        });
-        return baseRenderTarget;
-    })();
-    /** 可选的屏幕空间水流对象（WaterFlow）。默认 null；调用 enableWaterFlow() 后创建。启用时
-     * 每帧消费 baseRenderTarget/baseDepthTexture，把水面合成进后处理链（不额外渲染主场景）。 */
-    waterFlow = null;
-    _waterFlowLastTime = 0;
-    waterFlowElapsed = 0;
-    // 调试用：被排除面 mask 渲染目标（仅「排除面标记」调试档使用，尺寸随主渲染目标同步）
-    excludedMaskRenderTarget = new WebGLRenderTarget(128, 128, {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-        stencilBuffer: false,
-        depthBuffer: false,
-    });
-    // 深度专用渲染目标（无 MSAA，深度值稳定，供后处理深度比对使用）
-    depthRenderTarget = new WebGLRenderTarget(128, 128, {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-        stencilBuffer: false,
-        depthTexture: this.baseDepthTexture,
-    });
-    // AO 深度纹理（含地板）：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
-    // 法线 pass（renderAoNormalPass，includeFloor=true）渲染时深度由光栅器顺带写入，白拿一张含地板深度。
-    // （2026-09-14 优化：删掉原 ssao_pass 内那次 renderAoDepthPass(true)，每帧省一次全场景遍历。）
-    // SSAO 的 GTAO 采样它（地板保留为实体 → 接触 AO），合成时再与 depthRenderTarget
-    // （地板排除 = 可见深度）比对，作废"透过半透明地板看到的实体"上的地板接触 AO。
-    // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
-    aoDepthTexture = (() => {
-        const t = new DepthTexture(4096, 4096);
-        t.format = DepthFormat;
-        t.type = UnsignedIntType;
-        t.anisotropy = 16;
-        return t;
-    })();
-    /**
-     * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
-     *   - "none"    ：正常渲染（默认）
-     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
-     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
-     *   - "compare" ：R=全局 base 深度，G=最近一次 glow/stroke 选区 select 深度。两路任一全白即该侧写入失败。
-     *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=该面写不进深度，永远挡不住后处理）。
-     *                 物体区域（G 暗）若 B 全黑 → 判定从不触发；再看该区 R/G 谁大即可定位是谁缺深度。
-     * 兼容旧控制台入口：设置 `window.__BASE_DEPTH_VIS = true` 等价于切到 "global"。
-     * 通用控制台入口：任意页面都可 `window.__TB_DEBUG_DEPTH = "judge"`（优先级高于面板属性）。
-     */
-    debugDepthPreview = "none";
-    /**
-     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
-     *
-     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
-     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
-     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
-     */
-    get baseDepthIncludeFloor() {
-        return visibleDepthOptions.includeFloor;
-    }
-    set baseDepthIncludeFloor(v) {
-        visibleDepthOptions.includeFloor = v;
-        this.needRender = true;
-    }
-    // 法线专用渲染目标（无 MSAA，存储视图空间法线，供 GTAO 风格 SSAO 使用真实法线）
-    normalRenderTarget = new WebGLRenderTarget(128, 128, {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-        stencilBuffer: false,
-        // ⚠️ 挂 depthTexture：法线 pass 渲染时深度由光栅器顺带写进来，直接就是「含地板」的 AO 深度
-        // （零成本，无需再单独渲一遍深度 pass）。见上方 aoDepthTexture 注释。
-        depthTexture: this.aoDepthTexture,
-    });
-    // 屏幕合成目标（无 MSAA）：base（含 SSAO + 描边/发光/bloom）拷进来后，
-    // 颜色叠加/磨砂玻璃/水流/屏幕辉光 在此目标上叠加，最后由 FXAA 终处理输出到屏幕。
-    // 不挂 MSAA（FXAA 负责边缘）。
-    // ⚠️ 注意：SSAO 不在本目标上做——2026-09-14 起 SSAO 提前到对象级特效之前、直接乘进 baseRenderTarget
-    //    （见 render() 内注释与 test/depthDebug.test.js K 组护栏）。
-    // 与 baseRenderTarget 同为线性（NoColorSpace）：后处理全程在线性空间做颜色混合，
-    // 仅由终处理 baseTextureToRenderShader 用 sRGBTransferOETF 做一次 sRGB 编码输出屏幕，
-    // 避免「RT 已按 sRGB 编码 + 终处理再编一次」导致的双重编码发白。
-    // ⚠️ 同 baseRenderTarget：必须为 HalfFloatType。SSAO/颜色叠加/磨砂玻璃都在本目标上做线性混合，
-    //    若这里是 8bit，前面 base 用半浮点保住的渐变会在这一步重新被量化成色带（前功尽弃）。
-    screenRenderTarget = new WebGLRenderTarget(128, 128, {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-        type: HalfFloatType,
-        stencilBuffer: false,
-    });
-    // 基础纹理 -> 屏幕合成目标的纯拷贝（关掉深度，仅透传颜色），用于把 base 图像拷入
-    // screenRenderTarget 供后续后处理叠加。克隆自共享 copyShader，避免改动其状态。
-    screenCopyShader = (() => {
-        const shader = copyShader.clone();
-        shader.depthTest = false;
-        shader.depthWrite = false;
-        shader.transparent = false;
-        return shader;
-    })();
-    // 法线材质（MeshNormalMaterial 输出视图空间法线 pack 到 RGB，与 SSAO 的 unpackRGBToNormal 对应）
-    // ⚠️ side 必须 DoubleSide：本材质还兼职产出「含地板 AO 深度」（挂在 normalRenderTarget 上），
-    // 若只渲正面，DoubleSide / 背面朝向的几何会丢深度，与被它取代的那次独立深度 pass 行为不一致。
-    // 深度测试会让最近面胜出，故法线图内容不会因 DoubleSide 变差。
-    normalMaterial = new MeshNormalMaterial({ side: DoubleSide });
-    // 公用渲染目标1（无 MSAA：超采样已收敛到基础纹理与选中目标，其余通道去掉以提速）
-    renderTarget = new WebGLRenderTarget(128, 128, {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-    });
-    // 渲染目标2（无 MSAA）
-    renderTarget2 = new WebGLRenderTarget(128, 128, {
-        minFilter: LinearFilter,
-        magFilter: LinearFilter,
-        format: RGBAFormat,
-    });
-    // 公用二维向量
-    tempVector2 = new Vector2();
-    // 公用的三维向量
-    tempVector3 = new Vector3();
-    //渲染器的尺寸
-    size = new Vector2(0, 0);
-    //上下文丢失
-    rendererLost = false;
-    // 渲染器对象
-    renderer = (() => {
-        const renderer = new WebGLRenderer({
-            alpha: true,
-            precision: "highp",
-            logarithmicDepthBuffer: true,
-            preserveDrawingBuffer: true,
-            stencil: false,
-            powerPreference: 'high-performance' // 高性能模式
-        });
-        renderer.domElement.id = generateUUID();
-        //监听上下文的销毁事件
-        renderer.domElement.addEventListener("webglcontextlost", (event) => {
-            this.rendererLost = true;
-        }, false);
-        // 监听上下文的恢复事件
-        renderer.domElement.addEventListener("webglcontextrestored", (event) => {
-            this.rendererLost = false;
-        }, false);
-        renderer.localClippingEnabled = true;
-        renderer.setPixelRatio(Math.max(window.devicePixelRatio, this.minDevicePixelRatio)),
-            renderer.autoClear = false;
-        renderer.clear();
-        renderer.outputColorSpace = SRGBColorSpace;
-        // 颜色空间：图片什么颜色、3D 里就是什么颜色（sRGB 直出，所见即所得，不发白不褪色）。
-        // 关闭色调映射后，场景渲染进线性 baseRenderTarget 时不做 tonemap 压缩，终处理只做一次 sRGB
-        // 编码（baseTextureToRenderShader 手写 sRGBTransferOETF），全链路无额外提亮/降饱和，
-        // 颜色与原贴图一致。如需电影感可改回 ACESFilmicToneMapping（但会带来发白/褪色观感）。
-        renderer.toneMapping = NoToneMapping;
-        threeLoader.setAnisotropy(renderer.capabilities.getMaxAnisotropy());
-        return renderer;
-    })();
-    //透视相机
-    perspectiveCamera = new PerspectiveCamera(45, 1, 0.01, 20000);
-    //正交相机
-    orthographicCamera = new OrthographicCamera(-1, 1, 1, -1, 0.01, 20000);
-    //相机的类型 有透视相机和正交相机
-    cameraType = "perspectiveCamera";
-    setCameraType(cameraType) {
-        if (this.cameraType !== cameraType) {
-            this.cameraType = cameraType;
-            if (this.cameraType === "perspectiveCamera") {
-                this.threeMouse._camera = this.perspectiveCamera;
-                this.controls.object = this.perspectiveCamera;
-            }
-            else if (this.cameraType === "orthographicCamera") {
-                this.threeMouse._camera = this.orthographicCamera;
-                this.controls.object = this.orthographicCamera;
-            }
-        }
-    }
-    //获取当前使用的的相机
-    getCamera() {
-        switch (this.cameraType) {
-            case "orthographicCamera":
-                return this.orthographicCamera;
-            case "perspectiveCamera":
-            default:
-                return this.perspectiveCamera;
-        }
-    }
-    // 场景对象
-    scene = (() => {
-        const scene = new Scene();
-        return scene;
-    })();
-    // 这个方法等效 this.scene.add
-    // 想少写2个字母就用这个方法
-    add(...object) {
-        this.scene.add(...object);
-        return this;
-    }
-    ///鼠标事件对象
-    threeMouse = new ThreeMouse(this.renderer, this.perspectiveCamera, this.scene);
-    // 轨道控制器
-    controls = (() => {
-        const controls = new OrbitControls(this.perspectiveCamera, this.renderer.domElement);
-        controls.addEventListener("change", () => {
-            this.needRender = true;
-        });
-        // 转速：git 历史实证——以前（1826ab1）rotateSpeed=0.2 + enableDamping=true + dampingFactor=0.05
-        // 时「加阻尼也不晃」；a9f3ec9 把 rotateSpeed 提到 1.0（快 5 倍）才是"快速晃动中心点飘"的真因，
-        // 与阻尼无关。此处折中到 0.5：比 0.2 跟手、比 1.0 不易飘。若仍飘可降到 0.2 完全复原。
-        controls.rotateSpeed = 0.5;
-        controls.maxPolarAngle = Math.PI;
-        // 阻尼：回到以前不飘的配置（enableDamping=true + dampingFactor=0.05）。
-        // 0.05 是 1826ab1 验证过"加阻尼不晃"的值，配合下面 render 循环的帧率无关换算。
-        controls.enableDamping = true;
-        controls.dampingFactor = CONTROLS_DAMPING_BASE;
-        controls.screenSpacePanning = true;
-        return controls;
-    })();
-    // 帧率无关阻尼用的上一帧时间戳（performance.now() 毫秒），初始 0 表示首帧用 60fps 基准
-    _lastControlsTime = 0;
-    // 固定的实例化分组器：自动把所有 InstancedChild 合并进 InstancedMesh 批量渲染
-    instancedGroup = new InstancedGroup();
-    /**
-     * 自定义描边目标：不在 scene 内的独立对象（如 InstancedChild 的"选择代理"），
-     * 渲染循环在效果阶段单独对其调用 stroke_pass，使其获得与普通 Mesh 一致的描边，
-     * 且不会被正常 base pass 重复绘制（因为它不在 scene 树内）。
-     * 典型用途：InstancedChild / 一组 InstancedChild 没有自身几何，无法直接描边，
-     * 用 buildSelectProxy 重建其几何代理后再注册到这里即可。
-     */
-    _strokeObjects = [];
-    /** 注册一个自定义描边对象（效果阶段对其描边） */
-    addStrokeObject(object) {
-        if (this._strokeObjects.indexOf(object) < 0) {
-            this._strokeObjects.push(object);
-        }
-        return this;
-    }
-    /** 移除自定义描边对象 */
-    removeStrokeObject(object) {
-        const i = this._strokeObjects.indexOf(object);
-        if (i >= 0) {
-            this._strokeObjects.splice(i, 1);
-        }
-        return this;
-    }
-    // 设置 dom 容器
-    async setContainer(div) {
-        if (div) {
-            div.style.overflow = "hidden";
-            div.innerHTML = "";
-            div.append(this.renderer.domElement);
-            if (this.rendererLost) {
-                this.renderer.forceContextRestore();
-                this.needRender = true;
-                setTimeout(() => {
-                    this.needRender = true;
-                }, 100);
-                setTimeout(() => {
-                    this.renderer.domElement.style.opacity = "1";
-                }, 200);
-            }
-            this.setSize(div.clientWidth, div.clientHeight);
-            // 开启时时渲染
-            threeUtils.removeEventListener("requestAnimationFrame", this.renderBindThis);
-            threeUtils.addEventListener("requestAnimationFrame", this.renderBindThis);
-        }
-    }
-    // 修改尺寸
-    setSize(width, height) {
-        // 防御容器未布局/隐藏导致的 0 尺寸：相机 aspect、renderer、RT 都不能接受 0，
-        // 否则 WebGL 会报 GL_INVALID_VALUE / Framebuffer incomplete: Attachment has zero size。
-        width = Math.max(1, Math.floor(width));
-        height = Math.max(1, Math.floor(height));
-        //修改透视相机的比例
-        this.perspectiveCamera.aspect = width / height;
-        this.perspectiveCamera.updateProjectionMatrix();
-        //修改正交相机的比例
-        // this.orthographicCamera.top = height / width;
-        // this.orthographicCamera.bottom = -height / width;
-        this.orthographicCamera.left = -width / height;
-        this.orthographicCamera.right = width / height;
-        this.renderer.setPixelRatio(Math.max(window.devicePixelRatio, this.minDevicePixelRatio)),
-            this.renderer.setSize(width, height);
-        // 所有 RT 尺寸按 effectiveRatio × resolution 重建（容器尺寸变化与 resolution 变化共用）
-        this.updateRenderTargetSizes(width, height);
-        this.size.set(width, height);
-        setTimeout(() => {
-            this.needRender = true;
-        }, 100);
-        // 渲染场景
-        // this.renderer.clear();
-        // this.renderer.render(this.scene, this.camera);
-    }
-    /**
-     * 按「容器尺寸 × effectiveRatio × resolution」重建所有渲染目标尺寸。
-     * 由 setSize()（容器尺寸变化）与 resolution setter（运行时调倍率）共用 ——
-     * 关键：resolution 是运行时可调的性能/质量旋钮，改完必须立刻重建 RT，
-     * 否则倍率变了而 RT 尺寸没变，画面毫无变化（历史坑："调分辨率没感觉"）。
-     */
-    updateRenderTargetSizes(width, height) {
-        // 防御 0 尺寸：RT 不接受 0，否则 WebGL 报 framebuffer incomplete
-        const w = Math.max(1, Math.round(width * this.effectiveRatio * this._resolution));
-        const h = Math.max(1, Math.round(height * this.effectiveRatio * this._resolution));
-        // 主画面：超采样渲染，纹理摩尔纹在此被根治
-        this.baseRenderTarget.setSize(w, h);
-        // 深度/法线辅助通道：与 base 同倍率，保证 depthTest 1:1 无漏光、SSAO 深度不黑。
-        // 其 depthTexture(baseDepthTexture) 尺寸由 renderer 在 setRenderTarget 时
-        // 强制同步为 depthRenderTarget 尺寸，下面再手动对齐一次避免首帧抖动。
-        this.depthRenderTarget.setSize(w, h);
-        this.normalRenderTarget.setSize(w, h);
-        this.excludedMaskRenderTarget.setSize(w, h);
-        // 屏幕合成目标：同样跟随 resolution，全链路 1:1 对齐
-        this.screenRenderTarget.setSize(w, h);
-        // 水流后处理目标跟随同倍率重建（pass 内部粒子 RT 仍按 scale 降采样，compositeTarget 全分辨率）
-        this.waterFlow?.resize(w, h);
-        this.baseDepthTexture.image.width = w;
-        this.baseDepthTexture.image.height = h;
-        // 立即渲染一帧，避免静态场景下改了倍率却停在旧画面
-        this.needRender = true;
-    }
-    // 视角距离过度
-    controlsDistanceTransition = (() => {
-        const controlsDistanceTransition = new Transition({ distance: 0 });
-        controlsDistanceTransition.setDuration(1000);
-        return controlsDistanceTransition;
-    })();
-    //控制器的Y值过度计算
-    controlsYTransition = (() => {
-        const controlsYTransition = new Transition({ y: 0 });
-        controlsYTransition.setDuration(1000);
-        return controlsYTransition;
-    })();
-    //控制器的XZ值过度计算
-    controlsXZTransition = (() => {
-        const controlsXZTransition = new Transition({ x: 0, z: 0 });
-        controlsXZTransition.setDuration(1000);
-        return controlsXZTransition;
-    })();
-    // 控制器的 朝向带缓动的计算的顶点对象
-    controlsCenter = (() => {
-        const controlsCenter = new Transition({ x: 0, y: 0, z: 0 });
-        controlsCenter.setDuration(1000);
-        controlsCenter.onChange(({ x, y, z }) => {
-            this.controls.target.set(x, y, z);
-            this.perspectiveCamera.lookAt(this.controls.target);
-            this.orthographicCamera.lookAt(this.controls.target);
-            this.needRender = true;
-        });
-        return controlsCenter;
-    })();
-    // 控制器的位置缓动的计算的顶点对象
-    controlsPosition = (() => {
-        const controlsPosition = new Transition({ x: 100, y: 100, z: 100 });
-        controlsPosition.setDuration(1000);
-        controlsPosition.onChange(({ x, y, z }) => {
-            const distance = this.controlsDistanceTransition.get("distance");
-            this.perspectiveCamera.position.set(x + 0.0001, y, z + 0.0001);
-            this.perspectiveCamera.lookAt(this.controls.target);
-            //计算正交相机的缓动
-            this.orthographicCamera.position
-                .set(x + 0.01, y, z + 0.01)
-                .sub(this.controls.target)
-                .setLength(5000)
-                .add(this.controls.target);
-            this.orthographicCamera.lookAt(this.controls.target);
-            this.needRender = true;
-        });
-        return controlsPosition;
-    })();
-    // 网格辅助线
-    gridHelper = (() => {
-        const gridHelper = new GridHelper(1000, 100, 0x303030, 0x303030);
-        if (threeUtils.isDev) {
-            this.scene.add(gridHelper);
-        }
-        return gridHelper;
-    })();
-    //坐标轴线
-    axesHelper = (() => {
-        const axesHelper = new AxesHelper(10000);
-        if (threeUtils.isDev) {
-            this.scene.add(axesHelper);
-        }
-        return axesHelper;
-    })();
-    init() {
-        // 屏幕空间水流：?waterflow=1 时自动启用（默认关闭，需显式 enableWaterFlow 或此 URL 参数）。
-        // 创建后每帧消费 base 深度 + 后处理合成画面，把水面合成进后处理链，不自渲染主场景。
-        try {
-            const params = new URLSearchParams(typeof location !== 'undefined' ? location.search : '');
-            if (params.get('waterflow') === '1') {
-                this.enableWaterFlow();
-            }
-        }
-        catch (_e) {
-            // 非浏览器环境（如 Node 测试/SSR）忽略
-        }
-    }
-    /**
-     * 启用屏幕空间水流（GPGPU 粒子流体）。默认关闭，需显式调用或携带 ?waterflow=1。
-     * 创建后每帧自动消费 base 深度 + 当前合成画面，把水面合成进后处理链，不自渲染主场景。
-     * @param options.size   粒子网格边长（size×size 粒子），越大越细腻、越费
-     * @param options.speed  射流初速
-     * @param options.aperture 喷嘴开度
-     * @param options.nozzle 喷流起点坐标 [x,y,z]，默认 [0.58,1.55,0]
-     * @param options.jetDirection 喷流方向（轴向，会被归一化），默认 [1,0,0]（沿 +X）
-     * @param options.collision 是否开启粒子与 basin/地面碰撞回弹，默认 true
-     */
-    enableWaterFlow(options = {}) {
-        if (this.waterFlow) {
-            console.warn('[ThreeBase] WaterFlow 已启用，重复调用无效');
-            return;
-        }
-        const { size = 200, speed = 2.4, aperture = 0.78, nozzle, jetDirection, collision = true, } = options;
-        const waterFlow = new WaterFlow(this.renderer, {
-            size,
-            speed,
-            aperture,
-            nozzle: nozzle ? new Vector3(nozzle[0], nozzle[1], nozzle[2]) : undefined,
-            jetDirection: jetDirection ? new Vector3(jetDirection[0], jetDirection[1], jetDirection[2]) : undefined,
-            collision,
-        });
-        if (!waterFlow.supported) {
-            console.warn('[ThreeBase] 当前环境不支持浮点纹理，WaterFlow 未启用');
-            waterFlow.dispose();
-            return;
-        }
-        // 创建 pass 并注入基础纹理（externalBase 模式）；后续每帧 renderInto 会刷新注入的纹理。
-        // ⚠️ 2026-10-08（WaterFlow 全量 TS 化）：ScreenSpaceFluidPass 内部按透视相机建模
-        //    （setSize 读 camera.fov 算 pointScale、depthMaterial 走 projectionMatrix 重建深度），
-        //    故此处显式窄化。getCamera() 在 cameraType==="orthographicCamera" 时会返回
-        //    OrthographicCamera —— 原 JS 同样会把 fov=undefined 传进去（pointScale 变 NaN），
-        //    本次**只补类型、未改运行时行为**，保持与线上一致。
-        waterFlow.createPass(this.scene, this.getCamera(), {
-            colorTexture: this.baseRenderTarget.texture,
-            depthTexture: this.baseDepthTexture,
-            depthMode: 'logarithmic',
-        });
-        // 首帧按当前容器尺寸对齐（后续 setSize/resolution 变化由 updateRenderTargetSizes 兜底）。
-        const w = Math.max(1, Math.round(this.size.x * this.effectiveRatio * this._resolution));
-        const h = Math.max(1, Math.round(this.size.y * this.effectiveRatio * this._resolution));
-        if (this.size.x > 1 && this.size.y > 1)
-            waterFlow.resize(w, h);
-        this.waterFlow = waterFlow;
-        this._waterFlowLastTime = 0;
-        this.waterFlowElapsed = 0;
-        console.info('[ThreeBase] WaterFlow 已启用');
-    }
-    /** 运行时改喷流起点（喷嘴）坐标（WaterFlow 已启用时有效） */
-    setWaterFlowNozzle(x, y, z) {
-        this.waterFlow?.setNozzle(x, y, z);
-    }
-    /** 运行时改喷流方向（轴向，会被归一化） */
-    setWaterFlowJetDirection(x, y, z) {
-        this.waterFlow?.setJetDirection(x, y, z);
-    }
-    /** 运行时开关粒子与 basin/地面碰撞回弹 */
-    setWaterFlowCollision(enabled) {
-        this.waterFlow?.setCollision(enabled);
-    }
-    /**
-     * 关闭屏幕空间水流并释放其 GPU 资源（enableWaterFlow 的反操作）。
-     * 切走页面时必须调用，否则其它页面 render 仍会合成水面（this.waterFlow 非空）。
-     */
-    disableWaterFlow() {
-        if (!this.waterFlow)
-            return;
-        this.waterFlow.dispose();
-        this.waterFlow = null;
-        this._waterFlowLastTime = 0;
-        this.waterFlowElapsed = 0;
-        console.info('[ThreeBase] WaterFlow 已关闭');
-    }
-    // 重置控制器的位置
-    resetLookAt({ position = this.perspectiveCamera.position, center = this.controls.target, }) {
-        // 停止控制器的惯性
-        const originEnableDamping = this.controls.enableDamping;
-        this.controls.saveState();
-        this.controls.update();
-        this.controls.reset();
-        this.controls.enableDamping = originEnableDamping;
-        this.controlsDistanceTransition.reset({
-            distance: new Vector3(position.x, position.y, position.z).distanceTo(new Vector3(center.x, center.y, center.z))
-        });
-        position &&
-            this.controlsPosition.reset({
-                x: position.x,
-                y: position.y,
-                z: position.z,
-            });
-        center &&
-            this.controlsCenter.reset({ x: center.x, y: center.y, z: center.z });
-        this.needRender = true;
-    }
-    // 设置控制器的位置 以动画的方式移动控制器
-    async setLookAt({ position = this.perspectiveCamera.position, center = this.controls.target, duration = 1000, }) {
-        // 停止控制器的惯性
-        const originEnableDamping = this.controls.enableDamping;
-        this.controls.saveState();
-        this.controls.update();
-        this.controls.reset();
-        this.controls.enableDamping = originEnableDamping;
-        let currentPosition = this.perspectiveCamera.position.clone();
-        let currentCenter = this.controls.target.clone();
-        let currentDistance = this.perspectiveCamera.position.distanceTo(this.controls.target);
-        let targetPosition = new Vector3(position.x, position.y, position.z);
-        let targetCenter = new Vector3(center.x, center.y, center.z);
-        let targetDistance = targetPosition.distanceTo(targetCenter);
-        // 等待动画执行完成
-        await Promise.all([
-            new Promise(async (resolve, reject) => {
-                this.controlsDistanceTransition.setDuration(duration).reset({
-                    distance: currentDistance,
-                });
-                await this.controlsDistanceTransition.set({
-                    distance: targetDistance
-                });
-                resolve();
-            }),
-            new Promise(async (resolve, reject) => {
-                this.controlsPosition.setDuration(duration).reset({
-                    x: currentPosition.x,
-                    y: currentPosition.y,
-                    z: currentPosition.z,
-                });
-                await this.controlsPosition.set({
-                    x: position.x,
-                    y: position.y,
-                    z: position.z,
-                });
-                resolve();
-            }),
-            new Promise(async (resolve, reject) => {
-                this.controlsCenter.setDuration(duration).reset({
-                    x: currentCenter.x,
-                    y: currentCenter.y,
-                    z: currentCenter.z,
-                });
-                await this.controlsCenter.set({
-                    x: center.x,
-                    y: center.y,
-                    z: center.z,
-                });
-                resolve();
-            }),
-        ]);
-    }
-    // 获取控制的位置和朝向 保留3位小数
-    getLookAt() {
-        //判断需要使用那个相机
-        const position = this.perspectiveCamera.position
-            .toArray()
-            .map((v) => round(v, 3));
-        const center = this.controls.target.toArray().map((v) => round(v, 3));
-        return {
-            center: new Vector3(...center),
-            position: new Vector3(...position),
-            centerPosition: `center: new Vector3(${center.join(",")}),position: new Vector3(${position.join(",")})`,
-        };
-    }
-    // 查看对象
-    lookatObjects({ objects, duration = 1000, direction = new Vector3(0.3, 0.3, 1), offset = new Vector3(0, 0, 0), distance = 1, }) {
-        const box3 = new Box3();
-        objects.map((o) => {
-            o.traverseVisible((oo) => {
-                box3.expandByObject(oo);
-            });
-        });
-        const size = new Vector3();
-        box3.getSize(size);
-        const center = new Vector3();
-        box3.getCenter(center);
-        center.add(offset);
-        const modelSize = size.length() * distance;
-        if (this.cameraType === "perspectiveCamera") {
-            const { fov } = this.getCamera();
-            const cameraDistance = modelSize / (2 * Math.tan((fov * Math.PI) / 360));
-            const position = direction.setLength(cameraDistance).add(center);
-            this.setLookAt({ center, position, duration });
-        }
-    }
-    // 三维向量转化成屏幕上的2维向量
-    v3tov2(v3) {
-        //判断需要使用那个相机
-        const camera = this.getCamera();
-        v3.project(camera);
-        const v2 = new Vector2((v3.x + 1) * this.size.x * 0.5, (-v3.y + 1) * this.size.y * 0.5);
-        return v2;
-    }
-    // 控制器类型
-    controlType = "OrbitControls";
-    // 记录一下空间平移方式 在切换控制器的时候保留一下平移方式
-    originScreenSpacePanning = false;
-    //改变控制器的类型
-    setControlType(controlType) {
-        if (controlType === "OrbitControls") {
-            this.controls.screenSpacePanning = this.originScreenSpacePanning;
-            this.controls.mouseButtons = {
-                LEFT: MOUSE.ROTATE,
-                MIDDLE: MOUSE.DOLLY,
-                RIGHT: MOUSE.PAN,
-            };
-            this.controls.touches = { ONE: TOUCH.ROTATE, TWO: TOUCH.DOLLY_PAN };
-        }
-        else if (controlType === "MapControls") {
-            this.originScreenSpacePanning = this.controls.screenSpacePanning;
-            // pan orthogonal to world-space direction camera.up
-            this.controls.screenSpacePanning = false;
-            this.controls.mouseButtons.LEFT = MOUSE.PAN;
-            this.controls.mouseButtons.RIGHT = MOUSE.ROTATE;
-            this.controls.touches.ONE = TOUCH.PAN;
-            this.controls.touches.TWO = TOUCH.DOLLY_ROTATE;
-        }
-    }
-    // 是否自动渲染
-    autoRender = true;
-    //是否需要渲染, 当autoRender=false的时候就需要 手动触发渲染
-    needRender = false;
-    // SSAO 配置
-    ssao = {
-        enable: false,
-        debug: false,
-        radius: 5.0,
-        falloff: 5.0,
-        bias: 0.3,
-        intensity: 1.0,
-        sampleCount: 16,
-        blurRadius: 4.0,
-        strength: 1.0,
-        resolutionScale: 0.5,
-        distanceExponent: 1.0,
-        distanceFallOff: 1.0,
-        scale: 1.0, // GTAO：AO 次幂（gamma 校正）
-    };
-    // 屏幕空间辉光（经典 gaussian bloom）配置：纯颜色、无深度依赖，在 screenRenderTarget 上做加性叠加
-    bloom = {
-        enable: false,
-        strength: 0.6,
-        radius: 0.4,
-        threshold: 0.85,
-    };
-    // 停止渲染
-    stopRender() {
-        threeUtils.removeEventListener("requestAnimationFrame", this.renderBindThis);
-        if (!this.rendererLost) {
-            this.renderer.forceContextLoss();
-            this.setSize(100, 100);
-            this.renderer.domElement.style.opacity = "0";
-        }
-    }
-    // 彻底销毁当前渲染器实例：停止渲染循环、释放 WebGL 上下文与场景资源、卸载画布 DOM。
-    // 用于「每个 demo 视图各自持有渲染器、切换页面时自行销毁」的生命周期管理。
-    dispose() {
-        // 1. 停止渲染循环（移除 rAF 监听 + 丢失上下文）
-        this.stopRender();
-        // 2. 轨道控制器（移除其 DOM 事件监听）
-        this.controls?.dispose();
-        // 3. 鼠标拾取（移除 canvas 上的事件监听）
-        this.threeMouse?.dispose();
-        // 4. 释放场景内所有几何体 / 材质 / 纹理
-        this.scene.traverse((obj) => {
-            const mesh = obj;
-            if (mesh.geometry) {
-                mesh.geometry.dispose();
-            }
-            const material = mesh.material;
-            if (Array.isArray(material)) {
-                material.forEach((m) => this._disposeMaterial(m));
-            }
-            else if (material) {
-                this._disposeMaterial(material);
-            }
-        });
-        // 5. 渲染器与画布 DOM
-        const dom = this.renderer.domElement;
-        if (dom.parentElement) {
-            dom.parentElement.removeChild(dom);
-        }
-        this.renderer.dispose();
-    }
-    /** 释放单个材质及其引用的纹理（遍历材质属性找 Texture 并 dispose） */
-    _disposeMaterial(material) {
-        const record = material;
-        for (const key in record) {
-            const value = record[key];
-            if (value && value.isTexture) {
-                value.dispose();
-            }
-        }
-        material.dispose();
-    }
-    // 渲染场景
-    render() {
-        // canvas 没有在页面上面的话 就停止渲染
-        if (!threeUtils.inDocument(this.renderer.domElement)) {
-            this.stopRender();
-            return;
-        }
-        // 相机的朝向
-        const center = new Vector3(...this.controls.target.toArray().map((v) => round(v, 3)));
-        //透视相机和正交相机参数的时时转换
-        if (this.cameraType === "perspectiveCamera") {
-            const { fov } = this.perspectiveCamera;
-            const distaned = this.perspectiveCamera.position
-                .clone()
-                .sub(center)
-                .length();
-            const zoom = 1 / (Math.tan(degToRad(fov) / 2) * distaned);
-            this.orthographicCamera.zoom = zoom;
-            this.orthographicCamera.position
-                .copy(this.perspectiveCamera.position.clone().sub(center))
-                .setLength(2500)
-                .add(center);
-        }
-        else if (this.cameraType === "orthographicCamera") {
-            const { fov } = this.perspectiveCamera;
-            const { zoom } = this.orthographicCamera;
-            const distaned = 1 / zoom / Math.tan(degToRad(fov) / 2);
-            this.perspectiveCamera.position
-                .copy(this.orthographicCamera.position.clone().sub(center))
-                .setLength(distaned)
-                .add(center);
-        }
-        //判断需要使用那个相机
-        const camera = this.getCamera();
-        //判断尺寸发生改变时重置尺寸
-        const parentNode = this.renderer.domElement.parentNode;
-        if (parentNode.clientWidth !== this.size.x ||
-            parentNode.clientHeight !== this.size.y) {
-            this.setSize(parentNode.clientWidth, parentNode.clientHeight);
-        }
-        // 分发鼠标事件
-        this.threeMouse.dispatchEvent();
-        // 在不自动渲染时, needRender=false 就跳过渲染
-        if (!this.autoRender && !this.needRender) {
-            return; // 标识未渲染
-        }
-        this.needRender = false;
-        // 水流模拟推进：独立于相机控制，按真实帧间隔累计时间推进 GPGPU 粒子模拟。
-        // 默认 this.waterFlow 为 null（关闭），调用 enableWaterFlow() 或 ?waterflow=1 才创建。
-        if (this.waterFlow && this.waterFlow.supported) {
-            const wnow = performance.now();
-            const wdt = this._waterFlowLastTime > 0
-                ? Math.min((wnow - this._waterFlowLastTime) / 1000, 0.05)
-                : 1 / 60;
-            this._waterFlowLastTime = wnow;
-            this.waterFlowElapsed += wdt;
-            this.waterFlow.update(wdt, this.waterFlowElapsed);
-        }
-        if (this.controls.enabled) {
-            // 让 OrbitControls 始终接管"当前渲染相机"：OrbitControls 构造时只绑定了
-            // perspectiveCamera，但渲染相机随 cameraType 切换。若切到正交相机时仍让 OrbitControls
-            // 控制 perspectiveCamera、却用正交相机渲染，且每帧用正交相机反推并覆盖 perspectiveCamera，
-            // 两者打架 → 旋转中心漂移、运动错乱。此处把 controls.object 同步为渲染相机即可根治。
-            if (this.controls.object !== camera) {
-                this.controls.object = camera;
-            }
-            // 帧率无关的阻尼换算：OrbitControls 的 dampingFactor 是「每帧」衰减比例，固定值会随帧率变化
-            // 导致阻尼手感不一致——后处理管线重，快速晃动掉帧时单帧间隔变大、衰减比例却不变，
-            // 镜头运动一顿一顿、中心点发飘。这里把基准 dampingFactor 按真实帧间隔归一化到 60fps：
-            //   effective = 1 - (1 - BASE)^(dt*60)
-            // 掉帧（dt 变大）时自动加大单帧衰减比例，让阻尼手感与帧率解耦。
-            const now = performance.now();
-            const dt = this._lastControlsTime > 0
-                ? Math.min((now - this._lastControlsTime) / 1000, 0.05)
-                : 1 / 60;
-            this._lastControlsTime = now;
-            // 帧率无关阻尼换算：OrbitControls 的 dampingFactor 是「每帧」衰减比例，固定值会随帧率变化
-            // 导致阻尼手感不一致（后处理管线重、快速晃动掉帧时单帧间隔变大、衰减比例却不变 → 一顿一顿）。
-            // 把基准 dampingFactor 按真实帧间隔归一化到 60fps：effective = 1 - (1 - BASE)^(dt*60)，
-            // 掉帧时自动加大单帧衰减比例，让阻尼手感与帧率解耦。每帧无条件 update()（与 1826ab1 一致，
-            // 该版本 enableDamping=true + dampingFactor=0.05 已验证不飘）。
-            this.controls.dampingFactor = 1 - Math.pow(1 - CONTROLS_DAMPING_BASE, dt * 60);
-            this.controls.update();
-        }
-        {
-            // 先派发 beforeRender，让用户动画在当前帧修改 transform（修改会在下方一次性更新进世界矩阵）
-            this.dispatchEvent({ type: "beforeRender" });
-            // 实例化分组器：场景世界矩阵更新后，把 InstancedChild 同步进真实 InstancedMesh
-            this.instancedGroup.update();
-            // 渲染场景
-            // 把基础场景渲染到 帧缓冲区 在后期通道中会用到
-            this.renderer.setRenderTarget(this.baseRenderTarget);
-            this.renderer.clear();
-            this.renderer.render(this.scene, camera);
-            // 深度 pass：固定排除非实体表面后渲到 depthRenderTarget（生成 baseDepthTexture）。
-            // 必须在 base render 之后、所有依赖深度的特效（描边/发光/覆盖/磨砂）之前更新，
-            // 否则这些特效会用到上一帧旧深度 → 遮挡判定错乱。法线 pass 已收进 ssao_pass 内部。
-            renderAoDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
-            // 切回 baseRenderTarget，后处理 pass 需要把效果叠加到颜色渲染目标上
-            this.renderer.setRenderTarget(this.baseRenderTarget);
-            // 效果 mask 灰度图尺寸 = effectiveRatio × resolution，与 baseRenderTarget / baseDepthTexture 同倍率，
-            // 全链路 1:1 对齐（mask 跟随 resolution，深度也跟随 resolution，辉光漏光/mask 合成 UV 错位均消除）。
-            // 几何/效果边缘抗锯齿由「baseRenderTarget/screenRenderTarget 超采样(resolution) + 终处理 FXAA 降采样」承担。
-            const dpr = this.effectiveRatio * this.resolution;
-            // SSAO 后处理（基于深度计算遮蔽，乘法叠加）：数据准备 + 计算全在 ssao_pass 内部，
-            // 结果输出到「调用时绑定的渲染目标」。
-            // ⚠️ 顺序（2026-09-14 皇上旨）：SSAO 必须排在对象级特效（描边/发光/bloom/覆盖/磨砂）之前——
-            // 遮蔽只作用于纯场景底色，特效叠在 AO 之上，描边/辉光不会被 AO 压暗、也不会被 AO 的噪声污染。
-            // 此处绑定的是 baseRenderTarget，故 AO 直接乘进 base；后面的特效与「base → screen 拷贝」
-            // 全部基于「已含 AO」的底色，后续 pass 无需任何改动。
-            ssao_pass(this.renderer, camera, this.scene, this.depthRenderTarget, this.normalRenderTarget, this.normalMaterial, dpr, this.ssao);
-            // 后处理特效渲染(描边,发光,颜色覆盖,bloom,磨砂玻璃)：叠加到 baseRenderTarget（此时已含 SSAO）
-            this.scene.traverseVisible((child) => {
-                if (child instanceof Mesh || child instanceof Line || child instanceof Points) {
-                    stroke_pass(this.renderer, camera, child, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                    glow_pass(this.renderer, camera, child, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                    bloom_pass(this.renderer, camera, child, this.baseRenderTarget, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                }
-            });
-            // 自定义描边对象（如 InstancedChild 的选择代理）：不在 scene 内，单独在效果阶段描边。
-            // 代理用实例自身的 matrixWorld + 同款 geometry/material 重建，故其深度/灰度与真实实例严格对齐，
-            // 并复用同一张 baseDepthTexture 做遮挡判定（被其他物体挡住的部分不描边）。
-            for (const so of this._strokeObjects) {
-                stroke_pass(this.renderer, camera, so, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                glow_pass(this.renderer, camera, so, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                bloom_pass(this.renderer, camera, so, this.baseRenderTarget, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-            }
-            // 把 base(含 SSAO)+描边/发光/bloom 合成结果拷到屏幕合成目标，后续 颜色叠加/磨砂玻璃
-            // 在此目标上叠加；最后统一跑一次 FXAA 终处理输出到屏幕，覆盖全部后处理的锯齿/摩尔纹。
-            this.renderer.setRenderTarget(this.screenRenderTarget);
-            this.renderer.clear();
-            this.screenCopyShader.uniforms.map.value = this.baseRenderTarget.texture;
-            fsQuad.render(this.renderer, this.screenCopyShader);
-            // 颜色叠加
-            this.scene.traverseVisible((child) => {
-                if (child instanceof Mesh || child instanceof Line || child instanceof Points) {
-                    cover_pass(this.renderer, camera, child, this.baseDepthTexture, dpr);
-                }
-            });
-            for (const so of this._strokeObjects) {
-                cover_pass(this.renderer, camera, so, this.baseDepthTexture, dpr);
-            }
-            // 一次性处理所有支持毛玻璃特效的对象
-            frosted_glass_pass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, dpr);
-            // 屏幕空间水流：消费 base 深度 + 当前合成画面（含 ssao/覆盖/磨砂），把水面合成进
-            // screenRenderTarget。插在磨砂之后、screenBloom 之前，使水面高光也能被泛光处理。
-            // 默认关闭（this.waterFlow 为 null 时不产生任何开销）。
-            if (this.waterFlow && this.waterFlow.supported) {
-                waterFlowPass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, this.waterFlow);
-            }
-            // 屏幕空间辉光（经典 gaussian bloom）：纯颜色、无深度依赖，把亮度超阈值的部分做
-            // 连续高斯模糊后加性叠加回 screenRenderTarget。单分辨率多迭代，柔和均匀、无 mip 分层。
-            if (this.bloom.enable) {
-                screenBloomPass(this.renderer, this.screenRenderTarget, {
-                    strength: this.bloom.strength,
-                    radius: this.bloom.radius,
-                    threshold: this.bloom.threshold,
-                });
-            }
-            // FXAA 终处理：对最终合成图像（含 SSAO/AO/叠加/磨砂/辉光）跑一次 FXAA 统一兜底锯齿与摩尔纹，
-            // 分辨率按实际帧缓冲像素（已乘 dpr）设置，修复高分屏下 FXAA 采样比例偏大失效的问题。
-            // ⚠️ 深度调试预览（面板「深度调试」切换，定位"深度测试全部失效"根因）：
-            //   旧控制台入口 `window.__BASE_DEPTH_VIS = true` 仍可用，等价于切到 "global"。
-            //   global  → baseDepthTexture 灰度。全白=深度为空(renderAoDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
-            //   ao      → aoDepthTexture 灰度（含地板）。确认深度管线本身是否工作（GTAO 是否拿到正确深度）。
-            //   compare → R=全局 base 深度，G=最近一次 glow/stroke 选区的 select 深度。两路任一全白即该侧写入失败。
-            //   judge   → R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)。
-            // 通用控制台入口（任意页面可用，优先级高于面板属性）：
-            //   `window.__TB_DEBUG_DEPTH = "global" | "ao" | "compare" | "judge"`，设回 "none" 恢复。
-            const dbgWin = window.__TB_DEBUG_DEPTH;
-            const dbgMode = window.__BASE_DEPTH_VIS
-                ? "global"
-                : (dbgWin ?? this.debugDepthPreview);
-            if (dbgMode !== "none") {
-                this.renderer.setRenderTarget(null);
-                this.renderer.clear();
-                if (dbgMode === "global") {
-                    baseDepthVisShader.uniforms.tDepth.value = this.baseDepthTexture;
-                    fsQuad.render(this.renderer, baseDepthVisShader);
-                }
-                else if (dbgMode === "ao") {
-                    baseDepthVisShader.uniforms.tDepth.value = this.aoDepthTexture;
-                    fsQuad.render(this.renderer, baseDepthVisShader);
-                }
-                else if (dbgMode === "compare") {
-                    debugDepthCompareShader.uniforms.tBase.value = this.baseDepthTexture;
-                    debugDepthCompareShader.uniforms.tSelect.value =
-                        debugDepthState.lastSelectDepth ?? this.baseDepthTexture;
-                    debugDepthCompareShader.uniforms.cameraFar.value = camera.far;
-                    fsQuad.render(this.renderer, debugDepthCompareShader);
-                }
-                else if (dbgMode === "judge") {
-                    debugDepthJudgeShader.uniforms.tBase.value = this.baseDepthTexture;
-                    debugDepthJudgeShader.uniforms.tSelect.value =
-                        debugDepthState.lastSelectDepth ?? this.baseDepthTexture;
-                    fsQuad.render(this.renderer, debugDepthJudgeShader);
-                }
-                else if (dbgMode === "excluded") {
-                    // 先渲「被排除面 mask」，再与深度图叠加：红=挡不住任何后处理的面
-                    renderExcludedMaskPass(this.renderer, camera, this.scene, this.excludedMaskRenderTarget);
-                    debugExcludedShader.uniforms.tDepth.value = this.baseDepthTexture;
-                    debugExcludedShader.uniforms.tMask.value = this.excludedMaskRenderTarget.texture;
-                    fsQuad.render(this.renderer, debugExcludedShader);
-                }
-                flushLensflareOverlays(this.renderer, camera);
-                return;
-            }
-            this.renderer.setRenderTarget(null);
-            this.renderer.clear();
-            this.renderRendererTarget(this.screenRenderTarget);
-            // 镜头光晕（Lensflare）解耦：渲染器输出屏幕后统一叠加所有可见鬼影。
-            // flushLensflareOverlays 内部仅当渲染目标为屏幕时生效，不污染任何中间后处理 target；
-            // LensFlare 实例自己管理状态（构造注册进全局表、dispose 注销），ThreeBase 不遍历场景、不认识其类型。
-            flushLensflareOverlays(this.renderer, camera);
-        }
-    }
-    renderBindThis = this.render.bind(this);
-    //获取渲染图blob对象
-    async getThumbBlob() {
-        this.renderer.setRenderTarget(this.baseRenderTarget);
-        this.renderer.clear();
-        this.renderer.render(this.scene, this.getCamera());
-        this.renderer.setRenderTarget(null);
-        this.renderer.clear();
-        this.renderRendererTarget(this.baseRenderTarget);
-        const blob = await new Promise((resolve, reject) => {
-            this.renderer.domElement.toBlob((blob) => {
-                resolve(blob);
-            }, "image/png", 1);
-        });
-        return blob;
-    }
-    //获取渲染图base64
-    getThumbBase64() {
-        this.renderer.setRenderTarget(this.baseRenderTarget);
-        this.renderer.clear();
-        this.renderer.render(this.scene, this.getCamera());
-        this.renderer.setRenderTarget(null);
-        this.renderer.clear();
-        this.renderRendererTarget(this.baseRenderTarget);
-        const base64 = this.renderer.domElement.toDataURL("image/png");
-        return base64;
-    }
-    //获取渲染图文件对象
-    async getThumbFile() {
-        const blob = await this.getThumbBlob();
-        const file = new File([blob], "thumb.png", { type: blob.type });
-        return file;
-    }
-    // 下载渲染图
-    async download(fileName = "download") {
-        const blob = await this.getThumbBlob();
-        let saveLink = document.createElement("a");
-        saveLink.download = `${fileName}.png`;
-        saveLink.href = URL.createObjectURL(blob);
-        document.body.append(saveLink);
-        saveLink.click();
-    }
-    //把渲染目标渲染到canvas上
-    renderRendererTarget(renderTarget) {
-        // FXAA 分辨率按实际帧缓冲像素尺寸（乘 devicePixelRatio）设置，否则高分屏下
-        // 采样步长被当成 CSS 像素，FXAA 失效甚至引入摩尔纹。
-        const dpr = Math.max(window.devicePixelRatio, this.minDevicePixelRatio);
-        baseTextureToRenderShader.uniforms.resolution.value.set(1 / (this.size.x * dpr), 1 / (this.size.y * dpr));
-        baseTextureToRenderShader.uniforms.tDiffuse.value = renderTarget.texture;
-        fsQuad.render(this.renderer, baseTextureToRenderShader);
-    }
-    // 渲染纹理
-    renderTexture(texture, alpha = false) {
-        copyShader.uniforms.map.value = texture;
-        copyShader.uniforms.opacity.value = 1.0;
-        copyShader.blending = alpha ? NoBlending : NormalBlending;
-        fsQuad.render(this.renderer, copyShader);
-    }
-}
+/*
+ * @Author: xiaosihan
+ * @Date: 2021-12-20 13:38:22
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2025-01-28 04:26:41
+ */
+import { round } from "lodash";
+import { AxesHelper, Box3, DepthFormat, DepthTexture, DoubleSide, EventDispatcher, GridHelper, HalfFloatType, LinearFilter, Line, Mesh, MeshNormalMaterial, MOUSE, NearestFilter, NoBlending, NoColorSpace, NormalBlending, OrthographicCamera, PerspectiveCamera, Points, RGBAFormat, RGBFormat, FloatType, UnsignedByteType, NoToneMapping, Scene, SRGBColorSpace, TOUCH, UnsignedIntType, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
+import { MathUtils } from "three";
+const { degToRad, generateUUID } = MathUtils;
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+import ThreeMouse from "./ThreeMouse";
+import InstancedGroup from "./instanced/InstancedGroup";
+import Transition from "./Transition";
+import bloom_pass from "./pass/bloom_pass";
+import cover_pass from "./pass/cover_pass";
+import frosted_glass_pass from "./pass/frosted_glass_pass";
+import { flushLensflareOverlays } from "./lensflare/LensFlare";
+import glow_pass from "./pass/glow_pass";
+import stroke_pass from "./pass/stroke_pass";
+import ssao_pass, { renderAoDepthPass, renderExcludedMaskPass, visibleDepthOptions } from "./pass/ssao_pass";
+import screenBloomPass from "./pass/screen_bloom_pass";
+import copyShader from "./shaders/copyShader";
+import { baseTextureToRenderShader } from "./shaders/baseTextureToRenderShader";
+import baseDepthVisShader from "./shaders/baseDepthVisShader";
+import debugDepthCompareShader from "./shaders/debugDepthCompareShader";
+import debugDepthJudgeShader from "./shaders/debugDepthJudgeShader";
+import debugExcludedShader from "./shaders/debugExcludedShader";
+import { debugDepthState } from "./pass/debugDepthState";
+import { WaterFlow } from "./WaterFlow/WaterFlow";
+import waterFlowPass from "./WaterFlow/waterFlowPass";
+import threeLoader from "./threeLoader";
+import threeUtils from "./threeUtils";
+import fsQuad from "./pass/fsQuad";
+/** OrbitControls 阻尼基准值（等价于 60fps 下的单帧衰减比例）。
+ *  render 循环会按真实帧间隔把它换算成「帧率无关」的单帧衰减比例（见下方 controls.update 处）。
+ *  取值历史：0.05（1826ab1 验证过"加阻尼也不晃"的正常值，配合 rotateSpeed=0.2）→
+ *  a9f3ec9 把 rotateSpeed 提到 1.0 才导致"快速晃动中心点飘"，与阻尼无关；该次顺手把阻尼关成 false 诊断。
+ *  本轮复原：enableDamping=true + dampingFactor=0.05（回到不飘配置），rotateSpeed 折中 0.5（0.2 跟手、
+ *  1.0 易飘）。若 0.5 仍飘，降到 0.2 完全复原 1826ab1；若想更跟手，升到 0.3~0.4 之间试。 */
+const CONTROLS_DAMPING_BASE = 0.05;
+// three.js 的基础对象
+export default class ThreeBase extends EventDispatcher {
+    constructor() {
+        super();
+        // 资源加载进度有更新时, 需要渲染
+        threeLoader.addEventListener("loadding", () => {
+            this.dispatchEvent({ type: "loadding" });
+            setTimeout(() => {
+                this.needRender = true;
+            }, 100);
+        });
+        threeLoader.addEventListener("onLoad", () => {
+            this.dispatchEvent({ type: "onLoad" });
+            setTimeout(() => {
+                this.needRender = true;
+            }, 100);
+        });
+        // 固定的实例化分组器挂进场景，并注入到鼠标事件系统用于 InstancedMesh 命中路由
+        this.scene.add(this.instancedGroup);
+        this.threeMouse.instancedGroup = this.instancedGroup;
+        this.init();
+    }
+    // 设置最小分辨率
+    minDevicePixelRatio = 1;
+    // 实际帧缓冲像素比硬上限：SSAA 超采样可能把总像素比推得过高导致卡顿，
+    // 这里硬性限制 effectiveRatio 不超过该值（无论设备像素比或 renderScale 多大）。
+    // 高 dpr 屏（如 2×）下 effectiveRatio=2 会让整条后处理链在 2× 分辨率跑，快速晃动掉帧顿挫、
+    // 像素抖动（用户感知为"飘"）；收紧到 1（高 dpr 屏 base RT 最多 1×2=2× 每维）进一步压中间 RT 填充率。注意 renderer 自身
+    // setPixelRatio 仍按 dpr 输出最终屏幕，这里只压中间 RT 计算量，不影响最终清晰度。
+    maxPixelRatio = 1;
+    // 超采样倍数（SSAA）：在帧缓冲分辨率基础上再乘 renderScale 渲染，
+    // 最后由 FXAA 降采样输出到屏幕。renderScale>1 可消除"纹理缩小产生的摩尔纹"——
+    // MSAA 只处理几何边缘、管不到着色器内的纹理采样；SSAA 才是纹理摩尔纹的治本手段
+    // （纹理被欠采样时的拍频，必须靠提高实际采样率才能消除）。
+    // 1 = 关闭超采样（仅设备 pixelRatio）；2 = 2 倍超采样（质量最高，片元开销 ×4，需强 GPU）。
+    renderScale = 1;
+    // 全局超采样/分辨率倍率（SSAA）：base / 深度 / 法线 / 效果 mask / 屏幕合成 全部按
+    // effectiveRatio × resolution 内部超采样渲染，终处理 FXAA 降采样输出到屏幕。
+    // 全链路同倍率 → 各 RT 严格 1:1 对齐：几何锯齿、效果边缘锯齿、辉光漏光（深度 vs mask 错位）、
+    // mask 合成 UV 缩放错位、SSAO 深度错位变黑 一并消除。默认 2 = 每维 2×、总像素 4×；
+    // 代价全链路填充 ×4（base + 深度 + 法线 + 后处理 SSAO/cover/frosted）。要省性能整体降 1
+    // （关超采样，仅 FXAA 兜底，几何硬边锯齿回弹）。历史坑：baseRenderScale/auxRenderScale/
+    // effectRenderScale 三参各自为政，倍率不同步必错位，故统一为单参数 resolution 管全局。
+    // ⚠️ 必须用 getter/setter，不能是普通字段：所有 RT 尺寸只在 updateRenderTargetSizes()
+    // 里按 effectiveRatio × resolution 计算，而该方法过去只被 setSize()（容器尺寸变化）调用
+    // → 运行时改 resolution 不会重建任何 RT，画面毫无变化（表现为"调分辨率没感觉"）。
+    // 故 setter 里改动倍率后立刻重建全部 RT。
+    _resolution = 2;
+    get resolution() {
+        return this._resolution;
+    }
+    set resolution(value) {
+        // 夹到合理区间：0 或负值会让 RT 尺寸为 0，WebGL 报 framebuffer incomplete
+        const next = Math.min(4, Math.max(0.25, Number.isFinite(value) ? value : 2));
+        if (next === this._resolution) {
+            return;
+        }
+        this._resolution = next;
+        // 尚未布局（size 为 0）时跳过，等首次 setSize 时自然会带上新倍率
+        if (this.size.x > 0 && this.size.y > 0) {
+            this.updateRenderTargetSizes(this.size.x, this.size.y);
+        }
+    }
+    /**
+     * 终处理抖动强度（消除 8bit 输出量化的色带，见 baseTextureToRenderShader）。
+     * 1.0 = 标准 ±0.5 LSB（默认，肉眼无感但能打散色带）；0 = 完全关闭。
+     * ⚠️ 若某处柔和渐变（外辉光/天空）看着"发脏/有颗粒"，先把它设 0 做 A/B 对比：
+     *    0 时若色带回来，说明抖动是必需的，应调小到 0.5 而不是关掉。
+     */
+    get ditherStrength() {
+        return baseTextureToRenderShader.uniforms.uDitherStrength.value;
+    }
+    set ditherStrength(value) {
+        const next = Math.max(0, Number.isFinite(value) ? value : 1);
+        baseTextureToRenderShader.uniforms.uDitherStrength.value = next;
+    }
+    /**
+     * 渲染目标(RT)底层配置（运行时可调，改即重建 base / screen 两个主颜色 RT）。
+     * 皇上要的「RT 上面的配置」= type / format / colorSpace / filter；
+     * 默认与原始硬编码一致（HalfFloatType + RGBAFormat + 线性 NoColorSpace + Linear 滤波）。
+     * 调这些能直观复现/消除典型问题：
+     *   - type=UnsignedByteType(8bit 线性)：柔和渐变被压成 3~6 色阶 → 同心环色带（banding）
+     *   - colorSpace=SRGBColorSpace：RT 已按 sRGB 编码 + 终处理再编一次 → 双重编码发白
+     *   - filter=NearestFilter：颜色插值变最近邻 → 边缘像素化/糊
+     */
+    _rtOptions = {
+        type: HalfFloatType,
+        colorSpace: NoColorSpace,
+        format: RGBAFormat,
+        filter: LinearFilter,
+    };
+    /** 面板/代码里的字符串名 → THREE 常量（单一映射点，避免散落硬编码数字） */
+    static rtNameToConstant(key, name) {
+        switch (key) {
+            case "type":
+                return { HalfFloat: HalfFloatType, Byte: UnsignedByteType, Float: FloatType }[name] ?? HalfFloatType;
+            case "colorSpace":
+                return { Linear: NoColorSpace, SRGB: SRGBColorSpace }[name] ?? NoColorSpace;
+            case "format":
+                return { RGBA: RGBAFormat, RGB: RGBFormat }[name] ?? RGBAFormat;
+            case "filter":
+                return { Linear: LinearFilter, Nearest: NearestFilter }[name] ?? LinearFilter;
+        }
+    }
+    /**
+     * 运行时改 RT 底层配置：更新 _rtOptions 后重建 base / screen 两个主颜色 RT（保留当前尺寸）。
+     * 必须在已布局（size>0）后才重建；否则等下次 setSize 自然带新选项。
+     * 仅重建主颜色 RT（base/screen）；深度/法线/aoDepth 是辅助通道，其 type 由对应 depthTexture 决定，
+     * 不在面板暴露，避免破坏深度比对 / SSAO 深度黑。
+     */
+    applyRenderTargetOption(key, name) {
+        switch (key) {
+            case "type":
+                this._rtOptions.type = ThreeBase.rtNameToConstant("type", name);
+                break;
+            case "colorSpace":
+                this._rtOptions.colorSpace = ThreeBase.rtNameToConstant("colorSpace", name);
+                break;
+            case "format":
+                this._rtOptions.format = ThreeBase.rtNameToConstant("format", name);
+                break;
+            case "filter":
+                this._rtOptions.filter = ThreeBase.rtNameToConstant("filter", name);
+                break;
+        }
+        this.rebuildRenderTargets();
+    }
+    rebuildRenderTargets() {
+        if (this.size.x <= 0 || this.size.y <= 0) {
+            return;
+        }
+        const w = Math.max(1, Math.round(this.size.x * this.effectiveRatio * this._resolution));
+        const h = Math.max(1, Math.round(this.size.y * this.effectiveRatio * this._resolution));
+        const opts = {
+            minFilter: this._rtOptions.filter,
+            magFilter: this._rtOptions.filter,
+            format: this._rtOptions.format,
+            type: this._rtOptions.type,
+            stencilBuffer: false,
+            anisotropy: 16,
+        };
+        this.baseRenderTarget.dispose();
+        this.baseRenderTarget = new WebGLRenderTarget(w, h, { ...opts });
+        this.baseRenderTarget.texture.colorSpace = this._rtOptions.colorSpace;
+        this.screenRenderTarget.dispose();
+        this.screenRenderTarget = new WebGLRenderTarget(w, h, { ...opts });
+        this.screenRenderTarget.texture.colorSpace = this._rtOptions.colorSpace;
+        this.needRender = true;
+    }
+    // 效果 mask 像素比硬上限：避免高 dpr 屏（如 2×）上 effectiveRatio×resolution 爆到 4×，
+    // 让效果 mask RT（含辉光多次高斯迭代）填充量失控。经验值 2×：相对设备 dpr 输出足够平滑，
+    // 且把"效果 mask 超采样"的填充量控制在场景同级的 2× 以内（原本 3× 在高 dpr 屏是"还是卡"的高嫌疑点）。
+    effectMaxPixelRatio = 2;
+    // 超采样倍率已统一为上方 resolution 字段（base / 深度 / 法线 / mask / 屏幕全部取它）。
+    // 辅助通道（深度/法线）分辨率系数。
+    // 关键：描边/发光/辉光/毛玻璃都拿 baseDepthTexture 做遮挡比对（deathTestShader 以全分辨率
+    // UV 采样半分辨率深度，并与全分辨率物体深度做硬阈值比较）。半分辨率深度（Nearest 滤波）被
+    // 放大采样后与锐利的物体深度在边缘逐像素翻转 discard，产生边缘摩尔纹/锯齿——这是这 4 个特效
+    // 共同的摩尔纹根因。故深度必须与 mask 同分辨率（全分辨率），1:1 采样才无放大错位。
+    // 法线仅 SSAO 使用（首页默认关闭、不渲染），全分辨率无额外开销。
+    // 之前为"不卡"降到 0.5 反而引入摩尔纹，已恢复为 1。
+    // 辅助通道(深度/法线)倍率已并入 resolution，不再单独设 auxRenderScale。
+    // 实际帧缓冲像素比 = min( max(devicePixelRatio, minDevicePixelRatio) * renderScale, maxPixelRatio )
+    get effectiveRatio() {
+        return Math.min(Math.max(window.devicePixelRatio, this.minDevicePixelRatio) * this.renderScale, this.maxPixelRatio);
+    }
+    // 基础深度纹理
+    baseDepthTexture = (() => {
+        const baseDepthTexture = new DepthTexture(4096, 4096);
+        baseDepthTexture.format = DepthFormat;
+        // 升级为 24/32 位深度（UnsignedIntType），相比原 16 位（UnsignedShortType）
+        // 能显著提升对数深度在远场的精度，消除 SSAO 与深度比对的 banding 瑕疵。
+        baseDepthTexture.type = UnsignedIntType;
+        baseDepthTexture.anisotropy = 16;
+        return baseDepthTexture;
+    })();
+    // 基础纹理渲染对象（无 MSAA）：抗锯齿统一由终处理 FXAA 承担。
+    // ⚠️ 必须保持与 depthRenderTarget 同样的「无 MSAA」策略——颜色 MSAA 会让物体边缘平滑成
+    // 半透明渐入，而 baseDepth（无 MSAA 硬边缘）在相交像素仍记完整深度，二者错位会导致
+    // depthTestShader 判定边界与人眼视觉不一致，描边/辉光在遮挡边界呈现锯齿状闪缩。
+    // 统一无 MSAA 后颜色与深度边缘严格对齐，边缘抗锯齿改由最终 FXAA 兜底（见 renderRendererTarget）。
+    // ⚠️ type 必须是 HalfFloatType（16bit 浮点），不能用默认的 UnsignedByteType（8bit）：
+    //    本 RT 存的是「线性」颜色（NoColorSpace），而 8bit 线性空间在暗部码值极度稀疏
+    //    （linear 码值 0/1/2/3 对应 sRGB 0/12.7/21.7/28.2，相邻码值跨度肉眼可见），
+    //    导致柔和渐变（外辉光、天空、雾、bloom 衰减）被压成 3~6 个色阶 → 呈现"一层一层"色带。
+    //    实测（2026-09-06 SpriteText3 外辉光 42px 扫描线）：
+    //      8bit linear：R 通道 42px 内仅 3 个色阶（每 14px 一跳）、G 通道 6 个色阶
+    //      sRGB 8bit  ：B 通道 42px 内 42 个色阶（每像素一阶，完全平滑）
+    //    改半浮点后渐变不再在中间量化，终处理仍只做一次 sRGB 编码（见 baseTextureToRenderShader）。
+    baseRenderTarget = (() => {
+        const baseRenderTarget = new WebGLRenderTarget(128, 128, {
+            minFilter: LinearFilter,
+            magFilter: LinearFilter,
+            format: RGBAFormat,
+            type: HalfFloatType,
+            stencilBuffer: false,
+            anisotropy: 16,
+        });
+        return baseRenderTarget;
+    })();
+    /** 可选的屏幕空间水流对象（WaterFlow）。默认 null；调用 enableWaterFlow() 后创建。启用时
+     * 每帧消费 baseRenderTarget/baseDepthTexture，把水面合成进后处理链（不额外渲染主场景）。 */
+    waterFlow = null;
+    _waterFlowLastTime = 0;
+    waterFlowElapsed = 0;
+    // 调试用：被排除面 mask 渲染目标（仅「排除面标记」调试档使用，尺寸随主渲染目标同步）
+    excludedMaskRenderTarget = new WebGLRenderTarget(128, 128, {
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        format: RGBAFormat,
+        stencilBuffer: false,
+        depthBuffer: false,
+    });
+    // 深度专用渲染目标（无 MSAA，深度值稳定，供后处理深度比对使用）
+    depthRenderTarget = new WebGLRenderTarget(128, 128, {
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        format: RGBAFormat,
+        stencilBuffer: false,
+        depthTexture: this.baseDepthTexture,
+    });
+    // AO 深度纹理（含地板）：**不再单独渲染一遍** —— 它挂在 normalRenderTarget 上当 depth attachment，
+    // 法线 pass（renderAoNormalPass，includeFloor=true）渲染时深度由光栅器顺带写入，白拿一张含地板深度。
+    // （2026-09-14 优化：删掉原 ssao_pass 内那次 renderAoDepthPass(true)，每帧省一次全场景遍历。）
+    // SSAO 的 GTAO 采样它（地板保留为实体 → 接触 AO），合成时再与 depthRenderTarget
+    // （地板排除 = 可见深度）比对，作废"透过半透明地板看到的实体"上的地板接触 AO。
+    // 见 three-base/pass/ssao_pass.ts 的复合守卫说明。
+    aoDepthTexture = (() => {
+        const t = new DepthTexture(4096, 4096);
+        t.format = DepthFormat;
+        t.type = UnsignedIntType;
+        t.anisotropy = 16;
+        return t;
+    })();
+    /**
+     * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
+     *   - "none"    ：正常渲染（默认）
+     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
+     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
+     *   - "compare" ：R=全局 base 深度，G=最近一次 glow/stroke 选区 select 深度。两路任一全白即该侧写入失败。
+     *   - "excluded"：深度图灰度 + 「被排除出深度图的面」叠红（红=该面写不进深度，永远挡不住后处理）。
+     *                 物体区域（G 暗）若 B 全黑 → 判定从不触发；再看该区 R/G 谁大即可定位是谁缺深度。
+     * 兼容旧控制台入口：设置 `window.__BASE_DEPTH_VIS = true` 等价于切到 "global"。
+     * 通用控制台入口：任意页面都可 `window.__TB_DEBUG_DEPTH = "judge"`（优先级高于面板属性）。
+     */
+    debugDepthPreview = "none";
+    /**
+     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
+     *
+     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
+     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
+     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
+     */
+    get baseDepthIncludeFloor() {
+        return visibleDepthOptions.includeFloor;
+    }
+    set baseDepthIncludeFloor(v) {
+        visibleDepthOptions.includeFloor = v;
+        this.needRender = true;
+    }
+    // 法线专用渲染目标（无 MSAA，存储视图空间法线，供 GTAO 风格 SSAO 使用真实法线）
+    normalRenderTarget = new WebGLRenderTarget(128, 128, {
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        format: RGBAFormat,
+        stencilBuffer: false,
+        // ⚠️ 挂 depthTexture：法线 pass 渲染时深度由光栅器顺带写进来，直接就是「含地板」的 AO 深度
+        // （零成本，无需再单独渲一遍深度 pass）。见上方 aoDepthTexture 注释。
+        depthTexture: this.aoDepthTexture,
+    });
+    // 屏幕合成目标（无 MSAA）：base（含 SSAO + 描边/发光/bloom）拷进来后，
+    // 颜色叠加/磨砂玻璃/水流/屏幕辉光 在此目标上叠加，最后由 FXAA 终处理输出到屏幕。
+    // 不挂 MSAA（FXAA 负责边缘）。
+    // ⚠️ 注意：SSAO 不在本目标上做——2026-09-14 起 SSAO 提前到对象级特效之前、直接乘进 baseRenderTarget
+    //    （见 render() 内注释与 test/depthDebug.test.js K 组护栏）。
+    // 与 baseRenderTarget 同为线性（NoColorSpace）：后处理全程在线性空间做颜色混合，
+    // 仅由终处理 baseTextureToRenderShader 用 sRGBTransferOETF 做一次 sRGB 编码输出屏幕，
+    // 避免「RT 已按 sRGB 编码 + 终处理再编一次」导致的双重编码发白。
+    // ⚠️ 同 baseRenderTarget：必须为 HalfFloatType。SSAO/颜色叠加/磨砂玻璃都在本目标上做线性混合，
+    //    若这里是 8bit，前面 base 用半浮点保住的渐变会在这一步重新被量化成色带（前功尽弃）。
+    screenRenderTarget = new WebGLRenderTarget(128, 128, {
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        format: RGBAFormat,
+        type: HalfFloatType,
+        stencilBuffer: false,
+    });
+    // 基础纹理 -> 屏幕合成目标的纯拷贝（关掉深度，仅透传颜色），用于把 base 图像拷入
+    // screenRenderTarget 供后续后处理叠加。克隆自共享 copyShader，避免改动其状态。
+    screenCopyShader = (() => {
+        const shader = copyShader.clone();
+        shader.depthTest = false;
+        shader.depthWrite = false;
+        shader.transparent = false;
+        return shader;
+    })();
+    // 法线材质（MeshNormalMaterial 输出视图空间法线 pack 到 RGB，与 SSAO 的 unpackRGBToNormal 对应）
+    // ⚠️ side 必须 DoubleSide：本材质还兼职产出「含地板 AO 深度」（挂在 normalRenderTarget 上），
+    // 若只渲正面，DoubleSide / 背面朝向的几何会丢深度，与被它取代的那次独立深度 pass 行为不一致。
+    // 深度测试会让最近面胜出，故法线图内容不会因 DoubleSide 变差。
+    normalMaterial = new MeshNormalMaterial({ side: DoubleSide });
+    // 公用渲染目标1（无 MSAA：超采样已收敛到基础纹理与选中目标，其余通道去掉以提速）
+    renderTarget = new WebGLRenderTarget(128, 128, {
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        format: RGBAFormat,
+    });
+    // 渲染目标2（无 MSAA）
+    renderTarget2 = new WebGLRenderTarget(128, 128, {
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        format: RGBAFormat,
+    });
+    // 公用二维向量
+    tempVector2 = new Vector2();
+    // 公用的三维向量
+    tempVector3 = new Vector3();
+    //渲染器的尺寸
+    size = new Vector2(0, 0);
+    //上下文丢失
+    rendererLost = false;
+    // 渲染器对象
+    renderer = (() => {
+        const renderer = new WebGLRenderer({
+            alpha: true, // 透明背景
+            precision: "highp", //highp/mediump/lowp着色精度选择
+            logarithmicDepthBuffer: true, // 对数深度缓冲区 避免当2个面挨的很近时闪烁
+            preserveDrawingBuffer: true, // 是否保存绘图缓冲
+            stencil: false, // 模版
+            powerPreference: 'high-performance' // 高性能模式
+        });
+        renderer.domElement.id = generateUUID();
+        //监听上下文的销毁事件
+        renderer.domElement.addEventListener("webglcontextlost", (event) => {
+            this.rendererLost = true;
+        }, false);
+        // 监听上下文的恢复事件
+        renderer.domElement.addEventListener("webglcontextrestored", (event) => {
+            this.rendererLost = false;
+        }, false);
+        renderer.localClippingEnabled = true;
+        renderer.setPixelRatio(Math.max(window.devicePixelRatio, this.minDevicePixelRatio)),
+            renderer.autoClear = false;
+        renderer.clear();
+        renderer.outputColorSpace = SRGBColorSpace;
+        // 颜色空间：图片什么颜色、3D 里就是什么颜色（sRGB 直出，所见即所得，不发白不褪色）。
+        // 关闭色调映射后，场景渲染进线性 baseRenderTarget 时不做 tonemap 压缩，终处理只做一次 sRGB
+        // 编码（baseTextureToRenderShader 手写 sRGBTransferOETF），全链路无额外提亮/降饱和，
+        // 颜色与原贴图一致。如需电影感可改回 ACESFilmicToneMapping（但会带来发白/褪色观感）。
+        renderer.toneMapping = NoToneMapping;
+        threeLoader.setAnisotropy(renderer.capabilities.getMaxAnisotropy());
+        return renderer;
+    })();
+    //透视相机
+    perspectiveCamera = new PerspectiveCamera(45, 1, 0.01, 20000);
+    //正交相机
+    orthographicCamera = new OrthographicCamera(-1, 1, 1, -1, 0.01, 20000);
+    //相机的类型 有透视相机和正交相机
+    cameraType = "perspectiveCamera";
+    setCameraType(cameraType) {
+        if (this.cameraType !== cameraType) {
+            this.cameraType = cameraType;
+            if (this.cameraType === "perspectiveCamera") {
+                this.threeMouse._camera = this.perspectiveCamera;
+                this.controls.object = this.perspectiveCamera;
+            }
+            else if (this.cameraType === "orthographicCamera") {
+                this.threeMouse._camera = this.orthographicCamera;
+                this.controls.object = this.orthographicCamera;
+            }
+        }
+    }
+    //获取当前使用的的相机
+    getCamera() {
+        switch (this.cameraType) {
+            case "orthographicCamera":
+                return this.orthographicCamera;
+            case "perspectiveCamera":
+            default:
+                return this.perspectiveCamera;
+        }
+    }
+    // 场景对象
+    scene = (() => {
+        const scene = new Scene();
+        return scene;
+    })();
+    // 这个方法等效 this.scene.add
+    // 想少写2个字母就用这个方法
+    add(...object) {
+        this.scene.add(...object);
+        return this;
+    }
+    ///鼠标事件对象
+    threeMouse = new ThreeMouse(this.renderer, this.perspectiveCamera, this.scene);
+    // 轨道控制器
+    controls = (() => {
+        const controls = new OrbitControls(this.perspectiveCamera, this.renderer.domElement);
+        controls.addEventListener("change", () => {
+            this.needRender = true;
+        });
+        // 转速：git 历史实证——以前（1826ab1）rotateSpeed=0.2 + enableDamping=true + dampingFactor=0.05
+        // 时「加阻尼也不晃」；a9f3ec9 把 rotateSpeed 提到 1.0（快 5 倍）才是"快速晃动中心点飘"的真因，
+        // 与阻尼无关。此处折中到 0.5：比 0.2 跟手、比 1.0 不易飘。若仍飘可降到 0.2 完全复原。
+        controls.rotateSpeed = 0.5;
+        controls.maxPolarAngle = Math.PI;
+        // 阻尼：回到以前不飘的配置（enableDamping=true + dampingFactor=0.05）。
+        // 0.05 是 1826ab1 验证过"加阻尼不晃"的值，配合下面 render 循环的帧率无关换算。
+        controls.enableDamping = true;
+        controls.dampingFactor = CONTROLS_DAMPING_BASE;
+        controls.screenSpacePanning = true;
+        return controls;
+    })();
+    // 帧率无关阻尼用的上一帧时间戳（performance.now() 毫秒），初始 0 表示首帧用 60fps 基准
+    _lastControlsTime = 0;
+    // 固定的实例化分组器：自动把所有 InstancedChild 合并进 InstancedMesh 批量渲染
+    instancedGroup = new InstancedGroup();
+    /**
+     * 自定义描边目标：不在 scene 内的独立对象（如 InstancedChild 的"选择代理"），
+     * 渲染循环在效果阶段单独对其调用 stroke_pass，使其获得与普通 Mesh 一致的描边，
+     * 且不会被正常 base pass 重复绘制（因为它不在 scene 树内）。
+     * 典型用途：InstancedChild / 一组 InstancedChild 没有自身几何，无法直接描边，
+     * 用 buildSelectProxy 重建其几何代理后再注册到这里即可。
+     */
+    _strokeObjects = [];
+    /** 注册一个自定义描边对象（效果阶段对其描边） */
+    addStrokeObject(object) {
+        if (this._strokeObjects.indexOf(object) < 0) {
+            this._strokeObjects.push(object);
+        }
+        return this;
+    }
+    /** 移除自定义描边对象 */
+    removeStrokeObject(object) {
+        const i = this._strokeObjects.indexOf(object);
+        if (i >= 0) {
+            this._strokeObjects.splice(i, 1);
+        }
+        return this;
+    }
+    // 设置 dom 容器
+    async setContainer(div) {
+        if (div) {
+            div.style.overflow = "hidden";
+            div.innerHTML = "";
+            div.append(this.renderer.domElement);
+            if (this.rendererLost) {
+                this.renderer.forceContextRestore();
+                this.needRender = true;
+                setTimeout(() => {
+                    this.needRender = true;
+                }, 100);
+                setTimeout(() => {
+                    this.renderer.domElement.style.opacity = "1";
+                }, 200);
+            }
+            this.setSize(div.clientWidth, div.clientHeight);
+            // 开启时时渲染
+            threeUtils.removeEventListener("requestAnimationFrame", this.renderBindThis);
+            threeUtils.addEventListener("requestAnimationFrame", this.renderBindThis);
+        }
+    }
+    // 修改尺寸
+    setSize(width, height) {
+        // 防御容器未布局/隐藏导致的 0 尺寸：相机 aspect、renderer、RT 都不能接受 0，
+        // 否则 WebGL 会报 GL_INVALID_VALUE / Framebuffer incomplete: Attachment has zero size。
+        width = Math.max(1, Math.floor(width));
+        height = Math.max(1, Math.floor(height));
+        //修改透视相机的比例
+        this.perspectiveCamera.aspect = width / height;
+        this.perspectiveCamera.updateProjectionMatrix();
+        //修改正交相机的比例
+        // this.orthographicCamera.top = height / width;
+        // this.orthographicCamera.bottom = -height / width;
+        this.orthographicCamera.left = -width / height;
+        this.orthographicCamera.right = width / height;
+        this.renderer.setPixelRatio(Math.max(window.devicePixelRatio, this.minDevicePixelRatio)),
+            this.renderer.setSize(width, height);
+        // 所有 RT 尺寸按 effectiveRatio × resolution 重建（容器尺寸变化与 resolution 变化共用）
+        this.updateRenderTargetSizes(width, height);
+        this.size.set(width, height);
+        setTimeout(() => {
+            this.needRender = true;
+        }, 100);
+        // 渲染场景
+        // this.renderer.clear();
+        // this.renderer.render(this.scene, this.camera);
+    }
+    /**
+     * 按「容器尺寸 × effectiveRatio × resolution」重建所有渲染目标尺寸。
+     * 由 setSize()（容器尺寸变化）与 resolution setter（运行时调倍率）共用 ——
+     * 关键：resolution 是运行时可调的性能/质量旋钮，改完必须立刻重建 RT，
+     * 否则倍率变了而 RT 尺寸没变，画面毫无变化（历史坑："调分辨率没感觉"）。
+     */
+    updateRenderTargetSizes(width, height) {
+        // 防御 0 尺寸：RT 不接受 0，否则 WebGL 报 framebuffer incomplete
+        const w = Math.max(1, Math.round(width * this.effectiveRatio * this._resolution));
+        const h = Math.max(1, Math.round(height * this.effectiveRatio * this._resolution));
+        // 主画面：超采样渲染，纹理摩尔纹在此被根治
+        this.baseRenderTarget.setSize(w, h);
+        // 深度/法线辅助通道：与 base 同倍率，保证 depthTest 1:1 无漏光、SSAO 深度不黑。
+        // 其 depthTexture(baseDepthTexture) 尺寸由 renderer 在 setRenderTarget 时
+        // 强制同步为 depthRenderTarget 尺寸，下面再手动对齐一次避免首帧抖动。
+        this.depthRenderTarget.setSize(w, h);
+        this.normalRenderTarget.setSize(w, h);
+        this.excludedMaskRenderTarget.setSize(w, h);
+        // 屏幕合成目标：同样跟随 resolution，全链路 1:1 对齐
+        this.screenRenderTarget.setSize(w, h);
+        // 水流后处理目标跟随同倍率重建（pass 内部粒子 RT 仍按 scale 降采样，compositeTarget 全分辨率）
+        this.waterFlow?.resize(w, h);
+        this.baseDepthTexture.image.width = w;
+        this.baseDepthTexture.image.height = h;
+        // 立即渲染一帧，避免静态场景下改了倍率却停在旧画面
+        this.needRender = true;
+    }
+    // 视角距离过度
+    controlsDistanceTransition = (() => {
+        const controlsDistanceTransition = new Transition({ distance: 0 });
+        controlsDistanceTransition.setDuration(1000);
+        return controlsDistanceTransition;
+    })();
+    //控制器的Y值过度计算
+    controlsYTransition = (() => {
+        const controlsYTransition = new Transition({ y: 0 });
+        controlsYTransition.setDuration(1000);
+        return controlsYTransition;
+    })();
+    //控制器的XZ值过度计算
+    controlsXZTransition = (() => {
+        const controlsXZTransition = new Transition({ x: 0, z: 0 });
+        controlsXZTransition.setDuration(1000);
+        return controlsXZTransition;
+    })();
+    // 控制器的 朝向带缓动的计算的顶点对象
+    controlsCenter = (() => {
+        const controlsCenter = new Transition({ x: 0, y: 0, z: 0 });
+        controlsCenter.setDuration(1000);
+        controlsCenter.onChange(({ x, y, z }) => {
+            this.controls.target.set(x, y, z);
+            this.perspectiveCamera.lookAt(this.controls.target);
+            this.orthographicCamera.lookAt(this.controls.target);
+            this.needRender = true;
+        });
+        return controlsCenter;
+    })();
+    // 控制器的位置缓动的计算的顶点对象
+    controlsPosition = (() => {
+        const controlsPosition = new Transition({ x: 100, y: 100, z: 100 });
+        controlsPosition.setDuration(1000);
+        controlsPosition.onChange(({ x, y, z }) => {
+            const distance = this.controlsDistanceTransition.get("distance");
+            this.perspectiveCamera.position.set(x + 0.0001, y, z + 0.0001);
+            this.perspectiveCamera.lookAt(this.controls.target);
+            //计算正交相机的缓动
+            this.orthographicCamera.position
+                .set(x + 0.01, y, z + 0.01)
+                .sub(this.controls.target)
+                .setLength(5000)
+                .add(this.controls.target);
+            this.orthographicCamera.lookAt(this.controls.target);
+            this.needRender = true;
+        });
+        return controlsPosition;
+    })();
+    // 网格辅助线
+    gridHelper = (() => {
+        const gridHelper = new GridHelper(1000, 100, 0x303030, 0x303030);
+        if (threeUtils.isDev) {
+            this.scene.add(gridHelper);
+        }
+        return gridHelper;
+    })();
+    //坐标轴线
+    axesHelper = (() => {
+        const axesHelper = new AxesHelper(10000);
+        if (threeUtils.isDev) {
+            this.scene.add(axesHelper);
+        }
+        return axesHelper;
+    })();
+    init() {
+        // 屏幕空间水流：?waterflow=1 时自动启用（默认关闭，需显式 enableWaterFlow 或此 URL 参数）。
+        // 创建后每帧消费 base 深度 + 后处理合成画面，把水面合成进后处理链，不自渲染主场景。
+        try {
+            const params = new URLSearchParams(typeof location !== 'undefined' ? location.search : '');
+            if (params.get('waterflow') === '1') {
+                this.enableWaterFlow();
+            }
+        }
+        catch (_e) {
+            // 非浏览器环境（如 Node 测试/SSR）忽略
+        }
+    }
+    /**
+     * 启用屏幕空间水流（GPGPU 粒子流体）。默认关闭，需显式调用或携带 ?waterflow=1。
+     * 创建后每帧自动消费 base 深度 + 当前合成画面，把水面合成进后处理链，不自渲染主场景。
+     * @param options.size   粒子网格边长（size×size 粒子），越大越细腻、越费
+     * @param options.speed  射流初速
+     * @param options.aperture 喷嘴开度
+     * @param options.nozzle 喷流起点坐标 [x,y,z]，默认 [0.58,1.55,0]
+     * @param options.jetDirection 喷流方向（轴向，会被归一化），默认 [1,0,0]（沿 +X）
+     * @param options.collision 是否开启粒子与 basin/地面碰撞回弹，默认 true
+     */
+    enableWaterFlow(options = {}) {
+        if (this.waterFlow) {
+            console.warn('[ThreeBase] WaterFlow 已启用，重复调用无效');
+            return;
+        }
+        const { size = 200, speed = 2.4, aperture = 0.78, nozzle, jetDirection, collision = true, } = options;
+        const waterFlow = new WaterFlow(this.renderer, {
+            size,
+            speed,
+            aperture,
+            nozzle: nozzle ? new Vector3(nozzle[0], nozzle[1], nozzle[2]) : undefined,
+            jetDirection: jetDirection ? new Vector3(jetDirection[0], jetDirection[1], jetDirection[2]) : undefined,
+            collision,
+        });
+        if (!waterFlow.supported) {
+            console.warn('[ThreeBase] 当前环境不支持浮点纹理，WaterFlow 未启用');
+            waterFlow.dispose();
+            return;
+        }
+        // 创建 pass 并注入基础纹理（externalBase 模式）；后续每帧 renderInto 会刷新注入的纹理。
+        // ⚠️ 2026-10-08（WaterFlow 全量 TS 化）：ScreenSpaceFluidPass 内部按透视相机建模
+        //    （setSize 读 camera.fov 算 pointScale、depthMaterial 走 projectionMatrix 重建深度），
+        //    故此处显式窄化。getCamera() 在 cameraType==="orthographicCamera" 时会返回
+        //    OrthographicCamera —— 原 JS 同样会把 fov=undefined 传进去（pointScale 变 NaN），
+        //    本次**只补类型、未改运行时行为**，保持与线上一致。
+        waterFlow.createPass(this.scene, this.getCamera(), {
+            colorTexture: this.baseRenderTarget.texture,
+            depthTexture: this.baseDepthTexture,
+            depthMode: 'logarithmic',
+        });
+        // 首帧按当前容器尺寸对齐（后续 setSize/resolution 变化由 updateRenderTargetSizes 兜底）。
+        const w = Math.max(1, Math.round(this.size.x * this.effectiveRatio * this._resolution));
+        const h = Math.max(1, Math.round(this.size.y * this.effectiveRatio * this._resolution));
+        if (this.size.x > 1 && this.size.y > 1)
+            waterFlow.resize(w, h);
+        this.waterFlow = waterFlow;
+        this._waterFlowLastTime = 0;
+        this.waterFlowElapsed = 0;
+        console.info('[ThreeBase] WaterFlow 已启用');
+    }
+    /** 运行时改喷流起点（喷嘴）坐标（WaterFlow 已启用时有效） */
+    setWaterFlowNozzle(x, y, z) {
+        this.waterFlow?.setNozzle(x, y, z);
+    }
+    /** 运行时改喷流方向（轴向，会被归一化） */
+    setWaterFlowJetDirection(x, y, z) {
+        this.waterFlow?.setJetDirection(x, y, z);
+    }
+    /** 运行时开关粒子与 basin/地面碰撞回弹 */
+    setWaterFlowCollision(enabled) {
+        this.waterFlow?.setCollision(enabled);
+    }
+    /**
+     * 关闭屏幕空间水流并释放其 GPU 资源（enableWaterFlow 的反操作）。
+     * 切走页面时必须调用，否则其它页面 render 仍会合成水面（this.waterFlow 非空）。
+     */
+    disableWaterFlow() {
+        if (!this.waterFlow)
+            return;
+        this.waterFlow.dispose();
+        this.waterFlow = null;
+        this._waterFlowLastTime = 0;
+        this.waterFlowElapsed = 0;
+        console.info('[ThreeBase] WaterFlow 已关闭');
+    }
+    // 重置控制器的位置
+    resetLookAt({ position = this.perspectiveCamera.position, center = this.controls.target, }) {
+        // 停止控制器的惯性
+        const originEnableDamping = this.controls.enableDamping;
+        this.controls.saveState();
+        this.controls.update();
+        this.controls.reset();
+        this.controls.enableDamping = originEnableDamping;
+        this.controlsDistanceTransition.reset({
+            distance: new Vector3(position.x, position.y, position.z).distanceTo(new Vector3(center.x, center.y, center.z))
+        });
+        position &&
+            this.controlsPosition.reset({
+                x: position.x,
+                y: position.y,
+                z: position.z,
+            });
+        center &&
+            this.controlsCenter.reset({ x: center.x, y: center.y, z: center.z });
+        this.needRender = true;
+    }
+    // 设置控制器的位置 以动画的方式移动控制器
+    async setLookAt({ position = this.perspectiveCamera.position, center = this.controls.target, duration = 1000, }) {
+        // 停止控制器的惯性
+        const originEnableDamping = this.controls.enableDamping;
+        this.controls.saveState();
+        this.controls.update();
+        this.controls.reset();
+        this.controls.enableDamping = originEnableDamping;
+        let currentPosition = this.perspectiveCamera.position.clone();
+        let currentCenter = this.controls.target.clone();
+        let currentDistance = this.perspectiveCamera.position.distanceTo(this.controls.target);
+        let targetPosition = new Vector3(position.x, position.y, position.z);
+        let targetCenter = new Vector3(center.x, center.y, center.z);
+        let targetDistance = targetPosition.distanceTo(targetCenter);
+        // 等待动画执行完成
+        await Promise.all([
+            new Promise(async (resolve, reject) => {
+                this.controlsDistanceTransition.setDuration(duration).reset({
+                    distance: currentDistance,
+                });
+                await this.controlsDistanceTransition.set({
+                    distance: targetDistance
+                });
+                resolve();
+            }),
+            new Promise(async (resolve, reject) => {
+                this.controlsPosition.setDuration(duration).reset({
+                    x: currentPosition.x,
+                    y: currentPosition.y,
+                    z: currentPosition.z,
+                });
+                await this.controlsPosition.set({
+                    x: position.x,
+                    y: position.y,
+                    z: position.z,
+                });
+                resolve();
+            }),
+            new Promise(async (resolve, reject) => {
+                this.controlsCenter.setDuration(duration).reset({
+                    x: currentCenter.x,
+                    y: currentCenter.y,
+                    z: currentCenter.z,
+                });
+                await this.controlsCenter.set({
+                    x: center.x,
+                    y: center.y,
+                    z: center.z,
+                });
+                resolve();
+            }),
+        ]);
+    }
+    // 获取控制的位置和朝向 保留3位小数
+    getLookAt() {
+        //判断需要使用那个相机
+        const position = this.perspectiveCamera.position
+            .toArray()
+            .map((v) => round(v, 3));
+        const center = this.controls.target.toArray().map((v) => round(v, 3));
+        return {
+            center: new Vector3(...center),
+            position: new Vector3(...position),
+            centerPosition: `center: new Vector3(${center.join(",")}),position: new Vector3(${position.join(",")})`,
+        };
+    }
+    // 查看对象
+    lookatObjects({ objects, duration = 1000, direction = new Vector3(0.3, 0.3, 1), offset = new Vector3(0, 0, 0), distance = 1, }) {
+        const box3 = new Box3();
+        objects.map((o) => {
+            o.traverseVisible((oo) => {
+                box3.expandByObject(oo);
+            });
+        });
+        const size = new Vector3();
+        box3.getSize(size);
+        const center = new Vector3();
+        box3.getCenter(center);
+        center.add(offset);
+        const modelSize = size.length() * distance;
+        if (this.cameraType === "perspectiveCamera") {
+            const { fov } = this.getCamera();
+            const cameraDistance = modelSize / (2 * Math.tan((fov * Math.PI) / 360));
+            const position = direction.setLength(cameraDistance).add(center);
+            this.setLookAt({ center, position, duration });
+        }
+    }
+    // 三维向量转化成屏幕上的2维向量
+    v3tov2(v3) {
+        //判断需要使用那个相机
+        const camera = this.getCamera();
+        v3.project(camera);
+        const v2 = new Vector2((v3.x + 1) * this.size.x * 0.5, (-v3.y + 1) * this.size.y * 0.5);
+        return v2;
+    }
+    // 控制器类型
+    controlType = "OrbitControls";
+    // 记录一下空间平移方式 在切换控制器的时候保留一下平移方式
+    originScreenSpacePanning = false;
+    //改变控制器的类型
+    setControlType(controlType) {
+        if (controlType === "OrbitControls") {
+            this.controls.screenSpacePanning = this.originScreenSpacePanning;
+            this.controls.mouseButtons = {
+                LEFT: MOUSE.ROTATE,
+                MIDDLE: MOUSE.DOLLY,
+                RIGHT: MOUSE.PAN,
+            };
+            this.controls.touches = { ONE: TOUCH.ROTATE, TWO: TOUCH.DOLLY_PAN };
+        }
+        else if (controlType === "MapControls") {
+            this.originScreenSpacePanning = this.controls.screenSpacePanning;
+            // pan orthogonal to world-space direction camera.up
+            this.controls.screenSpacePanning = false;
+            this.controls.mouseButtons.LEFT = MOUSE.PAN;
+            this.controls.mouseButtons.RIGHT = MOUSE.ROTATE;
+            this.controls.touches.ONE = TOUCH.PAN;
+            this.controls.touches.TWO = TOUCH.DOLLY_ROTATE;
+        }
+    }
+    // 是否自动渲染
+    autoRender = true;
+    //是否需要渲染, 当autoRender=false的时候就需要 手动触发渲染
+    needRender = false;
+    // SSAO 配置
+    ssao = {
+        enable: false,
+        debug: false,
+        radius: 5.0, // 世界空间遮蔽半径（单位：世界空间单位）
+        falloff: 5.0, // 世界空间衰减距离
+        bias: 0.3, // 切面距离阈值（过滤平坦面）
+        intensity: 1.0, // AO 叠加强度 mix(1.0, ao, intensity)
+        sampleCount: 16, // 采样数
+        blurRadius: 4.0, // 去噪半径（像素，越大越平滑、降噪越强）
+        strength: 1.0, // 与 intensity 同义，两者都设时以 strength 为准
+        resolutionScale: 0.5, // SSAO 计算分辨率缩放（0.5 = 半分辨率，性能更好）
+        distanceExponent: 1.0, // GTAO：采样点沿半径分布的幂次
+        distanceFallOff: 1.0, // GTAO：距离衰减混合系数
+        scale: 1.0, // GTAO：AO 次幂（gamma 校正）
+    };
+    // 屏幕空间辉光（经典 gaussian bloom）配置：纯颜色、无深度依赖，在 screenRenderTarget 上做加性叠加
+    bloom = {
+        enable: false,
+        strength: 0.6,
+        radius: 0.4,
+        threshold: 0.85,
+    };
+    // 停止渲染
+    stopRender() {
+        threeUtils.removeEventListener("requestAnimationFrame", this.renderBindThis);
+        if (!this.rendererLost) {
+            this.renderer.forceContextLoss();
+            this.setSize(100, 100);
+            this.renderer.domElement.style.opacity = "0";
+        }
+    }
+    // 彻底销毁当前渲染器实例：停止渲染循环、释放 WebGL 上下文与场景资源、卸载画布 DOM。
+    // 用于「每个 demo 视图各自持有渲染器、切换页面时自行销毁」的生命周期管理。
+    dispose() {
+        // 1. 停止渲染循环（移除 rAF 监听 + 丢失上下文）
+        this.stopRender();
+        // 2. 轨道控制器（移除其 DOM 事件监听）
+        this.controls?.dispose();
+        // 3. 鼠标拾取（移除 canvas 上的事件监听）
+        this.threeMouse?.dispose();
+        // 4. 释放场景内所有几何体 / 材质 / 纹理
+        this.scene.traverse((obj) => {
+            const mesh = obj;
+            if (mesh.geometry) {
+                mesh.geometry.dispose();
+            }
+            const material = mesh.material;
+            if (Array.isArray(material)) {
+                material.forEach((m) => this._disposeMaterial(m));
+            }
+            else if (material) {
+                this._disposeMaterial(material);
+            }
+        });
+        // 5. 渲染器与画布 DOM
+        const dom = this.renderer.domElement;
+        if (dom.parentElement) {
+            dom.parentElement.removeChild(dom);
+        }
+        this.renderer.dispose();
+    }
+    /** 释放单个材质及其引用的纹理（遍历材质属性找 Texture 并 dispose） */
+    _disposeMaterial(material) {
+        const record = material;
+        for (const key in record) {
+            const value = record[key];
+            if (value && value.isTexture) {
+                value.dispose();
+            }
+        }
+        material.dispose();
+    }
+    // 渲染场景
+    render() {
+        // canvas 没有在页面上面的话 就停止渲染
+        if (!threeUtils.inDocument(this.renderer.domElement)) {
+            this.stopRender();
+            return;
+        }
+        // 相机的朝向
+        const center = new Vector3(...this.controls.target.toArray().map((v) => round(v, 3)));
+        //透视相机和正交相机参数的时时转换
+        if (this.cameraType === "perspectiveCamera") {
+            const { fov } = this.perspectiveCamera;
+            const distaned = this.perspectiveCamera.position
+                .clone()
+                .sub(center)
+                .length();
+            const zoom = 1 / (Math.tan(degToRad(fov) / 2) * distaned);
+            this.orthographicCamera.zoom = zoom;
+            this.orthographicCamera.position
+                .copy(this.perspectiveCamera.position.clone().sub(center))
+                .setLength(2500)
+                .add(center);
+        }
+        else if (this.cameraType === "orthographicCamera") {
+            const { fov } = this.perspectiveCamera;
+            const { zoom } = this.orthographicCamera;
+            const distaned = 1 / zoom / Math.tan(degToRad(fov) / 2);
+            this.perspectiveCamera.position
+                .copy(this.orthographicCamera.position.clone().sub(center))
+                .setLength(distaned)
+                .add(center);
+        }
+        //判断需要使用那个相机
+        const camera = this.getCamera();
+        //判断尺寸发生改变时重置尺寸
+        const parentNode = this.renderer.domElement.parentNode;
+        if (parentNode.clientWidth !== this.size.x ||
+            parentNode.clientHeight !== this.size.y) {
+            this.setSize(parentNode.clientWidth, parentNode.clientHeight);
+        }
+        // 分发鼠标事件
+        this.threeMouse.dispatchEvent();
+        // 在不自动渲染时, needRender=false 就跳过渲染
+        if (!this.autoRender && !this.needRender) {
+            return; // 标识未渲染
+        }
+        this.needRender = false;
+        // 水流模拟推进：独立于相机控制，按真实帧间隔累计时间推进 GPGPU 粒子模拟。
+        // 默认 this.waterFlow 为 null（关闭），调用 enableWaterFlow() 或 ?waterflow=1 才创建。
+        if (this.waterFlow && this.waterFlow.supported) {
+            const wnow = performance.now();
+            const wdt = this._waterFlowLastTime > 0
+                ? Math.min((wnow - this._waterFlowLastTime) / 1000, 0.05)
+                : 1 / 60;
+            this._waterFlowLastTime = wnow;
+            this.waterFlowElapsed += wdt;
+            this.waterFlow.update(wdt, this.waterFlowElapsed);
+        }
+        if (this.controls.enabled) {
+            // 让 OrbitControls 始终接管"当前渲染相机"：OrbitControls 构造时只绑定了
+            // perspectiveCamera，但渲染相机随 cameraType 切换。若切到正交相机时仍让 OrbitControls
+            // 控制 perspectiveCamera、却用正交相机渲染，且每帧用正交相机反推并覆盖 perspectiveCamera，
+            // 两者打架 → 旋转中心漂移、运动错乱。此处把 controls.object 同步为渲染相机即可根治。
+            if (this.controls.object !== camera) {
+                this.controls.object = camera;
+            }
+            // 帧率无关的阻尼换算：OrbitControls 的 dampingFactor 是「每帧」衰减比例，固定值会随帧率变化
+            // 导致阻尼手感不一致——后处理管线重，快速晃动掉帧时单帧间隔变大、衰减比例却不变，
+            // 镜头运动一顿一顿、中心点发飘。这里把基准 dampingFactor 按真实帧间隔归一化到 60fps：
+            //   effective = 1 - (1 - BASE)^(dt*60)
+            // 掉帧（dt 变大）时自动加大单帧衰减比例，让阻尼手感与帧率解耦。
+            const now = performance.now();
+            const dt = this._lastControlsTime > 0
+                ? Math.min((now - this._lastControlsTime) / 1000, 0.05)
+                : 1 / 60;
+            this._lastControlsTime = now;
+            // 帧率无关阻尼换算：OrbitControls 的 dampingFactor 是「每帧」衰减比例，固定值会随帧率变化
+            // 导致阻尼手感不一致（后处理管线重、快速晃动掉帧时单帧间隔变大、衰减比例却不变 → 一顿一顿）。
+            // 把基准 dampingFactor 按真实帧间隔归一化到 60fps：effective = 1 - (1 - BASE)^(dt*60)，
+            // 掉帧时自动加大单帧衰减比例，让阻尼手感与帧率解耦。每帧无条件 update()（与 1826ab1 一致，
+            // 该版本 enableDamping=true + dampingFactor=0.05 已验证不飘）。
+            this.controls.dampingFactor = 1 - Math.pow(1 - CONTROLS_DAMPING_BASE, dt * 60);
+            this.controls.update();
+        }
+        {
+            // 先派发 beforeRender，让用户动画在当前帧修改 transform（修改会在下方一次性更新进世界矩阵）
+            this.dispatchEvent({ type: "beforeRender" });
+            // 实例化分组器：场景世界矩阵更新后，把 InstancedChild 同步进真实 InstancedMesh
+            this.instancedGroup.update();
+            // 渲染场景
+            // 把基础场景渲染到 帧缓冲区 在后期通道中会用到
+            this.renderer.setRenderTarget(this.baseRenderTarget);
+            this.renderer.clear();
+            this.renderer.render(this.scene, camera);
+            // 深度 pass：固定排除非实体表面后渲到 depthRenderTarget（生成 baseDepthTexture）。
+            // 必须在 base render 之后、所有依赖深度的特效（描边/发光/覆盖/磨砂）之前更新，
+            // 否则这些特效会用到上一帧旧深度 → 遮挡判定错乱。法线 pass 已收进 ssao_pass 内部。
+            renderAoDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
+            // 切回 baseRenderTarget，后处理 pass 需要把效果叠加到颜色渲染目标上
+            this.renderer.setRenderTarget(this.baseRenderTarget);
+            // 效果 mask 灰度图尺寸 = effectiveRatio × resolution，与 baseRenderTarget / baseDepthTexture 同倍率，
+            // 全链路 1:1 对齐（mask 跟随 resolution，深度也跟随 resolution，辉光漏光/mask 合成 UV 错位均消除）。
+            // 几何/效果边缘抗锯齿由「baseRenderTarget/screenRenderTarget 超采样(resolution) + 终处理 FXAA 降采样」承担。
+            const dpr = this.effectiveRatio * this.resolution;
+            // SSAO 后处理（基于深度计算遮蔽，乘法叠加）：数据准备 + 计算全在 ssao_pass 内部，
+            // 结果输出到「调用时绑定的渲染目标」。
+            // ⚠️ 顺序（2026-09-14 皇上旨）：SSAO 必须排在对象级特效（描边/发光/bloom/覆盖/磨砂）之前——
+            // 遮蔽只作用于纯场景底色，特效叠在 AO 之上，描边/辉光不会被 AO 压暗、也不会被 AO 的噪声污染。
+            // 此处绑定的是 baseRenderTarget，故 AO 直接乘进 base；后面的特效与「base → screen 拷贝」
+            // 全部基于「已含 AO」的底色，后续 pass 无需任何改动。
+            ssao_pass(this.renderer, camera, this.scene, this.depthRenderTarget, this.normalRenderTarget, this.normalMaterial, dpr, this.ssao);
+            // 后处理特效渲染(描边,发光,颜色覆盖,bloom,磨砂玻璃)：叠加到 baseRenderTarget（此时已含 SSAO）
+            this.scene.traverseVisible((child) => {
+                if (child instanceof Mesh || child instanceof Line || child instanceof Points) {
+                    stroke_pass(this.renderer, camera, child, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+                    glow_pass(this.renderer, camera, child, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+                    bloom_pass(this.renderer, camera, child, this.baseRenderTarget, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+                }
+            });
+            // 自定义描边对象（如 InstancedChild 的选择代理）：不在 scene 内，单独在效果阶段描边。
+            // 代理用实例自身的 matrixWorld + 同款 geometry/material 重建，故其深度/灰度与真实实例严格对齐，
+            // 并复用同一张 baseDepthTexture 做遮挡判定（被其他物体挡住的部分不描边）。
+            for (const so of this._strokeObjects) {
+                stroke_pass(this.renderer, camera, so, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+                glow_pass(this.renderer, camera, so, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+                bloom_pass(this.renderer, camera, so, this.baseRenderTarget, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+            }
+            // 把 base(含 SSAO)+描边/发光/bloom 合成结果拷到屏幕合成目标，后续 颜色叠加/磨砂玻璃
+            // 在此目标上叠加；最后统一跑一次 FXAA 终处理输出到屏幕，覆盖全部后处理的锯齿/摩尔纹。
+            this.renderer.setRenderTarget(this.screenRenderTarget);
+            this.renderer.clear();
+            this.screenCopyShader.uniforms.map.value = this.baseRenderTarget.texture;
+            fsQuad.render(this.renderer, this.screenCopyShader);
+            // 颜色叠加
+            this.scene.traverseVisible((child) => {
+                if (child instanceof Mesh || child instanceof Line || child instanceof Points) {
+                    cover_pass(this.renderer, camera, child, this.baseDepthTexture, dpr);
+                }
+            });
+            for (const so of this._strokeObjects) {
+                cover_pass(this.renderer, camera, so, this.baseDepthTexture, dpr);
+            }
+            // 一次性处理所有支持毛玻璃特效的对象
+            frosted_glass_pass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, dpr);
+            // 屏幕空间水流：消费 base 深度 + 当前合成画面（含 ssao/覆盖/磨砂），把水面合成进
+            // screenRenderTarget。插在磨砂之后、screenBloom 之前，使水面高光也能被泛光处理。
+            // 默认关闭（this.waterFlow 为 null 时不产生任何开销）。
+            if (this.waterFlow && this.waterFlow.supported) {
+                waterFlowPass(this.renderer, camera, this.scene, this.baseRenderTarget, this.baseDepthTexture, this.waterFlow);
+            }
+            // 屏幕空间辉光（经典 gaussian bloom）：纯颜色、无深度依赖，把亮度超阈值的部分做
+            // 连续高斯模糊后加性叠加回 screenRenderTarget。单分辨率多迭代，柔和均匀、无 mip 分层。
+            if (this.bloom.enable) {
+                screenBloomPass(this.renderer, this.screenRenderTarget, {
+                    strength: this.bloom.strength,
+                    radius: this.bloom.radius,
+                    threshold: this.bloom.threshold,
+                });
+            }
+            // FXAA 终处理：对最终合成图像（含 SSAO/AO/叠加/磨砂/辉光）跑一次 FXAA 统一兜底锯齿与摩尔纹，
+            // 分辨率按实际帧缓冲像素（已乘 dpr）设置，修复高分屏下 FXAA 采样比例偏大失效的问题。
+            // ⚠️ 深度调试预览（面板「深度调试」切换，定位"深度测试全部失效"根因）：
+            //   旧控制台入口 `window.__BASE_DEPTH_VIS = true` 仍可用，等价于切到 "global"。
+            //   global  → baseDepthTexture 灰度。全白=深度为空(renderAoDepthPass 没写进)→后处理一律显示在前；有灰阶=深度正常，问题在比对侧。
+            //   ao      → aoDepthTexture 灰度（含地板）。确认深度管线本身是否工作（GTAO 是否拿到正确深度）。
+            //   compare → R=全局 base 深度，G=最近一次 glow/stroke 选区的 select 深度。两路任一全白即该侧写入失败。
+            //   judge   → R=base 原始深度、G=select 原始深度、B=判定结果(1=判为被遮挡应 discard)。
+            // 通用控制台入口（任意页面可用，优先级高于面板属性）：
+            //   `window.__TB_DEBUG_DEPTH = "global" | "ao" | "compare" | "judge"`，设回 "none" 恢复。
+            const dbgWin = window.__TB_DEBUG_DEPTH;
+            const dbgMode = window.__BASE_DEPTH_VIS
+                ? "global"
+                : (dbgWin ?? this.debugDepthPreview);
+            if (dbgMode !== "none") {
+                this.renderer.setRenderTarget(null);
+                this.renderer.clear();
+                if (dbgMode === "global") {
+                    baseDepthVisShader.uniforms.tDepth.value = this.baseDepthTexture;
+                    fsQuad.render(this.renderer, baseDepthVisShader);
+                }
+                else if (dbgMode === "ao") {
+                    baseDepthVisShader.uniforms.tDepth.value = this.aoDepthTexture;
+                    fsQuad.render(this.renderer, baseDepthVisShader);
+                }
+                else if (dbgMode === "compare") {
+                    debugDepthCompareShader.uniforms.tBase.value = this.baseDepthTexture;
+                    debugDepthCompareShader.uniforms.tSelect.value =
+                        debugDepthState.lastSelectDepth ?? this.baseDepthTexture;
+                    debugDepthCompareShader.uniforms.cameraFar.value = camera.far;
+                    fsQuad.render(this.renderer, debugDepthCompareShader);
+                }
+                else if (dbgMode === "judge") {
+                    debugDepthJudgeShader.uniforms.tBase.value = this.baseDepthTexture;
+                    debugDepthJudgeShader.uniforms.tSelect.value =
+                        debugDepthState.lastSelectDepth ?? this.baseDepthTexture;
+                    fsQuad.render(this.renderer, debugDepthJudgeShader);
+                }
+                else if (dbgMode === "excluded") {
+                    // 先渲「被排除面 mask」，再与深度图叠加：红=挡不住任何后处理的面
+                    renderExcludedMaskPass(this.renderer, camera, this.scene, this.excludedMaskRenderTarget);
+                    debugExcludedShader.uniforms.tDepth.value = this.baseDepthTexture;
+                    debugExcludedShader.uniforms.tMask.value = this.excludedMaskRenderTarget.texture;
+                    fsQuad.render(this.renderer, debugExcludedShader);
+                }
+                flushLensflareOverlays(this.renderer, camera);
+                return;
+            }
+            this.renderer.setRenderTarget(null);
+            this.renderer.clear();
+            this.renderRendererTarget(this.screenRenderTarget);
+            // 镜头光晕（Lensflare）解耦：渲染器输出屏幕后统一叠加所有可见鬼影。
+            // flushLensflareOverlays 内部仅当渲染目标为屏幕时生效，不污染任何中间后处理 target；
+            // LensFlare 实例自己管理状态（构造注册进全局表、dispose 注销），ThreeBase 不遍历场景、不认识其类型。
+            flushLensflareOverlays(this.renderer, camera);
+        }
+    }
+    renderBindThis = this.render.bind(this);
+    //获取渲染图blob对象
+    async getThumbBlob() {
+        this.renderer.setRenderTarget(this.baseRenderTarget);
+        this.renderer.clear();
+        this.renderer.render(this.scene, this.getCamera());
+        this.renderer.setRenderTarget(null);
+        this.renderer.clear();
+        this.renderRendererTarget(this.baseRenderTarget);
+        const blob = await new Promise((resolve, reject) => {
+            this.renderer.domElement.toBlob((blob) => {
+                resolve(blob);
+            }, "image/png", 1);
+        });
+        return blob;
+    }
+    //获取渲染图base64
+    getThumbBase64() {
+        this.renderer.setRenderTarget(this.baseRenderTarget);
+        this.renderer.clear();
+        this.renderer.render(this.scene, this.getCamera());
+        this.renderer.setRenderTarget(null);
+        this.renderer.clear();
+        this.renderRendererTarget(this.baseRenderTarget);
+        const base64 = this.renderer.domElement.toDataURL("image/png");
+        return base64;
+    }
+    //获取渲染图文件对象
+    async getThumbFile() {
+        const blob = await this.getThumbBlob();
+        const file = new File([blob], "thumb.png", { type: blob.type });
+        return file;
+    }
+    // 下载渲染图
+    async download(fileName = "download") {
+        const blob = await this.getThumbBlob();
+        let saveLink = document.createElement("a");
+        saveLink.download = `${fileName}.png`;
+        saveLink.href = URL.createObjectURL(blob);
+        document.body.append(saveLink);
+        saveLink.click();
+    }
+    //把渲染目标渲染到canvas上
+    renderRendererTarget(renderTarget) {
+        // FXAA 分辨率按实际帧缓冲像素尺寸（乘 devicePixelRatio）设置，否则高分屏下
+        // 采样步长被当成 CSS 像素，FXAA 失效甚至引入摩尔纹。
+        const dpr = Math.max(window.devicePixelRatio, this.minDevicePixelRatio);
+        baseTextureToRenderShader.uniforms.resolution.value.set(1 / (this.size.x * dpr), 1 / (this.size.y * dpr));
+        baseTextureToRenderShader.uniforms.tDiffuse.value = renderTarget.texture;
+        fsQuad.render(this.renderer, baseTextureToRenderShader);
+    }
+    // 渲染纹理
+    renderTexture(texture, alpha = false) {
+        copyShader.uniforms.map.value = texture;
+        copyShader.uniforms.opacity.value = 1.0;
+        copyShader.blending = alpha ? NoBlending : NormalBlending;
+        fsQuad.render(this.renderer, copyShader);
+    }
+}