@haiyue/extensions 0.1.0 → 0.2.0

package/src/animation/Animation2DStateMachineVisualRuntime.ts

@@ -1,282 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,84 +0,0 @@
-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

@@ -1,140 +0,0 @@
-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));
-}