@haiyue/extensions 0.1.0

package/src/animation/Animation2DStateMachine.ts

@@ -0,0 +1,39 @@
+import type {
+  AnimationStateMachineDefinition,
+} from '../animation-state-machine/AnimationStateMachine.js';
+import {
+  AnimationStateMachineController,
+  compileAnimationStateMachine,
+  type AnimationStateMachineActionHandle,
+  type AnimationStateMachineControllerOptions,
+  type AnimationStateMachineMixerPort,
+} from '../animation-state-machine/runtime/index.js';
+
+export type Animation2DStateMachineActionHandle =
+  AnimationStateMachineActionHandle;
+export type Animation2DStateMachineMixerPort<
+  TAction extends Animation2DStateMachineActionHandle =
+    Animation2DStateMachineActionHandle,
+> = AnimationStateMachineMixerPort<TAction>;
+
+/**
+ * Creates a shared state-machine controller for a 2D mixer adapter.
+ *
+ * Animation2DComponent remains a single-composition player. A port must own
+ * the 2D pose sampling, blending, discrete-property policy, and side-effect
+ * lifecycle; this factory intentionally does not emulate those semantics by
+ * switching component timelines.
+ */
+export function createAnimation2DStateMachineController<
+  TAction extends Animation2DStateMachineActionHandle,
+>(
+  definition: AnimationStateMachineDefinition,
+  port: Animation2DStateMachineMixerPort<TAction>,
+  options?: AnimationStateMachineControllerOptions,
+): AnimationStateMachineController<TAction> {
+  return new AnimationStateMachineController(
+    compileAnimationStateMachine(definition),
+    port,
+    options,
+  );
+}

package/src/animation/Animation2DStateMachineComponent.ts

@@ -0,0 +1,228 @@
+import {
+  parseAnimation,
+  type AnimationSource,
+  type HyaStateMachineExtension,
+  type HyaStateMachineParameter,
+  type ParsedAnimation,
+} from '@haiyue/animation-spec';
+import { Component, type Entity, type World } from '@haiyue/engine';
+import { ComponentLifecycleFlags, UniqueCheckType } from '@haiyue/engine/ecs';
+import type { AnimationStateMachineLayerSnapshot } from '../animation-state-machine/runtime/index.js';
+import type { AnimationStateMachineChannelDiagnostic } from '../animation-state-machine/AnimationStateMachineChannels.js';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
+import type {
+  Animation2DStateMachineParameterValue,
+  Animation2DStateMachineRuntime,
+} from './Animation2DStateMachineRuntime.js';
+import type { Animation2DRuntimeStats } from './Animation2DComponent.js';
+import { getHyaStateMachineExtension } from './HyaAnimation2DClipAdapter.js';
+
+export interface Animation2DStateMachineComponentOptions {
+  autoplay?: boolean;
+  speed?: number;
+  runtimeExtensions?: Animation2DExtensionRegistry;
+}
+
+/**
+ * Plays multiple named animation ranges and a state machine from one HYA
+ * asset. Transitions blend one pose onto one generated scene hierarchy.
+ */
+export class Animation2DStateMachineComponent extends Component {
+  static override UniqueCheckType = UniqueCheckType.SYMBOL | UniqueCheckType.REPLACE;
+  static override UniqueSymbol = Symbol.for('Animation2DStateMachineComponent');
+  static override Lifecycle = ComponentLifecycleFlags.EntityRemoveComponent
+    | ComponentLifecycleFlags.EntityRemoveFromWorld;
+
+  readonly animation: ParsedAnimation;
+  readonly stateMachineExtension: HyaStateMachineExtension;
+  readonly runtimeExtensions: Animation2DExtensionRegistry | undefined;
+  playing: boolean;
+  speed: number;
+  _runtime: Animation2DStateMachineRuntime | null = null;
+  _needsUpdate = true;
+
+  private readonly _parametersByName: ReadonlyMap<string, HyaStateMachineParameter>;
+  private readonly _parameterValues = new Map<string, Animation2DStateMachineParameterValue>();
+
+  constructor(
+    source: AnimationSource | ParsedAnimation,
+    options: Animation2DStateMachineComponentOptions = {},
+  ) {
+    super('Animation2DStateMachineComponent');
+    this.animation = isParsed(source) ? source : parseAnimation(source);
+    this.stateMachineExtension = getHyaStateMachineExtension(this.animation);
+    this.runtimeExtensions = options.runtimeExtensions;
+    this.playing = options.autoplay ?? true;
+    this.speed = finiteSpeed(options.speed ?? 1);
+    this._parametersByName = new Map(
+      this.stateMachineExtension.stateMachine.parameters.map(parameter => [parameter.name, parameter]),
+    );
+  }
+
+  get runtimeStats(): Animation2DRuntimeStats {
+    return this._runtime?.stats ?? EMPTY_RUNTIME_STATS;
+  }
+
+  get layerSnapshots(): readonly AnimationStateMachineLayerSnapshot[] {
+    if (this._runtime) return this._runtime.layerSnapshots;
+    return Object.freeze(this.stateMachineExtension.stateMachine.layers.map(layer => Object.freeze({
+      layerId: layer.id,
+      currentStateId: layer.initialStateId,
+      currentTime: 0,
+      transitionId: null,
+      sourceStateId: null,
+      destinationStateId: null,
+      transitionProgress: 0,
+    })));
+  }
+
+  get channelDiagnostics(): readonly AnimationStateMachineChannelDiagnostic[] {
+    return this._runtime?.diagnostics ?? EMPTY_CHANNEL_DIAGNOSTICS;
+  }
+
+  get liveActionCount(): number { return this._runtime?.liveActionCount ?? 0; }
+  get liveBindingCount(): number { return this._runtime?.liveBindingCount ?? 0; }
+  get sideEffectOwnerCount(): number { return this._runtime?.sideEffectOwnerCount ?? 0; }
+
+  play(): this {
+    this.playing = true;
+    this._runtime?.setPlaying(true);
+    this._needsUpdate = true;
+    return this;
+  }
+
+  pause(): this {
+    this.playing = false;
+    this._runtime?.setPlaying(false);
+    return this;
+  }
+
+  setSpeed(speed: number): this {
+    this.speed = finiteSpeed(speed);
+    return this;
+  }
+
+  setFloat(name: string, value: number): this {
+    if (!Number.isFinite(value)) throw new RangeError('Float parameters must be finite.');
+    this._setParameter(name, 'float', value);
+    this._runtime?.controller.setFloat(name, value);
+    return this;
+  }
+
+  setInteger(name: string, value: number): this {
+    if (!Number.isSafeInteger(value)) throw new RangeError('Integer parameters must be safe integers.');
+    this._setParameter(name, 'integer', value);
+    this._runtime?.controller.setInteger(name, value);
+    return this;
+  }
+
+  setBoolean(name: string, value: boolean): this {
+    if (typeof value !== 'boolean') throw new TypeError('Boolean parameters require a boolean.');
+    this._setParameter(name, 'boolean', value);
+    this._runtime?.controller.setBoolean(name, value);
+    return this;
+  }
+
+  setTrigger(name: string): this {
+    this._setParameter(name, 'trigger', true);
+    this._runtime?.controller.setTrigger(name);
+    return this;
+  }
+
+  resetTrigger(name: string): this {
+    this._setParameter(name, 'trigger', false);
+    this._runtime?.controller.resetTrigger(name);
+    return this;
+  }
+
+  getParameter(name: string): number | boolean {
+    const parameter = this._requireParameter(name);
+    if (this._runtime) return this._runtime.controller.getParameter(name);
+    if (this._parameterValues.has(name)) return this._parameterValues.get(name)!;
+    return parameter.type === 'trigger' ? false : parameter.defaultValue;
+  }
+
+  reset(): this {
+    this._parameterValues.clear();
+    this._runtime?.reset();
+    this._needsUpdate = this._runtime === null;
+    return this;
+  }
+
+  onEntityRemoveComponent(_entity: Entity, component: Component): void {
+    if (component === this) this._disposeRuntime();
+  }
+
+  onEntityRemoveFromWorld(_entity: Entity, _world: World): void {
+    this._disposeRuntime();
+  }
+
+  override clone(): Animation2DStateMachineComponent {
+    const clone = new Animation2DStateMachineComponent(this.animation, {
+      autoplay: this.playing,
+      speed: this.speed,
+      ...(this.runtimeExtensions ? { runtimeExtensions: this.runtimeExtensions } : {}),
+    });
+    for (const parameter of this.stateMachineExtension.stateMachine.parameters) {
+      clone._parameterValues.set(parameter.name, this.getParameter(parameter.name));
+    }
+    clone.disabled = this.disabled;
+    return clone;
+  }
+
+  _getParameterValues(): ReadonlyMap<string, Animation2DStateMachineParameterValue> {
+    return this._parameterValues;
+  }
+
+  _disposeRuntime(): void {
+    if (!this._runtime) return;
+    for (const parameter of this.stateMachineExtension.stateMachine.parameters) {
+      this._parameterValues.set(parameter.name, this._runtime.controller.getParameter(parameter.name));
+    }
+    this._runtime.destroy();
+    this._runtime = null;
+    this._needsUpdate = true;
+  }
+
+  private _setParameter(
+    name: string,
+    type: HyaStateMachineParameter['type'],
+    value: Animation2DStateMachineParameterValue,
+  ): void {
+    const parameter = this._requireParameter(name);
+    if (parameter.type !== type) {
+      throw new TypeError(`State-machine parameter "${name}" is ${parameter.type}, not ${type}.`);
+    }
+    this._parameterValues.set(name, value);
+    this._needsUpdate = true;
+  }
+
+  private _requireParameter(name: string): HyaStateMachineParameter {
+    const parameter = this._parametersByName.get(name);
+    if (!parameter) throw new ReferenceError(`Unknown state-machine parameter "${name}".`);
+    return parameter;
+  }
+}
+
+const EMPTY_RUNTIME_STATS: Animation2DRuntimeStats = Object.freeze({
+  nodeCount: 0,
+  visualCount: 0,
+  unsupportedComponentCount: 0,
+  pendingResourceCount: 0,
+  failedResourceCount: 0,
+  textCount: 0,
+  particleCount: 0,
+  audioCount: 0,
+});
+const EMPTY_CHANNEL_DIAGNOSTICS: readonly AnimationStateMachineChannelDiagnostic[] = Object.freeze([]);
+
+function isParsed(source: AnimationSource | ParsedAnimation): source is ParsedAnimation {
+  return typeof source === 'object' && source !== null && 'source' in source;
+}
+
+function finiteSpeed(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError('Animation2D state-machine speed must be finite and non-negative.');
+  }
+  return value;
+}

package/src/animation/Animation2DStateMachineRuntime.ts

@@ -0,0 +1,141 @@
+import type {
+  HyaStateMachineExtension,
+  ParsedAnimation,
+} from '@haiyue/animation-spec';
+import type { Entity } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+import type {
+  AnimationStateMachineDefinition,
+} from '../animation-state-machine/AnimationStateMachine.js';
+import type {
+  AnimationStateMachineController,
+  AnimationStateMachineLayerSnapshot,
+} from '../animation-state-machine/runtime/index.js';
+import {
+  Animation2DStateMachineMixerAdapter,
+  runAnimationStateMachineControllerUpdateTransaction,
+  type Animation2DStateMachineActionRuntimeHandle,
+} from '../animation-state-machine/runtime/index.js';
+import type { AnimationStateMachineChannelDiagnostic } from '../animation-state-machine/AnimationStateMachineChannels.js';
+import { createAnimation2DStateMachineController } from './Animation2DStateMachine.js';
+import type { Animation2DExtensionRegistry } from './Animation2DExtensionRegistry.js';
+import { Animation2DStateMachineVisualRuntime } from './Animation2DStateMachineVisualRuntime.js';
+import { createHyaAnimation2DClips } from './HyaAnimation2DClipAdapter.js';
+import {
+  Animation2DMixerRuntime,
+  Animation2DPoseBuffer,
+} from './runtime/mixer/index.js';
+import type { Animation2DRuntimeStats } from './Animation2DComponent.js';
+
+export type Animation2DStateMachineParameterValue = number | boolean;
+
+export class Animation2DStateMachineRuntime {
+  private readonly _mixer: Animation2DMixerRuntime;
+  private readonly _adapter: Animation2DStateMachineMixerAdapter;
+  private readonly _pose = new Animation2DPoseBuffer();
+  private readonly _visual!: Animation2DStateMachineVisualRuntime;
+  private _destroyed = false;
+
+  readonly controller!: AnimationStateMachineController<Animation2DStateMachineActionRuntimeHandle>;
+
+  constructor(
+    owner: Entity,
+    animation: ParsedAnimation,
+    readonly extension: HyaStateMachineExtension,
+    parameterValues: ReadonlyMap<string, Animation2DStateMachineParameterValue>,
+    runtimeExtensions?: Animation2DExtensionRegistry,
+    assetManager?: AssetManager,
+  ) {
+    const clips = createHyaAnimation2DClips(animation, extension);
+    this._mixer = new Animation2DMixerRuntime(clips);
+    this._adapter = new Animation2DStateMachineMixerAdapter(this._mixer);
+    let visual: Animation2DStateMachineVisualRuntime | undefined;
+    try {
+      this.controller = createAnimation2DStateMachineController(
+        extension.stateMachine as AnimationStateMachineDefinition,
+        this._adapter,
+      );
+      applyParameterValues(this.controller, extension, parameterValues);
+      this.controller.update(0);
+      visual = new Animation2DStateMachineVisualRuntime(
+        owner,
+        animation,
+        runtimeExtensions,
+        assetManager,
+      );
+      this._visual = visual;
+    } catch (error) {
+      visual?.destroy();
+      this.controller?.destroy();
+      this._adapter.destroy();
+      this._mixer.destroy();
+      throw error;
+    }
+  }
+
+  get stats(): Animation2DRuntimeStats { return this._visual.stats; }
+  get diagnostics(): readonly AnimationStateMachineChannelDiagnostic[] { return this._visual.diagnostics; }
+  get liveActionCount(): number { return this._adapter.liveActionCount; }
+  get liveBindingCount(): number { return this._adapter.liveBindingCount; }
+  get sideEffectOwnerCount(): number { return this._visual.sideEffectOwnerCount; }
+  get layerSnapshots(): readonly AnimationStateMachineLayerSnapshot[] {
+    return this.controller.layerSnapshots;
+  }
+
+  update(deltaSeconds: number, playing: boolean, speed: number): void {
+    this._requireActive();
+    const pose = runAnimationStateMachineControllerUpdateTransaction(
+      this.controller,
+      playing ? deltaSeconds * speed : 0,
+      () => undefined,
+      () => this._mixer.evaluate(this._pose),
+    );
+    this._visual.applyPose(pose, playing, speed);
+  }
+
+  setPlaying(playing: boolean): void {
+    this._requireActive();
+    this._visual.setPlaying(playing);
+  }
+
+  reset(): void {
+    this._requireActive();
+    this._visual.resetSideEffects();
+    this.controller.reset();
+    const pose = runAnimationStateMachineControllerUpdateTransaction(
+      this.controller,
+      0,
+      () => undefined,
+      () => this._mixer.evaluate(this._pose),
+    );
+    this._visual.applyPose(pose, false, 1);
+  }
+
+  destroy(): void {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this.controller.destroy();
+    this._adapter.destroy();
+    this._mixer.destroy();
+    this._visual.destroy();
+  }
+
+  private _requireActive(): void {
+    if (this._destroyed) throw new Error('Animation2D state-machine runtime has been destroyed.');
+  }
+}
+
+function applyParameterValues(
+  controller: Animation2DStateMachineRuntime['controller'],
+  extension: HyaStateMachineExtension,
+  values: ReadonlyMap<string, Animation2DStateMachineParameterValue>,
+): void {
+  for (const parameter of extension.stateMachine.parameters) {
+    if (!values.has(parameter.name)) continue;
+    const value = values.get(parameter.name)!;
+    if (parameter.type === 'float') controller.setFloat(parameter.name, value as number);
+    else if (parameter.type === 'integer') controller.setInteger(parameter.name, value as number);
+    else if (parameter.type === 'boolean') controller.setBoolean(parameter.name, value as boolean);
+    else if (value) controller.setTrigger(parameter.name);
+  }
+}

package/src/animation/Animation2DStateMachineSystem.ts

@@ -0,0 +1,60 @@
+import { System, type Entity, type World } from '@haiyue/engine';
+import type { AssetManager } from '@haiyue/engine/assets';
+import { Animation2DStateMachineComponent } from './Animation2DStateMachineComponent.js';
+import { Animation2DStateMachineRuntime } from './Animation2DStateMachineRuntime.js';
+
+export interface Animation2DStateMachineSystemOptions {
+  priority?: number;
+  /** Shared engine asset manager used by sprite2d resources. */
+  assetManager?: AssetManager;
+}
+
+export class Animation2DStateMachineSystem extends System {
+  private readonly _assetManager: AssetManager | undefined;
+
+  constructor(options: Animation2DStateMachineSystemOptions = {}) {
+    super({ all: [Animation2DStateMachineComponent] });
+    this.name = 'Animation2DStateMachineSystem';
+    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(Animation2DStateMachineComponent)?._disposeRuntime();
+      }
+    }
+    return super.destroy();
+  }
+
+  private _updateEntity(entity: Entity, delta: number): void {
+    const component = entity.getComponent(Animation2DStateMachineComponent);
+    if (!component) return;
+    if (component.disabled) {
+      component._disposeRuntime();
+      return;
+    }
+    component._runtime ??= new Animation2DStateMachineRuntime(
+      entity,
+      component.animation,
+      component.stateMachineExtension,
+      component._getParameterValues(),
+      component.runtimeExtensions,
+      this._assetManager,
+    );
+    if ((!component.playing || component.speed === 0) && !component._needsUpdate) return;
+    component._runtime.update(Math.max(0, delta) * 0.001, component.playing, component.speed);
+    component._needsUpdate = false;
+  }
+}