@haiyue/extensions 0.1.0

package/dist/animation-state-machine/runtime/AnimationStateMachineCompiler.d.ts

@@ -0,0 +1,109 @@
+import type { AnimationStateMachineBindingMask as Animation3DBindingMask, AnimationStateMachineBlendMode as Animation3DBlendMode, AnimationStateMachineDefinition, AnimationStateMachineLoopMode as Animation3DLoopMode, AnimationStateMachineTransitionInterruption as Animation3DTransitionInterruption } from '../AnimationStateMachine.js';
+type LegacyAnimation3DStateMachineDefinition = Omit<AnimationStateMachineDefinition, 'format'> & Readonly<{
+    format: 'haiyue-animation3d-state-machine@1';
+}>;
+type SupportedAnimationStateMachineDefinition = AnimationStateMachineDefinition | LegacyAnimation3DStateMachineDefinition;
+export type Animation3DStateMachineValidationCode = 'invalid-value' | 'duplicate-id' | 'missing-reference' | 'parameter-type-mismatch' | 'invalid-operator' | 'empty-blend-tree' | 'invalid-thresholds' | 'recursive-motion';
+export interface Animation3DStateMachineValidationIssue {
+    readonly code: Animation3DStateMachineValidationCode;
+    readonly path: string;
+    readonly message: string;
+}
+export declare class AnimationStateMachineValidationError extends Error {
+    readonly issues: readonly Animation3DStateMachineValidationIssue[];
+    constructor(issues: readonly Animation3DStateMachineValidationIssue[]);
+}
+export type CompiledAnimation3DParameterType = 'float' | 'integer' | 'boolean' | 'trigger';
+export interface CompiledAnimation3DParameter {
+    readonly index: number;
+    readonly name: string;
+    readonly type: CompiledAnimation3DParameterType;
+    /** Triggers and false booleans use 0; true booleans use 1. */
+    readonly defaultValue: number;
+}
+export type CompiledAnimation3DConditionOperator = 'greater' | 'greater-or-equal' | 'less' | 'less-or-equal' | 'equal' | 'not-equal' | 'is-true' | 'is-false' | 'triggered';
+export interface CompiledAnimation3DCondition {
+    readonly parameterIndex: number;
+    readonly operator: CompiledAnimation3DConditionOperator;
+    readonly value: number;
+}
+export interface CompiledAnimation3DClipMotion {
+    readonly kind: 'clip';
+    readonly clipId: string;
+}
+export interface CompiledAnimation3DBlend1DChild {
+    readonly threshold: number;
+    readonly motion: CompiledAnimation3DMotion;
+}
+export interface CompiledAnimation3DBlend1DMotion {
+    readonly kind: 'blend-1d';
+    readonly parameterIndex: number;
+    readonly children: readonly CompiledAnimation3DBlend1DChild[];
+}
+export interface CompiledAnimation3DBlend2DChild {
+    readonly position: readonly [number, number];
+    readonly motion: CompiledAnimation3DMotion;
+    readonly declarationIndex: number;
+}
+export interface CompiledAnimation3DBlend2DMotion {
+    readonly kind: 'blend-2d';
+    readonly algorithm: 'cartesian' | 'directional';
+    readonly parameterXIndex: number;
+    readonly parameterYIndex: number;
+    readonly children: readonly CompiledAnimation3DBlend2DChild[];
+}
+export type CompiledAnimation3DMotion = CompiledAnimation3DClipMotion | CompiledAnimation3DBlend1DMotion | CompiledAnimation3DBlend2DMotion;
+export interface CompiledAnimation3DState {
+    readonly index: number;
+    readonly id: string;
+    readonly name: string;
+    readonly motion: CompiledAnimation3DMotion;
+    readonly speed: number;
+    readonly speedParameterIndex: number;
+    readonly loop: Animation3DLoopMode;
+}
+export interface CompiledAnimation3DTransition {
+    readonly index: number;
+    readonly id: string;
+    /** -1 denotes any-state. */
+    readonly fromStateIndex: number;
+    readonly toStateIndex: number;
+    readonly conditions: readonly CompiledAnimation3DCondition[];
+    readonly triggerParameterIndices: readonly number[];
+    readonly duration: number;
+    readonly hasExitTime: boolean;
+    readonly exitTime: number;
+    readonly destinationOffset: number;
+    readonly interruption: Animation3DTransitionInterruption;
+}
+export interface CompiledAnimation3DLayer {
+    readonly index: number;
+    readonly id: string;
+    readonly name: string;
+    readonly initialStateIndex: number;
+    readonly states: readonly CompiledAnimation3DState[];
+    /** Preserves declaration order, which is transition priority. */
+    readonly transitions: readonly CompiledAnimation3DTransition[];
+    readonly blendMode: Animation3DBlendMode;
+    readonly weight: number;
+    readonly mask: Animation3DBindingMask | null;
+    /** Compiler-created lookup; the update path uses numeric indices instead. */
+    readonly stateIndexById: ReadonlyMap<string, number>;
+}
+export interface CompiledAnimation3DStateMachine {
+    readonly format: 'haiyue-animation-state-machine-compiled@1';
+    readonly id: string;
+    readonly name: string;
+    readonly parameters: readonly CompiledAnimation3DParameter[];
+    readonly layers: readonly CompiledAnimation3DLayer[];
+    /** Setter/query boundary lookup; the update path uses numeric indices. */
+    readonly parameterIndexByName: ReadonlyMap<string, number>;
+    readonly layerIndexById: ReadonlyMap<string, number>;
+}
+export declare function validateAnimationStateMachineDefinition(definition: SupportedAnimationStateMachineDefinition): readonly Animation3DStateMachineValidationIssue[];
+export declare function compileAnimationStateMachineDefinition(definition: SupportedAnimationStateMachineDefinition): CompiledAnimation3DStateMachine;
+/** Compatibility aliases for the original 3D-prefixed runtime API. */
+export { AnimationStateMachineValidationError as Animation3DStateMachineValidationError, };
+export declare const validateAnimation3DStateMachineDefinition: typeof validateAnimationStateMachineDefinition;
+export declare const compileAnimation3DStateMachineDefinition: typeof compileAnimationStateMachineDefinition;
+export declare const compileAnimation3DStateMachine: typeof compileAnimationStateMachineDefinition;

package/dist/animation-state-machine/runtime/AnimationStateMachineController.d.ts

@@ -0,0 +1,103 @@
+import type { CompiledAnimation3DStateMachine } from './AnimationStateMachineCompiler.js';
+import type { Animation3DStateMachineActionHandle, Animation3DStateMachineMixerPort } from './AnimationStateMachineMixerPort.js';
+declare const CONTROLLER_UPDATE_TRANSACTION: unique symbol;
+export type Animation3DStateMachineControllerStatus = 'active' | 'destroyed';
+export interface Animation3DStateMachineControllerOptions {
+    /**
+     * Bounds zero-duration transition cycles and pathological large-delta
+     * updates per layer. Remaining time is still advanced after the limit is
+     * reached.
+     */
+    readonly maxTransitionsPerUpdate?: number;
+}
+export interface Animation3DStateMachineLayerSnapshot {
+    readonly layerId: string;
+    readonly currentStateId: string;
+    readonly currentTime: number;
+    readonly transitionId: string | null;
+    readonly sourceStateId: string | null;
+    readonly destinationStateId: string | null;
+    readonly transitionProgress: number;
+}
+/**
+ * Deterministic, mixer-agnostic runtime controller for a compiled definition.
+ * All string resolution happens in the compiler or at setter/query boundaries.
+ */
+export declare class Animation3DStateMachineController<TAction extends Animation3DStateMachineActionHandle = Animation3DStateMachineActionHandle> {
+    readonly compiled: CompiledAnimation3DStateMachine;
+    readonly port: Animation3DStateMachineMixerPort<TAction>;
+    readonly maxTransitionsPerUpdate: number;
+    lastUpdateTransitionCount: number;
+    transitionLimitReached: boolean;
+    private readonly _parameterValues;
+    private readonly _transactionParameterValues;
+    private readonly _layers;
+    private readonly _layerTransactionCheckpoints;
+    private _transactionLastUpdateTransitionCount;
+    private _transactionLimitReached;
+    private _transactionActive;
+    private _status;
+    constructor(compiled: CompiledAnimation3DStateMachine, port: Animation3DStateMachineMixerPort<TAction>, options?: Animation3DStateMachineControllerOptions);
+    get status(): Animation3DStateMachineControllerStatus;
+    get layerSnapshots(): readonly Animation3DStateMachineLayerSnapshot[];
+    getLayerSnapshot(layerId: string): Animation3DStateMachineLayerSnapshot;
+    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;
+    update(deltaSeconds: number): this;
+    /** @internal Keeps controller and transactional mixer ports atomic through final pose evaluation. */
+    [CONTROLLER_UPDATE_TRANSACTION](deltaSeconds: number, beforeUpdate?: () => void, complete?: () => unknown): unknown;
+    /**
+     * Restores defaults and initial states. Repeated reset calls are safe and
+     * leave the same observable controller state.
+     */
+    reset(): this;
+    /** Stops and releases all port actions. Idempotent. */
+    destroy(): void;
+    private _updateLayer;
+    private _captureUpdateTransaction;
+    private _restoreUpdateTransaction;
+    private _findEligibleTransition;
+    private _findInterruption;
+    private _startTransition;
+    private _interruptTransition;
+    private _completeTransition;
+    private _timeUntilNextExitTransition;
+    private _exitTimeReached;
+    private _timeUntilExit;
+    private _conditionsPass;
+    private _consumeTriggers;
+    private _createPlayback;
+    private _createRuntimeMotion;
+    private _advancePlayback;
+    private _advanceWithoutTransitions;
+    private _synchronizeAllLayers;
+    private _synchronizeLayer;
+    private _applyPlayback;
+    private _applyMotion;
+    private _playbackDuration;
+    private _motionDuration;
+    private _playbackSpeed;
+    private _evaluateDirectWeights;
+    private _fadePlayback;
+    private _fadeMotion;
+    private _destroyPlayback;
+    private _destroyAllLayers;
+    private _forEachAction;
+    private _snapshotLayer;
+    private _setTypedParameter;
+    private _resolveParameter;
+    private _restoreParameterDefaults;
+    private _requireActive;
+}
+/**
+ * @internal Extends one controller update transaction through caller-owned
+ * pose evaluation. It is intentionally not re-exported from package entries.
+ */
+export declare function runAnimationStateMachineControllerUpdateTransaction<TAction extends Animation3DStateMachineActionHandle, TResult>(controller: Animation3DStateMachineController<TAction>, deltaSeconds: number, beforeUpdate: () => void, complete: () => TResult): TResult;
+/** Factory kept internal to the runtime directory. */
+export declare function createAnimation3DStateMachineController<TAction extends Animation3DStateMachineActionHandle>(compiled: CompiledAnimation3DStateMachine, port: Animation3DStateMachineMixerPort<TAction>, options?: Animation3DStateMachineControllerOptions): Animation3DStateMachineController<TAction>;
+export {};

package/dist/animation-state-machine/runtime/AnimationStateMachineMixerPort.d.ts

@@ -0,0 +1,35 @@
+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/dist/animation-state-machine/runtime/index.d.ts

@@ -0,0 +1,7 @@
+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/dist/animation.d.ts

@@ -0,0 +1,15 @@
+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';