three-base 2.0.142 → 2.0.166

package/instanced/InstancedChild.d.ts

@@ -1,174 +1,174 @@
-import { BufferGeometry, Color, Group, Material, Object3D } from "three";
-import type { InstancedTemplate } from "./InstancedTemplate";
-/** 选择代理可叠加的后处理效果开关；默认只开描边（保持向后兼容），可被 glow / bloom / cover 任意叠加。 */
-export interface SelectProxyOptions {
-    stroke?: boolean;
-    glow?: boolean;
-    bloom?: boolean;
-    cover?: boolean;
-    /** 描边粗细（像素级，越大越粗）；不传则沿用 stroke_pass 默认 1 */
-    stroke_width?: number;
-    stroke_color?: string;
-    glow_color?: string;
-    glow_width?: number;
-    glow_opacity?: number;
-    bloom_strength?: number;
-    bloom_radius?: number;
-    cover_color?: string;
-    cover_opacity?: number;
-}
-/**
- * 所有活着的 InstancedChild 实例集合，供 InstancedGroup 每帧收集。
- * 用全局注册表而非遍历整棵 scene，避免大场景每帧 traverse 全树的性能开销。
- *
- * ⚠️ 多 InstancedGroup 共存时的归属（owner）：见 `instancedChildOwner` 与 `getOwner()`。
- * 同一个进程里可能并存多个 InstancedGroup（如主编辑器的 ThreeBase 与预览弹窗各自一套），
- * 若不隔离，双方会互相把对方的实例收进自己的 batch，导致「A 场景的立方体出现在 B 场景」。
- */
-export declare const instancedChildRegistry: Set<InstancedChild>;
-/**
- * 实例归属（owner tag）注册表：child -> owner 字符串。
- * InstancedGroup 构造时可声明自己的 owner，每帧只收集 `owner` 匹配（或未声明 owner）的实例。
- * 未在表中登记的实例视为「无归属」，会被**声明了 owner 的组**忽略、
- * 被**未声明 owner 的组**（如 ThreeBase 的默认组）收集 —— 保持对既有代码零影响。
- */
-export declare const instancedChildOwner: Map<InstancedChild, string>;
-/**
- * 用户继承的「逻辑实例」基类。自身不参与渲染，只描述"一个实例"的位置 / 颜色 / 事件。
- *
- * 用法：
- * ```ts
- * class Cube extends InstancedChild {
- *   static geometry = new BoxGeometry(1, 1, 1);
- *   static material = new MeshStandardMaterial({ color: 0xffffff });
- *   constructor() {
- *     super();
- *     this.addEventListener("click", () => {
- *       this.setColor("#ff0000");
- *       this.position.set(0, 0, 0);
- *     });
- *   }
- * }
- * const cube = new Cube();
- * cube.position.set(1, 2, 3);
- * threeBase.scene.add(cube); // 加进任意层级即可
- * ```
- *
- * ThreeBase 里固定的 InstancedGroup 会自动把「同 geometry+material」（或「同 instanceUrl+animation」）
- * 的 InstancedChild 合并进同一个 InstancedMesh 批量渲染，无需用户管理实例缓冲。
- */
-export default class InstancedChild extends Object3D {
-    /** 内置几何模式：子类覆盖这两个静态字段 */
-    static geometry?: BufferGeometry;
-    /** 内置几何模式材质 */
-    static material?: Material;
-    /** GLB 模式：模型地址（与 geometry/material 互斥，优先于内置） */
-    static instanceUrl?: string;
-    /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
-    static animation?: string;
-    /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
-    static prepareTemplate?: (template: InstancedTemplate) => void;
-    /** 实例颜色，写入 InstancedMesh.instanceColor */
-    color: Color;
-    /**
-     * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
-     * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
-     */
-    needUpdate: boolean;
-    /** 模板是否就绪（GLB 异步加载完成后置 true） */
-    templateReady: boolean;
-    /**
-     * 第一人称碰撞检测标记：为 true 时，本实例所属 batch 的 InstancedMesh 会被打上
-     * `userData.fpsCollision = true`，从而被 FPScontrol 的碰撞射线命中（实例自身的世界矩阵即碰撞体位置）。
-     * 需配合 three-base 的 FPScontrol 使用（详见 FPSDemo 示例页）。
-     *
-     * ⚠️ 语义约束：真实几何合并在同一个 InstancedMesh 里，故碰撞以「整个 batch
-     * （相同 geometry+material / 相同 instanceUrl+animation 的所有实例）」为单位开关——
-     * 同一 batch 内的所有实例要么都参与碰撞、要么都不参与。若只想让部分实例参与碰撞，
-     * 请把它们拆成不同的 InstancedChild 子类（不同 geometry 或不同 batchKey）。
-     */
-    fpsCollision: boolean;
-    /**
-     * 自动脏检测开关（实验用，默认开）：
-     * - true：markDirtyIfWorldChanged 每帧比对 matrixWorld，变化则自动置 needUpdate（位置/旋转/缩放变化无需手动置位）；
-     * - false：关闭自动检测，仅手动置 needUpdate（如 setColor）的实例才会写回实例缓冲。
-     * 关闭后，静态布置的实例渲染不变，但「运动」（旋转/移动/缩放）将不再反映到画面（因为 matrixWorld 变了却没写回）。
-     * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
-     */
-    static AUTO_MARK_DIRTY: boolean;
-    /**
-     * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
-     * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
-     * 默认 null 表示不主动切换，沿用 batch 构造时的 static animation。
-     */
-    private _pendingClip;
-    private _cachedWorld;
-    constructor(fpsCollision?: boolean);
-    /** 该实例归属哪个 batch 的 key：相同 geometry+material 或相同 instanceUrl+当前生效动画 合并为一类。
-     *  因 key 含「当前生效动画」，切换动画 = 实例在「glb+旧动画」与「glb+新动画」两个常驻 batch 间迁移，而非 batch 内切 mixer。 */
-    getBatchKey(): string;
-    /** 本实例当前生效的动画名：优先 playClip 请求，否则类声明的 static animation；用于分桶 key 与 batch mixer 构建 */
-    getEffectiveAnimation(): string | undefined;
-    /**
-     * 为一组 InstancedChild 构建"选择代理"（select proxy）：
-     * 用每个实例的世界矩阵 matrixWorld + 同款 geometry/material 重建独立网格，
-     * 供 stroke_pass 单独渲染其深度 / 灰度，从而得到这组实例"专属"的描边。
-     *
-     * 为什么需要它：InstancedChild 是纯逻辑节点（无几何），真实几何在 InstancedGroup 合并出的
-     * InstancedMesh 里，且一个 InstancedMesh 通常包含很多实例。要单独描边"某一个 / 某一组"实例，
-     * 无法靠直接渲染该 InstancedChild（空）或整个 InstancedMesh（会描到所有实例）。
-     * 本方法把目标实例重新"画"成一份独立几何，就能像普通 Mesh 一样单独取深度、单独描边。
-     *
-     * 关键点：
-     * - 用 instance.matrixWorld 直接作为代理网格的 local matrix（代理本身不在 scene 内、无父变换），
-     *   因此代理在屏幕上的位置 / 深度与真实实例严格一致，描边轮廓正好贴合，且能被同一张 baseDepthTexture 正确遮挡；
-     * - 代理对象通常注册到 ThreeBase.addStrokeObject（不在 scene 内），由渲染管线在效果阶段描边，
-     *   不会被正常 base pass 重复绘制。
-     *
-     * 仅支持内置几何模式（static geometry + static material）；GLB 模式的几何由 batch 解析，
-     * 需从对应 InstancedBatch 取几何，此处暂跳过（无 static geometry 的实例不进代理）。
-     *
-     * @param children 要描边的一组实例（如某个 Group 的全部 InstancedChild）
-     * @returns 代理 Group（含顺序与 children 一一对应的代理网格）；若没有任何可重建的实例则返回 null
-     */
-    static buildSelectProxy(children: InstancedChild[], options?: SelectProxyOptions): {
-        proxy: Group;
-        sources: InstancedChild[];
-    } | null;
-    /** 把代理网格的矩阵同步到各源实例最新的 matrixWorld（组旋转 / 实例移动时描边跟着动）。
-     *  代理网格与 sources 一一对应（顺序由 buildSelectProxy 保证）。 */
-    static syncSelectProxy(proxy: Group): void;
-    /** 设置实例颜色（自动置 needUpdate） */
-    setColor(c: Color | number | string): this;
-    /**
-     * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
-     * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch
-     * 迁移到新动画 batch（两 batch 常驻、不销毁）。传 null 恢复为 static animation。
-     * 例：soldier.playClip("Walk") / soldier.playClip("Idle")
-     */
-    playClip(name: string | null): this;
-    /** 供 InstancedBatch 每帧读取当前请求的动画剪辑 */
-    get pendingClip(): string | null;
-    /**
-     * 位置 / 缩放 / 旋转直接用 three 原生写法即可（position.set / scale.setScalar / rotation.set），
-     * 无需任何自定义 setter；任一变换变化都会由 InstancedGroup 每帧的 matrixWorld 比对自动置 needUpdate。
-     * 注：Vector3 在 three 0.167 没有 onChange 回调；Euler/Quaternion 虽有 onChange，但 three 内部已用它
-     * 同步 rotation↔quaternion，不能覆盖，故统一用 matrixWorld 比对兜底，最贴合 three 的变换检测机制。
-     */
-    /** 设置鼠标手势（悬停时光标样式）：pointer / grab / move / text / crosshair ... */
-    setCursor(c: string): this;
-    /** 由 InstancedGroup 每帧调用：世界矩阵变化则置 needUpdate（setPosition 等已置过，这里双保险） */
-    markDirtyIfWorldChanged(): void;
-    /** 从注册表移除（对象销毁时调用，避免内存泄漏） */
-    dispose(): void;
-    /**
-     * 声明本实例归属哪个 InstancedGroup（owner tag）。多组共存时用于隔离，
-     * 只有 owner 相同的 InstancedGroup 会收集本实例。
-     *
-     * 用法：`new Cube().setOwner("preview")`，配合 `new InstancedGroup("preview")`。
-     * 不调用则归属为空 —— 会被「未声明 owner 的组」（如 ThreeBase 默认组）收集，保持旧行为。
-     */
-    setOwner(tag: string): this;
-    /** 读取本实例的归属 tag（未声明返回 undefined） */
-    getOwner(): string | undefined;
-}
+import { BufferGeometry, Color, Group, Material, Object3D } from "three";
+import type { InstancedTemplate } from "./InstancedTemplate";
+/** 选择代理可叠加的后处理效果开关；默认只开描边（保持向后兼容），可被 glow / bloom / cover 任意叠加。 */
+export interface SelectProxyOptions {
+    stroke?: boolean;
+    glow?: boolean;
+    bloom?: boolean;
+    cover?: boolean;
+    /** 描边粗细（像素级，越大越粗）；不传则沿用 stroke_pass 默认 1 */
+    stroke_width?: number;
+    stroke_color?: string;
+    glow_color?: string;
+    glow_width?: number;
+    glow_opacity?: number;
+    bloom_strength?: number;
+    bloom_radius?: number;
+    cover_color?: string;
+    cover_opacity?: number;
+}
+/**
+ * 所有活着的 InstancedChild 实例集合，供 InstancedGroup 每帧收集。
+ * 用全局注册表而非遍历整棵 scene，避免大场景每帧 traverse 全树的性能开销。
+ *
+ * ⚠️ 多 InstancedGroup 共存时的归属（owner）：见 `instancedChildOwner` 与 `getOwner()`。
+ * 同一个进程里可能并存多个 InstancedGroup（如主编辑器的 ThreeBase 与预览弹窗各自一套），
+ * 若不隔离，双方会互相把对方的实例收进自己的 batch，导致「A 场景的立方体出现在 B 场景」。
+ */
+export declare const instancedChildRegistry: Set<InstancedChild>;
+/**
+ * 实例归属（owner tag）注册表：child -> owner 字符串。
+ * InstancedGroup 构造时可声明自己的 owner，每帧只收集 `owner` 匹配（或未声明 owner）的实例。
+ * 未在表中登记的实例视为「无归属」，会被**声明了 owner 的组**忽略、
+ * 被**未声明 owner 的组**（如 ThreeBase 的默认组）收集 —— 保持对既有代码零影响。
+ */
+export declare const instancedChildOwner: Map<InstancedChild, string>;
+/**
+ * 用户继承的「逻辑实例」基类。自身不参与渲染，只描述"一个实例"的位置 / 颜色 / 事件。
+ *
+ * 用法：
+ * ```ts
+ * class Cube extends InstancedChild {
+ *   static geometry = new BoxGeometry(1, 1, 1);
+ *   static material = new MeshStandardMaterial({ color: 0xffffff });
+ *   constructor() {
+ *     super();
+ *     this.addEventListener("click", () => {
+ *       this.setColor("#ff0000");
+ *       this.position.set(0, 0, 0);
+ *     });
+ *   }
+ * }
+ * const cube = new Cube();
+ * cube.position.set(1, 2, 3);
+ * threeBase.scene.add(cube); // 加进任意层级即可
+ * ```
+ *
+ * ThreeBase 里固定的 InstancedGroup 会自动把「同 geometry+material」（或「同 instanceUrl+animation」）
+ * 的 InstancedChild 合并进同一个 InstancedMesh 批量渲染，无需用户管理实例缓冲。
+ */
+export default class InstancedChild extends Object3D {
+    /** 内置几何模式：子类覆盖这两个静态字段 */
+    static geometry?: BufferGeometry;
+    /** 内置几何模式材质 */
+    static material?: Material;
+    /** GLB 模式：模型地址（与 geometry/material 互斥，优先于内置） */
+    static instanceUrl?: string;
+    /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
+    static animation?: string;
+    /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
+    static prepareTemplate?: (template: InstancedTemplate) => void;
+    /** 实例颜色，写入 InstancedMesh.instanceColor */
+    color: Color;
+    /**
+     * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
+     * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
+     */
+    needUpdate: boolean;
+    /** 模板是否就绪（GLB 异步加载完成后置 true） */
+    templateReady: boolean;
+    /**
+     * 第一人称碰撞检测标记：为 true 时，本实例所属 batch 的 InstancedMesh 会被打上
+     * `userData.fpsCollision = true`，从而被 FPScontrol 的碰撞射线命中（实例自身的世界矩阵即碰撞体位置）。
+     * 需配合 three-base 的 FPScontrol 使用（详见 FPSDemo 示例页）。
+     *
+     * ⚠️ 语义约束：真实几何合并在同一个 InstancedMesh 里，故碰撞以「整个 batch
+     * （相同 geometry+material / 相同 instanceUrl+animation 的所有实例）」为单位开关——
+     * 同一 batch 内的所有实例要么都参与碰撞、要么都不参与。若只想让部分实例参与碰撞，
+     * 请把它们拆成不同的 InstancedChild 子类（不同 geometry 或不同 batchKey）。
+     */
+    fpsCollision: boolean;
+    /**
+     * 自动脏检测开关（实验用，默认开）：
+     * - true：markDirtyIfWorldChanged 每帧比对 matrixWorld，变化则自动置 needUpdate（位置/旋转/缩放变化无需手动置位）；
+     * - false：关闭自动检测，仅手动置 needUpdate（如 setColor）的实例才会写回实例缓冲。
+     * 关闭后，静态布置的实例渲染不变，但「运动」（旋转/移动/缩放）将不再反映到画面（因为 matrixWorld 变了却没写回）。
+     * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
+     */
+    static AUTO_MARK_DIRTY: boolean;
+    /**
+     * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
+     * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
+     * 默认 null 表示不主动切换，沿用 batch 构造时的 static animation。
+     */
+    private _pendingClip;
+    private _cachedWorld;
+    constructor(fpsCollision?: boolean);
+    /** 该实例归属哪个 batch 的 key：相同 geometry+material 或相同 instanceUrl+当前生效动画 合并为一类。
+     *  因 key 含「当前生效动画」，切换动画 = 实例在「glb+旧动画」与「glb+新动画」两个常驻 batch 间迁移，而非 batch 内切 mixer。 */
+    getBatchKey(): string;
+    /** 本实例当前生效的动画名：优先 playClip 请求，否则类声明的 static animation；用于分桶 key 与 batch mixer 构建 */
+    getEffectiveAnimation(): string | undefined;
+    /**
+     * 为一组 InstancedChild 构建"选择代理"（select proxy）：
+     * 用每个实例的世界矩阵 matrixWorld + 同款 geometry/material 重建独立网格，
+     * 供 stroke_pass 单独渲染其深度 / 灰度，从而得到这组实例"专属"的描边。
+     *
+     * 为什么需要它：InstancedChild 是纯逻辑节点（无几何），真实几何在 InstancedGroup 合并出的
+     * InstancedMesh 里，且一个 InstancedMesh 通常包含很多实例。要单独描边"某一个 / 某一组"实例，
+     * 无法靠直接渲染该 InstancedChild（空）或整个 InstancedMesh（会描到所有实例）。
+     * 本方法把目标实例重新"画"成一份独立几何，就能像普通 Mesh 一样单独取深度、单独描边。
+     *
+     * 关键点：
+     * - 用 instance.matrixWorld 直接作为代理网格的 local matrix（代理本身不在 scene 内、无父变换），
+     *   因此代理在屏幕上的位置 / 深度与真实实例严格一致，描边轮廓正好贴合，且能被同一张 baseDepthTexture 正确遮挡；
+     * - 代理对象通常注册到 ThreeBase.addStrokeObject（不在 scene 内），由渲染管线在效果阶段描边，
+     *   不会被正常 base pass 重复绘制。
+     *
+     * 仅支持内置几何模式（static geometry + static material）；GLB 模式的几何由 batch 解析，
+     * 需从对应 InstancedBatch 取几何，此处暂跳过（无 static geometry 的实例不进代理）。
+     *
+     * @param children 要描边的一组实例（如某个 Group 的全部 InstancedChild）
+     * @returns 代理 Group（含顺序与 children 一一对应的代理网格）；若没有任何可重建的实例则返回 null
+     */
+    static buildSelectProxy(children: InstancedChild[], options?: SelectProxyOptions): {
+        proxy: Group;
+        sources: InstancedChild[];
+    } | null;
+    /** 把代理网格的矩阵同步到各源实例最新的 matrixWorld（组旋转 / 实例移动时描边跟着动）。
+     *  代理网格与 sources 一一对应（顺序由 buildSelectProxy 保证）。 */
+    static syncSelectProxy(proxy: Group): void;
+    /** 设置实例颜色（自动置 needUpdate） */
+    setColor(c: Color | number | string): this;
+    /**
+     * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
+     * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch
+     * 迁移到新动画 batch（两 batch 常驻、不销毁）。传 null 恢复为 static animation。
+     * 例：soldier.playClip("Walk") / soldier.playClip("Idle")
+     */
+    playClip(name: string | null): this;
+    /** 供 InstancedBatch 每帧读取当前请求的动画剪辑 */
+    get pendingClip(): string | null;
+    /**
+     * 位置 / 缩放 / 旋转直接用 three 原生写法即可（position.set / scale.setScalar / rotation.set），
+     * 无需任何自定义 setter；任一变换变化都会由 InstancedGroup 每帧的 matrixWorld 比对自动置 needUpdate。
+     * 注：Vector3 在 three 0.167 没有 onChange 回调；Euler/Quaternion 虽有 onChange，但 three 内部已用它
+     * 同步 rotation↔quaternion，不能覆盖，故统一用 matrixWorld 比对兜底，最贴合 three 的变换检测机制。
+     */
+    /** 设置鼠标手势（悬停时光标样式）：pointer / grab / move / text / crosshair ... */
+    setCursor(c: string): this;
+    /** 由 InstancedGroup 每帧调用：世界矩阵变化则置 needUpdate（setPosition 等已置过，这里双保险） */
+    markDirtyIfWorldChanged(): void;
+    /** 从注册表移除（对象销毁时调用，避免内存泄漏） */
+    dispose(): void;
+    /**
+     * 声明本实例归属哪个 InstancedGroup（owner tag）。多组共存时用于隔离，
+     * 只有 owner 相同的 InstancedGroup 会收集本实例。
+     *
+     * 用法：`new Cube().setOwner("preview")`，配合 `new InstancedGroup("preview")`。
+     * 不调用则归属为空 —— 会被「未声明 owner 的组」（如 ThreeBase 默认组）收集，保持旧行为。
+     */
+    setOwner(tag: string): this;
+    /** 读取本实例的归属 tag（未声明返回 undefined） */
+    getOwner(): string | undefined;
+}