three-base 2.0.134 → 2.0.142

package/instanced/InstancedMeshBase.ts

@@ -0,0 +1,292 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-02-05 09:31:57
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2025-06-25
+ */
+import { first, isString, throttle } from "lodash";
+import { Color, Event, Euler, InstancedBufferAttribute, InstancedMesh, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
+import MeshBase from "../MeshBase";
+import threeUtils from "../threeUtils";
+import threeLoader from "../threeLoader";
+import { DebouncedFuncLeading } from "lodash";
+import { dispatchCustomEvent, type InstancedMeshBaseEventMap } from "../EventMap";
+
+// 实例模型组对象
+export default class InstancedMeshBase extends MeshBase {
+    constructor(url?: string) {
+        super(url);
+    }
+    count: number = 0;
+    size: Vector3 = new Vector3(1, 1, 1);
+    meshCollect: Record<string, Mesh[]> = {};
+    instanceCollect: Record<string, InstancedMesh> = {};
+    colorMap: Map<String, Color> = new Map();
+    static _position: Vector3 = new Vector3();
+    static _scale: Vector3 = new Vector3(1, 1, 1);
+    static _rotation: Euler = new Euler();
+    static _Quaternion: Quaternion = new Quaternion();
+    static _matrix: Matrix4 = new Matrix4();
+    instanceMatrix: InstancedBufferAttribute = new InstancedBufferAttribute(new Float32Array(0 * 16), 16);
+    instanceColor: InstancedBufferAttribute = new InstancedBufferAttribute(new Float32Array(0 * 3), 3);
+    // 重置子元素
+    reset(...object: Object3D[]): this {
+        super.clear();
+        super.add(...object);
+        return this;
+    }
+    // 重构加载模型的方法
+    async loadModel(url: string | File | Array<File>, filename: string = ""): Promise<void> {
+        //获取模型文件的地址
+        const modelurl = await (async (): Promise<string> => {
+            if (isString(url)) {
+                return url;
+            }
+            else if (url instanceof File) {
+                return url.name;
+            }
+            else if (url instanceof Array) {
+                let modelurl = "";
+                const suffixs = [
+                    "zip",
+                    "obj",
+                    "glb",
+                    "gltf",
+                    "fbx",
+                    "dae",
+                    "stl",
+                    "usdz",
+                ];
+                for (let file of url) {
+                    if (suffixs.includes(threeUtils.getSuffix(file.name))) {
+                        modelurl = file.name;
+                    }
+                }
+                return modelurl;
+            }
+            return "";
+        })();
+        this.url = modelurl || "";
+        if (!url) {
+            return;
+        }
+        this.loaded = false;
+        // 没有模型并且没有加载任务时就去加载模型
+        if (!MeshBase.models.get(this.url) &&
+            !MeshBase.loadModeling.get(this.url)) {
+            MeshBase.loadModeling.set(this.url, true);
+            // 万能加载器
+            let modal = await threeLoader.loadModel(url, filename);
+            MeshBase.models.set(this.url, modal);
+            MeshBase.loadModeling.set(this.url, false);
+        }
+        // 如果模型还在加载中, 就等待模型加载完成
+        do {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        } while (MeshBase.loadModeling.get(this.url));
+        if (MeshBase.models.get(this.url)) {
+            const mesh = MeshBase.models.get(this.url)!;
+            // 兜底：与 MeshBase 一致，为缺失顶点法线的几何体补算法线，避免 AO 全黑与金属材质发黑
+            this.ensureNormals(mesh);
+            this.size.copy(threeUtils.getSize(mesh));
+            const { meshCollect, instanceCollect } = this;
+            mesh.updateMatrixWorld(true);
+            // collect all mesh counts
+            mesh.traverse((obj) => {
+                const mesh = obj as Mesh;
+                if (mesh.isMesh) {
+                    mesh.matrixWorld.decompose(mesh.position, mesh.quaternion, mesh.scale);
+                    mesh.rotation.setFromQuaternion(mesh.quaternion);
+                    mesh.updateMatrix();
+                    const materialUuid = mesh.material instanceof Array ? mesh.material[0].uuid : mesh.material.uuid;
+                    const uuid = mesh.geometry.uuid + "/" + materialUuid;
+                    if (meshCollect[uuid]) {
+                        meshCollect[uuid].push(mesh);
+                    }
+                    else {
+                        meshCollect[uuid] = [mesh];
+                    }
+                }
+                else {
+                    obj.position.set(0, 0, 0);
+                    obj.scale.set(1, 1, 1);
+                    obj.rotation.set(0, 0, 0);
+                }
+            });
+            this.clear();
+            // create all instances
+            Object.keys(meshCollect).forEach((uuid) => {
+                const meshes = meshCollect[uuid];
+                const mesh = meshes[0];
+                const instancedMesh = new InstancedMesh(mesh.geometry, mesh.material, meshes.length * this.count);
+                instancedMesh.name = mesh.name;
+                instancedMesh.frustumCulled = false;
+                instanceCollect[uuid] = instancedMesh;
+                this.add(instancedMesh);
+            });
+            // 加载完成事件
+            await new Promise((resolve) => setTimeout(resolve, 30));
+            this.loaded = true;
+            dispatchCustomEvent(this, { type: "loaded" });
+        }
+    }
+    // 更新包围盒
+    computeBoundingSphere: DebouncedFuncLeading<() => void> = throttle(() => {
+        for (const child of this.children) {
+            const instancedMesh = child as InstancedMesh;
+            instancedMesh.computeBoundingSphere && instancedMesh.computeBoundingSphere();
+        }
+    }, 1000);
+    //初始实例矩阵的数量
+    async setCount(count: number = 0): Promise<void> {
+        if (this.count === count) {
+            return;
+        }
+        await this.awaitLoaded();
+        const instanceMatrix = new InstancedBufferAttribute(new Float32Array(count * 16), 16);
+        const instanceColor = new InstancedBufferAttribute(new Float32Array(count * 3).fill(1), 3);
+        for (let i = 0; i < count; i++) {
+            instanceMatrix.set(InstancedMeshBase._matrix.identity().toArray(), i * 16);
+            instanceColor.set([1, 1, 1], i * 3);
+        }
+        for (let i = 0; i < this.count; i++) {
+            instanceMatrix.copyAt(i, this.instanceMatrix, i);
+            instanceColor.copyAt(i, this.instanceColor, i);
+        }
+        this.instanceMatrix = instanceMatrix;
+        this.instanceColor = instanceColor;
+        this.count = count;
+        for (const child of this.children) {
+            const instanceMesh = child as InstancedMesh;
+            const im = new InstancedBufferAttribute(new Float32Array(count * 16), 16);
+            const ic = new InstancedBufferAttribute(new Float32Array(count * 3).fill(1), 3);
+            for (let i = 0; i < count; i++) {
+                im.set(InstancedMeshBase._matrix.identity().toArray(), i * 16);
+                ic.set([1, 1, 1], i * 3);
+            }
+            for (let i = 0; i < instanceMesh.count; i++) {
+                im.copyAt(i, instanceMesh.instanceMatrix, i);
+                if (instanceMesh.instanceColor) {
+                    ic.copyAt(i, instanceMesh.instanceColor, i);
+                }
+            }
+            instanceMesh.instanceMatrix = im;
+            instanceMesh.instanceColor = ic;
+            instanceMesh.count = count;
+        }
+    }
+    // 设置矩阵
+    async setMatrixAt(index: number, matrix: Matrix4 = new Matrix4().identity()): Promise<void> {
+        const new_matrix = matrix.clone();
+        await this.awaitLoaded();
+        Object.keys(this.meshCollect).forEach((uuid) => {
+            const instancedMesh = this.instanceCollect[uuid];
+            const collect = this.meshCollect[uuid];
+            collect.forEach((mesh, i) => {
+                InstancedMeshBase._matrix.copy(mesh.matrix);
+                InstancedMeshBase._matrix.premultiply(new_matrix);
+                instancedMesh.setMatrixAt(collect.length * index + i, InstancedMeshBase._matrix);
+                instancedMesh.instanceMatrix.needsUpdate = true;
+            });
+        });
+        this.computeBoundingSphere();
+    }
+    //设置移动旋转缩放
+    async setTRS(index: number, { position, rotation, scale, }: {
+        position?: Vector3;
+        rotation?: Euler;
+        scale?: Vector3;
+    }): Promise<void> {
+        const new_position = position ? position.clone() : undefined;
+        const new_rotation = rotation ? rotation.clone() : undefined;
+        const new_scale = scale ? scale.clone() : undefined;
+        await this.awaitLoaded();
+        Object.keys(this.meshCollect).forEach((uuid) => {
+            const instancedMesh = this.instanceCollect[uuid];
+            const collect = this.meshCollect[uuid];
+            collect.forEach((mesh, i) => {
+                instancedMesh.getMatrixAt(collect.length * index + i, InstancedMeshBase._matrix);
+                InstancedMeshBase._matrix.premultiply(mesh.matrix.clone().invert());
+                InstancedMeshBase._matrix.decompose(InstancedMeshBase._position, InstancedMeshBase._Quaternion, InstancedMeshBase._scale);
+                InstancedMeshBase._rotation.setFromQuaternion(InstancedMeshBase._Quaternion);
+                new_position && InstancedMeshBase._position.copy(new_position);
+                new_rotation && InstancedMeshBase._rotation.copy(new_rotation);
+                new_scale && InstancedMeshBase._scale.copy(new_scale);
+                InstancedMeshBase._Quaternion.setFromEuler(InstancedMeshBase._rotation);
+                InstancedMeshBase._matrix.compose(InstancedMeshBase._position, InstancedMeshBase._Quaternion, InstancedMeshBase._scale);
+                InstancedMeshBase._matrix.premultiply(mesh.matrix);
+                instancedMesh.setMatrixAt(collect.length * index + i, InstancedMeshBase._matrix);
+                instancedMesh.instanceMatrix.needsUpdate = true;
+            });
+        });
+        this.computeBoundingSphere();
+    }
+    //获取指定位置的移动旋转缩放
+    async getTRS(index: number = 0): Promise<{
+        position: Vector3;
+        rotation: Euler;
+        scale: Vector3;
+    }> {
+        await this.awaitLoaded();
+        const position = new Vector3();
+        const rotation = new Euler();
+        const scale = new Vector3();
+        const uuid = first(Object.keys(this.instanceCollect));
+        const instancedMesh = this.instanceCollect[uuid!];
+        if (instancedMesh) {
+            instancedMesh.getMatrixAt(index, InstancedMeshBase._matrix);
+            InstancedMeshBase._matrix.decompose(position, InstancedMeshBase._Quaternion, scale);
+            rotation.setFromQuaternion(InstancedMeshBase._Quaternion);
+        }
+        return { position, rotation, scale };
+    }
+    // 设置颜色
+    async setColorAt(index: number, color: (instancedMesh: InstancedMesh) => Color | undefined): Promise<void> {
+        await this.awaitLoaded();
+        Object.keys(this.meshCollect).forEach((uuid) => {
+            const instancedMesh = this.instanceCollect[uuid];
+            const collect = this.meshCollect[uuid];
+            collect.forEach((mesh, i) => {
+                const c = color(instancedMesh);
+                if (c) {
+                    instancedMesh.setColorAt(collect.length * index + i, c);
+                    instancedMesh.instanceColor.needsUpdate = true;
+                }
+            });
+        });
+    }
+    // 获取颜色
+    async getColorAt(index: number = 0): Promise<Color> {
+        await this.awaitLoaded();
+        const color = new Color();
+        const uuid = first(Object.keys(this.instanceCollect));
+        const instancedMesh = this.instanceCollect[uuid!];
+        if (instancedMesh) {
+            instancedMesh.getColorAt(index, color);
+        }
+        return color;
+    }
+    // 同步属性
+    updateMatrixWorld(force?: boolean): void {
+        super.updateMatrixWorld(force);
+        const { cursor, enableEvent } = this.userData;
+        this.traverse((obj) => {
+            Object.assign(obj.userData, { cursor, enableEvent });
+        });
+    }
+    // 事件监听
+    async addEventListener<T extends string>(name: T, callback: (e: Event<T, this>) => void): Promise<void> {
+        super.addEventListener(name, callback);
+        await this.awaitLoaded();
+        for (const child of this.children) {
+            (child as InstancedMesh).addEventListener(name, callback as unknown as (e: Event<T, InstancedMesh>) => void);
+        }
+    }
+    // 取消事件的监听
+    removeEventListener<T extends string>(name: T, callback: (e: Event<T, this>) => void): void {
+        super.removeEventListener(name, callback);
+        for (const child of this.children) {
+            (child as InstancedMesh).removeEventListener(name, callback as unknown as (e: Event<T, InstancedMesh>) => void);
+        }
+    }
+}

package/instanced/InstancedTemplate.d.ts

@@ -0,0 +1,46 @@
+import { AnimationClip, BufferGeometry, Material, Matrix4, Object3D, Skeleton } from "three";
+import InstancedChild from "./InstancedChild";
+/** 一个 submesh 的描述：几何 + 材质 + 是否骨骼网格 */
+export interface InstancedSubmesh {
+    geometry: BufferGeometry;
+    material: Material;
+    skinned: boolean;
+    /** 非骨骼动画：拥有该几何的节点（取世界变换烘焙进几何） */
+    node?: Object3D;
+    /** 非骨骼动画：原始局部几何副本（每帧重新变换的源，避免累积误差） */
+    localGeometry?: BufferGeometry;
+    /**
+     * 该 submesh 在 GLB 场景图里的世界变换（加载时快照）。
+     * GLTF 常把模型整体包在一层带缩放/位移的根节点里（如 Soldier.glb 根节点 scale=0.01），
+     * 只克隆几何会丢掉这层变换导致模型大小/位置错乱。写实例矩阵时把它乘到 child.matrixWorld 上，
+     * 使实例化渲染与"把整棵 GLB 场景图加进场景"的效果一致（对齐 MeshBase 行为）。
+     */
+    nodeWorldMatrix?: Matrix4;
+}
+/**
+ * 模板：描述"一类实例"的渲染数据。
+ * - 内置几何：submeshes 含一份几何+材质；
+ * - GLB：submeshes 按 geometry/material uuid 分组（多 submesh），并可能带 skeleton/animations。
+ */
+export interface InstancedTemplate {
+    submeshes: InstancedSubmesh[];
+    skeleton?: Skeleton;
+    animations: AnimationClip[];
+    /** 含骨骼时：每帧把骨骼姿态烘焙进 sharedGeometry，所有实例复用（共享姿态） */
+    sharedGeometry?: BufferGeometry;
+    /**
+     * 含骨骼时：原始 bind-pose 几何（只读，永不修改）。
+     * bakeSkinning 必须每帧从这里读"绑定姿态顶点"，再写到 sharedGeometry，
+     * 绝不能原地读改写 sharedGeometry（否则上一帧的烘焙结果被当成 bind-pose 再烤一遍 → 蒙皮累积错位、越动越乱）。
+     */
+    sourceGeometry?: BufferGeometry;
+    /** 含骨骼时：动画驱动用根对象（含 skeleton 层级，不渲染，仅用于 mixer 更新骨骼） */
+    animRoot?: Object3D;
+    /** 含骨骼时：SkinnedMesh 的 bindMatrix / bindMatrixInverse，烘焙蒙皮用 */
+    bindMatrix?: Matrix4;
+    bindMatrixInverse?: Matrix4;
+}
+/**
+ * 解析某实例的模板：内置几何同步返回；GLB 异步加载并按 batchKey 缓存。
+ */
+export declare function loadTemplate(child: InstancedChild): Promise<InstancedTemplate>;

package/instanced/InstancedTemplate.js

@@ -0,0 +1,125 @@
+import { Matrix4, } from "three";
+import threeLoader from "../threeLoader";
+/** 按 batchKey 缓存模板加载 Promise，避免同一 GLB 重复加载 */
+const _templateCache = new Map();
+function uuidOf(geometry, material) {
+    return `${geometry.uuid}/${material.uuid}`;
+}
+/**
+ * 解析某实例的模板：内置几何同步返回；GLB 异步加载并按 batchKey 缓存。
+ */
+export function loadTemplate(child) {
+    const ctor = child.constructor;
+    // 内置几何：同步构造
+    if (ctor.geometry && ctor.material) {
+        return Promise.resolve({
+            submeshes: [
+                { geometry: ctor.geometry, material: ctor.material, skinned: false },
+            ],
+            animations: [],
+        });
+    }
+    // GLB：异步加载 + 按 batchKey 缓存
+    if (ctor.instanceUrl) {
+        const key = child.getBatchKey();
+        const cached = _templateCache.get(key);
+        if (cached) {
+            return cached;
+        }
+        const p = resolveGLB(ctor.instanceUrl);
+        _templateCache.set(key, p);
+        return p;
+    }
+    return Promise.reject(new Error("[loadTemplate] 子类未定义 geometry+material 或 instanceUrl"));
+}
+/** 加载 GLB 并按 geometry/material 分组，提取首个 skeleton 与动画剪辑 */
+function resolveGLB(url) {
+    return threeLoader.loadModel(url).then((root) => {
+        if (!root) {
+            throw new Error(`[resolveGLB] 加载失败: ${url}`);
+        }
+        // 确保场景图世界矩阵已就绪，下面快照每个 submesh 的 nodeWorldMatrix 才准确
+        root.updateMatrixWorld(true);
+        const geometryMap = new Map();
+        let skeleton;
+        let firstSkinned;
+        let animations = [];
+        root.traverse((obj) => {
+            const mesh = obj;
+            const isMesh = mesh.isMesh === true;
+            if (!isMesh) {
+                return;
+            }
+            const geom = mesh.geometry;
+            const rawMat = mesh.material;
+            const mat = Array.isArray(rawMat) ? rawMat[0] : rawMat;
+            const skinned = mesh.isSkinnedMesh === true;
+            const key = uuidOf(geom, mat);
+            if (!geometryMap.has(key)) {
+                geometryMap.set(key, {
+                    geometry: geom,
+                    material: mat,
+                    skinned,
+                    node: mesh,
+                    // nodeWorldMatrix 先留空，下方按 骨骼/节点动画 类型统一确定
+                });
+            }
+            if (skinned && !firstSkinned) {
+                firstSkinned = mesh;
+                skeleton = mesh.skeleton;
+            }
+        });
+        // GLTF 加载器把 animations 挂在 scene 上（threeLoader 已 res.scene.animations = res.animations）
+        const rootAnims = root.animations;
+        if (rootAnims && rootAnims.length) {
+            animations = rootAnims;
+        }
+        const template = {
+            submeshes: Array.from(geometryMap.values()),
+            skeleton,
+            animations,
+        };
+        // 含骨骼：保留原始 bind-pose 几何（sourceGeometry，只读） + 一份渲染用几何（sharedGeometry，每帧被烘焙覆盖）。
+        // 二者必须分开：bakeSkinning 从 sourceGeometry 读、写 sharedGeometry，避免原地累积烘焙导致动画越动越乱。
+        if (firstSkinned && skeleton) {
+            const src = firstSkinned.geometry;
+            template.sourceGeometry = src;
+            template.sharedGeometry = src.clone();
+            template.animRoot = root;
+            template.bindMatrix = firstSkinned.bindMatrix;
+            template.bindMatrixInverse = firstSkinned.bindMatrixInverse;
+        }
+        // 非骨骼动画（节点变换动画，如 point1.glb）：克隆几何，每帧把节点相对根的世界变换烘焙进几何。
+        // 与骨骼 LBS 同理 —— 把"节点层级动画"降级为每帧 CPU 几何变换，所有实例复用一份变换后的几何，
+        // 天然兼容项目所有材质与后处理。
+        if (!skeleton && animations.length > 0) {
+            template.animRoot = root;
+            for (const sub of template.submeshes) {
+                sub.localGeometry = sub.geometry.clone();
+                sub.geometry = sub.geometry.clone();
+            }
+        }
+        // 统一确定每个 submesh 的 nodeWorldMatrix：
+        // - 骨骼 / 静态：用 submesh 节点(mesh) 自身的完整世界变换（含祖先）。
+        //   bakeSkinning 输出在 skinned mesh 局部空间、静态几何即 GLTF 原始局部空间，都需完整世界变换才能落到位；
+        //   Soldier.glb 根节点 scale=0.01 这类"整模型套一层缩放根"的情形，靠这里补回
+        //   （对齐 MeshBase 把整棵 GLB 场景图加进场景的行为）。
+        // - 非骨骼节点动画（如 point1.glb）：bakeNodeTransform 已把"节点相对根的世界变换"
+        //   烘焙进几何（抵消了 animRoot），所以只需补 animRoot 的世界变换即可，
+        //   绝不能再用 mesh.matrixWorld（否则节点自身变换被重复应用 → 多节点模型整体扭曲）。
+        const animRootWorld = template.animRoot
+            ? template.animRoot.matrixWorld.clone()
+            : new Matrix4();
+        for (const sub of template.submeshes) {
+            if (!skeleton && animations.length > 0) {
+                sub.nodeWorldMatrix = animRootWorld;
+            }
+            else {
+                sub.nodeWorldMatrix = sub.node
+                    ? sub.node.matrixWorld.clone()
+                    : new Matrix4();
+            }
+        }
+        return template;
+    });
+}

package/instanced/InstancedTemplate.ts

@@ -0,0 +1,188 @@
+import {
+    AnimationClip,
+    BufferGeometry,
+    Material,
+    Matrix4,
+    Object3D,
+    Skeleton,
+    SkinnedMesh,
+} from "three";
+import threeLoader from "../threeLoader";
+import InstancedChild from "./InstancedChild";
+
+/** 一个 submesh 的描述：几何 + 材质 + 是否骨骼网格 */
+export interface InstancedSubmesh {
+    geometry: BufferGeometry;
+    material: Material;
+    skinned: boolean;
+    /** 非骨骼动画：拥有该几何的节点（取世界变换烘焙进几何） */
+    node?: Object3D;
+    /** 非骨骼动画：原始局部几何副本（每帧重新变换的源，避免累积误差） */
+    localGeometry?: BufferGeometry;
+    /**
+     * 该 submesh 在 GLB 场景图里的世界变换（加载时快照）。
+     * GLTF 常把模型整体包在一层带缩放/位移的根节点里（如 Soldier.glb 根节点 scale=0.01），
+     * 只克隆几何会丢掉这层变换导致模型大小/位置错乱。写实例矩阵时把它乘到 child.matrixWorld 上，
+     * 使实例化渲染与"把整棵 GLB 场景图加进场景"的效果一致（对齐 MeshBase 行为）。
+     */
+    nodeWorldMatrix?: Matrix4;
+}
+
+/**
+ * 模板：描述"一类实例"的渲染数据。
+ * - 内置几何：submeshes 含一份几何+材质；
+ * - GLB：submeshes 按 geometry/material uuid 分组（多 submesh），并可能带 skeleton/animations。
+ */
+export interface InstancedTemplate {
+    submeshes: InstancedSubmesh[];
+    skeleton?: Skeleton;
+    animations: AnimationClip[];
+    /** 含骨骼时：每帧把骨骼姿态烘焙进 sharedGeometry，所有实例复用（共享姿态） */
+    sharedGeometry?: BufferGeometry;
+    /**
+     * 含骨骼时：原始 bind-pose 几何（只读，永不修改）。
+     * bakeSkinning 必须每帧从这里读"绑定姿态顶点"，再写到 sharedGeometry，
+     * 绝不能原地读改写 sharedGeometry（否则上一帧的烘焙结果被当成 bind-pose 再烤一遍 → 蒙皮累积错位、越动越乱）。
+     */
+    sourceGeometry?: BufferGeometry;
+    /** 含骨骼时：动画驱动用根对象（含 skeleton 层级，不渲染，仅用于 mixer 更新骨骼） */
+    animRoot?: Object3D;
+    /** 含骨骼时：SkinnedMesh 的 bindMatrix / bindMatrixInverse，烘焙蒙皮用 */
+    bindMatrix?: Matrix4;
+    bindMatrixInverse?: Matrix4;
+}
+
+/** 按 batchKey 缓存模板加载 Promise，避免同一 GLB 重复加载 */
+const _templateCache = new Map<string, Promise<InstancedTemplate>>();
+
+function uuidOf(geometry: BufferGeometry, material: Material): string {
+    return `${geometry.uuid}/${material.uuid}`;
+}
+
+/**
+ * 解析某实例的模板：内置几何同步返回；GLB 异步加载并按 batchKey 缓存。
+ */
+export function loadTemplate(child: InstancedChild): Promise<InstancedTemplate> {
+    const ctor = child.constructor as typeof InstancedChild;
+    // 内置几何：同步构造
+    if (ctor.geometry && ctor.material) {
+        return Promise.resolve({
+            submeshes: [
+                { geometry: ctor.geometry, material: ctor.material, skinned: false },
+            ],
+            animations: [],
+        });
+    }
+    // GLB：异步加载 + 按 batchKey 缓存
+    if (ctor.instanceUrl) {
+        const key = child.getBatchKey();
+        const cached = _templateCache.get(key);
+        if (cached) {
+            return cached;
+        }
+        const p = resolveGLB(ctor.instanceUrl);
+        _templateCache.set(key, p);
+        return p;
+    }
+    return Promise.reject(
+        new Error("[loadTemplate] 子类未定义 geometry+material 或 instanceUrl")
+    );
+}
+
+/** 加载 GLB 并按 geometry/material 分组，提取首个 skeleton 与动画剪辑 */
+function resolveGLB(url: string): Promise<InstancedTemplate> {
+    return threeLoader.loadModel(url).then((root) => {
+        if (!root) {
+            throw new Error(`[resolveGLB] 加载失败: ${url}`);
+        }
+        // 确保场景图世界矩阵已就绪，下面快照每个 submesh 的 nodeWorldMatrix 才准确
+        root.updateMatrixWorld(true);
+        const geometryMap = new Map<string, InstancedSubmesh>();
+        let skeleton: Skeleton | undefined;
+        let firstSkinned: SkinnedMesh | undefined;
+        let animations: AnimationClip[] = [];
+
+        root.traverse((obj: Object3D) => {
+            const mesh = obj as SkinnedMesh;
+            const isMesh = (mesh as any).isMesh === true;
+            if (!isMesh) {
+                return;
+            }
+            const geom = (mesh as any).geometry as BufferGeometry;
+            const rawMat = (mesh as any).material;
+            const mat: Material = Array.isArray(rawMat) ? rawMat[0] : rawMat;
+            const skinned = (mesh as any).isSkinnedMesh === true;
+            const key = uuidOf(geom, mat);
+            if (!geometryMap.has(key)) {
+                geometryMap.set(key, {
+                    geometry: geom,
+                    material: mat,
+                    skinned,
+                    node: mesh,
+                    // nodeWorldMatrix 先留空，下方按 骨骼/节点动画 类型统一确定
+                });
+            }
+            if (skinned && !firstSkinned) {
+                firstSkinned = mesh;
+                skeleton = (mesh as any).skeleton as Skeleton | undefined;
+            }
+        });
+
+        // GLTF 加载器把 animations 挂在 scene 上（threeLoader 已 res.scene.animations = res.animations）
+        const rootAnims = (root as any).animations as AnimationClip[] | undefined;
+        if (rootAnims && rootAnims.length) {
+            animations = rootAnims;
+        }
+
+        const template: InstancedTemplate = {
+            submeshes: Array.from(geometryMap.values()),
+            skeleton,
+            animations,
+        };
+
+        // 含骨骼：保留原始 bind-pose 几何（sourceGeometry，只读） + 一份渲染用几何（sharedGeometry，每帧被烘焙覆盖）。
+        // 二者必须分开：bakeSkinning 从 sourceGeometry 读、写 sharedGeometry，避免原地累积烘焙导致动画越动越乱。
+        if (firstSkinned && skeleton) {
+            const src = firstSkinned.geometry as BufferGeometry;
+            template.sourceGeometry = src;
+            template.sharedGeometry = src.clone();
+            template.animRoot = root;
+            template.bindMatrix = firstSkinned.bindMatrix;
+            template.bindMatrixInverse = firstSkinned.bindMatrixInverse;
+        }
+
+        // 非骨骼动画（节点变换动画，如 point1.glb）：克隆几何，每帧把节点相对根的世界变换烘焙进几何。
+        // 与骨骼 LBS 同理 —— 把"节点层级动画"降级为每帧 CPU 几何变换，所有实例复用一份变换后的几何，
+        // 天然兼容项目所有材质与后处理。
+        if (!skeleton && animations.length > 0) {
+            template.animRoot = root;
+            for (const sub of template.submeshes) {
+                sub.localGeometry = sub.geometry.clone();
+                sub.geometry = sub.geometry.clone();
+            }
+        }
+
+        // 统一确定每个 submesh 的 nodeWorldMatrix：
+        // - 骨骼 / 静态：用 submesh 节点(mesh) 自身的完整世界变换（含祖先）。
+        //   bakeSkinning 输出在 skinned mesh 局部空间、静态几何即 GLTF 原始局部空间，都需完整世界变换才能落到位；
+        //   Soldier.glb 根节点 scale=0.01 这类"整模型套一层缩放根"的情形，靠这里补回
+        //   （对齐 MeshBase 把整棵 GLB 场景图加进场景的行为）。
+        // - 非骨骼节点动画（如 point1.glb）：bakeNodeTransform 已把"节点相对根的世界变换"
+        //   烘焙进几何（抵消了 animRoot），所以只需补 animRoot 的世界变换即可，
+        //   绝不能再用 mesh.matrixWorld（否则节点自身变换被重复应用 → 多节点模型整体扭曲）。
+        const animRootWorld = template.animRoot
+            ? template.animRoot.matrixWorld.clone()
+            : new Matrix4();
+        for (const sub of template.submeshes) {
+            if (!skeleton && animations.length > 0) {
+                sub.nodeWorldMatrix = animRootWorld;
+            } else {
+                sub.nodeWorldMatrix = sub.node
+                    ? sub.node.matrixWorld.clone()
+                    : new Matrix4();
+            }
+        }
+
+        return template;
+    });
+}

package/keyControls.d.ts

@@ -0,0 +1,30 @@
+/// <reference types="lodash" />
+import { EventDispatcher, EventListener, Vector3 } from "three";
+import type { KeyControlsEventTypeMap, KeyAddEvent, KeyDeleteEvent, KeyEnterEvent } from "./EventMap";
+/**
+ * 键盘 使用 ↑↓←→ 控制 x z 方向, 小键盘 1 0 控制 y 方向
+ *
+ * @class KeyControls
+ * @extends {EventDispatcher<KeyControlsEventTypeMap>}
+ */
+declare class KeyControls extends EventDispatcher<KeyControlsEventTypeMap> {
+    constructor();
+    uuid: string;
+    direction: Vector3;
+    _listeners?: {
+        [key: string]: Array<(event: {
+            type: string;
+        }) => void>;
+    };
+    add(e: KeyAddEvent): void;
+    delete(e: KeyboardEvent | KeyDeleteEvent): void;
+    enter(e: KeyboardEvent | KeyEnterEvent): void;
+    keyDown: (e: KeyboardEvent) => void;
+    removeEvent: import("lodash").DebouncedFuncLeading<(type: string) => void>;
+    addEventListener<T extends string>(type: T, listener: EventListener<{}, T, this>): void;
+    addEvent(): void;
+    dispose(): void;
+}
+declare const keyControls: KeyControls;
+export { KeyControls, keyControls };
+export default keyControls;