@nice2dev/game-engine 0.1.0 → 1.0.3

package/dist/types/ai/StateMachine.d.ts

@@ -0,0 +1,296 @@
+/**
+ * @file StateMachine.ts
+ * @description Finite State Machine System with Graphical Editor Support
+ * PRO-1.4: Professional Editor Features
+ *
+ * Features:
+ * - Hierarchical state machines (HSM)
+ * - Transitions with conditions and actions
+ * - Entry/Exit/Update callbacks
+ * - Transition triggers and events
+ * - Visual editor integration
+ * - Debugging and history
+ * - Parallel states
+ * - Animation state machine support
+ */
+import type { EntityId, Vec2 } from '../core/types';
+export type SMStateType = 'normal' | 'entry' | 'exit' | 'any' | 'parallel' | 'submachine';
+export interface SMParameter {
+    name: string;
+    type: 'bool' | 'int' | 'float' | 'trigger';
+    value: boolean | number;
+}
+export type SMConditionOperator = 'equals' | 'notEquals' | 'greater' | 'less' | 'greaterEqual' | 'lessEqual';
+export interface SMCondition {
+    id: string;
+    parameter: string;
+    operator: SMConditionOperator;
+    value: boolean | number;
+}
+export interface SMConditionGroup {
+    id: string;
+    /** AND = all must pass, OR = any must pass */
+    mode: 'and' | 'or';
+    conditions: SMCondition[];
+}
+export interface SMTransition {
+    id: string;
+    name?: string;
+    /** Source state ID (or 'any' for any-state transitions) */
+    from: string;
+    /** Target state ID */
+    to: string;
+    /** Conditions that must be met */
+    conditions: SMConditionGroup[];
+    /** Transition duration (for blending) */
+    duration: number;
+    /** Priority (lower = higher priority) */
+    priority: number;
+    /** Can interrupt current state */
+    canInterrupt: boolean;
+    /** Trigger name (consumed on use) */
+    trigger?: string;
+    /** Offset into target state (0-1) for animation */
+    targetOffset?: number;
+    /** Custom transition curve */
+    curve?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+    /** Editor: control points for curved transition line */
+    controlPoints?: Vec2[];
+    /** Is this transition muted (disabled) */
+    muted?: boolean;
+}
+export interface SMState {
+    id: string;
+    name: string;
+    type: SMStateType;
+    /** Position in editor */
+    position: Vec2;
+    /** Size in editor (for comments) */
+    size?: Vec2;
+    /** Custom color */
+    color?: string;
+    /** State speed multiplier (for animation) */
+    speed: number;
+    /** Motion/animation clip reference */
+    motion?: string;
+    /** Is this the default state? */
+    isDefault?: boolean;
+    /** Sub-state machine ID (for submachine states) */
+    submachineId?: string;
+    /** Child states (for parallel/hierarchical) */
+    children?: string[];
+    /** Tags for grouping */
+    tags?: string[];
+    /** Custom data */
+    customData?: Record<string, unknown>;
+    /** Behaviors attached to this state */
+    behaviors?: SMStateBehavior[];
+}
+export interface SMStateBehavior {
+    id: string;
+    type: string;
+    enabled: boolean;
+    properties: Record<string, unknown>;
+}
+export interface SMLayer {
+    id: string;
+    name: string;
+    /** Layer weight (for animation blending) */
+    weight: number;
+    /** Blending mode */
+    blendMode: 'override' | 'additive';
+    /** Sync with another layer */
+    syncedLayer?: string;
+    /** Is this layer active? */
+    active: boolean;
+    /** States in this layer */
+    states: SMState[];
+    /** Transitions in this layer */
+    transitions: SMTransition[];
+    /** Default state ID */
+    defaultState?: string;
+    /** Any-state transitions */
+    anyStateTransitions: SMTransition[];
+}
+export interface SMDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    /** Parameters */
+    parameters: SMParameter[];
+    /** Layers */
+    layers: SMLayer[];
+    /** Metadata */
+    metadata?: {
+        author?: string;
+        version?: string;
+        created?: number;
+        modified?: number;
+    };
+}
+export interface SMContext {
+    entityId: EntityId;
+    dt: number;
+    time: number;
+    world: unknown;
+    /** Custom services */
+    services: Map<string, unknown>;
+}
+export interface SMStateInstance {
+    stateId: string;
+    layerId: string;
+    enterTime: number;
+    elapsedTime: number;
+    normalizedTime: number;
+    isTransitioning: boolean;
+}
+export interface SMTransitionInstance {
+    transitionId: string;
+    fromState: string;
+    toState: string;
+    startTime: number;
+    duration: number;
+    progress: number;
+}
+export type SMEventType = 'state-enter' | 'state-exit' | 'state-update' | 'transition-start' | 'transition-complete' | 'parameter-changed';
+export interface SMEvent {
+    type: SMEventType;
+    timestamp: number;
+    layerId: string;
+    data: unknown;
+}
+export type SMCallback = (context: SMContext, state: SMState) => void;
+export type SMTransitionCallback = (context: SMContext, transition: SMTransition) => void;
+export declare class StateMachine {
+    private definition;
+    private layerStates;
+    private activeTransitions;
+    private parameters;
+    private triggers;
+    /** Callbacks */
+    private onEnter;
+    private onExit;
+    private onUpdate;
+    private onTransitionStart;
+    private onTransitionComplete;
+    /** Event listeners */
+    private eventListeners;
+    /** Debugging */
+    private history;
+    private historyLimit;
+    debugMode: boolean;
+    constructor(definition: SMDefinition);
+    private initializeParameters;
+    private initializeLayers;
+    setParameter(name: string, value: boolean | number): void;
+    getParameter(name: string): boolean | number | undefined;
+    setBool(name: string, value: boolean): void;
+    getBool(name: string): boolean;
+    setFloat(name: string, value: number): void;
+    getFloat(name: string): number;
+    setInteger(name: string, value: number): void;
+    getInteger(name: string): number;
+    setTrigger(name: string): void;
+    resetTrigger(name: string): void;
+    update(context: SMContext): void;
+    private updateLayer;
+    private findValidTransition;
+    private evaluateConditions;
+    private evaluateConditionGroup;
+    private evaluateCondition;
+    private startTransition;
+    private completeTransition;
+    private callOnEnter;
+    private callOnExit;
+    private callOnUpdate;
+    registerOnEnter(stateId: string, callback: SMCallback): void;
+    registerOnExit(stateId: string, callback: SMCallback): void;
+    registerOnUpdate(stateId: string, callback: SMCallback): void;
+    registerOnTransitionStart(callback: SMTransitionCallback): void;
+    registerOnTransitionComplete(callback: SMTransitionCallback): void;
+    on(event: SMEventType, listener: (event: SMEvent) => void): void;
+    off(event: SMEventType, listener: (event: SMEvent) => void): void;
+    private emit;
+    getCurrentState(layerId?: string): SMState | null;
+    getCurrentStateId(layerId?: string): string | null;
+    isInState(stateId: string, layerId?: string): boolean;
+    isTransitioning(layerId?: string): boolean;
+    getTransitionProgress(layerId?: string): number;
+    getStateTime(layerId?: string): number;
+    forceState(stateId: string, layerId?: string): void;
+    reset(): void;
+    getHistory(): SMEvent[];
+    clearHistory(): void;
+    getDebugInfo(): {
+        layers: Array<{
+            id: string;
+            name: string;
+            currentState: string | null;
+            isTransitioning: boolean;
+            transitionProgress: number;
+        }>;
+        parameters: Record<string, boolean | number>;
+    };
+    getDefinition(): SMDefinition;
+    clone(): StateMachine;
+}
+/** Extended state machine for animation control */
+export declare class AnimatorController extends StateMachine {
+    private motionValues;
+    private blendTrees;
+    constructor(definition: SMDefinition);
+    /** Get blended motion value for animation sampling */
+    getMotionValue(layerId: string): number;
+    /** Get current motion/clip name */
+    getMotionClip(layerId?: string): string | null;
+    /** Register a blend tree for a state */
+    registerBlendTree(stateId: string, blendTree: BlendTree): void;
+    /** Sample blend tree for current parameters */
+    sampleBlendTree(stateId: string): BlendTreeSample | null;
+    private getParameterMap;
+}
+export type BlendTreeType = '1d' | '2d-simple' | '2d-freeform' | 'direct';
+export interface BlendTreeMotion {
+    clip: string;
+    position: number | Vec2;
+    speed?: number;
+    mirror?: boolean;
+    threshold?: number;
+}
+export interface BlendTreeSample {
+    clips: Array<{
+        clip: string;
+        weight: number;
+        speed: number;
+        mirror: boolean;
+    }>;
+}
+export declare class BlendTree {
+    type: BlendTreeType;
+    parameterX: string;
+    parameterY?: string;
+    motions: BlendTreeMotion[];
+    constructor(type: BlendTreeType, parameterX: string, parameterY?: string);
+    addMotion(motion: BlendTreeMotion): void;
+    sample(parameters: Record<string, number>): BlendTreeSample;
+    private sample1D;
+    private sample2D;
+    private sampleDirect;
+}
+export declare function createStateMachine(definition: SMDefinition): StateMachine;
+export declare function createAnimatorController(definition: SMDefinition): AnimatorController;
+export declare function createBlendTree1D(parameter: string): BlendTree;
+export declare function createBlendTree2D(parameterX: string, parameterY: string, type?: '2d-simple' | '2d-freeform'): BlendTree;
+export declare function createSMDefinition(name: string): SMDefinition;
+export declare function createSMLayer(name: string): SMLayer;
+export declare function createSMState(name: string, type?: SMStateType): SMState;
+export declare function createSMTransition(from: string, to: string): SMTransition;
+export declare function createSMParameter(name: string, type: SMParameter['type'], value?: boolean | number): SMParameter;
+export declare function createSMCondition(parameter: string, operator: SMConditionOperator, value: boolean | number): SMCondition;
+export declare function createSMConditionGroup(mode?: 'and' | 'or'): SMConditionGroup;
+export declare function createSMContext(params: {
+    entityId: EntityId;
+    dt: number;
+    time: number;
+    world: unknown;
+}): SMContext;

package/dist/types/audio/AudioBridge.d.ts

@@ -0,0 +1,199 @@
+import { EventBus } from '../core/EventBus';
+import React from 'react';
+export type AudioBusType = 'master' | 'music' | 'sfx' | 'voice' | 'ambient' | 'ui';
+export type SpatialModel = 'none' | '2d-panning' | '3d-hrtf' | '3d-equal-power';
+export type AudioPoolStrategy = 'round-robin' | 'steal-oldest' | 'steal-quietest' | 'reject';
+export interface AudioBusConfig {
+    type: AudioBusType;
+    volume: number;
+    muted: boolean;
+    effects: AudioEffectNode[];
+}
+export interface AudioEffectNode {
+    type: 'reverb' | 'delay' | 'distortion' | 'compressor' | 'eq' | 'lowpass' | 'highpass';
+    enabled: boolean;
+    params: Record<string, number>;
+}
+export interface SpatialAudioConfig {
+    model: SpatialModel;
+    maxDistance: number;
+    refDistance: number;
+    rolloffFactor: number;
+    coneInnerAngle: number;
+    coneOuterAngle: number;
+    coneOuterGain: number;
+}
+export declare const DEFAULT_SPATIAL: SpatialAudioConfig;
+export interface AudioPoolConfig {
+    id: string;
+    src: string;
+    maxInstances: number;
+    strategy: AudioPoolStrategy;
+    bus: AudioBusType;
+    spatial?: SpatialAudioConfig;
+    cooldownMs?: number;
+}
+export interface GameAudioEvent {
+    type: 'play' | 'stop' | 'pause' | 'resume' | 'fade' | 'crossfade' | 'set-bus-volume';
+    sourceId?: string;
+    bus?: AudioBusType;
+    volume?: number;
+    fadeDuration?: number;
+    position?: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+}
+export interface MusicTrack {
+    id: string;
+    src: string;
+    bpm?: number;
+    loopStart?: number;
+    loopEnd?: number;
+    tags: string[];
+}
+export interface MusicCrossfadeConfig {
+    fromTrackId: string | null;
+    toTrackId: string;
+    duration: number;
+    curve: 'linear' | 'equal-power' | 'ease-in' | 'ease-out';
+}
+export interface AdaptiveAudioRule {
+    id: string;
+    /** Game event that triggers this rule */
+    triggerEvent: string;
+    /** Action to take */
+    action: 'switch-track' | 'add-layer' | 'remove-layer' | 'set-intensity' | 'play-stinger';
+    targetTrackId?: string;
+    layerId?: string;
+    intensity?: number;
+    fadeDuration?: number;
+    stingerSrc?: string;
+    priority: number;
+}
+export interface AudioSnapshot {
+    timestamp: number;
+    busVolumes: Record<AudioBusType, number>;
+    activeSounds: {
+        id: string;
+        src: string;
+        bus: AudioBusType;
+        volume: number;
+        playing: boolean;
+    }[];
+    currentMusicTrack: string | null;
+    musicPosition: number;
+}
+export declare class AudioBusMixer {
+    private buses;
+    private eventBus;
+    constructor(eventBus: EventBus);
+    getBus(type: AudioBusType): AudioBusConfig | undefined;
+    setVolume(type: AudioBusType, volume: number): void;
+    setMuted(type: AudioBusType, muted: boolean): void;
+    /** Get effective volume considering master and mute */
+    getEffectiveVolume(type: AudioBusType): number;
+    addEffect(type: AudioBusType, effect: AudioEffectNode): void;
+    removeEffect(type: AudioBusType, effectType: AudioEffectNode['type']): void;
+    getAllBuses(): ReadonlyMap<AudioBusType, AudioBusConfig>;
+    snapshot(): Record<AudioBusType, number>;
+}
+export declare class SFXPool {
+    private config;
+    private sounds;
+    private nextId;
+    private lastPlayedAt;
+    constructor(config: AudioPoolConfig);
+    play(volume?: number, position?: {
+        x: number;
+        y: number;
+        z?: number;
+    }): number | null;
+    stop(id: number): void;
+    stopAll(): void;
+    getActiveCount(): number;
+    getConfig(): Readonly<AudioPoolConfig>;
+}
+export declare class MusicManager {
+    private tracks;
+    private currentTrackId;
+    private adaptiveRules;
+    private eventBus;
+    private intensity;
+    constructor(eventBus: EventBus);
+    registerTrack(track: MusicTrack): void;
+    unregisterTrack(id: string): void;
+    getTrack(id: string): MusicTrack | undefined;
+    getCurrentTrackId(): string | null;
+    /** Start playing or crossfade to a new track */
+    play(trackId: string, crossfadeDuration?: number): MusicCrossfadeConfig | null;
+    stop(fadeOutMs?: number): void;
+    /** Adaptive audio rules — respond to game events */
+    addRule(rule: AdaptiveAudioRule): void;
+    removeRule(id: string): void;
+    /** Process a game event and apply matching adaptive rules */
+    processGameEvent(eventName: string): AdaptiveAudioRule | null;
+    getIntensity(): number;
+    setIntensity(value: number): void;
+    getRules(): readonly AdaptiveAudioRule[];
+    getAllTracks(): MusicTrack[];
+    /** Find tracks matching tags */
+    findByTags(tags: string[]): MusicTrack[];
+}
+/** Main bridge class connecting @nice2dev/ui-audio features to the game engine */
+export declare class GameAudioBridge {
+    readonly mixer: AudioBusMixer;
+    readonly music: MusicManager;
+    private pools;
+    private eventBus;
+    private paused;
+    private snapshot;
+    constructor(eventBus: EventBus);
+    private setupGameStateHandlers;
+    /** Register an SFX pool for frequent sounds */
+    registerPool(config: AudioPoolConfig): void;
+    /** Play a pooled SFX */
+    playSFX(poolId: string, volume?: number, position?: {
+        x: number;
+        y: number;
+        z?: number;
+    }): number | null;
+    /** Stop a pooled SFX instance */
+    stopSFX(poolId: string, instanceId: number): void;
+    /** Pause all audio (game menu, alt-tab, etc.) */
+    pauseAll(): void;
+    /** Resume all audio */
+    resumeAll(): void;
+    isPaused(): boolean;
+    /** Create a snapshot of current audio state for save/restore */
+    createSnapshot(): AudioSnapshot;
+    /** Restore audio from a snapshot */
+    restoreSnapshot(snap: AudioSnapshot): void;
+    /** Process a game audio event */
+    processEvent(event: GameAudioEvent): void;
+    getPool(id: string): SFXPool | undefined;
+    getAllPools(): Map<string, SFXPool>;
+    destroy(): void;
+}
+export declare function useGameAudio(eventBus: EventBus): {
+    bridge: GameAudioBridge;
+    playSFX: (poolId: string, volume?: number, position?: {
+        x: number;
+        y: number;
+        z?: number;
+    }) => number | null;
+    playMusic: (trackId: string, crossfadeDuration?: number) => MusicCrossfadeConfig | null;
+    stopMusic: (fadeOutMs?: number) => void;
+    setVolume: (bus: AudioBusType, volume: number) => void;
+    pauseAll: () => void;
+    resumeAll: () => void;
+    registerPool: (config: AudioPoolConfig) => void;
+    registerTrack: (track: MusicTrack) => void;
+};
+export interface GameAudioSettingsProps {
+    bridge: GameAudioBridge;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare const GameAudioSettings: React.FC<GameAudioSettingsProps>;