@haiyue/extensions 0.1.0

package/src/animation3d/hya/HyaAnimation3DTypes.ts

@@ -0,0 +1,168 @@
+import type { Scene } from '@haiyue/engine';
+import type { ParticleEmitter3DOptions } from '@haiyue/engine/components';
+import type { PbrMaterial } from '@haiyue/engine/material';
+import type { LoadedGltfModel, LoadGltfOptions } from '../../gltf/GltfLoaderContract';
+import type { Animation3DActionOptions } from '../Animation3DAction';
+import type { Animation3DBinding } from '../Animation3DBinding';
+import type { Animation3DEvent } from '../Animation3DClip';
+import type { Animation3DStateMachineDefinition } from '../Animation3DStateMachine';
+
+export interface HyaAnimation3DResource {
+  readonly id: string;
+  readonly type: 'image' | 'audio' | 'binary';
+  readonly uri: string;
+  readonly mimeType?: string;
+  readonly integrity?: string;
+}
+
+export interface HyaAnimation3DMaterialDescriptor {
+  readonly id: string;
+  readonly name: string;
+  readonly baseColorFactor: readonly [number, number, number, number];
+  readonly metallicFactor: number;
+  readonly roughnessFactor: number;
+  readonly emissiveFactor: readonly [number, number, number];
+  readonly alphaMode: 'opaque' | 'mask' | 'blend';
+  readonly alphaCutoff?: number;
+  readonly doubleSided: boolean;
+  readonly baseColorTexture?: string;
+  readonly normalTexture?: string;
+  readonly metallicRoughnessTexture?: string;
+  readonly emissiveTexture?: string;
+}
+
+export interface HyaAnimation3DTransformDescriptor {
+  readonly translation: readonly [number, number, number];
+  readonly rotation: readonly [number, number, number, number];
+  readonly scale: readonly [number, number, number];
+}
+
+export type HyaAnimation3DCameraProjection =
+  | Readonly<{ kind: 'perspective'; fovYRadians: number; near: number; far: number }>
+  | Readonly<{ kind: 'orthographic'; orthoHeight: number; near: number; far: number }>;
+
+export type HyaAnimation3DComponentDescriptor =
+  | Readonly<{ id: string; kind: 'camera3d'; projection: HyaAnimation3DCameraProjection }>
+  | Readonly<{
+      id: string;
+      kind: 'primitive3d';
+      primitive: 'box' | 'sphere' | 'plane' | 'cylinder' | 'cone';
+      materialId: string;
+    }>
+  | Readonly<{
+      id: string;
+      kind: 'model3d';
+      resource: string;
+      materialOverrides?: readonly Readonly<{ slot: string; materialId: string }>[];
+    }>
+  | Readonly<{ id: string; kind: 'particle3d'; descriptor: ParticleEmitter3DOptions & Readonly<{ textureResource?: string }> }>;
+
+export interface HyaAnimation3DNodeDescriptor {
+  readonly id: string;
+  readonly name: string;
+  readonly parent?: string;
+  readonly start?: number;
+  readonly duration?: number;
+  readonly transform: HyaAnimation3DTransformDescriptor;
+  readonly components: readonly HyaAnimation3DComponentDescriptor[];
+}
+
+export interface HyaAnimation3DClipDescriptor {
+  readonly format: 'haiyue-animation3d-clip@1';
+  readonly id: string;
+  readonly name: string;
+  readonly duration: number;
+  readonly tracks: readonly Readonly<{
+    id: string;
+    binding: Animation3DBinding;
+    interpolation: 'step' | 'linear' | 'cubic-spline';
+    times: ArrayLike<number>;
+    values: ArrayLike<number>;
+  }>[];
+  readonly events: readonly Animation3DEvent[];
+}
+
+/** Runtime port implemented by the validated animation-spec payload. */
+export interface HyaAnimation3DPayload {
+  readonly format: 'haiyue-animation-3d@1';
+  readonly mode: 'native-3d';
+  readonly viewport: Readonly<{ width: number; height: number }>;
+  readonly materials: readonly HyaAnimation3DMaterialDescriptor[];
+  readonly nodes: readonly HyaAnimation3DNodeDescriptor[];
+  readonly clips: readonly HyaAnimation3DClipDescriptor[];
+  readonly stateMachine?: Animation3DStateMachineDefinition | null;
+}
+
+export interface HyaAnimation3DRuntimeOptions {
+  readonly scene: Scene;
+  /** Payload returned by animation-spec native3d validation. */
+  readonly payload: HyaAnimation3DPayload;
+  readonly resources: readonly HyaAnimation3DResource[];
+  readonly signal?: AbortSignal;
+  readonly useAuthoredCamera?: boolean;
+  readonly addPreviewLights?: boolean;
+  readonly loadModel?: (uri: string, options: LoadGltfOptions) => Promise<LoadedGltfModel>;
+  readonly disposeModel?: (model: LoadedGltfModel) => void;
+  readonly resolveTexture?: (
+    resource: HyaAnimation3DResource,
+    material: PbrMaterial | null,
+  ) => ParticleEmitter3DOptions['textureSource'] | null;
+}
+
+export interface HyaAnimation3DPlayOptions extends Animation3DActionOptions {
+  readonly fadeFrom?: HyaAnimation3DActionGroup;
+  readonly fadeDuration?: number;
+  readonly warp?: boolean;
+}
+
+export interface HyaAnimation3DActionGroup {
+  readonly id: string;
+  readonly clipId: string;
+  readonly actionCount: number;
+  readonly playing: boolean;
+  play(): this;
+  stop(): this;
+  reset(): this;
+}
+
+export interface HyaAnimation3DRuntimeDiagnostics {
+  readonly state: 'active' | 'destroyed';
+  readonly entityCount: number;
+  readonly materialCount: number;
+  readonly modelCount: number;
+  readonly actionGroupCount: number;
+  readonly ownerResidualCount: number;
+}
+
+export interface HyaAnimation3DStateMachineLayerSnapshot {
+  readonly layerId: string;
+  readonly currentStateId: string;
+  readonly currentTime: number;
+  readonly transitionId: string | null;
+  readonly sourceStateId: string | null;
+  readonly destinationStateId: string | null;
+  readonly transitionProgress: number;
+}
+
+/** Stable parameter/query port for the runtime's unique state-machine clock. */
+export interface HyaAnimation3DStateMachineController {
+  readonly status: 'active' | 'destroyed';
+  readonly layerSnapshots: readonly HyaAnimation3DStateMachineLayerSnapshot[];
+  getLayerSnapshot(layerId: string): HyaAnimation3DStateMachineLayerSnapshot;
+  setFloat(name: string, value: number): this;
+  setInteger(name: string, value: number): this;
+  setBoolean(name: string, value: boolean): this;
+  setTrigger(name: string): this;
+  resetTrigger(name: string): this;
+  getParameter(name: string): number | boolean;
+}
+
+/** Stable lifecycle and diagnostic view of the HYA state-machine owner. */
+export interface HyaAnimation3DStateMachineRuntimeControl {
+  readonly controller: HyaAnimation3DStateMachineController;
+  readonly time: number;
+  readonly liveActionCount: number;
+  readonly liveBindingCount: number;
+  readonly sideEffectOwnerCount: number;
+  reset(): void;
+}

package/src/animation3d/hya/index.ts

@@ -0,0 +1,10 @@
+export { HyaAnimation3DRuntime, createHyaAnimation3DRuntime } from './HyaAnimation3DRuntime';
+export {
+  HyaAnimation3DStateMachineRuntime,
+} from './HyaAnimation3DStateMachineRuntime';
+export type {
+  HyaAnimation3DParticleCue,
+  HyaAnimation3DStateMachinePartition,
+  HyaAnimation3DStateMachineRuntimeOptions,
+} from './HyaAnimation3DStateMachineRuntime';
+export type * from './HyaAnimation3DTypes';

package/src/animation3d/index.ts

@@ -0,0 +1,76 @@
+export type {
+  Animation3DBinding,
+  Animation3DBindingMask,
+  Animation3DBindingResolver,
+  Animation3DBindingTarget,
+  Animation3DFixedValueSize,
+  Animation3DFixedValueType,
+  Animation3DMorphWeightsBinding,
+  Animation3DPropertyBinding,
+  Animation3DResolvedBinding,
+  Animation3DRotationBinding,
+  Animation3DScaleBinding,
+  Animation3DTranslationBinding,
+  Animation3DValueType,
+} from './Animation3DBinding.js';
+export type {
+  Animation3DInterpolation,
+  Animation3DTrack,
+  Animation3DTrackFor,
+} from './Animation3DTrack.js';
+export type {
+  Animation3DClip,
+  Animation3DEvent,
+} from './Animation3DClip.js';
+export type {
+  Animation3DMutablePose,
+  Animation3DPose,
+  Animation3DPoseChannel,
+  Animation3DPoseEvent,
+} from './Animation3DPose.js';
+export { Animation3DPoseApplier } from './Animation3DPose.js';
+export { Animation3DPoseBuffer } from './Animation3DPoseBuffer.js';
+export type {
+  Animation3DAction,
+  Animation3DActionOptions,
+  Animation3DActionStatus,
+  Animation3DBlendMode,
+  Animation3DLoopMode,
+} from './Animation3DAction.js';
+export { Animation3DMixer } from './Animation3DMixer.js';
+export type { Animation3DMixerState } from './Animation3DMixer.js';
+export { Animation3DError } from './Animation3DError.js';
+export type {
+  Animation3DErrorCode,
+  Animation3DErrorDetails,
+} from './Animation3DError.js';
+export type {
+  Animation3DBlend1DChild,
+  Animation3DBlend1DMotion,
+  Animation3DBlend2DChild,
+  Animation3DBlend2DMotion,
+  Animation3DClipMotion,
+  Animation3DMotionDefinition,
+  Animation3DParameterDefinition,
+  Animation3DStateDefinition,
+  Animation3DStateMachineDefinition,
+  Animation3DStateMachineLayer,
+  Animation3DTransitionCondition,
+  Animation3DTransitionDefinition,
+  Animation3DTransitionInterruption,
+} from './Animation3DStateMachine.js';
+export {
+  Animation3DStateMachineController,
+  Animation3DStateMachineValidationError,
+  compileAnimation3DStateMachineDefinition,
+  validateAnimation3DStateMachineDefinition,
+} from './Animation3DStateMachineRuntime.js';
+export type {
+  Animation3DCompiledStateMachine,
+  Animation3DStateMachineClipResolver,
+  Animation3DStateMachineControllerOptions,
+  Animation3DStateMachineControllerStatus,
+  Animation3DStateMachineLayerSnapshot,
+  Animation3DStateMachineValidationCode,
+  Animation3DStateMachineValidationIssue,
+} from './Animation3DStateMachineRuntime.js';

package/src/animation3d/runtime/integration/Animation3DStateMachineMixerAdapter.ts

@@ -0,0 +1,325 @@
+import type { Animation3DClip } from '../../Animation3DClip.js';
+import { Animation3DError } from '../../Animation3DError.js';
+import type { Animation3DMutablePose } from '../../Animation3DPose.js';
+import type {
+  AnimationStateMachineActionOptions,
+  AnimationStateMachineMixerPort,
+} from '../../../animation-state-machine/runtime/AnimationStateMachineMixerPort.js';
+import {
+  Animation3DActionRuntime,
+  type Animation3DActionSynchronizedState,
+} from '../mixer/Action.js';
+import { Animation3DMixerRuntime } from '../mixer/Mixer.js';
+
+let nextAdapterId = 1;
+
+/**
+ * Resolves the serializable clip ids stored in state-machine definitions.
+ * Returned clips remain resolver/caller-owned.
+ */
+export interface Animation3DStateMachineClipResolver {
+  resolve(clipId: string): Animation3DClip | null;
+}
+
+export class Animation3DStateMachineActionRuntimeHandle {
+  readonly duration: number;
+  readonly clipId: string;
+  readonly layerId: string;
+  readonly stateId: string;
+  readonly action: Animation3DActionRuntime;
+
+  targetTime = 0;
+  appliedTime = 0;
+  playing = false;
+  destroyed = false;
+  pendingDestroy = false;
+
+  private readonly _actionCheckpoint: Animation3DActionSynchronizedState;
+  private _checkpointTargetTime = 0;
+  private _checkpointAppliedTime = 0;
+  private _checkpointPlaying = false;
+
+  constructor(
+    clipId: string,
+    options: AnimationStateMachineActionOptions,
+    action: Animation3DActionRuntime,
+  ) {
+    this.duration = action.clip.duration;
+    this.clipId = clipId;
+    this.layerId = options.layerId;
+    this.stateId = options.stateId;
+    this.action = action;
+    this._actionCheckpoint = action.createSynchronizedState();
+  }
+
+  captureTransactionState(): void {
+    this._checkpointTargetTime = this.targetTime;
+    this._checkpointAppliedTime = this.appliedTime;
+    this._checkpointPlaying = this.playing;
+    this.action.captureSynchronizedState(this._actionCheckpoint);
+  }
+
+  restoreTransactionState(): void {
+    this.targetTime = this._checkpointTargetTime;
+    this.appliedTime = this._checkpointAppliedTime;
+    this.playing = this._checkpointPlaying;
+    this.pendingDestroy = false;
+    this.action.restoreSynchronizedState(this._actionCheckpoint);
+  }
+}
+
+/**
+ * Adapts the dimension-neutral state-machine port to the real 3D mixer.
+ *
+ * The controller owns every action playhead. The adapter applies its absolute
+ * times to actions while a synchronized mixer frame is open; it never calls
+ * mixer.update(), so the mixer clock cannot advance the same actions again.
+ */
+export class Animation3DStateMachineMixerAdapter implements
+  AnimationStateMachineMixerPort<Animation3DStateMachineActionRuntimeHandle> {
+  readonly mixer: Animation3DMixerRuntime;
+  readonly clipResolver: Animation3DStateMachineClipResolver;
+
+  private readonly _handles = new Set<Animation3DStateMachineActionRuntimeHandle>();
+  private readonly _transactionHandles: Animation3DStateMachineActionRuntimeHandle[] = [];
+  private readonly _transactionCreated: Animation3DStateMachineActionRuntimeHandle[] = [];
+  private readonly _transactionPendingDestroy: Animation3DStateMachineActionRuntimeHandle[] = [];
+  private readonly _actionIdPrefix: string;
+  private _nextActionId = 1;
+  private _transactionNextActionId = 1;
+  private _frameOut: Animation3DMutablePose | null = null;
+  private _controllerTransactionActive = false;
+  private _destroyed = false;
+
+  constructor(
+    mixer: Animation3DMixerRuntime,
+    clipResolver: Animation3DStateMachineClipResolver,
+  ) {
+    this.mixer = mixer;
+    this.clipResolver = clipResolver;
+    this._actionIdPrefix = `animation3d-state-machine:${nextAdapterId++}`;
+  }
+
+  get liveActionCount(): number {
+    return this._handles.size;
+  }
+
+  createAction(
+    clipId: string,
+    options: AnimationStateMachineActionOptions,
+  ): Animation3DStateMachineActionRuntimeHandle {
+    this._requireActive();
+    const clip = this.clipResolver.resolve(clipId);
+    if (!clip) {
+      throw new Animation3DError(
+        'resolver-miss',
+        `Animation3D clip resolver could not resolve "${clipId}".`,
+        { resolver: 'clip', clipId },
+      );
+    }
+    const action = this.mixer.createAction(clip, {
+      id: `${this._actionIdPrefix}:${this._nextActionId++}`,
+      loop: options.loop,
+      repetitions: options.loop === 'once' ? 1 : Infinity,
+      clampWhenFinished: true,
+      weight: 0,
+      blendMode: options.blendMode,
+      ...(options.mask ? { mask: options.mask } : {}),
+    }) as Animation3DActionRuntime;
+    const handle = new Animation3DStateMachineActionRuntimeHandle(
+      clipId,
+      options,
+      action,
+    );
+    this._handles.add(handle);
+    if (this._controllerTransactionActive) this._transactionCreated.push(handle);
+    return handle;
+  }
+
+  play(action: Animation3DStateMachineActionRuntimeHandle): void {
+    this._requireHandle(action);
+    action.action.play();
+    action.playing = true;
+  }
+
+  stop(action: Animation3DStateMachineActionRuntimeHandle): void {
+    this._requireHandle(action);
+    action.action.stop();
+    action.playing = false;
+  }
+
+  fade(
+    action: Animation3DStateMachineActionRuntimeHandle,
+    _targetWeight: number,
+    _durationSeconds: number,
+  ): void {
+    this._requireHandle(action);
+    // The controller computes exact source/destination weights for every
+    // transition segment. Scheduling an action-local fade here would multiply
+    // that weight and introduce a second transition clock.
+  }
+
+  setWeight(
+    action: Animation3DStateMachineActionRuntimeHandle,
+    weight: number,
+  ): void {
+    this._requireHandle(action);
+    action.action.weight = weight;
+  }
+
+  setTime(
+    action: Animation3DStateMachineActionRuntimeHandle,
+    timeSeconds: number,
+  ): void {
+    this._requireHandle(action);
+    action.targetTime = timeSeconds;
+    if (!action.playing) {
+      action.action.seekSynchronizedTime(timeSeconds);
+      action.appliedTime = timeSeconds;
+      return;
+    }
+    if (this._frameOut) this._applyTime(action, this._frameOut);
+  }
+
+  setTimeScale(
+    action: Animation3DStateMachineActionRuntimeHandle,
+    timeScale: number,
+  ): void {
+    this._requireHandle(action);
+    action.action.timeScale = timeScale;
+  }
+
+  destroyAction(action: Animation3DStateMachineActionRuntimeHandle): void {
+    if (action.destroyed) return;
+    if (!this._handles.has(action)) {
+      throw new Error('Animation3D state-machine action belongs to another adapter.');
+    }
+    if (this._controllerTransactionActive) {
+      if (action.pendingDestroy) return;
+      action.pendingDestroy = true;
+      this._transactionPendingDestroy.push(action);
+      return;
+    }
+    this._destroyHandleNow(action);
+  }
+
+  /** @internal Called by the shared controller transaction boundary. */
+  beginControllerTransaction(): void {
+    this._requireActive();
+    if (this._controllerTransactionActive) {
+      throw new Error('Animation3D state-machine adapter transaction is already active.');
+    }
+    this._controllerTransactionActive = true;
+    this._transactionNextActionId = this._nextActionId;
+    this._transactionHandles.length = 0;
+    this._transactionCreated.length = 0;
+    this._transactionPendingDestroy.length = 0;
+    for (const handle of this._handles) {
+      handle.captureTransactionState();
+      this._transactionHandles.push(handle);
+    }
+  }
+
+  /** @internal Makes deferred action destruction observable atomically. */
+  commitControllerTransaction(): void {
+    if (!this._controllerTransactionActive) {
+      throw new Error('Animation3D state-machine adapter has no active transaction.');
+    }
+    this._controllerTransactionActive = false;
+    for (let index = 0; index < this._transactionPendingDestroy.length; index++) {
+      this._destroyHandleNow(this._transactionPendingDestroy[index]!);
+    }
+    this._clearControllerTransaction();
+  }
+
+  /** @internal Removes new actions and restores exact event/playhead state. */
+  rollbackControllerTransaction(): void {
+    if (!this._controllerTransactionActive) return;
+    this._controllerTransactionActive = false;
+    for (let index = this._transactionCreated.length - 1; index >= 0; index--) {
+      this._destroyHandleNow(this._transactionCreated[index]!);
+    }
+    for (let index = 0; index < this._transactionHandles.length; index++) {
+      const handle = this._transactionHandles[index]!;
+      if (!handle.destroyed) handle.restoreTransactionState();
+    }
+    this._nextActionId = this._transactionNextActionId;
+    this._clearControllerTransaction();
+  }
+
+  beginFrame(out: Animation3DMutablePose): void {
+    this._requireActive();
+    if (this._frameOut) {
+      throw new Error('Animation3D state-machine adapter already has an active frame.');
+    }
+    this._frameOut = out;
+    for (const handle of this._handles) {
+      if (handle.playing) this._applyTime(handle, out);
+    }
+  }
+
+  endFrame(out: Animation3DMutablePose): void {
+    if (this._frameOut !== out) {
+      throw new Error('Animation3D state-machine adapter output does not match its active frame.');
+    }
+    this._frameOut = null;
+  }
+
+  cancelFrame(out: Animation3DMutablePose): void {
+    if (this._frameOut === out) this._frameOut = null;
+  }
+
+  /**
+   * Releases adapter-created actions only. The mixer, clips, and clip resolver
+   * are externally owned and are never destroyed by this adapter.
+   */
+  destroy(): void {
+    if (this._destroyed) return;
+    this.rollbackControllerTransaction();
+    this._frameOut = null;
+    for (const handle of this._handles) this._destroyHandleNow(handle);
+    this._destroyed = true;
+  }
+
+  private _applyTime(
+    handle: Animation3DStateMachineActionRuntimeHandle,
+    out: Animation3DMutablePose,
+  ): void {
+    handle.action.synchronizeTime(handle.targetTime, out);
+    handle.appliedTime = handle.targetTime;
+  }
+
+  private _destroyHandleNow(action: Animation3DStateMachineActionRuntimeHandle): void {
+    if (action.destroyed) return;
+    if (action.playing) action.action.stop();
+    this.mixer.removeAction(action.action);
+    action.playing = false;
+    action.pendingDestroy = false;
+    action.destroyed = true;
+    this._handles.delete(action);
+  }
+
+  private _clearControllerTransaction(): void {
+    for (let index = 0; index < this._transactionPendingDestroy.length; index++) {
+      this._transactionPendingDestroy[index]!.pendingDestroy = false;
+    }
+    this._transactionHandles.length = 0;
+    this._transactionCreated.length = 0;
+    this._transactionPendingDestroy.length = 0;
+  }
+
+  private _requireActive(): void {
+    if (this._destroyed) {
+      throw new Error('Animation3D state-machine mixer adapter has been destroyed.');
+    }
+  }
+
+  private _requireHandle(
+    handle: Animation3DStateMachineActionRuntimeHandle,
+  ): void {
+    this._requireActive();
+    if (handle.destroyed || !this._handles.has(handle)) {
+      throw new Error('Animation3D state-machine action is no longer valid.');
+    }
+  }
+}