three-base 2.0.134 → 2.0.142

package/WaterFlow/WaterFlow.js

@@ -0,0 +1,171 @@
+import { GPUFluidSimulation } from './GPUFluidSimulation';
+import { ScreenSpaceFluidPass } from './ScreenSpaceFluidPass';
+/**
+ * WaterFlow —— 可独立使用的水流对象封装。
+ *
+ * 把「GPGPU 粒子流体模拟」与「屏幕空间流体后处理」打包成一个对象：
+ * 对外只暴露 update / 参数 setter / createPass，调用方无需关心 GPU ping-pong、
+ * SPH 场、深度重建等内部细节。
+ *
+ * 两种渲染模式：
+ *  A. 自渲染模式（默认）：createPass(scene, camera) 不传 base 纹理。pass 内部
+ *     自己把主场景渲到带深度的缓冲，再与粒子深度合成。需要作为后处理链一环。
+ *  B. 注入基础纹理模式：createPass(scene, camera, baseTextures)，其中
+ *     baseTextures = { colorTexture, depthTexture, depthMode }。pass 直接消费
+ *     调用方已有的基础颜色/深度纹理，不再自渲染主场景 —— 与 three-base「共用
+ *     base 纹理 / base 深度图」的后处理方案完全契合，省掉一遍主场景渲染。
+ *     depthMode: 'standard'（默认，普通透视深度）| 'logarithmic'
+ *     （three-base 开 logarithmicDepthBuffer 时，与 frosted_glass_pass 解码对齐）。
+ *
+ * 集成到 three-base（手写 fsQuad 后处理）：
+ *   const water = new WaterFlow(renderer, { size: 200 });
+ *   const pass = water.createPass(scene, camera, {
+ *     colorTexture: this.baseRenderTarget.texture,
+ *     depthTexture: this.baseDepthTexture,
+ *     depthMode: 'logarithmic',
+ *   });
+ *   // 每帧：先 renderer.setRenderTarget(baseRenderTarget); renderer.render(scene, camera);
+ *   //       再 renderAoDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
+ *   //       然后 water.update(dt, elapsed);
+ *   //       最后 setRenderTarget(screenRT); fsQuad.render(renderer, pass.material);
+ *   // 注意：WaterFlow 的 composite 是纯消费 base 纹理的 fsQuad，可直接放进你的链。
+ */
+export class WaterFlow {
+    renderer;
+    width;
+    height;
+    scale;
+    simulation;
+    /** createPass 之前为 null；各渲染参数 setter 走 `this.pass?.xxx` 可选链。 */
+    pass;
+    constructor(renderer, options = {}) {
+        const { width = 1, height = 1, scale = 0.75, size = 200, speed = 2.4, aperture = 0.78, nozzle, basin, jetDirection, collision, } = options;
+        this.renderer = renderer;
+        this.width = width;
+        this.height = height;
+        this.scale = scale;
+        this.simulation = new GPUFluidSimulation(renderer, {
+            size,
+            speed,
+            aperture,
+            nozzle,
+            basin,
+            jetDirection,
+            collision,
+        });
+        this.pass = null;
+    }
+    get supported() {
+        return this.simulation.supported;
+    }
+    get count() {
+        return this.simulation.count;
+    }
+    get positionTexture() {
+        return this.simulation.positionTexture;
+    }
+    get velocityTexture() {
+        return this.simulation.velocityTexture;
+    }
+    /**
+     * 生成屏幕空间流体 pass 并接入渲染链。
+     * @param scene 主场景（注入 base 纹理模式下不会被 pass 自渲染）
+     * @param camera 主相机（粒子投影 / spray 渲染需要）
+     * @param baseTextures 传入即启用「注入基础纹理」模式：pass 直接消费调用方颜色+深度，不再自渲染主场景。
+     * @returns 不支持浮点纹理时返回 null
+     *
+     * ⚠️ ScreenSpaceFluidPass 按**透视相机**建模（setSize 无条件读 `camera.fov` 算 pointScale、
+     *    depthMaterial 走 projectionMatrix 重建深度），故此处收 PerspectiveCamera。
+     *    ThreeBase.getCamera() 的返回类型是 `PerspectiveCamera | OrthographicCamera`，
+     *    调用处已显式窄化（见 ThreeBase 内 waterFlow.createPass 那行）。
+     *    ⚠️ 若真用正交相机，fov 为 undefined → pointScale 变 NaN（**原 JS 既有行为，本次未改运行时**）。
+     */
+    createPass(scene, camera, baseTextures = null) {
+        if (!this.supported)
+            return null;
+        this.pass = new ScreenSpaceFluidPass(scene, camera, this.simulation, {
+            width: this.width,
+            height: this.height,
+            scale: this.scale,
+            activeCount: this.simulation.count,
+            externalBase: baseTextures ? {
+                colorTexture: baseTextures.colorTexture,
+                depthTexture: baseTextures.depthTexture,
+                depthMode: baseTextures.depthMode || 'standard',
+            } : null,
+        });
+        this.pass.setQuality({
+            scale: this.scale,
+            activeCount: this.simulation.count,
+            blurRadius: 5,
+        });
+        return this.pass;
+    }
+    /** 推进一帧模拟。 */
+    update(delta, elapsed) {
+        if (this.supported)
+            this.simulation.update(delta, elapsed);
+    }
+    // ---- 模拟参数代理 ----
+    setParameters(p) {
+        this.simulation.setParameters(p);
+    }
+    setReservoirState(state) {
+        this.simulation.setReservoirState(state);
+    }
+    setContainerMotion(accelerationX = 0, accelerationZ = 0) {
+        this.simulation.setContainerMotion(accelerationX, accelerationZ);
+    }
+    setBasin(basin) {
+        this.simulation.setBasin(basin);
+    }
+    /** 运行时改喷流起点（喷嘴）坐标 */
+    setNozzle(x, y, z) {
+        this.simulation.setNozzle(x, y, z);
+    }
+    /** 运行时改喷流方向（轴向，会被归一化） */
+    setJetDirection(dx, dy, dz) {
+        this.simulation.setJetDirection(dx, dy, dz);
+    }
+    /** 运行时开关粒子与 basin/地面碰撞回弹 */
+    setCollision(enabled) {
+        this.simulation.setCollision(enabled);
+    }
+    reset() {
+        this.simulation.reset();
+    }
+    // ---- 渲染参数代理（需 pass 已创建）----
+    setAirFraction(value) {
+        this.pass?.setAirFraction(value);
+    }
+    setParticleRadius(value) {
+        this.pass?.setParticleRadius(value);
+    }
+    setRetainedFluidVisible(value) {
+        this.pass?.setRetainedFluidVisible(value);
+    }
+    setQuality(quality) {
+        this.pass?.setQuality(quality);
+    }
+    /** 运行时刷新注入的基础纹理（three-base resize / 切换 baseRT 时调用）。 */
+    setBaseTextures(baseTextures) {
+        this.pass?.setBaseTextures(baseTextures);
+    }
+    resize(width, height) {
+        this.width = width;
+        this.height = height;
+        this.pass?.setSize(width, height);
+    }
+    /**
+     * 函数式渲染入口（three-base 手写 fsQuad 后处理链）：直接消费基础颜色/深度纹理，
+     * 把水面合成回当前渲染目标（与 frosted_glass_pass 同构，省去自渲染主场景）。
+     */
+    renderInto(renderer, opts) {
+        if (this.supported && this.pass)
+            this.pass.renderInto(renderer, opts);
+    }
+    dispose() {
+        this.pass?.dispose();
+        this.simulation.dispose();
+    }
+}

package/WaterFlow/WaterFlow.ts

@@ -0,0 +1,219 @@
+import * as THREE from 'three';
+import { GPUFluidSimulation } from './GPUFluidSimulation';
+import { ScreenSpaceFluidPass } from './ScreenSpaceFluidPass';
+import type {
+  BasinConfig,
+  FluidParameters,
+  FluidQuality,
+  ReservoirState,
+  WaterFlowBaseTextures,
+  WaterFlowOptions,
+  WaterFlowRenderOptions,
+} from './types';
+
+/**
+ * WaterFlow —— 可独立使用的水流对象封装。
+ *
+ * 把「GPGPU 粒子流体模拟」与「屏幕空间流体后处理」打包成一个对象：
+ * 对外只暴露 update / 参数 setter / createPass，调用方无需关心 GPU ping-pong、
+ * SPH 场、深度重建等内部细节。
+ *
+ * 两种渲染模式：
+ *  A. 自渲染模式（默认）：createPass(scene, camera) 不传 base 纹理。pass 内部
+ *     自己把主场景渲到带深度的缓冲，再与粒子深度合成。需要作为后处理链一环。
+ *  B. 注入基础纹理模式：createPass(scene, camera, baseTextures)，其中
+ *     baseTextures = { colorTexture, depthTexture, depthMode }。pass 直接消费
+ *     调用方已有的基础颜色/深度纹理，不再自渲染主场景 —— 与 three-base「共用
+ *     base 纹理 / base 深度图」的后处理方案完全契合，省掉一遍主场景渲染。
+ *     depthMode: 'standard'（默认，普通透视深度）| 'logarithmic'
+ *     （three-base 开 logarithmicDepthBuffer 时，与 frosted_glass_pass 解码对齐）。
+ *
+ * 集成到 three-base（手写 fsQuad 后处理）：
+ *   const water = new WaterFlow(renderer, { size: 200 });
+ *   const pass = water.createPass(scene, camera, {
+ *     colorTexture: this.baseRenderTarget.texture,
+ *     depthTexture: this.baseDepthTexture,
+ *     depthMode: 'logarithmic',
+ *   });
+ *   // 每帧：先 renderer.setRenderTarget(baseRenderTarget); renderer.render(scene, camera);
+ *   //       再 renderAoDepthPass(renderer, camera, scene, depthRenderTarget);  // 写 baseDepthTexture
+ *   //       然后 water.update(dt, elapsed);
+ *   //       最后 setRenderTarget(screenRT); fsQuad.render(renderer, pass.material);
+ *   // 注意：WaterFlow 的 composite 是纯消费 base 纹理的 fsQuad，可直接放进你的链。
+ */
+export class WaterFlow {
+  private readonly renderer: THREE.WebGLRenderer;
+  private width: number;
+  private height: number;
+  private readonly scale: number;
+  private readonly simulation: GPUFluidSimulation;
+  /** createPass 之前为 null；各渲染参数 setter 走 `this.pass?.xxx` 可选链。 */
+  private pass: ScreenSpaceFluidPass | null;
+
+  constructor(renderer: THREE.WebGLRenderer, options: WaterFlowOptions = {}) {
+    const {
+      width = 1,
+      height = 1,
+      scale = 0.75,
+      size = 200,
+      speed = 2.4,
+      aperture = 0.78,
+      nozzle,
+      basin,
+      jetDirection,
+      collision,
+    } = options;
+
+    this.renderer = renderer;
+    this.width = width;
+    this.height = height;
+    this.scale = scale;
+
+    this.simulation = new GPUFluidSimulation(renderer, {
+      size,
+      speed,
+      aperture,
+      nozzle,
+      basin,
+      jetDirection,
+      collision,
+    });
+    this.pass = null;
+  }
+
+  get supported(): boolean {
+    return this.simulation.supported;
+  }
+
+  get count(): number {
+    return this.simulation.count;
+  }
+
+  get positionTexture(): THREE.Texture | null {
+    return this.simulation.positionTexture;
+  }
+
+  get velocityTexture(): THREE.Texture | null {
+    return this.simulation.velocityTexture;
+  }
+
+  /**
+   * 生成屏幕空间流体 pass 并接入渲染链。
+   * @param scene 主场景（注入 base 纹理模式下不会被 pass 自渲染）
+   * @param camera 主相机（粒子投影 / spray 渲染需要）
+   * @param baseTextures 传入即启用「注入基础纹理」模式：pass 直接消费调用方颜色+深度，不再自渲染主场景。
+   * @returns 不支持浮点纹理时返回 null
+   *
+   * ⚠️ ScreenSpaceFluidPass 按**透视相机**建模（setSize 无条件读 `camera.fov` 算 pointScale、
+   *    depthMaterial 走 projectionMatrix 重建深度），故此处收 PerspectiveCamera。
+   *    ThreeBase.getCamera() 的返回类型是 `PerspectiveCamera | OrthographicCamera`，
+   *    调用处已显式窄化（见 ThreeBase 内 waterFlow.createPass 那行）。
+   *    ⚠️ 若真用正交相机，fov 为 undefined → pointScale 变 NaN（**原 JS 既有行为，本次未改运行时**）。
+   */
+  createPass(
+    scene: THREE.Scene,
+    camera: THREE.PerspectiveCamera,
+    baseTextures: WaterFlowBaseTextures | null = null,
+  ): ScreenSpaceFluidPass | null {
+    if (!this.supported) return null;
+    this.pass = new ScreenSpaceFluidPass(scene, camera, this.simulation, {
+      width: this.width,
+      height: this.height,
+      scale: this.scale,
+      activeCount: this.simulation.count,
+      externalBase: baseTextures ? {
+        colorTexture: baseTextures.colorTexture,
+        depthTexture: baseTextures.depthTexture,
+        depthMode: baseTextures.depthMode || 'standard',
+      } : null,
+    });
+    this.pass.setQuality({
+      scale: this.scale,
+      activeCount: this.simulation.count,
+      blurRadius: 5,
+    });
+    return this.pass;
+  }
+
+  /** 推进一帧模拟。 */
+  update(delta: number, elapsed: number): void {
+    if (this.supported) this.simulation.update(delta, elapsed);
+  }
+
+  // ---- 模拟参数代理 ----
+  setParameters(p: FluidParameters): void {
+    this.simulation.setParameters(p);
+  }
+
+  setReservoirState(state: ReservoirState): void {
+    this.simulation.setReservoirState(state);
+  }
+
+  setContainerMotion(accelerationX = 0, accelerationZ = 0): void {
+    this.simulation.setContainerMotion(accelerationX, accelerationZ);
+  }
+
+  setBasin(basin: BasinConfig): void {
+    this.simulation.setBasin(basin);
+  }
+
+  /** 运行时改喷流起点（喷嘴）坐标 */
+  setNozzle(x: number, y: number, z: number): void {
+    this.simulation.setNozzle(x, y, z);
+  }
+
+  /** 运行时改喷流方向（轴向，会被归一化） */
+  setJetDirection(dx: number, dy: number, dz: number): void {
+    this.simulation.setJetDirection(dx, dy, dz);
+  }
+
+  /** 运行时开关粒子与 basin/地面碰撞回弹 */
+  setCollision(enabled: boolean): void {
+    this.simulation.setCollision(enabled);
+  }
+
+  reset(): void {
+    this.simulation.reset();
+  }
+
+  // ---- 渲染参数代理（需 pass 已创建）----
+  setAirFraction(value: number): void {
+    this.pass?.setAirFraction(value);
+  }
+
+  setParticleRadius(value: number): void {
+    this.pass?.setParticleRadius(value);
+  }
+
+  setRetainedFluidVisible(value: boolean): void {
+    this.pass?.setRetainedFluidVisible(value);
+  }
+
+  setQuality(quality: FluidQuality): void {
+    this.pass?.setQuality(quality);
+  }
+
+  /** 运行时刷新注入的基础纹理（three-base resize / 切换 baseRT 时调用）。 */
+  setBaseTextures(baseTextures: WaterFlowBaseTextures): void {
+    this.pass?.setBaseTextures(baseTextures);
+  }
+
+  resize(width: number, height: number): void {
+    this.width = width;
+    this.height = height;
+    this.pass?.setSize(width, height);
+  }
+
+  /**
+   * 函数式渲染入口（three-base 手写 fsQuad 后处理链）：直接消费基础颜色/深度纹理，
+   * 把水面合成回当前渲染目标（与 frosted_glass_pass 同构，省去自渲染主场景）。
+   */
+  renderInto(renderer: THREE.WebGLRenderer, opts: WaterFlowRenderOptions): void {
+    if (this.supported && this.pass) this.pass.renderInto(renderer, opts);
+  }
+
+  dispose() {
+    this.pass?.dispose();
+    this.simulation.dispose();
+  }
+}

package/WaterFlow/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * WaterFlow 模块共享类型（单一来源，供 WaterFlow 目录内各 .ts 复用）。
+ *
+ * 2026-10-08 皇上旨「项目代码就应该写成 ts 来校验，尽量不写 js」——
+ * 原 WaterFlow/ 下 7 个手写 .js 全部改写为 .ts，公共入参/出参类型集中在此，
+ * 避免各文件重复声明高度相似的结构（也避免 any）。
+ */
+import type { Camera, DepthTexture, Scene, Texture, Vector3, Vector4, WebGLRenderer, WebGLRenderTarget } from 'three';
+/** 深度解码口径：普通透视深度 | three-base 的对数深度（logarithmicDepthBuffer）。 */
+export type DepthMode = 'standard' | 'logarithmic';
+/** 「注入基础纹理」模式：直接消费调用方已有的颜色/深度，省掉一遍主场景渲染。 */
+export interface WaterFlowBaseTextures {
+    colorTexture: Texture;
+    depthTexture: DepthTexture | Texture;
+    depthMode?: DepthMode;
+}
+/** renderInto 的入参：在基础纹理之上再加「输出目标 + 相机」。 */
+export interface WaterFlowRenderOptions extends WaterFlowBaseTextures {
+    /** 合成输出目标；null 表示沿用调用方当前渲染目标（由 renderer.getRenderTarget() 决定）。 */
+    outputTarget: WebGLRenderTarget | null;
+    camera: Camera;
+}
+/** 模拟参数（可部分更新，故全部可选）。 */
+export interface FluidParameters {
+    speed?: number;
+    aperture?: number;
+    fillRatio?: number;
+    emitting?: boolean;
+    turbulence?: number;
+}
+/** 蓄水池状态。 */
+export interface ReservoirState {
+    active?: boolean;
+    fillRatio?: number;
+}
+/** 容器（盆）几何口径：x 范围、z 半宽、中心、水面高度与壁高。 */
+export interface BasinConfig {
+    minX: number;
+    maxX: number;
+    halfZ: number;
+    centerZ?: number;
+    waterY: number;
+    wallTop: number;
+    floorY?: number;
+    containerFloorY?: number;
+    rimWidth?: number;
+}
+/** ShallowWaterSurface 构造选项。 */
+export interface ShallowWaterSurfaceOptions {
+    width?: number;
+    height?: number;
+    basinMinX?: number;
+    basinMaxX?: number;
+    basinHalfZ?: number;
+    basinCenterZ?: number;
+    waterY?: number;
+    cpuSampling?: boolean;
+}
+/** ShallowWaterSurface.setBounds 的入参（centerZ 省略时按 0 处理）。 */
+export interface ShallowWaterSurfaceBounds {
+    basinMinX: number;
+    basinMaxX: number;
+    basinHalfZ: number;
+    basinCenterZ?: number;
+    waterY: number;
+}
+/**
+ * 水面采样结果（ShallowWaterSurface.sampleSurface 回填 target 后返回）。
+ * 字段全为可选：调用方可只声明自己关心的部分，结构上兼容 FloatingDuck 的 DuckSurfaceSample。
+ */
+export interface WaterSurfaceSample {
+    height?: number;
+    velocityY?: number;
+    slopeX?: number;
+    slopeZ?: number;
+    flowX?: number;
+    flowZ?: number;
+    impact?: number;
+}
+/** 渲染质量档。 */
+export interface FluidQuality {
+    scale: number;
+    activeCount: number;
+    blurRadius: number;
+}
+/** 外层 WaterFlow 构造选项。 */
+export interface WaterFlowOptions {
+    width?: number;
+    height?: number;
+    scale?: number;
+    size?: number;
+    speed?: number;
+    aperture?: number;
+    nozzle?: Vector3;
+    basin?: Vector4;
+    jetDirection?: Vector3;
+    collision?: boolean;
+}
+/** GPUFluidSimulation 构造选项（与外层同源，保留喷嘴/盆/喷流方向）。 */
+export interface FluidSimulationOptions {
+    size?: number;
+    nozzle?: Vector3;
+    basin?: Vector4;
+    speed?: number;
+    aperture?: number;
+    jetDirection?: Vector3;
+    collision?: boolean;
+}
+/** SPHField 构造选项。 */
+export interface SPHFieldOptions {
+    mobile?: boolean;
+}
+/** ScreenSpaceFluidPass 构造选项。 */
+export interface ScreenSpaceFluidPassOptions {
+    width?: number;
+    height?: number;
+    scale?: number;
+    activeCount?: number;
+    externalBase?: {
+        colorTexture: Texture;
+        depthTexture: DepthTexture | Texture;
+        depthMode: DepthMode;
+    } | null;
+}
+/** 屏幕空间 pass 需要的场景/相机（构造期持有，避免每帧反查）。 */
+export interface ScreenSpaceFluidContext {
+    scene: Scene;
+    camera: Camera;
+}
+/** setBaseTextures 的部分更新入参。 */
+export interface PartialBaseTextures {
+    colorTexture?: Texture;
+    depthTexture?: DepthTexture | Texture;
+    depthMode?: DepthMode;
+}
+/** 渲染器能力判定结果：非 WebGL2 或缺浮点扩展时整套流体不可用。 */
+export interface FluidSupportInfo {
+    renderer: WebGLRenderer;
+}
+/**
+ * ScreenSpaceFluidPass 视角下的流体模拟器最小契约。
+ * 只声明 pass 真正读取的成员（粒子纹理边长 / 粒子数 / 能力位 / 位置与速度纹理），
+ * 使 pass 不必耦合 GPUFluidSimulation 的其余实现细节。
+ * GPUFluidSimulation 实例天然满足本结构（结构化子类型）。
+ */
+export interface ScreenSpaceFluidSource {
+    /** 粒子纹理边长，count === size * size。 */
+    size: number;
+    /** 粒子总数。 */
+    count: number;
+    /** 是否支持浮点纹理；false 时两个纹理成员为 null。 */
+    supported: boolean;
+    positionTexture: Texture | null;
+    velocityTexture: Texture | null;
+}
+/**
+ * 「外部注入基础纹理」三元组的非空形态。
+ * 等价于 ScreenSpaceFluidPassOptions['externalBase'] 去掉 null，
+ * 供 pass 内部字段（externalBase）与 GPUFluidSimulation 之外的调用方直接复用。
+ */
+export type ExternalBaseTextures = NonNullable<ScreenSpaceFluidPassOptions['externalBase']>;

package/WaterFlow/types.js

@@ -0,0 +1 @@
+export {};