three-base 2.0.169 → 2.0.175

package/PipeMesh/directRoute.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 直连管道走线（纯数字，零依赖）。
+ *
+ * 皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」：
+ * 相邻两个控制点之间就是一根直管（可以是斜的），不再按轴序拆正交段、不再有 90° 弯头。
+ * 每段只算三件事：长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *
+ * ⭐ 为什么仍单独一个零 import 模块：管道几何要写进 InstancedChild 的实例矩阵（见 PipeMesh.ts），
+ *   而「几段、每段多长、朝哪、球放哪」是可独立核对的算术。留成零依赖 ⇒ `test/pipeRoute.test.js`
+ *   能直接 require 编译产物逐字段断言，不必起浏览器。
+ *
+ * ⚠️ 拐角为什么必须补一颗球：直管是**开口圆柱**（CylinderGeometry openEnded，见 PipeStraight.ts），
+ *   两段斜管在拐角处只有轴线相交、端面是斜的 ⇒ 夹角外侧必然露一个楔形缺口，能直接看穿管子。
+ *   补法取最省事的一种：控制点上放一颗「直径同管」的球（PipeJoint），球面把缺口盖满。
+ *   球与管同径 ⇒ 共线时完全看不出来，有夹角时是光滑过渡，不是一串珠子。
+ *
+ * ⚠️ 上一版（`orthogonalRoute.ts`，2026-10-21 ～ 10-25）是按 axisOrder 逐轴补齐的正交走线 + 90° 弯头，
+ *   已整份删除。要找回请从 git 取，别在半路上重新发明一遍。
+ */
+/** 世界坐标点，单位米 */
+export type Vec3 = [number, number, number];
+/** 直管段：几何中心 + 轴向单位向量 + 段长 */
+export interface StraightPart {
+    /** 段序号（从 0 起，对应「控制点 i → 控制点 i+1」） */
+    index: number;
+    /** 直管几何体的中心（单位圆柱沿 +Y 生成，容器再旋转/缩放到此位姿） */
+    center: Vec3;
+    /** 走线方向，单位向量（任意朝向，不限六向） */
+    dir: Vec3;
+    /** 段长（米）= 两控制点欧氏距离 */
+    length: number;
+}
+/** 拐角补角球：球心压在控制点上，半径 = 直径/2 */
+export interface JointPart {
+    /** 对应控制点下标（1 … n-2；两端没有拐角，不补球） */
+    index: number;
+    center: Vec3;
+    radius: number;
+}
+export interface PipePlan {
+    straights: StraightPart[];
+    joints: JointPart[];
+    /** 退化输入说明（点重合、走线全零、直径非法…）；渲染不受影响，供面板提示 */
+    warnings: string[];
+}
+/** 段长可忽略的判据（与上一版正交方案同量级） */
+export declare const PIPE_EPS = 0.000001;
+/**
+ * 算出整条管道的直管 + 补角球清单。
+ *
+ * ⚠️ 重合的控制点对**不产生直管**（长度 0 的圆柱缩放会让法线退化），但两端点仍参与球的判定 ——
+ *   只要该点还连着别的有效直管，球照放，接缝才不会因为一个废段而开口。
+ */
+export declare function planDirectLayout(points: Vec3[], opts?: {
+    diameter?: number;
+}): PipePlan;
+/**
+ * JSON 是「管道对象」与「编辑页项目」共用的唯一数据形状。
+ * 单位米；points 是控制点（不是段），所以重新走线/改直径只改这几个字段即可。
+ *
+ * ⚠️ version 仍是 1：形状（points / diameter / color）与上一版一致，只是上一版的 `axisOrder`
+ *   从「必填参数」降级成「忽略的多余键」⇒ 皇上库里的旧项目照样打得开，只是形状按直连重算。
+ */
+export interface PipeJson {
+    format: "three-base.pipe";
+    version: 1;
+    diameter: number;
+    color?: string;
+    points: Vec3[];
+}
+export declare const PIPE_JSON_FORMAT = "three-base.pipe";
+export declare const PIPE_JSON_VERSION = 1;
+export declare function makePipeJson(points: Vec3[], diameter: number, color?: string): PipeJson;
+/**
+ * 解析结果：`ok=false` 时 `reason` 是人话，可直接弹给编辑页显示；`ok=true` 时 `json` 已归一化。
+ * ⚠️ 刻意不用 `{ok:true;json} | {ok:false;reason}` 可辨识联合：库编译走的是 `strict:false`
+ *   （three-base/tsconfig.json），实测那种写法在 `if (!r.ok)` 之后取 `r.reason` 会报 TS2339。
+ */
+export interface PipeJsonResult {
+    ok: boolean;
+    json?: PipeJson;
+    reason?: string;
+}
+/** 宽松校验：接受对象/字符串，字段缺失或类型错都返回 reason 而不抛异常（导入现场不许崩） */
+export declare function parsePipeJson(input: unknown): PipeJsonResult;

package/PipeMesh/directRoute.js

@@ -0,0 +1,126 @@
+/**
+ * 直连管道走线（纯数字，零依赖）。
+ *
+ * 皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」：
+ * 相邻两个控制点之间就是一根直管（可以是斜的），不再按轴序拆正交段、不再有 90° 弯头。
+ * 每段只算三件事：长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *
+ * ⭐ 为什么仍单独一个零 import 模块：管道几何要写进 InstancedChild 的实例矩阵（见 PipeMesh.ts），
+ *   而「几段、每段多长、朝哪、球放哪」是可独立核对的算术。留成零依赖 ⇒ `test/pipeRoute.test.js`
+ *   能直接 require 编译产物逐字段断言，不必起浏览器。
+ *
+ * ⚠️ 拐角为什么必须补一颗球：直管是**开口圆柱**（CylinderGeometry openEnded，见 PipeStraight.ts），
+ *   两段斜管在拐角处只有轴线相交、端面是斜的 ⇒ 夹角外侧必然露一个楔形缺口，能直接看穿管子。
+ *   补法取最省事的一种：控制点上放一颗「直径同管」的球（PipeJoint），球面把缺口盖满。
+ *   球与管同径 ⇒ 共线时完全看不出来，有夹角时是光滑过渡，不是一串珠子。
+ *
+ * ⚠️ 上一版（`orthogonalRoute.ts`，2026-10-21 ～ 10-25）是按 axisOrder 逐轴补齐的正交走线 + 90° 弯头，
+ *   已整份删除。要找回请从 git 取，别在半路上重新发明一遍。
+ */
+/** 段长可忽略的判据（与上一版正交方案同量级） */
+export const PIPE_EPS = 1e-6;
+/**
+ * 算出整条管道的直管 + 补角球清单。
+ *
+ * ⚠️ 重合的控制点对**不产生直管**（长度 0 的圆柱缩放会让法线退化），但两端点仍参与球的判定 ——
+ *   只要该点还连着别的有效直管，球照放，接缝才不会因为一个废段而开口。
+ */
+export function planDirectLayout(points, opts = {}) {
+    const diameter = opts.diameter ?? 1;
+    const warnings = [];
+    const radius = diameter / 2;
+    if (points.length < 2) {
+        warnings.push("控制点少于 2 个，无法走线");
+        return { straights: [], joints: [], warnings };
+    }
+    if (!(diameter > 0)) {
+        warnings.push(`直径 ${diameter} 非法（必须为正数，单位米）`);
+        return { straights: [], joints: [], warnings };
+    }
+    const straights = [];
+    /** 第 i 段（控制点 i → i+1）是否真的产生了一根直管 */
+    const segOk = [];
+    for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i];
+        const b = points[i + 1];
+        const dx = b[0] - a[0];
+        const dy = b[1] - a[1];
+        const dz = b[2] - a[2];
+        const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (len < PIPE_EPS) {
+            segOk.push(false);
+            warnings.push(`第 ${i + 1} 与第 ${i + 2} 个控制点重合，跳过这一段`);
+            continue;
+        }
+        segOk.push(true);
+        straights.push({
+            index: i,
+            center: [a[0] + dx / 2, a[1] + dy / 2, a[2] + dz / 2],
+            dir: [dx / len, dy / len, dz / len],
+            length: len,
+        });
+    }
+    const joints = [];
+    for (let i = 1; i < points.length - 1; i++) {
+        // 前后都没生出直管 ⇒ 这是个孤立点，补球只是凭空多一颗，没意义
+        if (!segOk[i - 1] && !segOk[i])
+            continue;
+        const p = points[i];
+        joints.push({ index: i, center: [p[0], p[1], p[2]], radius });
+    }
+    if (straights.length === 0 && warnings.length === 0) {
+        warnings.push("没有产生任何直管");
+    }
+    return { straights, joints, warnings };
+}
+export const PIPE_JSON_FORMAT = "three-base.pipe";
+export const PIPE_JSON_VERSION = 1;
+export function makePipeJson(points, diameter, color) {
+    const json = { format: PIPE_JSON_FORMAT, version: PIPE_JSON_VERSION, diameter, points };
+    if (color)
+        json.color = color;
+    return json;
+}
+/** 宽松校验：接受对象/字符串，字段缺失或类型错都返回 reason 而不抛异常（导入现场不许崩） */
+export function parsePipeJson(input) {
+    let raw = input;
+    if (typeof raw === "string") {
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch (e) {
+            return { ok: false, reason: "不是合法 JSON 文本" };
+        }
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, reason: "顶层不是 JSON 对象" };
+    }
+    const obj = raw;
+    if (obj.format !== PIPE_JSON_FORMAT) {
+        return { ok: false, reason: `format 应为 "${PIPE_JSON_FORMAT}"，实际 ${JSON.stringify(obj.format)}` };
+    }
+    if (obj.version !== PIPE_JSON_VERSION) {
+        return { ok: false, reason: `暂不支持 version ${String(obj.version)}（当前只认 ${PIPE_JSON_VERSION}）` };
+    }
+    const points = obj.points;
+    if (!Array.isArray(points) || points.length < 2) {
+        return { ok: false, reason: "points 至少要有 2 个控制点" };
+    }
+    const vecs = [];
+    for (let i = 0; i < points.length; i++) {
+        const p = points[i];
+        const isTuple = Array.isArray(p) && p.length === 3 && p.every((n) => typeof n === "number" && Number.isFinite(n));
+        if (!isTuple) {
+            return { ok: false, reason: `第 ${i + 1} 个控制点不是 [x,y,z] 三个有限数字` };
+        }
+        vecs.push([p[0], p[1], p[2]]);
+    }
+    const diameter = typeof obj.diameter === "number" && Number.isFinite(obj.diameter) && obj.diameter > 0
+        ? obj.diameter
+        : NaN;
+    if (!(diameter > 0)) {
+        return { ok: false, reason: "diameter 缺失或不是正数（单位米）" };
+    }
+    const color = typeof obj.color === "string" ? obj.color : undefined;
+    return { ok: true, json: makePipeJson(vecs, diameter, color) };
+}

package/PipeMesh/directRoute.ts

@@ -0,0 +1,190 @@
+/**
+ * 直连管道走线（纯数字，零依赖）。
+ *
+ * 皇上旨 2026-10-25「直接就是点与点直接连接，最简单的方案」：
+ * 相邻两个控制点之间就是一根直管（可以是斜的），不再按轴序拆正交段、不再有 90° 弯头。
+ * 每段只算三件事：长度 = 两点欧氏距离、方向 = 连线单位向量、中点 = 两点中点。
+ *
+ * ⭐ 为什么仍单独一个零 import 模块：管道几何要写进 InstancedChild 的实例矩阵（见 PipeMesh.ts），
+ *   而「几段、每段多长、朝哪、球放哪」是可独立核对的算术。留成零依赖 ⇒ `test/pipeRoute.test.js`
+ *   能直接 require 编译产物逐字段断言，不必起浏览器。
+ *
+ * ⚠️ 拐角为什么必须补一颗球：直管是**开口圆柱**（CylinderGeometry openEnded，见 PipeStraight.ts），
+ *   两段斜管在拐角处只有轴线相交、端面是斜的 ⇒ 夹角外侧必然露一个楔形缺口，能直接看穿管子。
+ *   补法取最省事的一种：控制点上放一颗「直径同管」的球（PipeJoint），球面把缺口盖满。
+ *   球与管同径 ⇒ 共线时完全看不出来，有夹角时是光滑过渡，不是一串珠子。
+ *
+ * ⚠️ 上一版（`orthogonalRoute.ts`，2026-10-21 ～ 10-25）是按 axisOrder 逐轴补齐的正交走线 + 90° 弯头，
+ *   已整份删除。要找回请从 git 取，别在半路上重新发明一遍。
+ */
+
+/** 世界坐标点，单位米 */
+export type Vec3 = [number, number, number];
+
+/** 直管段：几何中心 + 轴向单位向量 + 段长 */
+export interface StraightPart {
+    /** 段序号（从 0 起，对应「控制点 i → 控制点 i+1」） */
+    index: number;
+    /** 直管几何体的中心（单位圆柱沿 +Y 生成，容器再旋转/缩放到此位姿） */
+    center: Vec3;
+    /** 走线方向，单位向量（任意朝向，不限六向） */
+    dir: Vec3;
+    /** 段长（米）= 两控制点欧氏距离 */
+    length: number;
+}
+
+/** 拐角补角球：球心压在控制点上，半径 = 直径/2 */
+export interface JointPart {
+    /** 对应控制点下标（1 … n-2；两端没有拐角，不补球） */
+    index: number;
+    center: Vec3;
+    radius: number;
+}
+
+export interface PipePlan {
+    straights: StraightPart[];
+    joints: JointPart[];
+    /** 退化输入说明（点重合、走线全零、直径非法…）；渲染不受影响，供面板提示 */
+    warnings: string[];
+}
+
+/** 段长可忽略的判据（与上一版正交方案同量级） */
+export const PIPE_EPS = 1e-6;
+
+/**
+ * 算出整条管道的直管 + 补角球清单。
+ *
+ * ⚠️ 重合的控制点对**不产生直管**（长度 0 的圆柱缩放会让法线退化），但两端点仍参与球的判定 ——
+ *   只要该点还连着别的有效直管，球照放，接缝才不会因为一个废段而开口。
+ */
+export function planDirectLayout(points: Vec3[], opts: { diameter?: number } = {}): PipePlan {
+    const diameter = opts.diameter ?? 1;
+    const warnings: string[] = [];
+    const radius = diameter / 2;
+
+    if (points.length < 2) {
+        warnings.push("控制点少于 2 个，无法走线");
+        return { straights: [], joints: [], warnings };
+    }
+    if (!(diameter > 0)) {
+        warnings.push(`直径 ${diameter} 非法（必须为正数，单位米）`);
+        return { straights: [], joints: [], warnings };
+    }
+
+    const straights: StraightPart[] = [];
+    /** 第 i 段（控制点 i → i+1）是否真的产生了一根直管 */
+    const segOk: boolean[] = [];
+
+    for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i];
+        const b = points[i + 1];
+        const dx = b[0] - a[0];
+        const dy = b[1] - a[1];
+        const dz = b[2] - a[2];
+        const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (len < PIPE_EPS) {
+            segOk.push(false);
+            warnings.push(`第 ${i + 1} 与第 ${i + 2} 个控制点重合，跳过这一段`);
+            continue;
+        }
+        segOk.push(true);
+        straights.push({
+            index: i,
+            center: [a[0] + dx / 2, a[1] + dy / 2, a[2] + dz / 2],
+            dir: [dx / len, dy / len, dz / len],
+            length: len,
+        });
+    }
+
+    const joints: JointPart[] = [];
+    for (let i = 1; i < points.length - 1; i++) {
+        // 前后都没生出直管 ⇒ 这是个孤立点，补球只是凭空多一颗，没意义
+        if (!segOk[i - 1] && !segOk[i]) continue;
+        const p = points[i];
+        joints.push({ index: i, center: [p[0], p[1], p[2]], radius });
+    }
+
+    if (straights.length === 0 && warnings.length === 0) {
+        warnings.push("没有产生任何直管");
+    }
+    return { straights, joints, warnings };
+}
+
+/**
+ * JSON 是「管道对象」与「编辑页项目」共用的唯一数据形状。
+ * 单位米；points 是控制点（不是段），所以重新走线/改直径只改这几个字段即可。
+ *
+ * ⚠️ version 仍是 1：形状（points / diameter / color）与上一版一致，只是上一版的 `axisOrder`
+ *   从「必填参数」降级成「忽略的多余键」⇒ 皇上库里的旧项目照样打得开，只是形状按直连重算。
+ */
+export interface PipeJson {
+    format: "three-base.pipe";
+    version: 1;
+    diameter: number;
+    color?: string;
+    points: Vec3[];
+}
+
+export const PIPE_JSON_FORMAT = "three-base.pipe";
+export const PIPE_JSON_VERSION = 1;
+
+export function makePipeJson(points: Vec3[], diameter: number, color?: string): PipeJson {
+    const json: PipeJson = { format: PIPE_JSON_FORMAT, version: PIPE_JSON_VERSION, diameter, points };
+    if (color) json.color = color;
+    return json;
+}
+
+/**
+ * 解析结果：`ok=false` 时 `reason` 是人话，可直接弹给编辑页显示；`ok=true` 时 `json` 已归一化。
+ * ⚠️ 刻意不用 `{ok:true;json} | {ok:false;reason}` 可辨识联合：库编译走的是 `strict:false`
+ *   （three-base/tsconfig.json），实测那种写法在 `if (!r.ok)` 之后取 `r.reason` 会报 TS2339。
+ */
+export interface PipeJsonResult {
+    ok: boolean;
+    json?: PipeJson;
+    reason?: string;
+}
+
+/** 宽松校验：接受对象/字符串，字段缺失或类型错都返回 reason 而不抛异常（导入现场不许崩） */
+export function parsePipeJson(input: unknown): PipeJsonResult {
+    let raw: unknown = input;
+    if (typeof raw === "string") {
+        try {
+            raw = JSON.parse(raw);
+        } catch (e) {
+            return { ok: false, reason: "不是合法 JSON 文本" };
+        }
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, reason: "顶层不是 JSON 对象" };
+    }
+    const obj = raw as Record<string, unknown>;
+    if (obj.format !== PIPE_JSON_FORMAT) {
+        return { ok: false, reason: `format 应为 "${PIPE_JSON_FORMAT}"，实际 ${JSON.stringify(obj.format)}` };
+    }
+    if (obj.version !== PIPE_JSON_VERSION) {
+        return { ok: false, reason: `暂不支持 version ${String(obj.version)}（当前只认 ${PIPE_JSON_VERSION}）` };
+    }
+    const points = obj.points;
+    if (!Array.isArray(points) || points.length < 2) {
+        return { ok: false, reason: "points 至少要有 2 个控制点" };
+    }
+    const vecs: Vec3[] = [];
+    for (let i = 0; i < points.length; i++) {
+        const p = points[i];
+        const isTuple =
+            Array.isArray(p) && p.length === 3 && p.every((n) => typeof n === "number" && Number.isFinite(n));
+        if (!isTuple) {
+            return { ok: false, reason: `第 ${i + 1} 个控制点不是 [x,y,z] 三个有限数字` };
+        }
+        vecs.push([p[0] as number, p[1] as number, p[2] as number]);
+    }
+    const diameter = typeof obj.diameter === "number" && Number.isFinite(obj.diameter) && obj.diameter > 0
+        ? obj.diameter
+        : NaN;
+    if (!(diameter > 0)) {
+        return { ok: false, reason: "diameter 缺失或不是正数（单位米）" };
+    }
+    const color = typeof obj.color === "string" ? obj.color : undefined;
+    return { ok: true, json: makePipeJson(vecs, diameter, color) };
+}

package/PipeMesh/index.d.ts

@@ -1 +1,7 @@
 export { default } from "./PipeMesh";
+export { default as PipeMesh } from "./PipeMesh";
+export { default as PipeStraight } from "./PipeStraight";
+export { default as PipeJoint } from "./PipeJoint";
+export { createPipeMaterial, pipeMaterial, PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+export * from "./directRoute";
+export * from "./axisSnap";

package/PipeMesh/index.js

@@ -1 +1,7 @@
 export { default } from "./PipeMesh";
+export { default as PipeMesh } from "./PipeMesh";
+export { default as PipeStraight } from "./PipeStraight";
+export { default as PipeJoint } from "./PipeJoint";
+export { createPipeMaterial, pipeMaterial, PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+export * from "./directRoute";
+export * from "./axisSnap";

package/PipeMesh/index.ts

@@ -1 +1,7 @@
-export { default } from "./PipeMesh";
+export { default } from "./PipeMesh";
+export { default as PipeMesh } from "./PipeMesh";
+export { default as PipeStraight } from "./PipeStraight";
+export { default as PipeJoint } from "./PipeJoint";
+export { createPipeMaterial, pipeMaterial, PIPE_DEFAULT_COLOR } from "./pipeMaterial";
+export * from "./directRoute";
+export * from "./axisSnap";

package/PipeMesh/pipeMaterial.d.ts

@@ -0,0 +1,16 @@
+import { MeshStandardMaterial } from "three";
+/**
+ * 直管与弯头共用一份材质。
+ *
+ * ⭐ 为什么底色是白：实例化那条路，逐实例颜色走 `InstancedMesh.instanceColor`（InstancedBatch 预填 1.0，
+ *   setColor 覆盖），three 里最终 diffuse = material.color × instanceColor。材质底色若非白，setColor 的值
+ *   就会被整体压暗，面板上「这根管子涂什么色」就对不上画面了。
+ * ⭐ 为什么两边共享同一份：材质只有一份 ⇒ 粗糙度/金属度改一次，两个 batch（直管、弯头）同时跟上；
+ *   合批是按 geometry+material 分桶的，共享材质不会把它们并成一个 batch（几何不同），draw call 仍是 2。
+ * ⚠️ DoubleSide 是必需的：直管是开口圆柱（无端面），从管口往里看要能看到内壁，否则管子里是黑的空洞。
+ */
+export declare function createPipeMaterial(): MeshStandardMaterial;
+/** 全库共享的那一份材质实例（InstancedChild 的 static material 必须是同一个对象才会同桶/同改） */
+export declare const pipeMaterial: MeshStandardMaterial;
+/** 管道默认颜色，取自参考稿 */
+export declare const PIPE_DEFAULT_COLOR = 5227511;

package/PipeMesh/pipeMaterial.js

@@ -0,0 +1,23 @@
+import { DoubleSide, MeshStandardMaterial } from "three";
+/**
+ * 直管与弯头共用一份材质。
+ *
+ * ⭐ 为什么底色是白：实例化那条路，逐实例颜色走 `InstancedMesh.instanceColor`（InstancedBatch 预填 1.0，
+ *   setColor 覆盖），three 里最终 diffuse = material.color × instanceColor。材质底色若非白，setColor 的值
+ *   就会被整体压暗，面板上「这根管子涂什么色」就对不上画面了。
+ * ⭐ 为什么两边共享同一份：材质只有一份 ⇒ 粗糙度/金属度改一次，两个 batch（直管、弯头）同时跟上；
+ *   合批是按 geometry+material 分桶的，共享材质不会把它们并成一个 batch（几何不同），draw call 仍是 2。
+ * ⚠️ DoubleSide 是必需的：直管是开口圆柱（无端面），从管口往里看要能看到内壁，否则管子里是黑的空洞。
+ */
+export function createPipeMaterial() {
+    return new MeshStandardMaterial({
+        color: 0xffffff,
+        roughness: 0.35,
+        metalness: 0.5,
+        side: DoubleSide,
+    });
+}
+/** 全库共享的那一份材质实例（InstancedChild 的 static material 必须是同一个对象才会同桶/同改） */
+export const pipeMaterial = createPipeMaterial();
+/** 管道默认颜色，取自参考稿 */
+export const PIPE_DEFAULT_COLOR = 0x4fc3f7;

package/PipeMesh/pipeMaterial.ts

@@ -0,0 +1,26 @@
+import { DoubleSide, MeshStandardMaterial } from "three";
+
+/**
+ * 直管与弯头共用一份材质。
+ *
+ * ⭐ 为什么底色是白：实例化那条路，逐实例颜色走 `InstancedMesh.instanceColor`（InstancedBatch 预填 1.0，
+ *   setColor 覆盖），three 里最终 diffuse = material.color × instanceColor。材质底色若非白，setColor 的值
+ *   就会被整体压暗，面板上「这根管子涂什么色」就对不上画面了。
+ * ⭐ 为什么两边共享同一份：材质只有一份 ⇒ 粗糙度/金属度改一次，两个 batch（直管、弯头）同时跟上；
+ *   合批是按 geometry+material 分桶的，共享材质不会把它们并成一个 batch（几何不同），draw call 仍是 2。
+ * ⚠️ DoubleSide 是必需的：直管是开口圆柱（无端面），从管口往里看要能看到内壁，否则管子里是黑的空洞。
+ */
+export function createPipeMaterial(): MeshStandardMaterial {
+    return new MeshStandardMaterial({
+        color: 0xffffff,
+        roughness: 0.35,
+        metalness: 0.5,
+        side: DoubleSide,
+    });
+}
+
+/** 全库共享的那一份材质实例（InstancedChild 的 static material 必须是同一个对象才会同桶/同改） */
+export const pipeMaterial = createPipeMaterial();
+
+/** 管道默认颜色，取自参考稿 */
+export const PIPE_DEFAULT_COLOR = 0x4fc3f7;

package/ThreeBase.d.ts

@@ -4,7 +4,6 @@ import ThreeMouse from "./ThreeMouse";
 import InstancedGroup from "./instanced/InstancedGroup";
 import Transition from "./Transition";
 import { type DebugDepthMode } from "./pass/debugDepthState";
-import { WaterFlow } from "./WaterFlow/WaterFlow";
 import type { ThreeBaseEventTypeMap } from "./EventMap";
 type CameraType = "perspectiveCamera" | "orthographicCamera";
 type ControlType = "OrbitControls" | "MapControls";
@@ -79,35 +78,18 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
     get effectiveRatio(): number;
     baseDepthTexture: DepthTexture;
     baseRenderTarget: WebGLRenderTarget<Texture>;
-    /** 可选的屏幕空间水流对象（WaterFlow）。默认 null；调用 enableWaterFlow() 后创建。启用时
-     * 每帧消费 baseRenderTarget/baseDepthTexture，把水面合成进后处理链（不额外渲染主场景）。 */
-    waterFlow: WaterFlow | null;
-    private _waterFlowLastTime;
-    waterFlowElapsed: number;
-    excludedMaskRenderTarget: WebGLRenderTarget<Texture>;
     depthRenderTarget: WebGLRenderTarget<Texture>;
     aoDepthTexture: DepthTexture;
     /**
      * 调试用：深度预览模式。由面板「深度调试」切换，便于逐一看各深度图排查"深度测试全部失效"根因。
      *   - "none"    ：正常渲染（默认）
-     *   - "global"  ：仅预览全局深度图（baseDepthTexture，排除地板）。全白=深度为空→renderAoDepthPass 没写进深度。
-     *   - "ao"      ：仅预览 AO 深度图（aoDepthTexture = 法线 pass 顺带写入的含地板深度）。用于确认深度管线本身是否工作。
+     *   - "global"  ：仅预览可见深度图（baseDepthTexture；2026-10-18 起收全场景对象，含地板）。全白=深度为空→renderVisibleDepthPass 没写进深度。
+     *   - "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: DebugDepthMode;
-    /**
-     * 可见深度图是否包含「标了 userData.aoFloor 的地板」（如 Ground1）。
-     *
-     * 默认 false —— 原设计：地板可透视，透过地板看到的物体照常显示（不被地板挡住）。
-     * 置 true 后地板会写进 baseDepthTexture，**被地板挡住的描边/辉光/毛玻璃/覆盖色会被正确遮挡**。
-     * 排查"怎么都挡不住"时先开这个试一下：若开了就正常，说明挡你的正是可透视地板。
-     */
-    get baseDepthIncludeFloor(): boolean;
-    set baseDepthIncludeFloor(v: boolean);
     normalRenderTarget: WebGLRenderTarget<Texture>;
     screenRenderTarget: WebGLRenderTarget<Texture>;
     screenCopyShader: import("three").ShaderMaterial;
@@ -174,35 +156,6 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
     gridHelper: GridHelper;
     axesHelper: AxesHelper;
     init(): void;
-    /**
-     * 启用屏幕空间水流（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?: {
-        size?: number;
-        speed?: number;
-        aperture?: number;
-        nozzle?: [number, number, number];
-        jetDirection?: [number, number, number];
-        collision?: boolean;
-    }): void;
-    /** 运行时改喷流起点（喷嘴）坐标（WaterFlow 已启用时有效） */
-    setWaterFlowNozzle(x: number, y: number, z: number): void;
-    /** 运行时改喷流方向（轴向，会被归一化） */
-    setWaterFlowJetDirection(x: number, y: number, z: number): void;
-    /** 运行时开关粒子与 basin/地面碰撞回弹 */
-    setWaterFlowCollision(enabled: boolean): void;
-    /**
-     * 关闭屏幕空间水流并释放其 GPU 资源（enableWaterFlow 的反操作）。
-     * 切走页面时必须调用，否则其它页面 render 仍会合成水面（this.waterFlow 非空）。
-     */
-    disableWaterFlow(): void;
     resetLookAt({ position, center, }: {
         position: Vector3;
         center: Vector3;