@haiyue/extensions 0.1.0

package/src/animation-state-machine/runtime/AnimationStateMachineMixerPort.ts

@@ -0,0 +1,54 @@
+import type {
+  AnimationStateMachineBindingMask,
+  AnimationStateMachineBlendMode,
+  AnimationStateMachineLoopMode,
+} from '../AnimationStateMachine.js';
+
+/**
+ * The only action shape the state-machine runtime needs. Concrete mixer
+ * actions are adapted to this interface by the integration layer.
+ */
+export interface AnimationStateMachineActionHandle {
+  /** Source clip duration in seconds. */
+  readonly duration: number;
+}
+
+export interface AnimationStateMachineActionOptions {
+  readonly layerId: string;
+  readonly stateId: string;
+  readonly loop: AnimationStateMachineLoopMode;
+  readonly blendMode: AnimationStateMachineBlendMode;
+  readonly mask: AnimationStateMachineBindingMask | null;
+}
+
+/**
+ * Internal boundary between the state-machine controller and an animation
+ * mixer. It deliberately has no dependency on Animation3DMixer or
+ * Animation3DAction.
+ */
+export interface AnimationStateMachineMixerPort<
+  TAction extends AnimationStateMachineActionHandle =
+    AnimationStateMachineActionHandle,
+> {
+  createAction(
+    clipId: string,
+    options: AnimationStateMachineActionOptions,
+  ): TAction;
+  play(action: TAction): void;
+  stop(action: TAction): void;
+  fade(action: TAction, targetWeight: number, durationSeconds: number): void;
+  setWeight(action: TAction, weight: number): void;
+  setTime(action: TAction, timeSeconds: number): void;
+  setTimeScale(action: TAction, timeScale: number): void;
+  destroyAction(action: TAction): void;
+}
+
+/** Compatibility aliases for the original 3D-prefixed runtime boundary. */
+export type Animation3DStateMachineActionHandle =
+  AnimationStateMachineActionHandle;
+export type Animation3DStateMachineActionOptions =
+  AnimationStateMachineActionOptions;
+export type Animation3DStateMachineMixerPort<
+  TAction extends AnimationStateMachineActionHandle =
+    AnimationStateMachineActionHandle,
+> = AnimationStateMachineMixerPort<TAction>;

package/src/animation-state-machine/runtime/index.ts

@@ -0,0 +1,47 @@
+export {
+  evaluateAnimation3DBlend1DWeights as evaluateAnimationBlend1DWeights,
+  evaluateAnimation3DBlend2DWeights as evaluateAnimationBlend2DWeights,
+} from './AnimationStateMachineBlendTreeWeights.js';
+export {
+  AnimationStateMachineValidationError,
+  compileAnimationStateMachineDefinition as compileAnimationStateMachine,
+  compileAnimationStateMachineDefinition,
+  validateAnimationStateMachineDefinition,
+} from './AnimationStateMachineCompiler.js';
+export type {
+  Animation3DStateMachineValidationCode as AnimationStateMachineValidationCode,
+  Animation3DStateMachineValidationIssue as AnimationStateMachineValidationIssue,
+  CompiledAnimation3DBlend1DChild as CompiledAnimationBlend1DChild,
+  CompiledAnimation3DBlend1DMotion as CompiledAnimationBlend1DMotion,
+  CompiledAnimation3DBlend2DChild as CompiledAnimationBlend2DChild,
+  CompiledAnimation3DBlend2DMotion as CompiledAnimationBlend2DMotion,
+  CompiledAnimation3DClipMotion as CompiledAnimationClipMotion,
+  CompiledAnimation3DCondition as CompiledAnimationCondition,
+  CompiledAnimation3DConditionOperator as CompiledAnimationConditionOperator,
+  CompiledAnimation3DLayer as CompiledAnimationLayer,
+  CompiledAnimation3DMotion as CompiledAnimationMotion,
+  CompiledAnimation3DParameter as CompiledAnimationParameter,
+  CompiledAnimation3DParameterType as CompiledAnimationParameterType,
+  CompiledAnimation3DState as CompiledAnimationState,
+  CompiledAnimation3DStateMachine as CompiledAnimationStateMachine,
+  CompiledAnimation3DTransition as CompiledAnimationTransition,
+} from './AnimationStateMachineCompiler.js';
+export {
+  Animation3DStateMachineController as AnimationStateMachineController,
+  createAnimation3DStateMachineController as createAnimationStateMachineController,
+  runAnimationStateMachineControllerUpdateTransaction,
+} from './AnimationStateMachineController.js';
+export type {
+  Animation3DStateMachineControllerOptions as AnimationStateMachineControllerOptions,
+  Animation3DStateMachineControllerStatus as AnimationStateMachineControllerStatus,
+  Animation3DStateMachineLayerSnapshot as AnimationStateMachineLayerSnapshot,
+} from './AnimationStateMachineController.js';
+export type {
+  AnimationStateMachineActionHandle,
+  AnimationStateMachineActionOptions,
+  AnimationStateMachineMixerPort,
+} from './AnimationStateMachineMixerPort.js';
+export {
+  Animation2DStateMachineActionRuntimeHandle,
+  Animation2DStateMachineMixerAdapter,
+} from './Animation2DStateMachineMixerAdapter.js';

package/src/animation.ts

@@ -0,0 +1,33 @@
+export { Animation2DComponent } from './animation/Animation2DComponent';
+export type { Animation2DComponentOptions, Animation2DRuntimeStats } from './animation/Animation2DComponent';
+export { Animation2DSystem } from './animation/Animation2DSystem';
+export type { Animation2DSystemOptions } from './animation/Animation2DSystem';
+export { Animation2DRenderSystem } from './animation/Animation2DRenderSystem';
+export type { Animation2DRenderStats, Animation2DRenderSystemOptions } from './animation/Animation2DRenderSystem';
+export { tessellateAnimationPath } from './animation/AnimationPathTessellator';
+export { createAnimationAssetLoader, HAIYUE_ANIMATION_ASSET_TYPE } from './animation/AnimationAssetLoader';
+export type { AnimationAssetLoaderOptions } from './animation/AnimationAssetLoader';
+export { Animation2DExtensionRegistry } from './animation/Animation2DExtensionRegistry';
+export type {
+  Animation2DExtensionContext,
+  Animation2DExtensionHandler,
+  Animation2DExtensionInstance,
+} from './animation/Animation2DExtensionRegistry';
+export {
+  createAnimation2DStateMachineController,
+} from './animation/Animation2DStateMachine';
+export type {
+  AnimationStateMachineDefinition,
+} from './animation-state-machine/AnimationStateMachine';
+export {
+  AnimationStateMachineController,
+  AnimationStateMachineValidationError,
+  compileAnimationStateMachine,
+  validateAnimationStateMachineDefinition,
+} from './animation-state-machine/runtime/index';
+export type {
+  AnimationStateMachineControllerOptions,
+  AnimationStateMachineLayerSnapshot,
+  AnimationStateMachineMixerPort,
+  AnimationStateMachineValidationIssue,
+} from './animation-state-machine/runtime/index';

package/src/animation3d/Animation3DAction.ts

@@ -0,0 +1,73 @@
+import type {
+  Animation3DBindingMask,
+} from './Animation3DBinding';
+import type { Animation3DClip } from './Animation3DClip';
+
+export type Animation3DLoopMode =
+  | 'once'
+  | 'repeat'
+  | 'ping-pong';
+
+export type Animation3DBlendMode =
+  | 'override'
+  | 'additive';
+
+export type Animation3DActionStatus =
+  | 'idle'
+  | 'scheduled'
+  | 'running'
+  | 'paused'
+  | 'finished'
+  | 'stopped';
+
+export interface Animation3DActionOptions {
+  readonly id?: string;
+  readonly loop?: Animation3DLoopMode;
+  /** Infinity is valid for repeat and ping-pong. */
+  readonly repetitions?: number;
+  readonly clampWhenFinished?: boolean;
+  readonly timeScale?: number;
+  readonly weight?: number;
+  readonly blendMode?: Animation3DBlendMode;
+  readonly mask?: Animation3DBindingMask;
+}
+
+/**
+ * One mutable playback instance of an immutable clip.
+ * Actions are mixer-owned and become invalid after removal or mixer destroy.
+ */
+export interface Animation3DAction {
+  readonly id: string;
+  readonly clip: Animation3DClip;
+  readonly status: Animation3DActionStatus;
+  enabled: boolean;
+  paused: boolean;
+  time: number;
+  timeScale: number;
+  weight: number;
+  loop: Animation3DLoopMode;
+  repetitions: number;
+  clampWhenFinished: boolean;
+  blendMode: Animation3DBlendMode;
+  mask: Animation3DBindingMask | null;
+  readonly effectiveTimeScale: number;
+  readonly effectiveWeight: number;
+
+  play(): this;
+  stop(): this;
+  reset(): this;
+  startAt(mixerTimeSeconds: number): this;
+  fadeIn(durationSeconds: number): this;
+  fadeOut(durationSeconds: number): this;
+  crossFadeFrom(
+    source: Animation3DAction,
+    durationSeconds: number,
+    warp?: boolean,
+  ): this;
+  crossFadeTo(
+    destination: Animation3DAction,
+    durationSeconds: number,
+    warp?: boolean,
+  ): this;
+  stopFading(): this;
+}

package/src/animation3d/Animation3DBinding.ts

@@ -0,0 +1,116 @@
+/**
+ * Logical targets keep authored clips independent from a concrete ECS World.
+ * A runtime resolver maps one of these stable references to an actual target.
+ */
+export type Animation3DBindingTarget =
+  | Readonly<{
+      kind: 'node-id';
+      nodeId: string;
+    }>
+  | Readonly<{
+      kind: 'node-path';
+      segments: readonly string[];
+    }>
+  | Readonly<{
+      kind: 'slot';
+      slot: string;
+    }>;
+
+export type Animation3DFixedValueType =
+  | 'scalar'
+  | 'vec2'
+  | 'vec3'
+  | 'vec4'
+  | 'quaternion';
+
+export type Animation3DValueType =
+  | Animation3DFixedValueType
+  | 'weights';
+
+export interface Animation3DTranslationBinding {
+  readonly id: string;
+  readonly target: Animation3DBindingTarget;
+  readonly path: 'transform.translation';
+  readonly valueType: 'vec3';
+  readonly valueSize: 3;
+}
+
+export interface Animation3DRotationBinding {
+  readonly id: string;
+  readonly target: Animation3DBindingTarget;
+  readonly path: 'transform.rotation';
+  readonly valueType: 'quaternion';
+  readonly valueSize: 4;
+}
+
+export interface Animation3DScaleBinding {
+  readonly id: string;
+  readonly target: Animation3DBindingTarget;
+  readonly path: 'transform.scale';
+  readonly valueType: 'vec3';
+  readonly valueSize: 3;
+}
+
+export interface Animation3DMorphWeightsBinding {
+  readonly id: string;
+  readonly target: Animation3DBindingTarget;
+  readonly path: 'morph.weights';
+  readonly valueType: 'weights';
+  /** Positive morph target count. Loaders must reject zero or negative values. */
+  readonly valueSize: number;
+}
+
+export type Animation3DFixedValueSize = {
+  readonly scalar: 1;
+  readonly vec2: 2;
+  readonly vec3: 3;
+  readonly vec4: 4;
+  readonly quaternion: 4;
+};
+
+export type Animation3DPropertyBinding = {
+  [TValueType in Animation3DFixedValueType]: Readonly<{
+    id: string;
+    target: Animation3DBindingTarget;
+    path: 'property';
+    /** Stable component or adapter namespace, never a constructor reference. */
+    component: string;
+    property: string;
+    valueType: TValueType;
+    valueSize: Animation3DFixedValueSize[TValueType];
+  }>;
+}[Animation3DFixedValueType];
+
+export type Animation3DBinding =
+  | Animation3DTranslationBinding
+  | Animation3DRotationBinding
+  | Animation3DScaleBinding
+  | Animation3DMorphWeightsBinding
+  | Animation3DPropertyBinding;
+
+export interface Animation3DResolvedBinding<
+  TBinding extends Animation3DBinding = Animation3DBinding,
+> {
+  readonly binding: TBinding;
+  /** Writes exactly binding.valueSize values into out. */
+  read(out: Float32Array): void;
+  /** Reads exactly binding.valueSize values from value. */
+  write(value: ArrayLike<number>): void;
+}
+
+/**
+ * Resolver revisions invalidate cached resolved bindings after hierarchy or
+ * component structure changes.
+ */
+export interface Animation3DBindingResolver {
+  readonly revision: number;
+  resolve<TBinding extends Animation3DBinding>(
+    binding: TBinding,
+  ): Animation3DResolvedBinding<TBinding> | null;
+}
+
+export interface Animation3DBindingMask {
+  /** Empty or omitted include means all bindings are eligible. */
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+}

package/src/animation3d/Animation3DClip.ts

@@ -0,0 +1,22 @@
+import type { Animation3DTrack } from './Animation3DTrack';
+
+export interface Animation3DEvent {
+  readonly id: string;
+  readonly time: number;
+  readonly name: string;
+  /** Loader-validated, structured-cloneable event data. */
+  readonly payload?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Immutable, source-format-independent CPU animation resource.
+ * Times are seconds; rotations are normalized XYZW quaternions.
+ */
+export interface Animation3DClip {
+  readonly format: 'haiyue-animation3d-clip@1';
+  readonly id: string;
+  readonly name: string;
+  readonly duration: number;
+  readonly tracks: readonly Animation3DTrack[];
+  readonly events: readonly Animation3DEvent[];
+}

package/src/animation3d/Animation3DError.ts

@@ -0,0 +1,34 @@
+export type Animation3DErrorCode =
+  | 'mixer-destroyed'
+  | 'invalid-clip'
+  | 'invalid-track'
+  | 'invalid-action'
+  | 'duplicate-action-id'
+  | 'resolver-miss';
+
+export type Animation3DErrorDetails = Readonly<Record<
+  string,
+  string | number | boolean | null
+>>;
+
+/**
+ * Stable domain error for the Animation3D facade.
+ *
+ * Callers should branch on `code`; messages remain diagnostic and may gain
+ * additional context without changing the error contract.
+ */
+export class Animation3DError extends Error {
+  readonly code: Animation3DErrorCode;
+  readonly details: Animation3DErrorDetails;
+
+  constructor(
+    code: Animation3DErrorCode,
+    message: string,
+    details: Animation3DErrorDetails = {},
+  ) {
+    super(message);
+    this.name = 'Animation3DError';
+    this.code = code;
+    this.details = Object.freeze({ ...details });
+  }
+}

package/src/animation3d/Animation3DMixer.ts

@@ -0,0 +1,82 @@
+import type {
+  Animation3DBindingResolver,
+} from './Animation3DBinding.js';
+import type {
+  Animation3DAction,
+  Animation3DActionOptions,
+} from './Animation3DAction.js';
+import type { Animation3DClip } from './Animation3DClip.js';
+import type {
+  Animation3DMutablePose,
+  Animation3DPose,
+} from './Animation3DPose.js';
+import { Animation3DMixerRuntime } from './runtime/mixer/Mixer.js';
+import {
+  registerAnimation3DMixerRuntime,
+} from './runtime/mixer/Animation3DMixerRuntimeStore.js';
+
+export type Animation3DMixerState =
+  | 'active'
+  | 'destroyed';
+
+/**
+ * Public mixer facade. Controller-only clock/transaction hooks remain on the
+ * internal runtime and are intentionally absent from this surface.
+ */
+export class Animation3DMixer {
+  #runtime: Animation3DMixerRuntime;
+
+  constructor(resolver: Animation3DBindingResolver) {
+    this.#runtime = new Animation3DMixerRuntime(resolver);
+    registerAnimation3DMixerRuntime(this, this.#runtime);
+  }
+
+  get state(): Animation3DMixerState { return this.#runtime.state; }
+  get resolver(): Animation3DBindingResolver { return this.#runtime.resolver; }
+  get actions(): readonly Animation3DAction[] { return this.#runtime.actions; }
+  get time(): number { return this.#runtime.time; }
+  get timeScale(): number { return this.#runtime.timeScale; }
+  set timeScale(value: number) { this.#runtime.timeScale = value; }
+
+  createAction(
+    clip: Animation3DClip,
+    options?: Animation3DActionOptions,
+  ): Animation3DAction {
+    return this.#runtime.createAction(clip, options);
+  }
+
+  getAction(actionId: string): Animation3DAction | null {
+    return this.#runtime.getAction(actionId);
+  }
+
+  removeAction(action: Animation3DAction | string): boolean {
+    return this.#runtime.removeAction(action);
+  }
+
+  stopAllActions(): this {
+    this.#runtime.stopAllActions();
+    return this;
+  }
+
+  update(
+    deltaSeconds: number,
+    out: Animation3DMutablePose,
+  ): Animation3DPose {
+    return this.#runtime.update(deltaSeconds, out);
+  }
+
+  evaluate(out: Animation3DMutablePose): Animation3DPose {
+    return this.#runtime.evaluate(out);
+  }
+
+  setTime(
+    timeSeconds: number,
+    out: Animation3DMutablePose,
+  ): Animation3DPose {
+    return this.#runtime.setTime(timeSeconds, out);
+  }
+
+  destroy(): void {
+    this.#runtime.destroy();
+  }
+}

package/src/animation3d/Animation3DPose.ts

@@ -0,0 +1,100 @@
+import type {
+  Animation3DBinding,
+  Animation3DBindingResolver,
+  Animation3DResolvedBinding,
+} from './Animation3DBinding.js';
+import type { Animation3DEvent } from './Animation3DClip.js';
+import { Animation3DError } from './Animation3DError.js';
+
+export interface Animation3DPoseChannel<
+  TBinding extends Animation3DBinding = Animation3DBinding,
+> {
+  readonly binding: TBinding;
+  /** Exactly binding.valueSize sampled and blended values. */
+  readonly value: Readonly<Float32Array>;
+}
+
+export interface Animation3DPoseEvent {
+  readonly actionId: string;
+  readonly clipId: string;
+  readonly event: Animation3DEvent;
+}
+
+/**
+ * Frame-transient mixer output. Implementations may reuse its arrays on the
+ * next evaluate/update call; callers must copy values they need to retain.
+ */
+export interface Animation3DPose {
+  readonly sequence: number;
+  readonly mixerTime: number;
+  readonly channels: readonly Animation3DPoseChannel[];
+  readonly events: readonly Animation3DPoseEvent[];
+}
+
+/**
+ * Caller-provided scratch target used to keep mixer evaluation allocation-free.
+ * reset() begins a new pose and seal() returns the current read-only view.
+ */
+export interface Animation3DMutablePose {
+  reset(mixerTime: number): void;
+  write(
+    binding: Animation3DBinding,
+    value: ArrayLike<number>,
+  ): void;
+  emit(event: Animation3DPoseEvent): void;
+  seal(): Animation3DPose;
+}
+
+interface Animation3DPoseApplierState {
+  readonly resolver: Animation3DBindingResolver;
+  resolverRevision: number;
+  readonly resolvedBindings: Map<
+    string,
+    Animation3DResolvedBinding | null
+  >;
+}
+
+const POSE_APPLIER_STATES = new WeakMap<
+  Animation3DPoseApplier,
+  Animation3DPoseApplierState
+>();
+
+/**
+ * Applies pose channels through a revision-aware binding resolver cache.
+ * Resolver misses fail explicitly and never write to a fallback target.
+ */
+export class Animation3DPoseApplier {
+  constructor(resolver: Animation3DBindingResolver) {
+    POSE_APPLIER_STATES.set(this, {
+      resolver,
+      resolverRevision: Number.NaN,
+      resolvedBindings: new Map(),
+    });
+  }
+
+  apply(pose: Animation3DPose): void {
+    const state = POSE_APPLIER_STATES.get(this)!;
+    const { resolver } = state;
+    if (state.resolverRevision !== resolver.revision) {
+      state.resolverRevision = resolver.revision;
+      state.resolvedBindings.clear();
+    }
+    for (let index = 0; index < pose.channels.length; index++) {
+      const channel = pose.channels[index]!;
+      const bindingId = channel.binding.id;
+      let resolved = state.resolvedBindings.get(bindingId);
+      if (resolved === undefined && !state.resolvedBindings.has(bindingId)) {
+        resolved = resolver.resolve(channel.binding);
+        state.resolvedBindings.set(bindingId, resolved);
+      }
+      if (!resolved) {
+        throw new Animation3DError(
+          'resolver-miss',
+          `Animation3D binding resolver could not resolve "${bindingId}".`,
+          { resolver: 'binding', bindingId },
+        );
+      }
+      resolved.write(channel.value);
+    }
+  }
+}

package/src/animation3d/Animation3DPoseBuffer.ts

@@ -0,0 +1,85 @@
+import type { Animation3DBinding } from './Animation3DBinding.js';
+import type {
+  Animation3DMutablePose,
+  Animation3DPose,
+  Animation3DPoseChannel,
+  Animation3DPoseEvent,
+} from './Animation3DPose.js';
+
+class ReusablePoseChannel implements Animation3DPoseChannel {
+  binding: Animation3DBinding;
+  value: Float32Array;
+
+  constructor(binding: Animation3DBinding) {
+    this.binding = binding;
+    this.value = new Float32Array(binding.valueSize);
+  }
+
+  write(binding: Animation3DBinding, source: ArrayLike<number>): void {
+    this.binding = binding;
+    if (this.value.length !== binding.valueSize) {
+      this.value = new Float32Array(binding.valueSize);
+    }
+    for (let index = 0; index < binding.valueSize; index++) {
+      this.value[index] = source[index] ?? 0;
+    }
+  }
+}
+
+/**
+ * Reusable caller-owned mixer output.
+ *
+ * Channel records and value arrays are pooled after first use. seal() returns
+ * this object as the read-only pose view rather than allocating a snapshot.
+ */
+export class Animation3DPoseBuffer implements Animation3DMutablePose, Animation3DPose {
+  private readonly _channelPool: ReusablePoseChannel[] = [];
+  private readonly _channels: ReusablePoseChannel[] = [];
+  private readonly _events: Animation3DPoseEvent[] = [];
+  private _sequence = 0;
+  private _mixerTime = 0;
+  private _sealed = true;
+
+  get sequence(): number { return this._sequence; }
+  get mixerTime(): number { return this._mixerTime; }
+  get channels(): readonly Animation3DPoseChannel[] { return this._channels; }
+  get events(): readonly Animation3DPoseEvent[] { return this._events; }
+
+  reset(mixerTime: number): void {
+    if (!Number.isFinite(mixerTime)) {
+      throw new RangeError(`Animation3D pose mixerTime must be finite; received ${mixerTime}.`);
+    }
+    this._mixerTime = mixerTime;
+    this._channels.length = 0;
+    this._events.length = 0;
+    this._sealed = false;
+  }
+
+  write(binding: Animation3DBinding, value: ArrayLike<number>): void {
+    if (value.length < binding.valueSize) {
+      throw new RangeError(
+        `Animation3D pose channel "${binding.id}" requires ${binding.valueSize} values; received ${value.length}.`,
+      );
+    }
+    const index = this._channels.length;
+    let channel = this._channelPool[index];
+    if (!channel) {
+      channel = new ReusablePoseChannel(binding);
+      this._channelPool.push(channel);
+    }
+    channel.write(binding, value);
+    this._channels.push(channel);
+  }
+
+  emit(event: Animation3DPoseEvent): void {
+    this._events.push(event);
+  }
+
+  seal(): Animation3DPose {
+    if (!this._sealed) {
+      this._sequence++;
+      this._sealed = true;
+    }
+    return this;
+  }
+}