@realsee/dnalogel 3.81.0-alpha.4 → 3.81.0-alpha.5

package/libs/DigitalPerformancePlugin/core/DigitalHuman.d.ts

@@ -20,6 +20,11 @@ export declare class DigitalHuman {
     effectsGroup: THREE.Group;
     effectObjects: Map<string, THREE.Mesh>;
     container: THREE.Group;
+    /**
+     * 运动轨迹线（curveLine）开关。默认关闭、不绘制、不显示。
+     * 仅 debug / 特殊需求时由业务经插件显式开启（见 setTraceVisible）。
+     */
+    showTrace: boolean;
     private mixer;
     private action;
     private itemMatrixMap;
@@ -34,6 +39,18 @@ export declare class DigitalHuman {
         repeat: boolean;
         switchDuration: number;
     }): void;
+    /**
+     * seek/预览专用：立即「硬切」到目标动画（无 crossfade）。
+     *
+     * 背景：`playAnimation` 走 `crossFadeFrom(oldAction, switchDuration, true)` 做平滑过渡，依赖后续帧以
+     * 正的 delta 推进权重淡入淡出。但 seek/定格帧（delta===0）只做一次 `mixer.update(0)`，零时长的
+     * crossfade 不会推进——新动作权重可能仍≈0、旧动作权重仍≈1，且旧动作的 `stop()` 被 `setTimeout(…,0)`
+     * 推迟到本帧渲染之后执行。结果：跨动画 seek（如章节末「躺」姿回到起始帧「跑」）时旧姿态残留，
+     * 而位置/旋转因是直接拷贝关键帧的、已正确。
+     *
+     * 这里同步停旧动作、把新动作权重直接置 1，保证随后的 `mixer.update(0)` 立即定格到目标姿态。
+     */
+    private switchAnimationImmediately;
     pauseAnimation(): void;
     stopAnimation(): void;
     continueAnimation(): void;
@@ -62,6 +79,12 @@ export declare class DigitalHuman {
      * @param delta 距上一帧的时间增量(ms)，用于推进骨骼动画 mixer
      */
     renderAtTime(time: number, delta: number): void;
+    /**
+     * 运动轨迹线开关（默认关闭、不显示）。仅 debug / 特殊需求由业务显式开启。
+     * - 开启：显示 curveLine，并回填当前时间点之前的轨迹（此后每帧继续累积）。
+     * - 关闭：隐藏并清空轨迹几何。
+     */
+    setTraceVisible(visible: boolean): void;
     traceUpDate(): void;
     clearTrace(): void;
     clearProcessedNeedRenderKeyframeIndices(): void;

package/libs/DigitalPerformancePlugin/core/DigitalHuman.js

@@ -1,65 +1,87 @@
 var b = Object.defineProperty;
-var B = (w, e, i) => e in w ? b(w, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : w[e] = i;
-var c = (w, e, i) => (B(w, typeof e != "symbol" ? e + "" : e, i), i);
-var T = (w, e, i) => new Promise((s, f) => {
-  var r = (n) => {
+var R = (k, e, i) => e in k ? b(k, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : k[e] = i;
+var h = (k, e, i) => (R(k, typeof e != "symbol" ? e + "" : e, i), i);
+var v = (k, e, i) => new Promise((s, r) => {
+  var o = (n) => {
     try {
-      m(i.next(n));
-    } catch (u) {
-      f(u);
+      f(i.next(n));
+    } catch (p) {
+      r(p);
     }
-  }, d = (n) => {
+  }, u = (n) => {
     try {
-      m(i.throw(n));
-    } catch (u) {
-      f(u);
+      f(i.throw(n));
+    } catch (p) {
+      r(p);
     }
-  }, m = (n) => n.done ? s(n.value) : Promise.resolve(n.value).then(r, d);
-  m((i = i.apply(w, e)).next());
+  }, f = (n) => n.done ? s(n.value) : Promise.resolve(n.value).then(o, u);
+  f((i = i.apply(k, e)).next());
 });
 import * as t from "three";
-import { DigitalStateMachine as S } from "./DigitalStateMachine.js";
-import { Trace as L } from "./Trace.js";
-const v = 300;
+import { DigitalStateMachine as B } from "./DigitalStateMachine.js";
+import { Trace as S } from "./Trace.js";
+const F = 300;
 class O {
   constructor(e, i) {
-    c(this, "model");
-    c(this, "keyframesManager");
-    c(this, "keyframes");
-    c(this, "items");
-    c(this, "effects");
-    c(this, "digitalPlayground");
-    c(this, "state");
-    c(this, "animationFrameId");
-    c(this, "curveLine");
-    c(this, "effectsGroup");
-    c(this, "effectObjects");
-    c(this, "container");
-    c(this, "mixer");
-    c(this, "action");
-    c(this, "itemMatrixMap");
-    c(this, "trace");
+    h(this, "model");
+    h(this, "keyframesManager");
+    h(this, "keyframes");
+    h(this, "items");
+    h(this, "effects");
+    h(this, "digitalPlayground");
+    h(this, "state");
+    h(this, "animationFrameId");
+    h(this, "curveLine");
+    h(this, "effectsGroup");
+    h(this, "effectObjects");
+    h(this, "container");
+    /**
+     * 运动轨迹线（curveLine）开关。默认关闭、不绘制、不显示。
+     * 仅 debug / 特殊需求时由业务经插件显式开启（见 setTraceVisible）。
+     */
+    h(this, "showTrace", !1);
+    h(this, "mixer");
+    h(this, "action");
+    h(this, "itemMatrixMap");
+    h(this, "trace");
     // 用于跟踪已处理的needRender keyframeIndex
-    c(this, "processedNeedRenderKeyframeIndices", /* @__PURE__ */ new Set());
+    h(this, "processedNeedRenderKeyframeIndices", /* @__PURE__ */ new Set());
     // 跟踪已绑定到骨骼的 keyframe 道具（key: itemKey, value: item object）
-    c(this, "attachedItems", /* @__PURE__ */ new Map());
+    h(this, "attachedItems", /* @__PURE__ */ new Map());
     // 缓存 RightHand 骨骼
-    c(this, "rightHandBone", null);
+    h(this, "rightHandBone", null);
     // 加法式新增：供外部统一时钟（DigitalPerformanceV2Plugin）驱动时使用的特效贴图缓存。
     // 不影响既有 play() 路径（play 使用其内部局部 textures 变量）。
-    c(this, "externalTextures", /* @__PURE__ */ new Map());
-    this.model = e, this.model.visible = !1, this.model.mixer = null, this.mixer = new t.AnimationMixer(this.model), this.action = null, this.keyframesManager = new S(), this.keyframes = [], this.items = [], this.effects = [], this.digitalPlayground = i, this.state = {
+    h(this, "externalTextures", /* @__PURE__ */ new Map());
+    this.model = e, this.model.visible = !1, this.model.mixer = null, this.mixer = new t.AnimationMixer(this.model), this.action = null, this.keyframesManager = new B(), this.keyframes = [], this.items = [], this.effects = [], this.digitalPlayground = i, this.state = {
       currentTime: 0,
       currentAnimation: null,
       currentAnimationRepeat: !1,
       playing: !1
-    }, this.animationFrameId = null, this.itemMatrixMap = /* @__PURE__ */ new Map(), this.trace = new L(), this.curveLine = new t.Line(), this.curveLine.material = new t.LineBasicMaterial({ color: 14467195, linewidth: 5 }), this.effectsGroup = new t.Group(), this.effectObjects = /* @__PURE__ */ new Map(), this.container = new t.Group(), this.container.add(this.model), this.container.add(this.curveLine), this.container.add(this.effectsGroup);
+    }, this.animationFrameId = null, this.itemMatrixMap = /* @__PURE__ */ new Map(), this.trace = new S(), this.curveLine = new t.Line(), this.curveLine.material = new t.LineBasicMaterial({ color: 14467195, linewidth: 5 }), this.curveLine.visible = !1, this.effectsGroup = new t.Group(), this.effectObjects = /* @__PURE__ */ new Map(), this.container = new t.Group(), this.container.add(this.model), this.container.add(this.curveLine), this.container.add(this.effectsGroup);
   }
   playAnimation({ animation: e, repeat: i, switchDuration: s }) {
-    const f = this.action, r = this.mixer.clipAction(e);
-    r.reset(), i ? (r.setLoop(t.LoopRepeat, 1 / 0), r.clampWhenFinished = !1) : (r.setLoop(t.LoopOnce, 1), r.clampWhenFinished = !0), f && (r.enabled = !0, r.setEffectiveTimeScale(1), r.crossFadeFrom(f, s / 1e3, !0)), r.play(), f && f !== r && setTimeout(() => {
-      f !== this.action && f.stop();
-    }, s), this.action = r;
+    const r = this.action, o = this.mixer.clipAction(e);
+    o.reset(), i ? (o.setLoop(t.LoopRepeat, 1 / 0), o.clampWhenFinished = !1) : (o.setLoop(t.LoopOnce, 1), o.clampWhenFinished = !0), r && (o.enabled = !0, o.setEffectiveTimeScale(1), o.crossFadeFrom(r, s / 1e3, !0)), o.play(), r && r !== o && setTimeout(() => {
+      r !== this.action && r.stop();
+    }, s), this.action = o;
+  }
+  /**
+   * seek/预览专用：立即「硬切」到目标动画（无 crossfade）。
+   *
+   * 背景：`playAnimation` 走 `crossFadeFrom(oldAction, switchDuration, true)` 做平滑过渡，依赖后续帧以
+   * 正的 delta 推进权重淡入淡出。但 seek/定格帧（delta===0）只做一次 `mixer.update(0)`，零时长的
+   * crossfade 不会推进——新动作权重可能仍≈0、旧动作权重仍≈1，且旧动作的 `stop()` 被 `setTimeout(…,0)`
+   * 推迟到本帧渲染之后执行。结果：跨动画 seek（如章节末「躺」姿回到起始帧「跑」）时旧姿态残留，
+   * 而位置/旋转因是直接拷贝关键帧的、已正确。
+   *
+   * 这里同步停旧动作、把新动作权重直接置 1，保证随后的 `mixer.update(0)` 立即定格到目标姿态。
+   */
+  switchAnimationImmediately(e, i) {
+    const s = this.action;
+    s && s.getClip() !== e && s.stop();
+    const r = this.mixer.clipAction(e);
+    r.reset(), i ? (r.setLoop(t.LoopRepeat, 1 / 0), r.clampWhenFinished = !1) : (r.setLoop(t.LoopOnce, 1), r.clampWhenFinished = !0), r.enabled = !0, r.setEffectiveTimeScale(1), r.setEffectiveWeight(1), r.play(), this.action = r;
   }
   pauseAnimation() {
     this.action && (this.action.paused = !0), this.animationFrameId && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null), this.state.playing = !1;
@@ -79,78 +101,81 @@ class O {
     this.state.currentTime = 0, this.keyframes && this.keyframes.length > 0 && (this.model.position.copy(new t.Vector3().fromArray(this.keyframes[0].position)), this.model.quaternion.copy(new t.Quaternion().fromArray(this.keyframes[0].quaternion))), this.model.visible = !1, this.container.visible = !1, this.animationFrameId && cancelAnimationFrame(this.animationFrameId), this.stopAnimation(), this.clearTrace(), this.detachAllKeyframeItems(), this.state.playing = !1;
   }
   play(e) {
-    return T(this, null, function* () {
+    return v(this, null, function* () {
       this.clearProcessedNeedRenderKeyframeIndices();
-      const { keyframes: i, items: s, effects: f } = e || {};
-      return this.keyframes = i || this.keyframes, this.items = s || this.items, this.effects = f || this.effects, this.state.currentAnimation = null, this.state.currentAnimationRepeat = !1, this.state.playing = !0, new Promise((r) => {
+      const { keyframes: i, items: s, effects: r } = e || {};
+      return this.keyframes = i || this.keyframes, this.items = s || this.items, this.effects = r || this.effects, this.state.currentAnimation = null, this.state.currentAnimationRepeat = !1, this.state.playing = !0, new Promise((o) => {
         this.state.currentTime || this.init();
-        let d = null;
-        for (const l of this.items) {
-          const h = this.digitalPlayground.getDigitalItem(l.model);
-          if (h) {
+        let u = null;
+        for (const d of this.items) {
+          const l = this.digitalPlayground.getDigitalItem(d.model);
+          if (l) {
             let a = null;
-            const g = this.model.children[0].children.find((A) => A instanceof t.Bone), p = this.model.children[0].children.find((A) => A instanceof t.SkinnedMesh);
-            if (!g || !p)
+            const g = this.model.children[0].children.find((w) => w instanceof t.Bone), y = this.model.children[0].children.find((w) => w instanceof t.SkinnedMesh);
+            if (!g || !y)
               throw new Error("模型骨骼缺失");
-            if (this.model.children[0].children[2].traverse((A) => {
-              A instanceof t.Bone && A.name === "RightHand" && (a = A);
+            if (this.model.children[0].children[2].traverse((w) => {
+              w instanceof t.Bone && w.name === "RightHand" && (a = w);
             }), !a)
               throw new Error("没有找到绑定的骨骼");
-            a.add(h);
-            const k = new t.Vector3(), o = new t.Quaternion(), y = new t.Vector3();
-            new t.Matrix4().fromArray(l.initialMatrix).decompose(k, o, y), h.position.copy(k), h.quaternion.copy(o), h.scale.copy(y), h.updateMatrixWorld(!0);
+            a.add(l);
+            const m = new t.Vector3(), c = new t.Quaternion(), A = new t.Vector3();
+            new t.Matrix4().fromArray(d.initialMatrix).decompose(m, c, A), l.position.copy(m), l.quaternion.copy(c), l.scale.copy(A), l.updateMatrixWorld(!0);
           }
         }
-        const m = /* @__PURE__ */ new Map(), n = new t.TextureLoader();
-        for (const l of this.effects)
-          if (l.type === "frameSequence") {
-            const h = l.keyframes;
-            for (const a of h)
+        const f = /* @__PURE__ */ new Map(), n = new t.TextureLoader();
+        for (const d of this.effects)
+          if (d.type === "frameSequence") {
+            const l = d.keyframes;
+            for (const a of l)
               n.load(a.image, (g) => {
-                g.name = a.image, m.set(a.image, g);
+                g.name = a.image, f.set(a.image, g);
               });
           }
-        const u = (l) => {
-          var p, k;
-          d === null && (d = l);
-          const h = l - d;
-          d = l, this.state.currentTime += h;
+        const p = (d) => {
+          var g, y;
+          u === null && (u = d);
+          const l = d - u;
+          u = d, this.state.currentTime += l;
           const a = this.keyframesManager.getStateByTime(this.state.currentTime, this.keyframes, "model");
-          this.trace.addPoint(a.translation);
-          const g = new t.BufferGeometry().setFromPoints(this.trace.tracePoints);
-          if (this.curveLine.geometry = g, this.model.position.copy(a.translation), this.model.quaternion.copy(a.quaternion), this.model.scale.copy(a.scale), this.model.visible = a.visible, a.isFinal) {
-            this.model.visible = !1, this.container.visible = !1, this.stopAnimation(), this.model.needsRender = !0, r(!0), this.animationFrameId !== null && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null);
+          if (this.showTrace) {
+            this.trace.addPoint(a.translation);
+            const m = new t.BufferGeometry().setFromPoints(this.trace.tracePoints);
+            this.curveLine.geometry = m;
+          }
+          if (this.model.position.copy(a.translation), this.model.quaternion.copy(a.quaternion), this.model.scale.copy(a.scale), this.model.visible = a.visible, a.isFinal) {
+            this.model.visible = !1, this.container.visible = !1, this.stopAnimation(), this.model.needsRender = !0, o(!0), this.animationFrameId !== null && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null);
             return;
           } else if (a.animation) {
-            const o = this.digitalPlayground.getAnimation(a.animation.url), y = a.animation.needRender, I = a.animation.repeat !== this.state.currentAnimationRepeat;
-            (o !== this.state.currentAnimation || I || y && !this.hasProcessedNeedRenderForTimestamp(a.keyframeIndex)) && (y && o === this.state.currentAnimation && this.markNeedRenderProcessedForTimestamp(a.keyframeIndex), this.state.currentAnimation = o, this.state.currentAnimationRepeat = a.animation.repeat, this.playAnimation({
-              animation: o,
+            const m = this.digitalPlayground.getAnimation(a.animation.url), c = a.animation.needRender, A = a.animation.repeat !== this.state.currentAnimationRepeat;
+            (m !== this.state.currentAnimation || A || c && !this.hasProcessedNeedRenderForTimestamp(a.keyframeIndex)) && (c && m === this.state.currentAnimation && this.markNeedRenderProcessedForTimestamp(a.keyframeIndex), this.state.currentAnimation = m, this.state.currentAnimationRepeat = a.animation.repeat, this.playAnimation({
+              animation: m,
               repeat: a.animation.repeat,
-              switchDuration: (p = a.animation.switchDuration) != null ? p : v
-            })), this.mixer.update(h / 1e3), a.animation.isOver === !0 && (this.action.paused = !0, this.action.time = this.state.currentAnimation.duration, this.mixer.update(0));
+              switchDuration: (g = a.animation.switchDuration) != null ? g : F
+            })), this.mixer.update(l / 1e3), a.animation.isOver === !0 && (this.action.paused = !0, this.action.time = this.state.currentAnimation.duration, this.mixer.update(0));
           }
-          this.updateKeyframeItems((k = a.animation) == null ? void 0 : k.item);
-          for (const o of this.items) {
-            const y = this.digitalPlayground.getDigitalItem(o.model);
-            y && (this.keyframesManager.getStateByTime(this.state.currentTime, o.keyframes, "item").visible === !0 ? y.visible = !0 : y.visible = !1);
+          this.updateKeyframeItems((y = a.animation) == null ? void 0 : y.item);
+          for (const m of this.items) {
+            const c = this.digitalPlayground.getDigitalItem(m.model);
+            c && (this.keyframesManager.getStateByTime(this.state.currentTime, m.keyframes, "item").visible === !0 ? c.visible = !0 : c.visible = !1);
           }
-          for (let o = 0; o < this.effects.length; o++) {
-            const y = this.effects[o];
-            if (y.type === "frameSequence") {
-              const I = y.type + o;
-              if (!this.effectObjects.has(I)) {
-                const P = new t.PlaneGeometry(1, 1), R = new t.MeshBasicMaterial({
+          for (let m = 0; m < this.effects.length; m++) {
+            const c = this.effects[m];
+            if (c.type === "frameSequence") {
+              const A = c.type + m;
+              if (!this.effectObjects.has(A)) {
+                const M = new t.PlaneGeometry(1, 1), P = new t.MeshBasicMaterial({
                   transparent: !0
-                }), F = new t.Mesh(P, R);
-                F.rotateX(-Math.PI / 2), F.position.copy(new t.Vector3().fromArray(y.position)), this.effectObjects.set(I, F), this.effectsGroup.add(F);
+                }), T = new t.Mesh(M, P);
+                T.rotateX(-Math.PI / 2), T.position.copy(new t.Vector3().fromArray(c.position)), this.effectObjects.set(A, T), this.effectsGroup.add(T);
               }
-              const A = this.effectObjects.get(I), M = this.keyframesManager.getStateByTime(this.state.currentTime, this.effects[o].keyframes, "effect"), x = m.get(M.image);
-              A.material.map = x, A.visible = M.visible;
+              const I = this.effectObjects.get(A), w = this.keyframesManager.getStateByTime(this.state.currentTime, this.effects[m].keyframes, "effect"), x = f.get(w.image);
+              I.material.map = x, I.visible = w.visible;
             }
           }
-          this.model.needsRender = !0, this.animationFrameId = requestAnimationFrame(u);
+          this.model.needsRender = !0, this.animationFrameId = requestAnimationFrame(p);
         };
-        this.animationFrameId && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null), this.animationFrameId = requestAnimationFrame(u);
+        this.animationFrameId && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null), this.animationFrameId = requestAnimationFrame(p);
       });
     });
   }
@@ -161,30 +186,30 @@ class O {
    */
   prepareExternalDrive(e) {
     this.clearProcessedNeedRenderKeyframeIndices();
-    const { keyframes: i, items: s, effects: f } = e || {};
-    this.keyframes = i || this.keyframes, this.items = s || this.items, this.effects = f || this.effects, this.state.currentAnimation = null, this.state.currentAnimationRepeat = !1, this.state.playing = !0, this.keyframes.length > 0 && !this.state.currentTime && this.init();
-    for (const d of this.items) {
-      const m = this.digitalPlayground.getDigitalItem(d.model);
-      if (m) {
+    const { keyframes: i, items: s, effects: r } = e || {};
+    this.keyframes = i || this.keyframes, this.items = s || this.items, this.effects = r || this.effects, this.state.currentAnimation = null, this.state.currentAnimationRepeat = !1, this.state.playing = !0, this.keyframes.length > 0 && !this.state.currentTime && this.init();
+    for (const u of this.items) {
+      const f = this.digitalPlayground.getDigitalItem(u.model);
+      if (f) {
         let n = null;
-        const u = this.model.children[0].children.find((p) => p instanceof t.Bone), l = this.model.children[0].children.find((p) => p instanceof t.SkinnedMesh);
-        if (!u || !l)
+        const p = this.model.children[0].children.find((y) => y instanceof t.Bone), d = this.model.children[0].children.find((y) => y instanceof t.SkinnedMesh);
+        if (!p || !d)
           throw new Error("模型骨骼缺失");
-        if (this.model.children[0].children[2].traverse((p) => {
-          p instanceof t.Bone && p.name === "RightHand" && (n = p);
+        if (this.model.children[0].children[2].traverse((y) => {
+          y instanceof t.Bone && y.name === "RightHand" && (n = y);
         }), !n)
           throw new Error("没有找到绑定的骨骼");
-        n.add(m);
-        const h = new t.Vector3(), a = new t.Quaternion(), g = new t.Vector3();
-        new t.Matrix4().fromArray(d.initialMatrix).decompose(h, a, g), m.position.copy(h), m.quaternion.copy(a), m.scale.copy(g), m.updateMatrixWorld(!0);
+        n.add(f);
+        const l = new t.Vector3(), a = new t.Quaternion(), g = new t.Vector3();
+        new t.Matrix4().fromArray(u.initialMatrix).decompose(l, a, g), f.position.copy(l), f.quaternion.copy(a), f.scale.copy(g), f.updateMatrixWorld(!0);
       }
     }
-    const r = new t.TextureLoader();
-    for (const d of this.effects)
-      if (d.type === "frameSequence")
-        for (const m of d.keyframes)
-          m.image && r.load(m.image, (n) => {
-            n.name = m.image, this.externalTextures.set(m.image, n);
+    const o = new t.TextureLoader();
+    for (const u of this.effects)
+      if (u.type === "frameSequence")
+        for (const f of u.keyframes)
+          f.image && o.load(f.image, (n) => {
+            n.name = f.image, this.externalTextures.set(f.image, n);
           });
   }
   /**
@@ -194,51 +219,58 @@ class O {
    * @param delta 距上一帧的时间增量(ms)，用于推进骨骼动画 mixer
    */
   renderAtTime(e, i) {
-    var f, r, d, m;
+    var r, o, u, f;
     this.state.currentTime = e;
     const s = this.keyframesManager.getStateByTime(e, this.keyframes, "model");
-    if (this.trace.addPoint(s.translation), this.curveLine.geometry = new t.BufferGeometry().setFromPoints(this.trace.tracePoints), this.model.position.copy(s.translation), this.model.quaternion.copy(s.quaternion), this.model.scale.copy(s.scale), s.isFinal) {
+    if (this.showTrace && (this.trace.addPoint(s.translation), this.curveLine.geometry = new t.BufferGeometry().setFromPoints(this.trace.tracePoints)), this.model.position.copy(s.translation), this.model.quaternion.copy(s.quaternion), this.model.scale.copy(s.scale), s.isFinal) {
       this.model.visible = !1, this.container.visible = !1, this.model.needsRender = !0;
       return;
     }
     if (this.container.visible = !0, this.model.visible = s.visible, s.animation) {
-      const n = this.digitalPlayground.getAnimation(s.animation.url), u = s.animation.needRender, l = s.animation.repeat !== this.state.currentAnimationRepeat, h = i === 0;
-      if ((n !== this.state.currentAnimation || l || u && !this.hasProcessedNeedRenderForTimestamp(s.keyframeIndex)) && (u && n === this.state.currentAnimation && this.markNeedRenderProcessedForTimestamp(s.keyframeIndex), this.state.currentAnimation = n, this.state.currentAnimationRepeat = s.animation.repeat, this.playAnimation({
+      const n = this.digitalPlayground.getAnimation(s.animation.url), p = s.animation.needRender, d = s.animation.repeat !== this.state.currentAnimationRepeat, l = i === 0;
+      if ((n !== this.state.currentAnimation || d || p && !this.hasProcessedNeedRenderForTimestamp(s.keyframeIndex)) && (p && n === this.state.currentAnimation && this.markNeedRenderProcessedForTimestamp(s.keyframeIndex), this.state.currentAnimation = n, this.state.currentAnimationRepeat = s.animation.repeat, l ? this.switchAnimationImmediately(n, s.animation.repeat) : this.playAnimation({
         animation: n,
         repeat: s.animation.repeat,
-        // seek 时不做淡入淡出（淡入靠 delta 推进，seek 下不会进展，会得到错误姿态）
-        switchDuration: h ? 0 : (f = s.animation.switchDuration) != null ? f : v
-      })), h) {
+        switchDuration: (r = s.animation.switchDuration) != null ? r : F
+      })), l) {
         const g = this.state.currentAnimation;
         if (this.action && g) {
-          const p = (d = (r = this.keyframes[s.keyframeIndex]) == null ? void 0 : r.timeStamp) != null ? d : 0, k = Math.max(0, (e - p) / 1e3), o = g.duration || 0, y = s.animation.repeat && o > 0 ? k % o : Math.min(k, o);
-          this.action.paused = !1, this.action.time = y, this.mixer.update(0), this.action.paused = !0;
+          const y = (u = (o = this.keyframes[s.keyframeIndex]) == null ? void 0 : o.timeStamp) != null ? u : 0, m = Math.max(0, (e - y) / 1e3), c = g.duration || 0, A = s.animation.repeat && c > 0 ? m % c : Math.min(m, c);
+          this.action.paused = !1, this.action.time = A, this.mixer.update(0), this.action.paused = !0;
         }
       } else
         this.action && (this.action.paused = !1), this.mixer.update(i / 1e3), s.animation.isOver === !0 && (this.action.paused = !0, this.action.time = this.state.currentAnimation.duration, this.mixer.update(0));
     }
-    this.updateKeyframeItems((m = s.animation) == null ? void 0 : m.item);
+    this.updateKeyframeItems((f = s.animation) == null ? void 0 : f.item);
     for (const n of this.items) {
-      const u = this.digitalPlayground.getDigitalItem(n.model);
-      if (u) {
-        const l = this.keyframesManager.getStateByTime(e, n.keyframes, "item");
-        u.visible = l.visible === !0;
+      const p = this.digitalPlayground.getDigitalItem(n.model);
+      if (p) {
+        const d = this.keyframesManager.getStateByTime(e, n.keyframes, "item");
+        p.visible = d.visible === !0;
       }
     }
     for (let n = 0; n < this.effects.length; n++) {
-      const u = this.effects[n];
-      if (u.type === "frameSequence") {
-        const l = u.type + n;
-        if (!this.effectObjects.has(l)) {
-          const p = new t.PlaneGeometry(1, 1), k = new t.MeshBasicMaterial({ transparent: !0 }), o = new t.Mesh(p, k);
-          o.rotateX(-Math.PI / 2), o.position.copy(new t.Vector3().fromArray(u.position)), this.effectObjects.set(l, o), this.effectsGroup.add(o);
+      const p = this.effects[n];
+      if (p.type === "frameSequence") {
+        const d = p.type + n;
+        if (!this.effectObjects.has(d)) {
+          const y = new t.PlaneGeometry(1, 1), m = new t.MeshBasicMaterial({ transparent: !0 }), c = new t.Mesh(y, m);
+          c.rotateX(-Math.PI / 2), c.position.copy(new t.Vector3().fromArray(p.position)), this.effectObjects.set(d, c), this.effectsGroup.add(c);
         }
-        const h = this.effectObjects.get(l), a = this.keyframesManager.getStateByTime(e, this.effects[n].keyframes, "effect"), g = this.externalTextures.get(a.image);
-        h.material.map = g, h.visible = a.visible;
+        const l = this.effectObjects.get(d), a = this.keyframesManager.getStateByTime(e, this.effects[n].keyframes, "effect"), g = this.externalTextures.get(a.image);
+        l.material.map = g, l.visible = a.visible;
       }
     }
     this.model.needsRender = !0;
   }
+  /**
+   * 运动轨迹线开关（默认关闭、不显示）。仅 debug / 特殊需求由业务显式开启。
+   * - 开启：显示 curveLine，并回填当前时间点之前的轨迹（此后每帧继续累积）。
+   * - 关闭：隐藏并清空轨迹几何。
+   */
+  setTraceVisible(e) {
+    this.showTrace = e, this.curveLine.visible = e, e ? this.traceUpDate() : this.clearTrace();
+  }
   // 用于分段时 更新轨迹
   traceUpDate() {
     this.trace.clear();
@@ -276,16 +308,16 @@ class O {
   }
   // 根据当前帧的 items 动态绑定/解绑道具
   updateKeyframeItems(e) {
-    var f;
+    var r;
     const i = (e == null ? void 0 : e.url) || null;
-    for (const [r, d] of this.attachedItems)
-      i !== r && ((f = d.parent) == null || f.remove(d), this.attachedItems.delete(r));
+    for (const [o, u] of this.attachedItems)
+      i !== o && ((r = u.parent) == null || r.remove(u), this.attachedItems.delete(o));
     if (!i)
       return;
     const s = this.getRightHandBone();
     if (s && !this.attachedItems.has(i)) {
-      const r = this.digitalPlayground.getDigitalItem(i);
-      r && (s.add(r), this.attachedItems.set(i, r));
+      const o = this.digitalPlayground.getDigitalItem(i);
+      o && (s.add(o), this.attachedItems.set(i, o));
     }
   }
   // 解绑所有 keyframe 道具

package/libs/DigitalPerformancePlugin/core/DigitalPlayground.d.ts

@@ -10,6 +10,8 @@ export declare class DigitalPlayground {
     private digitalItemMap;
     private skeletalAnimationMap;
     private debugMode;
+    /** 运动轨迹线开关（默认关闭）。应用到已加载及后续加载的所有 DigitalHuman。 */
+    private showTrace;
     constructor(debugMode?: boolean);
     setScript(script: DigitalScript): void;
     loadModel(url: string, id?: string): Promise<DigitalHuman>;
@@ -32,6 +34,11 @@ export declare class DigitalPlayground {
     continue(): void;
     reset(): void;
     setTimelineTo(time: number): void;
+    /**
+     * 运动轨迹线开关（默认关闭）。作用于当前所有 DigitalHuman，并记忆给后续加载的模型。
+     * 仅 debug / 特殊需求由业务经插件显式开启。
+     */
+    setTraceVisible(visible: boolean): void;
     /**
      * 销毁 playground
      */