@haiyue/extensions 0.1.0

package/src/animation/Animation2DStateMachineVisualRuntime.ts

@@ -0,0 +1,282 @@
+import type { Entity } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+import type { ParsedAnimation } from '@haiyue/animation-spec';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
+import type { HyaAnimation2DEffectPayload } from './HyaAnimation2DClipAdapter.js';
+import {
+  Animation2DRuntime,
+  type Animation2DRuntimeNode,
+} from './Animation2DRuntime.js';
+import type { Animation2DEffectEvent, Animation2DPose } from './runtime/mixer/index.js';
+import {
+  audioAutoplayRejectedDiagnostic,
+  type AnimationStateMachineChannelDiagnostic,
+} from '../animation-state-machine/AnimationStateMachineChannels.js';
+
+/** State-machine-only pose writer kept out of the ordinary Animation2D bundle. */
+export class Animation2DStateMachineVisualRuntime extends Animation2DRuntime {
+  private readonly _particleOwners = new Map<string, string[]>();
+  private readonly _audioOwners = new Map<string, string[]>();
+  private readonly _effectPayloads = new Map<string, HyaAnimation2DEffectPayload>();
+  private readonly _diagnostics: AnimationStateMachineChannelDiagnostic[] = [];
+  private readonly _reportedAudioRejections = new Set<string>();
+
+  constructor(
+    owner: Entity,
+    animation: ParsedAnimation,
+    runtimeExtensions?: Animation2DExtensionRegistry,
+    assetManager?: AssetManager,
+  ) {
+    super(owner, animation, runtimeExtensions, assetManager);
+    for (const node of this._nodes) {
+      for (const particle of node.particles) {
+        particle.playing = false;
+        particle.emitting = false;
+        particle.clear();
+      }
+      for (const audio of node.audio) audio.exitStateMachine();
+    }
+  }
+
+  get diagnostics(): readonly AnimationStateMachineChannelDiagnostic[] {
+    return this._diagnostics;
+  }
+
+  get sideEffectOwnerCount(): number {
+    return ownerCount(this._particleOwners) + ownerCount(this._audioOwners);
+  }
+
+  resetSideEffects(): void {
+    this._particleOwners.clear();
+    this._audioOwners.clear();
+    this._effectPayloads.clear();
+    for (const node of this._nodes) {
+      for (const particle of node.particles) {
+        particle.playing = false;
+        particle.emitting = false;
+        particle.clear();
+      }
+      for (const audio of node.audio) audio.exitStateMachine();
+    }
+  }
+
+  applyPose(pose: Animation2DPose, playing = this._playing, speed = this._speed): void {
+    this._playing = playing;
+    this._speed = speed;
+    this._opacityMemo.clear();
+    for (const node of this._nodes) {
+      node.entity.disabled = false;
+      node.transform.setPosition(node.initialX, node.initialY);
+      node.transform.rotation = node.initialRotation;
+      node.transform.setScale(node.initialScaleX, node.initialScaleY);
+      node.opacity = node.initialOpacity;
+    }
+    for (const channel of pose.channels) {
+      const node = this._nodesById.get(channel.binding.targetId);
+      if (!node) {
+        throw new ReferenceError(`Animation2D pose references unknown node "${channel.binding.targetId}".`);
+      }
+      switch (channel.binding.path) {
+        case 'transform.position': {
+          const value = numericPoseValue(channel.value, channel.binding.id, 2);
+          node.transform.setPosition(value[0]!, -value[1]!);
+          break;
+        }
+        case 'transform.rotation': {
+          const value = numericPoseValue(channel.value, channel.binding.id, 1);
+          node.transform.rotation = -value[0]!;
+          break;
+        }
+        case 'transform.scale': {
+          const value = numericPoseValue(channel.value, channel.binding.id, 2);
+          node.transform.setScale(value[0]!, value[1]!);
+          break;
+        }
+        case 'opacity': {
+          const value = numericPoseValue(channel.value, channel.binding.id, 1);
+          node.opacity = clamp(value[0]!, 0, 1);
+          break;
+        }
+        case 'visibility':
+          if (typeof channel.value !== 'boolean') {
+            throw new TypeError(`Animation2D visibility binding "${channel.binding.id}" requires a boolean.`);
+          }
+          node.entity.disabled = !channel.value;
+          break;
+        default:
+          if (!this._applyStateMachineVisualChannel(node, channel.binding.path, channel.value)) {
+            throw new RangeError(`Animation2D state-machine runtime does not support pose binding path "${channel.binding.path}".`);
+          }
+      }
+    }
+    for (const node of this._nodes) this._applyVisualOpacity(node);
+    for (const [key, owners] of this._audioOwners) {
+      if (owners.length === 0) continue;
+      const target = parseEffectTargetKey(key);
+      const node = this._nodesById.get(target.targetId);
+      this._audioTarget(key)?.updateStateMachineProperties(
+        speed,
+        node ? this._resolveOpacity(node) : 1,
+      );
+    }
+    for (const effect of pose.effects) this._applyEffect(effect, playing, speed);
+    this._lastAppliedTime = Number.NaN;
+  }
+
+  override setPlaying(playing: boolean): void {
+    this._playing = playing;
+    for (const [key, owners] of this._particleOwners) {
+      if (owners.length === 0) continue;
+      const target = this._particleTarget(key);
+      if (target) target.playing = playing;
+    }
+    for (const [key, owners] of this._audioOwners) {
+      if (owners.length === 0) continue;
+      const target = this._audioTarget(key);
+      target?.setStateMachinePlaying(playing, this._speed, reason => this._reportAudioRejection(key, reason));
+    }
+  }
+
+  override destroy(): void {
+    this.resetSideEffects();
+    super.destroy();
+  }
+
+  private _applyVisualOpacity(node: Animation2DRuntimeNode): void {
+    const opacity = this._resolveOpacity(node);
+    if (node.deferredVisuals.length > 0 && this._isNodeActive(node)) {
+      for (const deferred of node.deferredVisuals.splice(0)) this._materializeCoreVisual(node, deferred);
+    }
+    for (const visual of node.visuals) {
+      const alpha = visual.baseAlpha * opacity;
+      if (Math.abs(alpha - visual.lastAlpha) < 1e-6) continue;
+      visual.color[3] = alpha;
+      visual.component.revision++;
+      visual.lastAlpha = alpha;
+    }
+    for (const extension of node.extensions) extension.setOpacity?.(opacity);
+  }
+
+  private _applyEffect(effect: Animation2DEffectEvent, playing: boolean, speed: number): void {
+    const payload = effect.cue.payload as HyaAnimation2DEffectPayload | undefined;
+    if (!payload || typeof payload.targetId !== 'string' || !Number.isSafeInteger(payload.slot)) {
+      throw new TypeError(`Animation2D effect cue "${effect.cue.id}" has an invalid HYA target payload.`);
+    }
+    const key = effectTargetKey(payload);
+    this._effectPayloads.set(key, payload);
+    const owners = effect.cue.kind === 'particle'
+      ? this._particleOwners
+      : this._audioOwners;
+    const stack = owners.get(key) ?? [];
+    if (!owners.has(key)) owners.set(key, stack);
+
+    if (effect.lifecycle === 'enter') {
+      const existing = stack.indexOf(effect.actionId);
+      if (existing >= 0) stack.splice(existing, 1);
+      stack.push(effect.actionId);
+      if (effect.cue.kind === 'particle') {
+        const particle = this._particleTarget(key);
+        if (particle) {
+          particle.emitting = true;
+          particle.restart(true);
+          particle.playing = playing;
+        }
+      } else {
+        const audio = this._audioTarget(key);
+        const node = this._nodesById.get(payload.targetId);
+        const opacity = node ? this._resolveOpacity(node) : 1;
+        audio?.enterStateMachine(playing, speed, opacity, reason => this._reportAudioRejection(key, reason));
+      }
+      return;
+    }
+
+    if (effect.lifecycle === 'exit') {
+      const index = stack.indexOf(effect.actionId);
+      const wasDominant = index === stack.length - 1;
+      if (index >= 0) stack.splice(index, 1);
+      if (stack.length === 0) {
+        owners.delete(key);
+        if (effect.cue.kind === 'particle') {
+          const particle = this._particleTarget(key);
+          if (particle) {
+            particle.playing = false;
+            particle.emitting = false;
+            particle.clear();
+          }
+        } else this._audioTarget(key)?.exitStateMachine();
+      } else if (wasDominant && effect.cue.kind === 'particle') {
+        const particle = this._particleTarget(key);
+        if (particle) {
+          particle.emitting = true;
+          particle.restart(true);
+          particle.playing = playing;
+        }
+      }
+      return;
+    }
+
+    if (stack[stack.length - 1] !== effect.actionId) return;
+    if (effect.lifecycle === 'loop') return;
+    if (effect.cue.kind === 'particle') {
+      const particle = this._particleTarget(key);
+      if (particle) {
+        particle.emitting = true;
+        particle.restart(true);
+        particle.playing = playing;
+      }
+    } else {
+      const audio = this._audioTarget(key);
+      const node = this._nodesById.get(payload.targetId);
+      const opacity = node ? this._resolveOpacity(node) : 1;
+      audio?.restartStateMachine(playing, speed, opacity, reason => this._reportAudioRejection(key, reason));
+    }
+  }
+
+  private _particleTarget(key: string) {
+    const target = parseEffectTargetKey(key);
+    return this._nodesById.get(target.targetId)?.particles[target.slot];
+  }
+
+  private _audioTarget(key: string) {
+    const target = parseEffectTargetKey(key);
+    return this._nodesById.get(target.targetId)?.audio[target.slot];
+  }
+
+  private _reportAudioRejection(key: string, reason: unknown): void {
+    if (this._reportedAudioRejections.has(key)) return;
+    this._reportedAudioRejections.add(key);
+    const target = parseEffectTargetKey(key);
+    const sourcePath = this._effectPayloads.get(key)?.sourcePath
+      ?? `$.nodes[id=${JSON.stringify(target.targetId)}].components[audio=${target.slot}]`;
+    this._diagnostics.push(audioAutoplayRejectedDiagnostic(sourcePath, reason));
+  }
+}
+
+function effectTargetKey(payload: HyaAnimation2DEffectPayload): string {
+  return `${payload.targetId}\u0000${payload.slot}`;
+}
+
+function parseEffectTargetKey(key: string): { readonly targetId: string; readonly slot: number } {
+  const separator = key.lastIndexOf('\u0000');
+  return {
+    targetId: key.slice(0, separator),
+    slot: Number(key.slice(separator + 1)),
+  };
+}
+
+function ownerCount(owners: ReadonlyMap<string, readonly string[]>): number {
+  let count = 0;
+  for (const stack of owners.values()) count += stack.length;
+  return count;
+}
+
+function numericPoseValue(value: unknown, bindingId: string, size: number): Readonly<Float32Array> {
+  if (!(value instanceof Float32Array) || value.length < size) {
+    throw new TypeError(`Animation2D numeric binding "${bindingId}" requires ${size} Float32 values.`);
+  }
+  return value;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}

package/src/animation/Animation2DSystem.ts

@@ -0,0 +1,72 @@
+import { System, type Entity, type World } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+import { Animation2DComponent } from './Animation2DComponent';
+import { Animation2DRuntime } from './Animation2DRuntime';
+
+export interface Animation2DSystemOptions {
+  priority?: number;
+  /** Shared engine asset manager used by sprite2d resources. */
+  assetManager?: AssetManager;
+}
+
+export class Animation2DSystem extends System {
+  private readonly _assetManager: AssetManager | undefined;
+
+  constructor(options: Animation2DSystemOptions = {}) {
+    super({ all: [Animation2DComponent] });
+    this.name = 'Animation2DSystem';
+    if (options.priority !== undefined) this.priority = options.priority;
+    this._assetManager = options.assetManager;
+  }
+
+  override update(world: World, _time: number, delta: number): this {
+    if (this.disabled) return this;
+    const entities = this.entitySet.get(world);
+    if (!entities) return this;
+    for (const entity of entities) this._updateEntity(entity, delta);
+    return this;
+  }
+
+  override destroy(): this {
+    for (const world of this.usedBy) {
+      const entities = this.entitySet.get(world);
+      if (!entities) continue;
+      for (const entity of entities) entity.getComponent(Animation2DComponent)?._disposeRuntime();
+    }
+    return super.destroy();
+  }
+
+  private _updateEntity(entity: Entity, delta: number): void {
+    const component = entity.getComponent(Animation2DComponent);
+    if (!component) return;
+    if (component.disabled) {
+      component._disposeRuntime();
+      return;
+    }
+    if (component.completed && component.animation.endBehavior === 'destroy' && !component.playing) return;
+    component._runtime ??= new Animation2DRuntime(entity, component.animation, component.runtimeExtensions, this._assetManager);
+    if (component.playing && delta > 0 && component.speed > 0) {
+      component.currentTime += delta * 0.001 * component.speed;
+      if (component.currentTime >= component.animation.duration) {
+        if (component.loop) {
+          component.currentTime %= component.animation.duration;
+          component._forceParticleSeek = true;
+        } else {
+          component.currentTime = component.animation.duration;
+          component.playing = false;
+          component.completed = true;
+          if (component.animation.endBehavior === 'destroy') {
+            component._disposeRuntime();
+            component._needsApply = false;
+            return;
+          }
+        }
+      }
+      component._needsApply = true;
+    }
+    if (!component._needsApply) return;
+    component._runtime.apply(component.currentTime, component.playing, component.speed, component._forceParticleSeek);
+    component._needsApply = false;
+    component._forceParticleSeek = false;
+  }
+}

package/src/animation/AnimationAssetLoader.ts

@@ -0,0 +1,84 @@
+import {
+  ANIMATION_MIME_TYPE,
+  parseAnimation,
+  type AnimationResource,
+  type AnimationParseOptions,
+  type ParsedAnimation,
+} from '@haiyue/animation-spec';
+import type { AssetLoaderRegistration } from '@haiyue/engine/assets';
+
+export const HAIYUE_ANIMATION_ASSET_TYPE = 'animation/haiyue' as const;
+
+export interface AnimationAssetLoaderOptions {
+  parse?: AnimationParseOptions;
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+
+let nextAnimationLoaderId = 1;
+
+/** Creates an AssetManager loader without installing source-format converters in the runtime. */
+export function createAnimationAssetLoader(
+  options: AnimationAssetLoaderOptions = {},
+): AssetLoaderRegistration<ParsedAnimation> {
+  const fetchResource = options.fetch ?? fetch;
+  const loaderId = nextAnimationLoaderId++;
+  return {
+    type: HAIYUE_ANIMATION_ASSET_TYPE,
+    extensions: ['.hya'],
+    mimeTypes: [ANIMATION_MIME_TYPE],
+    aliases: ['hya'],
+    async load(url, context) {
+      context.setPhase('loading');
+      const networkKey = `network:hya:${url}`;
+      let buffer = context.cache.network.get(networkKey) as ArrayBuffer | undefined;
+      let responseUrl = '';
+      if (!buffer) {
+        const response = await fetchResource(url, { signal: context.signal });
+        if (!response.ok) throw new Error(`Failed to load Haiyue animation (${response.status} ${response.statusText}): ${url}`);
+        responseUrl = response.url;
+        buffer = await response.arrayBuffer();
+        if (context.signal.aborted) throw context.signal.reason;
+        context.cache.network.set(networkKey, buffer, buffer.byteLength);
+      }
+      context.reportProgress(buffer.byteLength, buffer.byteLength);
+      context.setPhase('parsing');
+      const parsedKey = `parsed:hya:${loaderId}:${url}`;
+      let animation = context.cache.parsed.get(parsedKey) as ParsedAnimation | undefined;
+      if (!animation) {
+        animation = resolveAnimationResourceUris(
+          parseAnimation(buffer, options.parse),
+          responseUrl || absoluteAnimationUrl(url),
+        );
+        context.cache.parsed.set(parsedKey, animation, buffer.byteLength);
+      }
+      return animation;
+    },
+  };
+}
+
+/** Package-relative resources resolve from the fetched HYA, including redirects. */
+function resolveAnimationResourceUris(animation: ParsedAnimation, sourceUrl: string): ParsedAnimation {
+  if (!sourceUrl || animation.resources.length === 0) return animation;
+  const resources = animation.resources.map(resource => {
+    try {
+      return Object.freeze({ ...resource, uri: new URL(resource.uri, sourceUrl).href });
+    } catch {
+      return resource;
+    }
+  }) as readonly AnimationResource[];
+  return Object.freeze({ ...animation, resources: Object.freeze(resources) });
+}
+
+function absoluteAnimationUrl(url: string): string {
+  try {
+    return new URL(url).href;
+  } catch {
+    const base = typeof globalThis.location === 'object' ? globalThis.location.href : '';
+    if (!base) return '';
+    try {
+      return new URL(url, base).href;
+    } catch {
+      return '';
+    }
+  }
+}

package/src/animation/AnimationAudioClip.ts

@@ -0,0 +1,140 @@
+import type { AnimationAudioComponent, AnimationNode } from '@haiyue/animation-spec';
+
+/** HTML media-backed audio clip with composition-time seek and playback-rate synchronization. */
+export class AnimationAudioClip {
+  private readonly element: HTMLAudioElement | null;
+  private readonly nodeStart: number;
+  private readonly nodeEnd: number;
+  private readonly startOffset: number;
+  private readonly baseVolume: number;
+  private readonly clipRate: number;
+  private readonly loop: boolean;
+  private playPending = false;
+  private destroyed = false;
+  private stateMachineActive = false;
+  private playRequestEpoch = 0;
+
+  constructor(uri: string, component: AnimationAudioComponent, node: Readonly<AnimationNode>, animationDuration: number) {
+    this.nodeStart = node.start ?? 0;
+    this.nodeEnd = this.nodeStart + (node.duration ?? animationDuration - this.nodeStart);
+    this.startOffset = component.startOffset ?? 0;
+    this.baseVolume = component.volume ?? 1;
+    this.clipRate = component.playbackRate ?? 1;
+    this.loop = component.loop ?? false;
+    this.element = typeof Audio === 'undefined' ? null : new Audio(uri);
+    if (this.element) {
+      this.element.preload = 'auto';
+      this.element.loop = this.loop;
+    }
+  }
+
+  sync(compositionTime: number, playing: boolean, speed: number, opacity: number): void {
+    const element = this.element;
+    if (!element || this.destroyed) return;
+    const active = compositionTime >= this.nodeStart && compositionTime <= this.nodeEnd;
+    element.volume = clamp(this.baseVolume * opacity, 0, 1);
+    element.playbackRate = clamp(this.clipRate * speed, 0.0625, 16);
+    if (!active || !playing || speed <= 0) {
+      this._cancelPendingPlay();
+      return;
+    }
+    let target = this.startOffset + (compositionTime - this.nodeStart) * this.clipRate;
+    if (this.loop && Number.isFinite(element.duration) && element.duration > 0) target %= element.duration;
+    if (Number.isFinite(target) && Math.abs(element.currentTime - target) > 0.12) {
+      try { element.currentTime = Math.max(0, target); } catch { /* Metadata may not be loaded yet. */ }
+    }
+    if (element.paused) this._requestPlay();
+  }
+
+  enterStateMachine(
+    playing: boolean,
+    speed: number,
+    opacity: number,
+    rejected: (reason: unknown) => void,
+  ): void {
+    const element = this.element;
+    if (!element || this.destroyed) return;
+    this.stateMachineActive = true;
+    element.volume = clamp(this.baseVolume * opacity, 0, 1);
+    element.playbackRate = clamp(this.clipRate * Math.max(speed, 0.0625), 0.0625, 16);
+    try { element.currentTime = Math.max(0, this.startOffset); } catch { /* Metadata may not be loaded yet. */ }
+    if (playing && speed > 0) this._requestPlay(rejected);
+    else this._cancelPendingPlay();
+  }
+
+  restartStateMachine(
+    playing: boolean,
+    speed: number,
+    opacity: number,
+    rejected: (reason: unknown) => void,
+  ): void {
+    this.enterStateMachine(playing, speed, opacity, rejected);
+  }
+
+  setStateMachinePlaying(
+    playing: boolean,
+    speed: number,
+    rejected: (reason: unknown) => void,
+  ): void {
+    const element = this.element;
+    if (!element || this.destroyed || !this.stateMachineActive) return;
+    element.playbackRate = clamp(this.clipRate * Math.max(speed, 0.0625), 0.0625, 16);
+    if (playing && speed > 0) this._requestPlay(rejected);
+    else this._cancelPendingPlay();
+  }
+
+  updateStateMachineProperties(speed: number, opacity: number): void {
+    const element = this.element;
+    if (!element || this.destroyed || !this.stateMachineActive) return;
+    element.volume = clamp(this.baseVolume * opacity, 0, 1);
+    element.playbackRate = clamp(this.clipRate * Math.max(speed, 0.0625), 0.0625, 16);
+  }
+
+  exitStateMachine(): void {
+    this.stateMachineActive = false;
+    this._cancelPendingPlay();
+  }
+
+  pause(): void { this._cancelPendingPlay(); }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.stateMachineActive = false;
+    const element = this.element;
+    if (!element) return;
+    this._cancelPendingPlay();
+    element.removeAttribute('src');
+    element.load();
+  }
+
+  private _requestPlay(rejected?: (reason: unknown) => void): void {
+    const element = this.element;
+    if (!element || this.playPending || this.destroyed) return;
+    const epoch = ++this.playRequestEpoch;
+    const stateMachineRequest = rejected !== undefined;
+    this.playPending = true;
+    void element.play()
+      .then(() => {
+        if (epoch !== this.playRequestEpoch
+          || this.destroyed
+          || (stateMachineRequest && !this.stateMachineActive)) element.pause();
+      })
+      .catch(reason => {
+        if (epoch === this.playRequestEpoch) rejected?.(reason);
+      })
+      .finally(() => {
+        if (epoch === this.playRequestEpoch) this.playPending = false;
+      });
+  }
+
+  private _cancelPendingPlay(): void {
+    this.playRequestEpoch++;
+    this.playPending = false;
+    this.element?.pause();
+  }
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(maximum, Math.max(minimum, value));
+}