three-base 2.0.142 → 2.0.166

package/instanced/InstancedChild.js

@@ -1,264 +1,264 @@
-import { Color, Group, Matrix4, Mesh, Object3D, } from "three";
-/**
- * 所有活着的 InstancedChild 实例集合，供 InstancedGroup 每帧收集。
- * 用全局注册表而非遍历整棵 scene，避免大场景每帧 traverse 全树的性能开销。
- *
- * ⚠️ 多 InstancedGroup 共存时的归属（owner）：见 `instancedChildOwner` 与 `getOwner()`。
- * 同一个进程里可能并存多个 InstancedGroup（如主编辑器的 ThreeBase 与预览弹窗各自一套），
- * 若不隔离，双方会互相把对方的实例收进自己的 batch，导致「A 场景的立方体出现在 B 场景」。
- */
-export const instancedChildRegistry = new Set();
-/**
- * 实例归属（owner tag）注册表：child -> owner 字符串。
- * InstancedGroup 构造时可声明自己的 owner，每帧只收集 `owner` 匹配（或未声明 owner）的实例。
- * 未在表中登记的实例视为「无归属」，会被**声明了 owner 的组**忽略、
- * 被**未声明 owner 的组**（如 ThreeBase 的默认组）收集 —— 保持对既有代码零影响。
- */
-export const instancedChildOwner = new Map();
-/**
- * 用户继承的「逻辑实例」基类。自身不参与渲染，只描述"一个实例"的位置 / 颜色 / 事件。
- *
- * 用法：
- * ```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;
-    /** 内置几何模式材质 */
-    static material;
-    /** GLB 模式：模型地址（与 geometry/material 互斥，优先于内置） */
-    static instanceUrl;
-    /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
-    static animation;
-    /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
-    static prepareTemplate;
-    /** 实例颜色，写入 InstancedMesh.instanceColor */
-    color = new Color(0xffffff);
-    /**
-     * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
-     * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
-     */
-    needUpdate = false;
-    /** 模板是否就绪（GLB 异步加载完成后置 true） */
-    templateReady = false;
-    /**
-     * 第一人称碰撞检测标记：为 true 时，本实例所属 batch 的 InstancedMesh 会被打上
-     * `userData.fpsCollision = true`，从而被 FPScontrol 的碰撞射线命中（实例自身的世界矩阵即碰撞体位置）。
-     * 需配合 three-base 的 FPScontrol 使用（详见 FPSDemo 示例页）。
-     *
-     * ⚠️ 语义约束：真实几何合并在同一个 InstancedMesh 里，故碰撞以「整个 batch
-     * （相同 geometry+material / 相同 instanceUrl+animation 的所有实例）」为单位开关——
-     * 同一 batch 内的所有实例要么都参与碰撞、要么都不参与。若只想让部分实例参与碰撞，
-     * 请把它们拆成不同的 InstancedChild 子类（不同 geometry 或不同 batchKey）。
-     */
-    fpsCollision = false;
-    /**
-     * 自动脏检测开关（实验用，默认开）：
-     * - true：markDirtyIfWorldChanged 每帧比对 matrixWorld，变化则自动置 needUpdate（位置/旋转/缩放变化无需手动置位）；
-     * - false：关闭自动检测，仅手动置 needUpdate（如 setColor）的实例才会写回实例缓冲。
-     * 关闭后，静态布置的实例渲染不变，但「运动」（旋转/移动/缩放）将不再反映到画面（因为 matrixWorld 变了却没写回）。
-     * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
-     */
-    static AUTO_MARK_DIRTY = true;
-    /**
-     * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
-     * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
-     * 默认 null 表示不主动切换，沿用 batch 构造时的 static animation。
-     */
-    _pendingClip = null;
-    _cachedWorld = new Matrix4();
-    constructor(fpsCollision = false) {
-        super();
-        this.fpsCollision = fpsCollision;
-        // 标记：逻辑实例节点，ThreeMouse 收集候选时跳过（不渲染、无几何，靠 InstancedMesh 命中后路由回来）
-        this.userData.__instancedChild = true;
-        instancedChildRegistry.add(this);
-    }
-    /** 该实例归属哪个 batch 的 key：相同 geometry+material 或相同 instanceUrl+当前生效动画 合并为一类。
-     *  因 key 含「当前生效动画」，切换动画 = 实例在「glb+旧动画」与「glb+新动画」两个常驻 batch 间迁移，而非 batch 内切 mixer。 */
-    getBatchKey() {
-        const ctor = this.constructor;
-        if (ctor.instanceUrl) {
-            const anim = this.getEffectiveAnimation() || "__none__";
-            return `url:${ctor.instanceUrl}:anim:${anim}`;
-        }
-        const g = ctor.geometry;
-        const m = ctor.material;
-        if (g && m) {
-            return `geo:${g.uuid}/${m.uuid}`;
-        }
-        console.warn("[InstancedChild] 子类必须定义 static geometry + static material，或 static instanceUrl（可选 static animation）");
-        return `unknown:${(Math.random() * 1e9) | 0}`;
-    }
-    /** 本实例当前生效的动画名：优先 playClip 请求，否则类声明的 static animation；用于分桶 key 与 batch mixer 构建 */
-    getEffectiveAnimation() {
-        return this._pendingClip ?? this.constructor.animation;
-    }
-    /**
-     * 为一组 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, options = {}) {
-        const { stroke = true, glow = false, bloom = false, cover = false, stroke_width, stroke_color = "#ff8800", glow_color = "#ff8800", glow_width = 6, glow_opacity = 1, bloom_strength = 1.2, bloom_radius = 10, cover_color = "#ff8800", cover_opacity = 0.4, } = options;
-        const proxy = new Group();
-        const sources = [];
-        for (const child of children) {
-            const ctor = child.constructor;
-            const geometry = ctor.geometry;
-            const material = ctor.material;
-            if (!geometry || !material) {
-                continue; // GLB 模式：无 static geometry，跳过（待扩展）
-            }
-            const mesh = new Mesh(geometry, material);
-            // 代理不在 scene 树内 → 用 matrixWorld 作为 local matrix，render 时世界矩阵即等于实例世界矩阵
-            mesh.matrixAutoUpdate = false;
-            mesh.matrix.copy(child.matrixWorld);
-            proxy.add(mesh);
-            sources.push(child);
-        }
-        if (sources.length === 0) {
-            return null;
-        }
-        // 各后处理 pass 都读 object3d.userData 的对应开关（默认 false 直接 return），
-        // 代理只需在 userData 上打开需要的开关即可被效果阶段单独处理。开关逐一设置，互不耦合，
-        // 因此一个选择代理可以同时描边 + 辉光 + 泛光 + 覆盖色，或只开其中任意几个。
-        if (stroke) {
-            proxy.userData.stroke_enable = true;
-            proxy.userData.stroke_color = stroke_color;
-            // 仅当显式传入时才覆盖默认描边粗细，避免影响其他未传此参数的调用方
-            if (stroke_width !== undefined) {
-                proxy.userData.stroke_width = stroke_width;
-            }
-        }
-        if (glow) {
-            proxy.userData.glow_enable = true;
-            proxy.userData.glow_color = glow_color;
-            proxy.userData.glow_width = glow_width;
-            proxy.userData.glow_opacity = glow_opacity;
-        }
-        if (bloom) {
-            proxy.userData.bloom_enable = true;
-            proxy.userData.bloom_strength = bloom_strength;
-            proxy.userData.bloom_radius = bloom_radius;
-        }
-        if (cover) {
-            proxy.userData.cover_enable = true;
-            proxy.userData.cover_color = cover_color;
-            proxy.userData.cover_opacity = cover_opacity;
-        }
-        // 记录源实例顺序，便于每帧把代理矩阵同步到实例最新 matrixWorld（组旋转 / 实例移动时描边跟着动）
-        proxy.userData.__selectSources = sources;
-        return { proxy, sources };
-    }
-    /** 把代理网格的矩阵同步到各源实例最新的 matrixWorld（组旋转 / 实例移动时描边跟着动）。
-     *  代理网格与 sources 一一对应（顺序由 buildSelectProxy 保证）。 */
-    static syncSelectProxy(proxy) {
-        const sources = proxy.userData.__selectSources;
-        if (!sources) {
-            return;
-        }
-        for (let i = 0; i < proxy.children.length; i++) {
-            const src = sources[i];
-            const mesh = proxy.children[i];
-            if (src && mesh) {
-                mesh.matrix.copy(src.matrixWorld);
-            }
-        }
-    }
-    /** 设置实例颜色（自动置 needUpdate） */
-    setColor(c) {
-        this.color.set(c);
-        this.needUpdate = true;
-        return this;
-    }
-    /**
-     * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
-     * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch
-     * 迁移到新动画 batch（两 batch 常驻、不销毁）。传 null 恢复为 static animation。
-     * 例：soldier.playClip("Walk") / soldier.playClip("Idle")
-     */
-    playClip(name) {
-        this._pendingClip = name;
-        return this;
-    }
-    /** 供 InstancedBatch 每帧读取当前请求的动画剪辑 */
-    get pendingClip() {
-        return this._pendingClip;
-    }
-    /**
-     * 位置 / 缩放 / 旋转直接用 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) {
-        this.userData.cursor = c;
-        return this;
-    }
-    /** 由 InstancedGroup 每帧调用：世界矩阵变化则置 needUpdate（setPosition 等已置过，这里双保险） */
-    markDirtyIfWorldChanged() {
-        if (!InstancedChild.AUTO_MARK_DIRTY)
-            return; // 实验开关：关闭后不做自动脏检测
-        if (!this.matrixWorld.equals(this._cachedWorld)) {
-            this.needUpdate = true;
-            this._cachedWorld.copy(this.matrixWorld);
-        }
-    }
-    /** 从注册表移除（对象销毁时调用，避免内存泄漏） */
-    dispose() {
-        instancedChildRegistry.delete(this);
-        instancedChildOwner.delete(this);
-    }
-    /**
-     * 声明本实例归属哪个 InstancedGroup（owner tag）。多组共存时用于隔离，
-     * 只有 owner 相同的 InstancedGroup 会收集本实例。
-     *
-     * 用法：`new Cube().setOwner("preview")`，配合 `new InstancedGroup("preview")`。
-     * 不调用则归属为空 —— 会被「未声明 owner 的组」（如 ThreeBase 默认组）收集，保持旧行为。
-     */
-    setOwner(tag) {
-        instancedChildOwner.set(this, tag);
-        return this;
-    }
-    /** 读取本实例的归属 tag（未声明返回 undefined） */
-    getOwner() {
-        return instancedChildOwner.get(this);
-    }
-}
+import { Color, Group, Matrix4, Mesh, Object3D, } from "three";
+/**
+ * 所有活着的 InstancedChild 实例集合，供 InstancedGroup 每帧收集。
+ * 用全局注册表而非遍历整棵 scene，避免大场景每帧 traverse 全树的性能开销。
+ *
+ * ⚠️ 多 InstancedGroup 共存时的归属（owner）：见 `instancedChildOwner` 与 `getOwner()`。
+ * 同一个进程里可能并存多个 InstancedGroup（如主编辑器的 ThreeBase 与预览弹窗各自一套），
+ * 若不隔离，双方会互相把对方的实例收进自己的 batch，导致「A 场景的立方体出现在 B 场景」。
+ */
+export const instancedChildRegistry = new Set();
+/**
+ * 实例归属（owner tag）注册表：child -> owner 字符串。
+ * InstancedGroup 构造时可声明自己的 owner，每帧只收集 `owner` 匹配（或未声明 owner）的实例。
+ * 未在表中登记的实例视为「无归属」，会被**声明了 owner 的组**忽略、
+ * 被**未声明 owner 的组**（如 ThreeBase 的默认组）收集 —— 保持对既有代码零影响。
+ */
+export const instancedChildOwner = new Map();
+/**
+ * 用户继承的「逻辑实例」基类。自身不参与渲染，只描述"一个实例"的位置 / 颜色 / 事件。
+ *
+ * 用法：
+ * ```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;
+    /** 内置几何模式材质 */
+    static material;
+    /** GLB 模式：模型地址（与 geometry/material 互斥，优先于内置） */
+    static instanceUrl;
+    /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
+    static animation;
+    /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
+    static prepareTemplate;
+    /** 实例颜色，写入 InstancedMesh.instanceColor */
+    color = new Color(0xffffff);
+    /**
+     * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
+     * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
+     */
+    needUpdate = false;
+    /** 模板是否就绪（GLB 异步加载完成后置 true） */
+    templateReady = false;
+    /**
+     * 第一人称碰撞检测标记：为 true 时，本实例所属 batch 的 InstancedMesh 会被打上
+     * `userData.fpsCollision = true`，从而被 FPScontrol 的碰撞射线命中（实例自身的世界矩阵即碰撞体位置）。
+     * 需配合 three-base 的 FPScontrol 使用（详见 FPSDemo 示例页）。
+     *
+     * ⚠️ 语义约束：真实几何合并在同一个 InstancedMesh 里，故碰撞以「整个 batch
+     * （相同 geometry+material / 相同 instanceUrl+animation 的所有实例）」为单位开关——
+     * 同一 batch 内的所有实例要么都参与碰撞、要么都不参与。若只想让部分实例参与碰撞，
+     * 请把它们拆成不同的 InstancedChild 子类（不同 geometry 或不同 batchKey）。
+     */
+    fpsCollision = false;
+    /**
+     * 自动脏检测开关（实验用，默认开）：
+     * - true：markDirtyIfWorldChanged 每帧比对 matrixWorld，变化则自动置 needUpdate（位置/旋转/缩放变化无需手动置位）；
+     * - false：关闭自动检测，仅手动置 needUpdate（如 setColor）的实例才会写回实例缓冲。
+     * 关闭后，静态布置的实例渲染不变，但「运动」（旋转/移动/缩放）将不再反映到画面（因为 matrixWorld 变了却没写回）。
+     * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
+     */
+    static AUTO_MARK_DIRTY = true;
+    /**
+     * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
+     * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
+     * 默认 null 表示不主动切换，沿用 batch 构造时的 static animation。
+     */
+    _pendingClip = null;
+    _cachedWorld = new Matrix4();
+    constructor(fpsCollision = false) {
+        super();
+        this.fpsCollision = fpsCollision;
+        // 标记：逻辑实例节点，ThreeMouse 收集候选时跳过（不渲染、无几何，靠 InstancedMesh 命中后路由回来）
+        this.userData.__instancedChild = true;
+        instancedChildRegistry.add(this);
+    }
+    /** 该实例归属哪个 batch 的 key：相同 geometry+material 或相同 instanceUrl+当前生效动画 合并为一类。
+     *  因 key 含「当前生效动画」，切换动画 = 实例在「glb+旧动画」与「glb+新动画」两个常驻 batch 间迁移，而非 batch 内切 mixer。 */
+    getBatchKey() {
+        const ctor = this.constructor;
+        if (ctor.instanceUrl) {
+            const anim = this.getEffectiveAnimation() || "__none__";
+            return `url:${ctor.instanceUrl}:anim:${anim}`;
+        }
+        const g = ctor.geometry;
+        const m = ctor.material;
+        if (g && m) {
+            return `geo:${g.uuid}/${m.uuid}`;
+        }
+        console.warn("[InstancedChild] 子类必须定义 static geometry + static material，或 static instanceUrl（可选 static animation）");
+        return `unknown:${(Math.random() * 1e9) | 0}`;
+    }
+    /** 本实例当前生效的动画名：优先 playClip 请求，否则类声明的 static animation；用于分桶 key 与 batch mixer 构建 */
+    getEffectiveAnimation() {
+        return this._pendingClip ?? this.constructor.animation;
+    }
+    /**
+     * 为一组 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, options = {}) {
+        const { stroke = true, glow = false, bloom = false, cover = false, stroke_width, stroke_color = "#ff8800", glow_color = "#ff8800", glow_width = 6, glow_opacity = 1, bloom_strength = 1.2, bloom_radius = 10, cover_color = "#ff8800", cover_opacity = 0.4, } = options;
+        const proxy = new Group();
+        const sources = [];
+        for (const child of children) {
+            const ctor = child.constructor;
+            const geometry = ctor.geometry;
+            const material = ctor.material;
+            if (!geometry || !material) {
+                continue; // GLB 模式：无 static geometry，跳过（待扩展）
+            }
+            const mesh = new Mesh(geometry, material);
+            // 代理不在 scene 树内 → 用 matrixWorld 作为 local matrix，render 时世界矩阵即等于实例世界矩阵
+            mesh.matrixAutoUpdate = false;
+            mesh.matrix.copy(child.matrixWorld);
+            proxy.add(mesh);
+            sources.push(child);
+        }
+        if (sources.length === 0) {
+            return null;
+        }
+        // 各后处理 pass 都读 object3d.userData 的对应开关（默认 false 直接 return），
+        // 代理只需在 userData 上打开需要的开关即可被效果阶段单独处理。开关逐一设置，互不耦合，
+        // 因此一个选择代理可以同时描边 + 辉光 + 泛光 + 覆盖色，或只开其中任意几个。
+        if (stroke) {
+            proxy.userData.stroke_enable = true;
+            proxy.userData.stroke_color = stroke_color;
+            // 仅当显式传入时才覆盖默认描边粗细，避免影响其他未传此参数的调用方
+            if (stroke_width !== undefined) {
+                proxy.userData.stroke_width = stroke_width;
+            }
+        }
+        if (glow) {
+            proxy.userData.glow_enable = true;
+            proxy.userData.glow_color = glow_color;
+            proxy.userData.glow_width = glow_width;
+            proxy.userData.glow_opacity = glow_opacity;
+        }
+        if (bloom) {
+            proxy.userData.bloom_enable = true;
+            proxy.userData.bloom_strength = bloom_strength;
+            proxy.userData.bloom_radius = bloom_radius;
+        }
+        if (cover) {
+            proxy.userData.cover_enable = true;
+            proxy.userData.cover_color = cover_color;
+            proxy.userData.cover_opacity = cover_opacity;
+        }
+        // 记录源实例顺序，便于每帧把代理矩阵同步到实例最新 matrixWorld（组旋转 / 实例移动时描边跟着动）
+        proxy.userData.__selectSources = sources;
+        return { proxy, sources };
+    }
+    /** 把代理网格的矩阵同步到各源实例最新的 matrixWorld（组旋转 / 实例移动时描边跟着动）。
+     *  代理网格与 sources 一一对应（顺序由 buildSelectProxy 保证）。 */
+    static syncSelectProxy(proxy) {
+        const sources = proxy.userData.__selectSources;
+        if (!sources) {
+            return;
+        }
+        for (let i = 0; i < proxy.children.length; i++) {
+            const src = sources[i];
+            const mesh = proxy.children[i];
+            if (src && mesh) {
+                mesh.matrix.copy(src.matrixWorld);
+            }
+        }
+    }
+    /** 设置实例颜色（自动置 needUpdate） */
+    setColor(c) {
+        this.color.set(c);
+        this.needUpdate = true;
+        return this;
+    }
+    /**
+     * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
+     * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch
+     * 迁移到新动画 batch（两 batch 常驻、不销毁）。传 null 恢复为 static animation。
+     * 例：soldier.playClip("Walk") / soldier.playClip("Idle")
+     */
+    playClip(name) {
+        this._pendingClip = name;
+        return this;
+    }
+    /** 供 InstancedBatch 每帧读取当前请求的动画剪辑 */
+    get pendingClip() {
+        return this._pendingClip;
+    }
+    /**
+     * 位置 / 缩放 / 旋转直接用 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) {
+        this.userData.cursor = c;
+        return this;
+    }
+    /** 由 InstancedGroup 每帧调用：世界矩阵变化则置 needUpdate（setPosition 等已置过，这里双保险） */
+    markDirtyIfWorldChanged() {
+        if (!InstancedChild.AUTO_MARK_DIRTY)
+            return; // 实验开关：关闭后不做自动脏检测
+        if (!this.matrixWorld.equals(this._cachedWorld)) {
+            this.needUpdate = true;
+            this._cachedWorld.copy(this.matrixWorld);
+        }
+    }
+    /** 从注册表移除（对象销毁时调用，避免内存泄漏） */
+    dispose() {
+        instancedChildRegistry.delete(this);
+        instancedChildOwner.delete(this);
+    }
+    /**
+     * 声明本实例归属哪个 InstancedGroup（owner tag）。多组共存时用于隔离，
+     * 只有 owner 相同的 InstancedGroup 会收集本实例。
+     *
+     * 用法：`new Cube().setOwner("preview")`，配合 `new InstancedGroup("preview")`。
+     * 不调用则归属为空 —— 会被「未声明 owner 的组」（如 ThreeBase 默认组）收集，保持旧行为。
+     */
+    setOwner(tag) {
+        instancedChildOwner.set(this, tag);
+        return this;
+    }
+    /** 读取本实例的归属 tag（未声明返回 undefined） */
+    getOwner() {
+        return instancedChildOwner.get(this);
+    }
+}