soonspacejs 2.15.4 → 2.15.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soonspacejs",
-  "version": "2.15.4",
+  "version": "2.15.6",
   "homepage": "https://www.xwbuilders.com/soonspacejs/",
   "description": "soonspacejs 2.x",
   "module": "./dist/index.esm.js",

package/types/Animation/clip-animation.d.ts

@@ -0,0 +1,80 @@
+import { EventDispatcher, Object3D } from 'three';
+import { Tween } from 'three/examples/jsm/libs/tween.module.js';
+import { default as animation } from './index';
+import { IClipAnimation, IClipAnimationFrame, IClipAnimationPlayerEventMap, IClipTransform, IClipTweenSource } from '../Interface';
+/**
+ * 剪辑动画播放器
+ *
+ * @remarks
+ * SDK 内部实现。业务侧推荐使用 {@link SoonSpace.playClipAnimation} 等高层方法，
+ * 不需要直接构造该类。
+ *
+ * 行为：
+ * - 接收一组关键帧（{@link IClipAnimationFrame}），按数组顺序串行播放
+ * - 每段为一次 `ssp.animation()` 补间，覆盖目标的 position / rotation / scale
+ * - 通过 `update` / `start` 事件暴露每帧的 tween 数据，便于上层做 UI 同步
+ *
+ * 生命周期：
+ * - {@link initTransform} —— 记录初始姿态（首次 `play` 前自动调用）
+ * - {@link play} —— 顺序播放所有 frame，被 {@link stop} 中断时优雅退出
+ * - {@link reset} —— 把目标 transform 还原到 `initTransform` 时的快照
+ * - {@link dispose} —— `stop + reset + 移除初始姿态标记`
+ */
+export declare class ClipAnimationPlayer extends EventDispatcher<IClipAnimationPlayerEventMap> {
+    /** SoonSpace 实例 —— 仅用 `animation()` 调度补间 + `render()` 触发重绘 */
+    readonly ssp: {
+        animation: typeof animation;
+        render: () => void;
+    };
+    /** 被动画的目标对象（每帧的 position / rotation / scale 会写到这里） */
+    readonly target: Object3D;
+    /** 当前 in-flight 的 tween 集合，{@link stop} 时统一打断 */
+    readonly tweenSet: Set<Tween<IClipTweenSource>>;
+    /** 是否仍有 tween 在执行 */
+    get isPlaying(): boolean;
+    constructor(
+    /** SoonSpace 实例 —— 仅用 `animation()` 调度补间 + `render()` 触发重绘 */
+    ssp: {
+        animation: typeof animation;
+        render: () => void;
+    }, 
+    /** 被动画的目标对象（每帧的 position / rotation / scale 会写到这里） */
+    target: Object3D);
+    /**
+     * 把当前 target.position / rotation / scale 作为初始快照记录到 target 上的 Symbol 槽
+     *
+     * @remarks
+     * 通常无需手动调用 —— {@link play} 会在首次执行前惰性调用一次。
+     * 多次调用不会覆盖（除非显式传入 `defaultTransform`）。
+     *
+     * @param defaultTransform - 显式指定初始姿态（覆盖目标当前 transform 的快照）
+     */
+    initTransform(defaultTransform?: IClipTransform): IClipTransform;
+    /** 取出 {@link initTransform} 记录的初始姿态；未记录时返回 `undefined` */
+    getInitialTransform(): IClipTransform | undefined;
+    /**
+     * 按数组顺序播放关键帧
+     *
+     * @remarks
+     * - 首次调用时会通过 {@link initTransform} 记录初始姿态
+     * - 第 0 帧的"起点"为初始姿态；后续帧的"起点"为前一帧的 target 值
+     * - 被 {@link stop} 打断时立即结束剩余帧的播放并 resolve
+     *
+     * @param frames - 关键帧数组（**调用方需自行排序**；高层方法 `playClipAnimation` 会按 `index` 排序后再传入）
+     */
+    play(frames: IClipAnimationFrame[]): Promise<void>;
+    /** 停止所有 in-flight tween；{@link play} 会随之 resolve */
+    stop(): void;
+    /**
+     * 把 target 还原到 {@link initTransform} 时的初始姿态并触发一次重绘
+     *
+     * @remarks 未调用过 {@link initTransform} 时（无快照）此方法为 no-op
+     */
+    reset(): void;
+    /**
+     * 一站式清理：{@link stop} → {@link reset} → 移除 target 上的初始姿态 Symbol 槽
+     * @remarks 释放后再次 {@link play} 会重新捕获当前 target 状态作为新的初始姿态
+     */
+    dispose(): void;
+}
+export type { IClipAnimation, IClipAnimationFrame, IClipTransform, IClipTweenSource, IClipAnimationPlayerEventMap, };

package/types/Interface/animation.d.ts

@@ -1,3 +1,6 @@
+import { Tween } from 'three/examples/jsm/libs/tween.module.js';
+import { Vector3, Euler } from 'three';
+import { IVector3 } from './base';
 type AnimationModeType = 'Linear.None' | 'Quadratic.In' | 'Quadratic.Out' | 'Quadratic.InOut' | 'Cubic.In' | 'Cubic.Out' | 'Cubic.InOut' | 'Quartic.In' | 'Quartic.Out' | 'Quartic.InOut' | 'Quintic.In' | 'Quintic.Out' | 'Quintic.InOut' | 'Sinusoidal.In' | 'Sinusoidal.Out' | 'Sinusoidal.InOut' | 'Exponential.In' | 'Exponential.Out' | 'Exponential.InOut' | 'Circular.In' | 'Circular.Out' | 'Circular.InOut' | 'Elastic.In' | 'Elastic.Out' | 'Elastic.InOut' | 'Back.In' | 'Back.Out' | 'Back.InOut' | 'Bounce.In' | 'Bounce.Out' | 'Bounce.InOut';
 type AnimationModeValueType = (amount: number) => number;
 interface AnimationOptions {
@@ -7,4 +10,95 @@ interface AnimationOptions {
     mode?: AnimationModeType;
     yoyo?: boolean;
 }
-export { AnimationModeType, AnimationModeValueType, AnimationOptions, };
+/**
+ * 剪辑动画 —— 单个关键帧
+ *
+ * @remarks
+ * 字段与 bimeditor `IAnimationKeyframe` 协议对齐，可直接将服务端数据传入
+ * `ssp.playClipAnimation` 而不需要任何字段映射。
+ *
+ * - `position` / `scale` 单位为模型世界单位
+ * - `rotation` 为欧拉角，**单位：弧度**（与 three.js `Euler` 一致）
+ * - `repeat = -1` 解释为 `Infinity`
+ */
+interface IClipAnimationFrame {
+    /** 关键帧业务 ID（SDK 内部不使用） */
+    id?: string;
+    /** 目标 position */
+    position: IVector3;
+    /** 目标 rotation（欧拉角，弧度） */
+    rotation: IVector3;
+    /** 目标 scale */
+    scale: IVector3;
+    /** 缓动曲线名称 */
+    easing: AnimationModeType;
+    /** 持续时间（毫秒），默认 `1000` */
+    duration?: number;
+    /** 起始延迟（毫秒），默认 `0` */
+    delay?: number;
+    /** 重复次数；`-1` 视为无限循环；默认 `0`（不重复） */
+    repeat?: number;
+    /** 是否往返播放，默认 `false` */
+    yoyo?: boolean;
+    /** 帧排序索引；SDK 在播放前会按此字段升序排序 */
+    index?: number;
+    /** 业务保留字段（与 SDK 内部行为无关） */
+    mode?: string;
+}
+/**
+ * 剪辑动画
+ *
+ * @remarks
+ * 字段与 bimeditor `IAnimationClip` 协议对齐。`refId` 是目标对象的标识，
+ * SDK 在 `model` 子树内按 `sid → uuid → userData.key` 顺序查找命中节点。
+ */
+interface IClipAnimation {
+    /** 剪辑业务 ID（SDK 内部不使用） */
+    id?: string;
+    /** 剪辑名称（SDK 内部不使用） */
+    name?: string;
+    /** 目标对象的 sid / uuid / userData.key */
+    refId: string;
+    /** 关键帧列表（按 {@link IClipAnimationFrame.index} 升序播放） */
+    keyframes: IClipAnimationFrame[];
+}
+/**
+ * 剪辑动画 —— 初始 / 中间 transform 快照
+ * @internal 由 `ClipAnimationPlayer.initTransform` 记录，供 `reset` 还原使用
+ */
+interface IClipTransform {
+    position: Vector3 | IVector3;
+    rotation: Euler | IVector3;
+    scale: Vector3 | IVector3;
+}
+/**
+ * 剪辑动画 —— tween 内部使用的扁平 9 通道数据
+ * @internal 把 position / rotation / scale 拍平成 tween 能补间的标量集合
+ */
+interface IClipTweenSource {
+    x: number;
+    y: number;
+    z: number;
+    rotationX: number;
+    rotationY: number;
+    rotationZ: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+}
+/**
+ * 剪辑动画 —— 播放器事件
+ *
+ * - `update`：每帧 tween 更新时触发，`source` 为当前帧的 9 通道值
+ * - `start` ：每段 tween 开始时触发
+ */
+interface IClipAnimationPlayerEventMap {
+    update: {
+        source: IClipTweenSource;
+        tween: Tween<IClipTweenSource>;
+    };
+    start: {
+        tween: Tween<IClipTweenSource>;
+    };
+}
+export { AnimationModeType, AnimationModeValueType, AnimationOptions, IClipAnimationFrame, IClipAnimation, IClipTransform, IClipTweenSource, IClipAnimationPlayerEventMap, };

package/types/index.d.ts

@@ -2,12 +2,12 @@ import { Object3D, Vector3, Euler, Box3, AnimationClip, Light, Texture, Mesh, Sk
 import { default as Animation } from './Animation';
 import { PathAnimation, PathAnimationOptions } from './Animation/path-animation';
 import { CreatePathAnimationOptions, CreatePathAnimationActionForCameraOptions, CreateBonePathAnimationOptions, AnimationPath } from './Animation/createPathAnimation';
+import { IClipAnimation, BaseObjectInfo, ViewportOptions, SceneGlobalEvents, PluginsConstructor, IColor, Position, Rotation, OffsetPoint, ModelAnimationFindFunc, TopologyNodeInfo, FlyToViewpoint, FlyToOptions, FlyToObjOptions, SurroundOptions, LabelOptions, EdgeSelectOptions, StrokeSelectOptions, OpacitySelectOptions, HighlightSelectOptions, EmissiveSelectOptions, FogOptions, UserDataPropertyFindFunc, AmbientLightOptions, DirectionalLightOptions, HemisphereLightOptions, SpotLightOptions, PointLightOptions, CloneModelInfo, ClonePoiInfo, ShortestPathInfo, ShortestPathByMultipleStartPoints, ShortestPathByMultipleEndPoints, TopologyInfoForGml, GridHelperOptions, AxesHelperOptions, BoxHelperOptions, PlaneHelperOptions, GroundHelperOptions, DirectionalLightHelperOptions, HemisphereLightHelperOptions, SpotLightHelperOptions, PointLightHelperOptions, SignalsState, ControlsOptions, RectAreaLightOptions, RectAreaLightHelperOptions, SkyOptions, IColorSpace, ToneMappingOptions, SSAOOptions, BloomOptions, IVector3, EnvironmentOptions, PluginsConstructorWithOptions, TopologyPassableInfo, CameraViewpointData, CameraViewpointDataLegacy, CameraType } from './Interface';
 import { BaseObject3D, Model, ModelInfo, Poi, PoiInfo, PoiNode, PoiNodeInfo, Topology, TopologyInfo, Group, GroupInfo, Canvas3D, Canvas3DInfo, PluginObject, PluginObjectInfo, DecalInfo, Decal, DecalGeometryInfo, PoiMeshInfo, PolygonPoiMeshInfo } from './Library';
 import { ObjectsCache } from './Cache';
 import { default as Viewport } from './Viewport';
 import { default as Controls } from './Controls';
 import { default as Manager } from './Manager';
-import { BaseObjectInfo, ViewportOptions, SceneGlobalEvents, PluginsConstructor, IColor, Position, Rotation, OffsetPoint, ModelAnimationFindFunc, TopologyNodeInfo, FlyToViewpoint, FlyToOptions, FlyToObjOptions, SurroundOptions, LabelOptions, EdgeSelectOptions, StrokeSelectOptions, OpacitySelectOptions, HighlightSelectOptions, EmissiveSelectOptions, FogOptions, UserDataPropertyFindFunc, AmbientLightOptions, DirectionalLightOptions, HemisphereLightOptions, SpotLightOptions, PointLightOptions, CloneModelInfo, ClonePoiInfo, ShortestPathInfo, ShortestPathByMultipleStartPoints, ShortestPathByMultipleEndPoints, TopologyInfoForGml, GridHelperOptions, AxesHelperOptions, BoxHelperOptions, PlaneHelperOptions, GroundHelperOptions, DirectionalLightHelperOptions, HemisphereLightHelperOptions, SpotLightHelperOptions, PointLightHelperOptions, SignalsState, ControlsOptions, RectAreaLightOptions, RectAreaLightHelperOptions, SkyOptions, IColorSpace, ToneMappingOptions, SSAOOptions, BloomOptions, IVector3, EnvironmentOptions, PluginsConstructorWithOptions, TopologyPassableInfo, CameraViewpointData, CameraViewpointDataLegacy, CameraType } from './Interface';
 import { BoxSpace, FindObjectsNearPosition, FindNearbyObjects, SetTextureOptions } from './tools';
 import { ModelsBoundsTreeOptions } from './Viewport/Bvh';
 import { AnimationOperate, CreateChainSkeletalModelOptions, CreateCurveAnimationClipForBonesOptions } from '@three3d/animation';
@@ -1284,6 +1284,139 @@ declare class SoonSpace {
         skeletalModel: any;
         skeleton: any;
     };
+    /**
+     * 在指定模型上播放剪辑动画
+     *
+     * @description
+     * 在 `model` 子树内按 `clip.refId` 查找目标对象（依次匹配子节点的
+     * `sid` / `uuid` / `userData.key`），将 `clip.keyframes` 作为
+     * position / rotation / scale 的补间序列应用到目标。
+     *
+     * - 同一 `model` + `refId` 多次播放会复用内部 player，{@link resetClipAnimation}
+     *   能精确还原到首次播放前的姿态
+     * - 数组形式按数组顺序串行播放；中途调用 {@link stopClipAnimation}(model) /
+     *   {@link resetClipAnimation}(model) / {@link disposeClipAnimation}(model)
+     *   会打断剩余序列
+     *
+     * @param model - 模型作用域：`Object3D` 实例或其顶层 id 字符串
+     * @param data - 单个剪辑或剪辑数组（{@link IClipAnimation}）
+     * @returns 模型 / 目标找不到时立即 resolve；否则在动画完成、被 stop 或被打断时 resolve
+     *
+     * @example
+     * ```ts
+     * await ssp.playClipAnimation(model, clip)     // 单 clip
+     * await ssp.playClipAnimation(model, clips)    // 数组顺序播放
+     * ```
+     */
+    playClipAnimation(model: Object3D | string, data: IClipAnimation | IClipAnimation[]): Promise<void>;
+    /**
+     * 停止指定模型上的剪辑动画
+     *
+     * @description
+     * - 不传 `data`：停止该模型上**所有**已播放过的 target，并打断进行中的串行序列
+     * - 传 `data`：仅停止 `data` 对应的 target，**不**打断同模型上的串行序列
+     *
+     * @param model - 模型作用域：`Object3D` 实例或其顶层 id 字符串
+     * @param data - 单个剪辑或剪辑数组；省略则作用于整个模型
+     *
+     * @example
+     * ```ts
+     * ssp.stopClipAnimation(model)         // 停该模型上全部
+     * ssp.stopClipAnimation(model, clip)   // 只停指定 clip
+     * ssp.stopClipAnimation(model, clips)  // 只停一组 clip
+     * ```
+     */
+    stopClipAnimation(model: Object3D | string, data?: IClipAnimation | IClipAnimation[]): void;
+    /**
+     * 复位指定模型上的剪辑动画到首次播放前的姿态（停止 + 还原 transform）
+     *
+     * @description
+     * - 不传 `data`：复位该模型上**所有**已播放过的 target，并打断进行中的串行序列
+     * - 传 `data`：仅复位 `data` 对应的 target，**不**打断同模型上的串行序列
+     *
+     * 还原的姿态来自该 target 首次 `playClipAnimation` 之前的状态，由 SDK 内部记录。
+     *
+     * @param model - 模型作用域：`Object3D` 实例或其顶层 id 字符串
+     * @param data - 单个剪辑或剪辑数组；省略则作用于整个模型
+     *
+     * @example
+     * ```ts
+     * ssp.resetClipAnimation(model)        // 复位该模型上全部
+     * ssp.resetClipAnimation(model, clip)  // 只复位指定 clip
+     * ```
+     */
+    resetClipAnimation(model: Object3D | string, data?: IClipAnimation | IClipAnimation[]): void;
+    /**
+     * 释放指定模型在剪辑动画系统中的所有缓存与正在进行的播放
+     *
+     * @description
+     * 应在模型从场景移除前调用，否则缓存里会残留指向已脱离场景的 target 的 player。
+     * 内部会：
+     *  1. 打断该模型上进行中的串行序列
+     *  2. 对每个缓存 player 调用 dispose（停止 tween + 移除 initTransform 标记）
+     *  3. 清空 `model -> targets` / target -> player 的索引
+     *
+     * @param model - 模型作用域：`Object3D` 实例或其顶层 id 字符串
+     *
+     * @example
+     * ```ts
+     * ssp.disposeClipAnimation(model)
+     * ssp.removeObject(model)
+     * ```
+     */
+    disposeClipAnimation(model: Object3D | string): void;
+    /**
+     * 剪辑动画 —— player 缓存
+     * @internal key = target.uuid（three.js 自动分配，全局唯一），value = 该 target 的 player
+     */
+    private _clipPlayerCache;
+    /**
+     * 剪辑动画 —— 每个模型上播放过的 target 索引
+     * @internal key = model.uuid，value = 在该模型子树内播放过的所有 target.uuid
+     *
+     * 用于按模型范围实现 {@link stopClipAnimation} / {@link resetClipAnimation} / {@link disposeClipAnimation}
+     * 的 O(targets) 操作，避免遍历全局 player 缓存。
+     */
+    private _modelClipTargets;
+    /**
+     * 剪辑动画 —— 数组串行播放的 abort 注册表
+     * @internal key = model.uuid，value = 当前在该模型上 in-flight 的 aborter 集合
+     *
+     * 每个 in-flight 的 {@link playClipAnimation} 调用注册一个 aborter，stop / reset / dispose
+     * 不传 data 时调用 {@link _abortInFlight} 触发它，使 for 循环在下一次迭代前 bail。
+     */
+    private _modelInFlight;
+    /**
+     * 触发指定模型上所有 in-flight 串行播放的 aborter
+     * @internal
+     */
+    private _abortInFlight;
+    /**
+     * 把传入的 model 参数解析为 Object3D
+     * @internal 字符串走 {@link getObjectById}，Object3D 直接返回
+     */
+    private _resolveClipModel;
+    /**
+     * 取出（或惰性创建）某个 (model, refId) 对应的 player
+     * @internal
+     *
+     * - 缓存命中：复用，确保 `getInitialTransform()` 仍指向首次播放前的姿态
+     * - target 已替换（uuid 偶发复用）：dispose 旧的，重建
+     * - 新建时立刻 `initTransform()` 记录初始姿态，并登记到 `_modelClipTargets`
+     */
+    private _getOrCreateClipPlayer;
+    /**
+     * 在 model 子树（含 model 自身）内定位剪辑动画目标
+     * @internal
+     *
+     * 命中条件（按短路顺序）：`node.sid === id` → `node.uuid === id` → `node.userData.key === id`
+     *
+     * - `sid` —— SBM 子 mesh 的常见情形
+     * - `uuid` —— three.js 自动分配的全局唯一 id
+     * - `userData.key` —— 与 bimeditor `getMeshByUserDataUuid` 行为对齐，
+     *   用于组件编辑器写入 userData 的情形
+     */
+    private _findClipTarget;
     /**
      * 创建骨骼沿曲线路径运动的动画
      * @param model