@eva/plugin-tween 2.1.0-beta.1

package/lib/Tween.ts

@@ -0,0 +1,206 @@
+import { Component, decorators } from '@eva/eva.js';
+import { getSignalBus } from '@eva/plugin-signal-bus';
+import { Easing } from './easing';
+import { bindPath, PathBinding } from './path';
+import type { TweenParams, TweenStep, EasingName } from './types';
+
+interface RunningStep {
+  binding: PathBinding;
+  from: number;
+  to: number;
+  duration: number;
+  easing: (t: number) => number;
+  delay: number;
+  elapsed: number;
+  done: boolean;
+}
+
+/**
+ * Tween 组件 — Godot Tween 等价物。
+ *
+ * 与 plugin-transition 区别:
+ * - 不限制 target 类型(transform/Component/store 都行)
+ * - 内置 sequence 与 parallel 编排
+ * - 完成 emit 命名信号
+ *
+ * DSL 用法:
+ * ```json
+ * {
+ *   "type": "Tween",
+ *   "props": {
+ *     "step": {
+ *       "target": "components.RocketAimer.currentAngleDeg",
+ *       "from": -60, "to": 60, "duration": 1500, "easing": "easeInOutQuad"
+ *     },
+ *     "yoyo": true, "loop": -1, "autostart": true
+ *   }
+ * }
+ * ```
+ */
+@decorators.componentObserver({})
+export class Tween extends Component<TweenParams> {
+  static componentName = 'Tween';
+
+  private steps: TweenStep[] = [];
+  private parallel = false;
+  private yoyo = false;
+  private loop = 0;
+  private autostart = false;
+  private signal?: string;
+
+  private running: RunningStep[] = [];
+  private isPlaying = false;
+  private playedLoops = 0;
+  private cursor = 0; // sequence 当前 step
+  private direction: 1 | -1 = 1;
+
+  init(params?: TweenParams) {
+    if (!params) return;
+    this.steps = params.step ? [params.step] : (params.steps ?? []);
+    this.parallel = params.parallel ?? false;
+    this.yoyo = params.yoyo ?? false;
+    this.loop = params.loop ?? 0;
+    this.autostart = params.autostart ?? false;
+    this.signal = params.signal;
+  }
+
+  awake() {
+    if (this.autostart) this.play();
+  }
+
+  /** 重新开始 */
+  play() {
+    this.buildRunning();
+    this.isPlaying = true;
+    this.playedLoops = 0;
+    this.cursor = 0;
+    this.direction = 1;
+  }
+
+  pause() {
+    this.isPlaying = false;
+  }
+
+  resume() {
+    if (this.running.length) this.isPlaying = true;
+  }
+
+  stop() {
+    this.isPlaying = false;
+    this.running = [];
+  }
+
+  private buildRunning() {
+    this.running = [];
+    for (const s of this.steps) {
+      const binding = bindPath(this.gameObject, s.target);
+      if (!binding) {
+        // eslint-disable-next-line no-console
+        console.warn(`[plugin-tween] binding miss: ${s.target}`);
+        continue;
+      }
+      const from = s.from ?? binding.read();
+      this.running.push({
+        binding,
+        from,
+        to: s.to,
+        duration: Math.max(1, s.duration),
+        easing: Easing[(s.easing ?? 'linear') as EasingName] ?? Easing.linear,
+        delay: s.delay ?? 0,
+        elapsed: 0,
+        done: false,
+      });
+    }
+  }
+
+  update(e: { deltaTime: number }) {
+    if (!this.isPlaying || this.running.length === 0) return;
+    const dt = e.deltaTime;
+
+    if (this.parallel) {
+      this.advanceParallel(dt);
+    } else {
+      this.advanceSequence(dt);
+    }
+  }
+
+  private advanceParallel(dt: number) {
+    let allDone = true;
+    for (const r of this.running) {
+      if (r.done) continue;
+      this.tickStep(r, dt);
+      if (!r.done) allDone = false;
+    }
+    if (allDone) this.onCycleEnd();
+  }
+
+  private advanceSequence(dt: number) {
+    while (dt > 0 && this.cursor < this.running.length) {
+      const r = this.running[this.cursor];
+      if (r.done) {
+        this.cursor++;
+        continue;
+      }
+      const before = r.elapsed;
+      this.tickStep(r, dt);
+      const used = r.elapsed - before;
+      dt -= used;
+      if (!r.done) break;
+      this.cursor++;
+    }
+    if (this.cursor >= this.running.length) this.onCycleEnd();
+  }
+
+  private tickStep(r: RunningStep, dt: number) {
+    if (r.delay > 0) {
+      const used = Math.min(r.delay, dt);
+      r.delay -= used;
+      // 把延时算进 elapsed 不合适,留给 sequence 减 dt
+      // 这里直接消耗 dt 后返回
+      return;
+    }
+    r.elapsed += dt;
+    const t = Math.min(1, r.elapsed / r.duration);
+    const v = r.from + (r.to - r.from) * r.easing(t);
+    r.binding.write(v);
+    if (t >= 1) {
+      r.done = true;
+    }
+  }
+
+  private onCycleEnd() {
+    this.playedLoops++;
+    const shouldLoop = this.loop === -1 || this.playedLoops <= this.loop;
+    if (this.yoyo) {
+      this.direction = (this.direction === 1 ? -1 : 1) as 1 | -1;
+      // yoyo:反向重置
+      for (const r of this.running) {
+        const a = r.from;
+        r.from = r.to;
+        r.to = a;
+        r.elapsed = 0;
+        r.done = false;
+      }
+      this.cursor = 0;
+      if (!shouldLoop && this.direction === 1) {
+        this.finish();
+      }
+      return;
+    }
+    if (shouldLoop) {
+      for (const r of this.running) {
+        r.elapsed = 0;
+        r.done = false;
+      }
+      this.cursor = 0;
+      return;
+    }
+    this.finish();
+  }
+
+  private finish() {
+    this.isPlaying = false;
+    if (this.signal) getSignalBus().emit(this.signal, { component: this });
+    getSignalBus().emit('tween:finish', { component: this });
+  }
+}

package/lib/TweenSystem.ts

@@ -0,0 +1,9 @@
+import { System } from '@eva/eva.js';
+
+/**
+ * Tween 没有跨实体编排,System 仅用于注册 plugin。
+ */
+export class TweenSystem extends System {
+  static systemName = 'Tween';
+  readonly name = 'Tween';
+}

package/lib/easing.ts

@@ -0,0 +1,48 @@
+import type { EasingName } from './types';
+
+const PI = Math.PI;
+const c1 = 1.70158;
+const c2 = c1 * 1.525;
+const c3 = c1 + 1;
+const c4 = (2 * PI) / 3;
+const c5 = (2 * PI) / 4.5;
+const n1 = 7.5625;
+const d1 = 2.75;
+
+function easeInBounce(x: number): number {
+  return 1 - easeOutBounce(1 - x);
+}
+function easeOutBounce(x: number): number {
+  if (x < 1 / d1) return n1 * x * x;
+  if (x < 2 / d1) return n1 * (x -= 1.5 / d1) * x + 0.75;
+  if (x < 2.5 / d1) return n1 * (x -= 2.25 / d1) * x + 0.9375;
+  return n1 * (x -= 2.625 / d1) * x + 0.984375;
+}
+
+export const Easing: Record<EasingName, (t: number) => number> = {
+  linear: (t) => t,
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => 1 - (1 - t) * (1 - t),
+  easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2),
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2),
+  easeInElastic: (t) => (t === 0 ? 0 : t === 1 ? 1 : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4)),
+  easeOutElastic: (t) => (t === 0 ? 0 : t === 1 ? 1 : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1),
+  easeInOutElastic: (t) => {
+    if (t === 0) return 0;
+    if (t === 1) return 1;
+    return t < 0.5
+      ? -(Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * c5)) / 2
+      : (Math.pow(2, -20 * t + 10) * Math.sin((20 * t - 11.125) * c5)) / 2 + 1;
+  },
+  easeInBack: (t) => c3 * t * t * t - c1 * t * t,
+  easeOutBack: (t) => 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2),
+  easeInOutBack: (t) =>
+    t < 0.5
+      ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+      : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2,
+  easeInBounce,
+  easeOutBounce,
+  easeInOutBounce: (t) => (t < 0.5 ? (1 - easeOutBounce(1 - 2 * t)) / 2 : (1 + easeOutBounce(2 * t - 1)) / 2),
+};

package/lib/index.ts

@@ -0,0 +1,4 @@
+export { Tween } from './Tween';
+export { TweenSystem } from './TweenSystem';
+export { Easing } from './easing';
+export type { TweenParams, TweenStep, EasingName } from './types';

package/lib/path.ts

@@ -0,0 +1,75 @@
+import type { Component, GameObject } from '@eva/eva.js';
+
+/**
+ * 把字符串路径解析成 (target, key) 二元组,以便就地写入。
+ *
+ * 支持:
+ *   - "transform.position.x"
+ *   - "transform.rotation"
+ *   - "components.<ComponentName>.<key>"     // 通过 componentName 找
+ *   - "store.<keyPath>"                       // 走 mx.store(若存在)
+ */
+export interface PathBinding {
+  read(): number;
+  write(v: number): void;
+}
+
+export function bindPath(go: GameObject, path: string): PathBinding | null {
+  const parts = path.split('.');
+  if (parts[0] === 'transform') {
+    const obj = go.transform as any;
+    return diveIntoObject(obj, parts.slice(1));
+  }
+  if (parts[0] === 'components' && parts.length >= 3) {
+    const compName = parts[1];
+    const comp = findComponent(go, compName);
+    if (!comp) return null;
+    return diveIntoObject(comp as any, parts.slice(2));
+  }
+  if (parts[0] === 'store' && parts.length >= 2) {
+    return bindStore(parts.slice(1).join('.'));
+  }
+  return null;
+}
+
+function diveIntoObject(root: any, keys: string[]): PathBinding | null {
+  if (!root || keys.length === 0) return null;
+  let parent = root;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const k = keys[i];
+    if (parent[k] == null) return null;
+    parent = parent[k];
+  }
+  const last = keys[keys.length - 1];
+  return {
+    read: () => Number(parent[last] ?? 0),
+    write: (v: number) => {
+      parent[last] = v;
+    },
+  };
+}
+
+function findComponent(go: GameObject, name: string): Component | null {
+  const comps: any[] = (go as any).components || [];
+  for (const c of comps) {
+    const cn = c?.constructor?.componentName;
+    if (cn === name) return c;
+  }
+  // 退路:Eva.js 部分版本支持 getComponent(name)
+  if (typeof (go as any).getComponent === 'function') {
+    return ((go as any).getComponent(name) as Component) ?? null;
+  }
+  return null;
+}
+
+function bindStore(key: string): PathBinding | null {
+  // mx.store 是宿主全局,不强依赖
+  const mx: any = (globalThis as any).mx;
+  if (!mx?.store) return null;
+  return {
+    read: () => Number(mx.store.get?.(key) ?? 0),
+    write: (v: number) => {
+      mx.store.update?.({ [key]: v });
+    },
+  };
+}

package/lib/types.ts

@@ -0,0 +1,37 @@
+export type EasingName =
+  | 'linear'
+  | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad'
+  | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic'
+  | 'easeInElastic' | 'easeOutElastic' | 'easeInOutElastic'
+  | 'easeInBack' | 'easeOutBack' | 'easeInOutBack'
+  | 'easeInBounce' | 'easeOutBounce' | 'easeInOutBounce';
+
+export interface TweenStep {
+  /** 目标路径,例如:
+   *  - "transform.position.x"
+   *  - "transform.rotation"
+   *  - "components.RocketAimer.currentAngleDeg"
+   *  - "store.score" (走 mx.store)
+   */
+  target: string;
+  from?: number;
+  to: number;
+  duration: number;
+  easing?: EasingName;
+  delay?: number;
+}
+
+export interface TweenParams {
+  /** 单步 = 一次性 to;steps = 多步序列 */
+  step?: TweenStep;
+  steps?: TweenStep[];
+  /** 是否并行执行 steps(默认 sequence) */
+  parallel?: boolean;
+  yoyo?: boolean;
+  /** -1 = 无限循环 */
+  loop?: number;
+  /** 是否自动开始 */
+  autostart?: boolean;
+  /** 完成后 emit 的信号 */
+  signal?: string;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@eva/plugin-tween",
+  "version": "2.1.0-beta.1",
+  "description": "Godot Tween 等价物 — 任意字段补间(transform / 自定义 Component / mx.store),支持 sequence/parallel/yoyo/loop。",
+  "main": "lib/index.ts",
+  "module": "lib/index.ts",
+  "types": "lib/index.ts",
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "eva.js",
+    "plugin",
+    "tween",
+    "godot"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@eva/eva.js": "2.1.0-beta.1",
+    "@eva/plugin-signal-bus": "2.1.0-beta.1"
+  }
+}