@aura3d/editor-runtime 1.0.6

package/src/TimelineRuntimeBridge.ts

@@ -0,0 +1,280 @@
+import { TimelineModel } from "./TimelineModel";
+import type {
+  TimelineActiveClipSnapshot,
+  TimelineClipBlendMode,
+  TimelineSignalEventSnapshot,
+  TimelineSnapshot
+} from "./TimelineModel";
+
+export interface TimelineRuntimeBindingConfig {
+  readonly trackId?: string;
+  readonly trackName?: string;
+  readonly targetId: string;
+  readonly assetId?: string;
+  readonly clipNameMap?: Record<string, string>;
+}
+
+export interface TimelineRuntimeAnimationApplication {
+  readonly targetId: string;
+  readonly trackId: string;
+  readonly trackName: string;
+  readonly clipId: string;
+  readonly clipName: string;
+  readonly assetId?: string;
+  readonly localTime: number;
+  readonly assetTime: number;
+  readonly normalizedTime: number;
+  readonly blendWeight: number;
+  readonly blendMode: TimelineClipBlendMode;
+  readonly playback: TimelineSnapshot["playback"];
+  readonly properties: Record<string, string | number | boolean>;
+}
+
+export interface TimelineRuntimeSignalDispatch {
+  readonly targetId?: string;
+  readonly trackId: string;
+  readonly trackName: string;
+  readonly clipId: string;
+  readonly clipName: string;
+  readonly event: string;
+  readonly time: number;
+  readonly localTime: number;
+  readonly properties: Record<string, string | number | boolean>;
+}
+
+export interface TimelineRuntimeTarget {
+  readonly id: string;
+  applyTimelineAnimation?(application: TimelineRuntimeAnimationApplication): void;
+  applyTimelineSignal?(dispatch: TimelineRuntimeSignalDispatch): void;
+  snapshot?(): unknown;
+}
+
+export interface TimelineRuntimeBridgeConfig {
+  readonly timeline: TimelineModel;
+  readonly targets: readonly TimelineRuntimeTarget[];
+  readonly bindings?: readonly TimelineRuntimeBindingConfig[];
+  readonly strictBindings?: boolean;
+  readonly dispatchSignals?: boolean;
+}
+
+export interface TimelineRuntimeTargetSnapshot {
+  readonly id: string;
+  readonly appliedAnimationCount: number;
+  readonly dispatchedSignalCount: number;
+  readonly snapshot?: unknown;
+}
+
+export interface TimelineRuntimeBridgeSnapshot {
+  readonly kind: "aura-editor-timeline-runtime-bridge";
+  readonly timeline: TimelineSnapshot;
+  readonly appliedAnimationCount: number;
+  readonly dispatchedSignalCount: number;
+  readonly warnings: readonly string[];
+  readonly targets: readonly TimelineRuntimeTargetSnapshot[];
+  readonly lastApplications: readonly TimelineRuntimeAnimationApplication[];
+  readonly lastSignals: readonly TimelineRuntimeSignalDispatch[];
+  readonly evidence: {
+    readonly timelineToRuntimeBridge: true;
+    readonly deterministicApplyAt: true;
+    readonly animationClipBinding: boolean;
+    readonly signalDispatch: boolean;
+    readonly runtimeTargetSnapshots: boolean;
+  };
+}
+
+interface TargetCounters {
+  appliedAnimationCount: number;
+  dispatchedSignalCount: number;
+}
+
+export class TimelineRuntimeBridge {
+  private readonly timeline: TimelineModel;
+  private readonly targets = new Map<string, TimelineRuntimeTarget>();
+  private readonly counters = new Map<string, TargetCounters>();
+  private readonly bindings: readonly TimelineRuntimeBindingConfig[];
+  private readonly strictBindings: boolean;
+  private readonly dispatchSignals: boolean;
+  private readonly seenSignalKeys = new Set<string>();
+  private lastTimelineTime = 0;
+  private lastSnapshot: TimelineRuntimeBridgeSnapshot;
+
+  constructor(config: TimelineRuntimeBridgeConfig) {
+    this.timeline = config.timeline;
+    this.bindings = config.bindings ?? [];
+    this.strictBindings = config.strictBindings ?? false;
+    this.dispatchSignals = config.dispatchSignals ?? true;
+    for (const target of config.targets) {
+      const id = target.id.trim();
+      if (!id) throw new Error("Timeline runtime target id is required.");
+      if (this.targets.has(id)) throw new Error(`Duplicate timeline runtime target id: ${id}`);
+      this.targets.set(id, target);
+      this.counters.set(id, { appliedAnimationCount: 0, dispatchedSignalCount: 0 });
+    }
+    this.lastSnapshot = this.createBridgeSnapshot(this.timeline.snapshot(), [], [], []);
+  }
+
+  step(deltaSeconds: number): TimelineRuntimeBridgeSnapshot {
+    this.timeline.tick(deltaSeconds);
+    return this.applyCurrent();
+  }
+
+  applyAt(time: number, options: { readonly replaySignals?: boolean } = {}): TimelineRuntimeBridgeSnapshot {
+    this.timeline.seek(time);
+    if (options.replaySignals) this.resetSignalCursor();
+    return this.applyCurrent();
+  }
+
+  applyCurrent(): TimelineRuntimeBridgeSnapshot {
+    const timelineSnapshot = this.timeline.snapshot();
+    if (timelineSnapshot.time < this.lastTimelineTime) {
+      this.resetSignalCursor();
+    }
+    this.lastTimelineTime = timelineSnapshot.time;
+
+    const warnings: string[] = [];
+    const applications = this.applyAnimations(timelineSnapshot, warnings);
+    const signals = this.dispatchSignals ? this.applySignals(timelineSnapshot, warnings) : [];
+    this.lastSnapshot = this.createBridgeSnapshot(timelineSnapshot, applications, signals, warnings);
+    return this.lastSnapshot;
+  }
+
+  resetSignalCursor(): void {
+    this.seenSignalKeys.clear();
+  }
+
+  snapshot(): TimelineRuntimeBridgeSnapshot {
+    return this.lastSnapshot;
+  }
+
+  private applyAnimations(snapshot: TimelineSnapshot, warnings: string[]): TimelineRuntimeAnimationApplication[] {
+    const applications: TimelineRuntimeAnimationApplication[] = [];
+    for (const clip of snapshot.activeClips) {
+      if (clip.trackType !== "animation") continue;
+      const binding = this.resolveBinding(clip);
+      const targetId = clip.runtimeTargetId ?? binding?.targetId;
+      if (!targetId) {
+        this.warnOrThrow(`No runtime target binding for animation track ${clip.trackId}.`, warnings);
+        continue;
+      }
+      const target = this.targets.get(targetId);
+      if (!target) {
+        this.warnOrThrow(`Runtime target is not registered for timeline binding: ${targetId}`, warnings);
+        continue;
+      }
+      const clipName = binding?.clipNameMap?.[clip.assetClipName ?? clip.clipName] ?? binding?.clipNameMap?.[clip.clipName] ?? clip.assetClipName ?? clip.clipName;
+      const application: TimelineRuntimeAnimationApplication = {
+        targetId,
+        trackId: clip.trackId,
+        trackName: clip.trackName,
+        clipId: clip.clipId,
+        clipName,
+        assetId: clip.assetId ?? binding?.assetId,
+        localTime: clip.localTime,
+        assetTime: clip.assetTime,
+        normalizedTime: clip.normalizedTime,
+        blendWeight: clip.blendWeight,
+        blendMode: clip.blendMode,
+        playback: snapshot.playback,
+        properties: { ...clip.properties }
+      };
+      target.applyTimelineAnimation?.(application);
+      this.counters.get(targetId)!.appliedAnimationCount += 1;
+      applications.push(application);
+    }
+    return applications;
+  }
+
+  private applySignals(snapshot: TimelineSnapshot, warnings: string[]): TimelineRuntimeSignalDispatch[] {
+    const signals: TimelineRuntimeSignalDispatch[] = [];
+    for (const event of snapshot.signalEventDetails) {
+      const key = `${event.trackId}:${event.clipId}:${event.event}`;
+      if (this.seenSignalKeys.has(key)) continue;
+      this.seenSignalKeys.add(key);
+      const targetId = this.resolveSignalTargetId(event);
+      const dispatch: TimelineRuntimeSignalDispatch = {
+        targetId,
+        trackId: event.trackId,
+        trackName: event.trackName,
+        clipId: event.clipId,
+        clipName: event.clipName,
+        event: event.event,
+        time: event.time,
+        localTime: event.localTime,
+        properties: { ...event.properties }
+      };
+      if (targetId) {
+        const target = this.targets.get(targetId);
+        if (!target) {
+          this.warnOrThrow(`Runtime target is not registered for timeline signal: ${targetId}`, warnings);
+          signals.push(dispatch);
+          continue;
+        }
+        target.applyTimelineSignal?.(dispatch);
+        this.counters.get(targetId)!.dispatchedSignalCount += 1;
+      }
+      signals.push(dispatch);
+    }
+    return signals;
+  }
+
+  private resolveBinding(clip: TimelineActiveClipSnapshot): TimelineRuntimeBindingConfig | undefined {
+    return this.bindings.find((binding) => {
+      if (binding.trackId && binding.trackId === clip.trackId) return true;
+      if (binding.trackName && binding.trackName === clip.trackName) return true;
+      return false;
+    });
+  }
+
+  private resolveSignalTargetId(event: TimelineSignalEventSnapshot): string | undefined {
+    if (typeof event.properties.runtimeNodeId === "string" && event.properties.runtimeNodeId.trim().length > 0) return event.properties.runtimeNodeId;
+    if (typeof event.properties.targetId === "string" && event.properties.targetId.trim().length > 0) return event.properties.targetId;
+    const binding = this.bindings.find((candidate) => {
+      if (candidate.trackId && candidate.trackId === event.trackId) return true;
+      if (candidate.trackName && candidate.trackName === event.trackName) return true;
+      return false;
+    });
+    return binding?.targetId;
+  }
+
+  private createBridgeSnapshot(
+    timeline: TimelineSnapshot,
+    applications: readonly TimelineRuntimeAnimationApplication[],
+    signals: readonly TimelineRuntimeSignalDispatch[],
+    warnings: readonly string[]
+  ): TimelineRuntimeBridgeSnapshot {
+    return {
+      kind: "aura-editor-timeline-runtime-bridge",
+      timeline,
+      appliedAnimationCount: [...this.counters.values()].reduce((total, counter) => total + counter.appliedAnimationCount, 0),
+      dispatchedSignalCount: [...this.counters.values()].reduce((total, counter) => total + counter.dispatchedSignalCount, 0),
+      warnings,
+      targets: [...this.targets.values()].map((target) => {
+        const counter = this.counters.get(target.id)!;
+        return {
+          id: target.id,
+          appliedAnimationCount: counter.appliedAnimationCount,
+          dispatchedSignalCount: counter.dispatchedSignalCount,
+          snapshot: target.snapshot?.()
+        };
+      }),
+      lastApplications: applications,
+      lastSignals: signals,
+      evidence: {
+        timelineToRuntimeBridge: true,
+        deterministicApplyAt: true,
+        animationClipBinding: applications.length > 0,
+        signalDispatch: signals.length > 0,
+        runtimeTargetSnapshots: [...this.targets.values()].some((target) => typeof target.snapshot === "function")
+      }
+    };
+  }
+
+  private warnOrThrow(message: string, warnings: string[]): void {
+    if (this.strictBindings) throw new Error(message);
+    warnings.push(message);
+  }
+}
+
+export function createTimelineRuntimeBridge(config: TimelineRuntimeBridgeConfig): TimelineRuntimeBridge {
+  return new TimelineRuntimeBridge(config);
+}

package/src/TranslateGizmo.ts

@@ -0,0 +1,39 @@
+import { Gizmo, type GizmoDrag } from "./Gizmo";
+import { TransformCommand, type TransformLike } from "./commands/TransformCommand";
+
+export class TranslateGizmo extends Gizmo {
+  async drag(input: GizmoDrag): Promise<void> {
+    if (!this.target) return;
+    const current = readTransform(this.target);
+    const next = clone(current);
+    const delta = this.snapPositionDelta(input.delta);
+    if (input.axis === "x" || input.axis === "xy" || input.axis === "xz") next.position.x += delta;
+    if (input.axis === "y" || input.axis === "xy" || input.axis === "yz") next.position.y += delta;
+    if (input.axis === "z" || input.axis === "xz" || input.axis === "yz") next.position.z += delta;
+    if (input.axis === "uniform") {
+      next.position.x += delta;
+      next.position.y += delta;
+      next.position.z += delta;
+    }
+    await this.history.execute(new TransformCommand(this.target, next));
+  }
+}
+
+function readTransform(target: NonNullable<TranslateGizmo["target"]>): TransformLike {
+  if ("transform" in target) {
+    return {
+      position: { x: target.transform.position[0], y: target.transform.position[1], z: target.transform.position[2] },
+      rotation: { x: target.transform.rotation[0], y: target.transform.rotation[1], z: target.transform.rotation[2], w: target.transform.rotation[3] },
+      scale: { x: target.transform.scale[0], y: target.transform.scale[1], z: target.transform.scale[2] }
+    };
+  }
+  return clone(target);
+}
+
+function clone(transform: TransformLike): TransformLike {
+  return {
+    position: { ...transform.position },
+    rotation: transform.rotation ? { ...transform.rotation } : undefined,
+    scale: transform.scale ? { ...transform.scale } : undefined
+  };
+}

package/src/commands/CreateNodeCommand.ts

@@ -0,0 +1,23 @@
+import type { Command } from "../Command";
+
+export interface NodeContainer<TNode> {
+  add(node: TNode): void;
+  remove(node: TNode): void;
+}
+
+export class CreateNodeCommand<TNode> implements Command {
+  readonly name = "Create Node";
+
+  constructor(
+    private readonly container: NodeContainer<TNode>,
+    private readonly node: TNode
+  ) {}
+
+  execute(): void {
+    this.container.add(this.node);
+  }
+
+  undo(): void {
+    this.container.remove(this.node);
+  }
+}

package/src/commands/DeleteNodeCommand.ts

@@ -0,0 +1,74 @@
+import type { Command } from "../Command";
+import type { NodeContainer } from "./CreateNodeCommand";
+
+interface SceneNodeLike {
+  readonly children: SceneNodeLike[];
+  parent: SceneNodeLike | null;
+  addChild(child: SceneNodeLike): unknown;
+  removeChild(child: SceneNodeLike): boolean;
+  removeFromParent(): boolean;
+  markWorldDirty?(): void;
+}
+
+export class DeleteNodeCommand<TNode> implements Command {
+  readonly name = "Delete Node";
+  private sceneParent: SceneNodeLike | null = null;
+  private sceneIndex = -1;
+
+  constructor(
+    private readonly container: NodeContainer<TNode>,
+    private readonly node: TNode
+  ) {}
+
+  execute(): void {
+    const sceneNode = asSceneNode(this.node);
+    if (sceneNode) {
+      this.sceneParent = sceneNode.parent;
+      this.sceneIndex = this.sceneParent?.children.indexOf(sceneNode) ?? -1;
+      if (this.sceneParent && sceneNode.removeFromParent()) {
+        return;
+      }
+      this.sceneParent = null;
+      this.sceneIndex = -1;
+    }
+
+    this.container.remove(this.node);
+  }
+
+  undo(): void {
+    const sceneNode = asSceneNode(this.node);
+    if (sceneNode && this.sceneParent) {
+      this.sceneParent.addChild(sceneNode);
+      if (this.sceneIndex >= 0) {
+        const currentIndex = this.sceneParent.children.indexOf(sceneNode);
+        if (currentIndex >= 0 && currentIndex !== this.sceneIndex) {
+          this.sceneParent.children.splice(currentIndex, 1);
+          this.sceneParent.children.splice(Math.min(this.sceneIndex, this.sceneParent.children.length), 0, sceneNode);
+          sceneNode.markWorldDirty?.();
+        }
+      }
+      return;
+    }
+
+    this.container.add(this.node);
+  }
+}
+
+function asSceneNode(value: unknown): SceneNodeLike | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+
+  const candidate = value as Partial<SceneNodeLike>;
+  if (
+    Array.isArray(candidate.children) &&
+    "parent" in candidate &&
+    typeof candidate.addChild === "function" &&
+    typeof candidate.removeChild === "function" &&
+    typeof candidate.removeFromParent === "function"
+  ) {
+    return candidate as SceneNodeLike;
+  }
+
+  return undefined;
+}

package/src/commands/ReparentNodeCommand.ts

@@ -0,0 +1,55 @@
+import type { Command } from "../Command";
+
+interface ParentLike<TNode> {
+  readonly children: TNode[];
+  addChild(child: TNode): unknown;
+  removeChild(child: TNode): boolean;
+}
+
+interface ChildLike<TNode> {
+  parent: ParentLike<TNode> | null;
+  markWorldDirty?(): void;
+}
+
+export class ReparentNodeCommand<TNode extends ChildLike<TNode>> implements Command {
+  readonly name = "Reparent Node";
+  private readonly oldParent: ParentLike<TNode> | null;
+  private readonly oldIndex: number;
+  private readonly newIndex: number;
+
+  constructor(
+    private readonly node: TNode,
+    private readonly newParent: ParentLike<TNode>,
+    newIndex?: number
+  ) {
+    this.oldParent = node.parent;
+    this.oldIndex = this.oldParent?.children.indexOf(node) ?? -1;
+    this.newIndex = newIndex ?? newParent.children.length;
+  }
+
+  execute(): void {
+    this.move(this.newParent, this.newIndex);
+  }
+
+  undo(): void {
+    if (!this.oldParent) {
+      this.node.parent?.removeChild(this.node);
+      return;
+    }
+    this.move(this.oldParent, this.oldIndex);
+  }
+
+  private move(parent: ParentLike<TNode>, index: number): void {
+    if (this.node.parent !== parent) {
+      this.node.parent?.removeChild(this.node);
+      parent.addChild(this.node);
+    }
+    const currentIndex = parent.children.indexOf(this.node);
+    const targetIndex = Math.max(0, Math.min(index, parent.children.length - 1));
+    if (currentIndex >= 0 && currentIndex !== targetIndex) {
+      parent.children.splice(currentIndex, 1);
+      parent.children.splice(targetIndex, 0, this.node);
+      this.node.markWorldDirty?.();
+    }
+  }
+}

package/src/commands/SetPropertyCommand.ts

@@ -0,0 +1,47 @@
+import type { Command } from "../Command";
+
+export class SetPropertyCommand<T extends object> implements Command {
+  readonly name = "Set Property";
+  private readonly before: unknown;
+
+  constructor(
+    private readonly target: T,
+    private readonly path: readonly string[],
+    private readonly after: unknown
+  ) {
+    if (path.length === 0) {
+      throw new Error("Property path cannot be empty");
+    }
+    this.before = this.read();
+  }
+
+  execute(): void {
+    this.write(this.after);
+  }
+
+  undo(): void {
+    this.write(this.before);
+  }
+
+  private read(): unknown {
+    let cursor: unknown = this.target;
+    for (const segment of this.path) {
+      if (cursor === null || typeof cursor !== "object" || !(segment in cursor)) {
+        throw new Error(`Invalid property path: ${this.path.join(".")}`);
+      }
+      cursor = (cursor as Record<string, unknown>)[segment];
+    }
+    return cursor;
+  }
+
+  private write(value: unknown): void {
+    let cursor: unknown = this.target;
+    for (const segment of this.path.slice(0, -1)) {
+      if (cursor === null || typeof cursor !== "object" || !(segment in cursor)) {
+        throw new Error(`Invalid property path: ${this.path.join(".")}`);
+      }
+      cursor = (cursor as Record<string, unknown>)[segment];
+    }
+    (cursor as Record<string, unknown>)[this.path[this.path.length - 1]] = value;
+  }
+}

package/src/commands/TransformCommand.ts

@@ -0,0 +1,107 @@
+import type { Command } from "../Command";
+
+export interface TransformLike {
+  position: { x: number; y: number; z: number };
+  rotation?: { x: number; y: number; z: number; w?: number };
+  scale?: { x: number; y: number; z: number };
+}
+
+export interface SceneTransformTargetLike {
+  readonly transform: {
+    readonly position: [number, number, number];
+    readonly rotation: [number, number, number, number];
+    readonly scale: [number, number, number];
+    setPosition(x: number, y: number, z: number): unknown;
+    setRotation(x: number, y: number, z: number, w: number): unknown;
+    setScale(x: number, y: number, z: number): unknown;
+  };
+}
+
+export type TransformTarget = TransformLike | SceneTransformTargetLike;
+
+function cloneTransform(transform: TransformLike): TransformLike {
+  return {
+    position: { ...transform.position },
+    rotation: transform.rotation ? { ...transform.rotation } : undefined,
+    scale: transform.scale ? { ...transform.scale } : undefined
+  };
+}
+
+function readTransform(target: TransformTarget): TransformLike {
+  if ("transform" in target) {
+    return {
+      position: {
+        x: target.transform.position[0],
+        y: target.transform.position[1],
+        z: target.transform.position[2]
+      },
+      rotation: {
+        x: target.transform.rotation[0],
+        y: target.transform.rotation[1],
+        z: target.transform.rotation[2],
+        w: target.transform.rotation[3]
+      },
+      scale: {
+        x: target.transform.scale[0],
+        y: target.transform.scale[1],
+        z: target.transform.scale[2]
+      }
+    };
+  }
+  return cloneTransform(target);
+}
+
+function applyTransform(target: TransformTarget, transform: TransformLike): void {
+  if ("transform" in target) {
+    target.transform.setPosition(transform.position.x, transform.position.y, transform.position.z);
+    if (transform.rotation) {
+      target.transform.setRotation(
+        transform.rotation.x,
+        transform.rotation.y,
+        transform.rotation.z,
+        transform.rotation.w ?? 1
+      );
+    }
+    if (transform.scale) {
+      target.transform.setScale(transform.scale.x, transform.scale.y, transform.scale.z);
+    }
+    return;
+  }
+  target.position = { ...transform.position };
+  target.rotation = transform.rotation ? { ...transform.rotation } : undefined;
+  target.scale = transform.scale ? { ...transform.scale } : undefined;
+}
+
+export class TransformCommand implements Command {
+  readonly name = "Transform";
+  private readonly before: TransformLike;
+  private readonly after: TransformLike;
+
+  constructor(
+    private readonly target: TransformTarget,
+    next: TransformLike,
+    before?: TransformLike
+  ) {
+    this.before = cloneTransform(before ?? readTransform(target));
+    this.after = cloneTransform(next);
+  }
+
+  execute(): void {
+    applyTransform(this.target, this.after);
+  }
+
+  undo(): void {
+    applyTransform(this.target, this.before);
+  }
+
+  canMerge(next: Command): boolean {
+    return next instanceof TransformCommand && next.target === this.target;
+  }
+
+  merge(next: Command): Command {
+    if (!(next instanceof TransformCommand) || next.target !== this.target) {
+      throw new Error("TransformCommand can only merge commands for the same target.");
+    }
+    return new TransformCommand(this.target, next.after, this.before);
+  }
+}