@nice2dev/game-engine 1.1.5 → 1.1.6

package/dist/types/systems/NiceParticle.d.ts

@@ -0,0 +1,639 @@
+/**
+ * NiceParticle - Game Engine Particle System
+ *
+ * Comprehensive particle system supporting:
+ * - Emitter types (point, box, circle, cone, sphere)
+ * - Particle properties (color, size, rotation, velocity)
+ * - Emission patterns and bursts
+ * - Forces (gravity, wind, attractors)
+ * - Collision and bouncing
+ * - Sub-emitters
+ * - Texture atlases and animations
+ * - Trails and ribbons
+ * - GPU-accelerated rendering
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+export type EmitterId = string;
+export type ParticleId = number;
+export type EmitterShape = 'point' | 'box' | 'circle' | 'sphere' | 'cone' | 'line' | 'ring';
+export type EmissionMode = 'continuous' | 'burst' | 'distanceBased';
+export type BlendMode = 'normal' | 'additive' | 'multiply' | 'screen';
+export type SortMode = 'none' | 'byDistance' | 'byAge' | 'byDepth';
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Color {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export interface MinMax<T = number> {
+    min: T;
+    max: T;
+}
+export interface Curve {
+    keys: Array<{
+        time: number;
+        value: number;
+        inTangent?: number;
+        outTangent?: number;
+    }>;
+}
+export type ValueOverLifetime<T = number> = {
+    type: 'constant';
+    value: T;
+} | {
+    type: 'random';
+    range: MinMax<T>;
+} | {
+    type: 'curve';
+    curve: Curve;
+    multiplier?: number;
+} | {
+    type: 'twoConstants';
+    min: T;
+    max: T;
+} | {
+    type: 'twoCurves';
+    min: Curve;
+    max: Curve;
+    multiplier?: number;
+};
+export type ColorOverLifetime = {
+    type: 'constant';
+    color: Color;
+} | {
+    type: 'gradient';
+    gradient: ColorGradient;
+} | {
+    type: 'twoGradients';
+    min: ColorGradient;
+    max: ColorGradient;
+};
+export interface ColorGradient {
+    colorKeys: Array<{
+        time: number;
+        color: Color;
+    }>;
+    alphaKeys: Array<{
+        time: number;
+        alpha: number;
+    }>;
+}
+export interface Particle {
+    id: ParticleId;
+    emitterId: EmitterId;
+    position: Vec3;
+    velocity: Vec3;
+    acceleration: Vec3;
+    rotation: number;
+    rotationVelocity: number;
+    size: Vec2;
+    startSize: Vec2;
+    color: Color;
+    startColor: Color;
+    lifetime: number;
+    age: number;
+    normalizedAge: number;
+    alive: boolean;
+    frame?: number;
+    customData?: Record<string, unknown>;
+}
+export interface BoxShape {
+    type: 'box';
+    size: Vec3;
+    emitFromEdge?: boolean;
+}
+export interface CircleShape {
+    type: 'circle';
+    radius: number;
+    arc?: number;
+    emitFromEdge?: boolean;
+}
+export interface SphereShape {
+    type: 'sphere';
+    radius: number;
+    emitFromShell?: boolean;
+}
+export interface ConeShape {
+    type: 'cone';
+    angle: number;
+    radius: number;
+    length?: number;
+    emitFrom?: 'base' | 'volume' | 'shell';
+}
+export interface LineShape {
+    type: 'line';
+    start: Vec3;
+    end: Vec3;
+}
+export interface RingShape {
+    type: 'ring';
+    radius: number;
+    thickness: number;
+    arc?: number;
+}
+export interface PointShape {
+    type: 'point';
+}
+export type ShapeConfig = PointShape | BoxShape | CircleShape | SphereShape | ConeShape | LineShape | RingShape;
+export interface GravityForce {
+    type: 'gravity';
+    direction: Vec3;
+    strength: number;
+}
+export interface WindForce {
+    type: 'wind';
+    direction: Vec3;
+    strength: number;
+    turbulence?: number;
+    frequency?: number;
+}
+export interface AttractorForce {
+    type: 'attractor';
+    position: Vec3;
+    strength: number;
+    radius: number;
+    falloff?: 'linear' | 'squared' | 'none';
+}
+export interface VortexForce {
+    type: 'vortex';
+    position: Vec3;
+    axis: Vec3;
+    strength: number;
+    radius: number;
+}
+export interface NoiseForce {
+    type: 'noise';
+    strength: Vec3;
+    frequency: number;
+    scrollSpeed?: Vec3;
+    octaves?: number;
+}
+export interface DragForce {
+    type: 'drag';
+    coefficient: number;
+}
+export type Force = GravityForce | WindForce | AttractorForce | VortexForce | NoiseForce | DragForce;
+export interface Burst {
+    time: number;
+    count: number | MinMax<number>;
+    cycles?: number;
+    interval?: number;
+    probability?: number;
+}
+export interface EmissionConfig {
+    mode: EmissionMode;
+    rateOverTime?: ValueOverLifetime;
+    rateOverDistance?: ValueOverLifetime;
+    bursts?: Burst[];
+}
+export interface TextureConfig {
+    src?: string;
+    frameCount?: number;
+    rows?: number;
+    columns?: number;
+    animationMode?: 'lifetime' | 'fps' | 'randomRow';
+    fps?: number;
+    startFrame?: number | MinMax<number>;
+}
+export interface TrailConfig {
+    enabled: boolean;
+    lifetime: number;
+    minVertexDistance: number;
+    width: ValueOverLifetime;
+    color: ColorOverLifetime;
+    textureMode?: 'stretch' | 'tile';
+    inheritParticleColor?: boolean;
+}
+export interface CollisionConfig {
+    enabled: boolean;
+    type: 'plane' | 'world';
+    bounce?: number;
+    lifetimeLoss?: number;
+    dampen?: number;
+    planes?: Array<{
+        position: Vec3;
+        normal: Vec3;
+    }>;
+}
+export interface SubEmitterConfig {
+    emitterId: EmitterId;
+    trigger: 'birth' | 'death' | 'collision' | 'manual';
+    probability?: number;
+    inheritVelocity?: number;
+    inheritColor?: boolean;
+}
+export interface EmitterConfig {
+    id: EmitterId;
+    name?: string;
+    maxParticles: number;
+    duration: number;
+    looping: boolean;
+    prewarm?: boolean;
+    startDelay?: ValueOverLifetime;
+    emission: EmissionConfig;
+    shape: ShapeConfig;
+    startLifetime: ValueOverLifetime;
+    startSpeed: ValueOverLifetime;
+    startSize: ValueOverLifetime<Vec2> | ValueOverLifetime<number>;
+    startRotation?: ValueOverLifetime;
+    startColor: ColorOverLifetime;
+    velocityOverLifetime?: {
+        linear?: ValueOverLifetime<Vec3>;
+        orbital?: ValueOverLifetime<Vec3>;
+        radial?: ValueOverLifetime;
+        speedModifier?: ValueOverLifetime;
+    };
+    sizeOverLifetime?: ValueOverLifetime;
+    rotationOverLifetime?: ValueOverLifetime;
+    colorOverLifetime?: ColorOverLifetime;
+    forces?: Force[];
+    texture?: TextureConfig;
+    blendMode: BlendMode;
+    sortMode?: SortMode;
+    renderMode?: 'billboard' | 'stretchedBillboard' | 'horizontalBillboard' | 'mesh';
+    trails?: TrailConfig;
+    collision?: CollisionConfig;
+    subEmitters?: SubEmitterConfig[];
+    simulationSpace?: 'local' | 'world';
+    scalingMode?: 'local' | 'shape' | 'hierarchy';
+    customData?: Record<string, unknown>;
+}
+export interface EmitterInstance {
+    id: string;
+    configId: EmitterId;
+    position: Vec3;
+    rotation: Vec3;
+    scale: Vec3;
+    isPlaying: boolean;
+    isPaused: boolean;
+    time: number;
+    duration: number;
+    particles: Particle[];
+    particlePool: Particle[];
+    nextParticleId: number;
+    emissionAccumulator: number;
+    burstIndex: number;
+    burstCycles: Map<number, number>;
+    lastPosition?: Vec3;
+    distanceTraveled: number;
+    customData?: Record<string, unknown>;
+}
+export type ParticleEventType = 'emitter-started' | 'emitter-stopped' | 'emitter-paused' | 'emitter-resumed' | 'emitter-completed' | 'particle-spawned' | 'particle-died' | 'particle-collision';
+export interface ParticleEvent {
+    type: ParticleEventType;
+    emitterInstanceId?: string;
+    emitterId?: EmitterId;
+    particle?: Particle;
+    timestamp: number;
+}
+export type ParticleEventCallback = (event: ParticleEvent) => void;
+export interface ParticleSystemConfig {
+    maxEmitters: number;
+    maxParticlesTotal: number;
+    fixedDeltaTime: number;
+    maxSubSteps: number;
+    cullDistance?: number;
+    lodLevels?: Array<{
+        distance: number;
+        ratio: number;
+    }>;
+}
+export declare const DEFAULT_PARTICLE_CONFIG: ParticleSystemConfig;
+export declare const DEFAULT_EMITTER_CONFIG: Partial<EmitterConfig>;
+export declare class NiceParticle extends EventEmitter {
+    private config;
+    private emitterConfigs;
+    private emitterInstances;
+    private nextInstanceId;
+    private totalParticles;
+    private destroyed;
+    constructor(config?: Partial<ParticleSystemConfig>);
+    registerEmitter(config: Partial<EmitterConfig> & {
+        id: EmitterId;
+    }): void;
+    getEmitterConfig(emitterId: EmitterId): EmitterConfig | undefined;
+    unregisterEmitter(emitterId: EmitterId): void;
+    createEmitter(emitterId: EmitterId, position?: Vec3, rotation?: Vec3): string;
+    destroyEmitter(instanceId: string): void;
+    play(instanceId: string): void;
+    stop(instanceId: string, clear?: boolean): void;
+    pause(instanceId: string): void;
+    resume(instanceId: string): void;
+    setPosition(instanceId: string, position: Vec3): void;
+    setRotation(instanceId: string, rotation: Vec3): void;
+    setScale(instanceId: string, scale: Vec3): void;
+    getInstance(instanceId: string): EmitterInstance | undefined;
+    update(deltaTime: number): void;
+    private updateEmitter;
+    private emitParticles;
+    private canSpawnParticle;
+    private spawnParticle;
+    private createParticle;
+    private calculateSpawnPosition;
+    private calculateInitialVelocity;
+    private updateParticles;
+    private applyForces;
+    getParticles(instanceId: string): Particle[];
+    getParticleCount(instanceId?: string): number;
+    getAllEmitters(): EmitterInstance[];
+    getActiveEmitters(): EmitterInstance[];
+    getStats(): {
+        emitterConfigs: number;
+        activeEmitters: number;
+        totalEmitters: number;
+        totalParticles: number;
+        maxParticles: number;
+    };
+    on(event: 'particle', callback: ParticleEventCallback): this;
+    off(event: 'particle', callback: ParticleEventCallback): this;
+    clear(): void;
+    destroy(): void;
+}
+export declare function createParticleSystem(config?: Partial<ParticleSystemConfig>): NiceParticle;
+export declare const PARTICLE_PRESETS: {
+    readonly fire: {
+        readonly id: "fire";
+        readonly maxParticles: 500;
+        readonly duration: 0;
+        readonly looping: true;
+        readonly emission: {
+            readonly mode: "continuous";
+            readonly rateOverTime: {
+                readonly type: "constant";
+                readonly value: 50;
+            };
+        };
+        readonly shape: {
+            readonly type: "circle";
+            readonly radius: 0.5;
+        };
+        readonly startLifetime: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 0.5;
+                readonly max: 1.5;
+            };
+        };
+        readonly startSpeed: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 2;
+                readonly max: 5;
+            };
+        };
+        readonly startSize: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 0.3;
+                readonly max: 0.8;
+            };
+        };
+        readonly startColor: {
+            readonly type: "gradient";
+            readonly gradient: {
+                readonly colorKeys: readonly [{
+                    readonly time: 0;
+                    readonly color: {
+                        readonly r: 1;
+                        readonly g: 0.8;
+                        readonly b: 0.2;
+                        readonly a: 1;
+                    };
+                }, {
+                    readonly time: 0.5;
+                    readonly color: {
+                        readonly r: 1;
+                        readonly g: 0.3;
+                        readonly b: 0.1;
+                        readonly a: 1;
+                    };
+                }, {
+                    readonly time: 1;
+                    readonly color: {
+                        readonly r: 0.5;
+                        readonly g: 0.1;
+                        readonly b: 0.1;
+                        readonly a: 1;
+                    };
+                }];
+                readonly alphaKeys: readonly [{
+                    readonly time: 0;
+                    readonly alpha: 1;
+                }, {
+                    readonly time: 0.8;
+                    readonly alpha: 0.5;
+                }, {
+                    readonly time: 1;
+                    readonly alpha: 0;
+                }];
+            };
+        };
+        readonly sizeOverLifetime: {
+            readonly type: "curve";
+            readonly curve: {
+                readonly keys: readonly [{
+                    readonly time: 0;
+                    readonly value: 1;
+                }, {
+                    readonly time: 0.3;
+                    readonly value: 1.5;
+                }, {
+                    readonly time: 1;
+                    readonly value: 0;
+                }];
+            };
+        };
+        readonly forces: readonly [{
+            readonly type: "gravity";
+            readonly direction: {
+                readonly x: 0;
+                readonly y: 1;
+                readonly z: 0;
+            };
+            readonly strength: 2;
+        }];
+        readonly blendMode: "additive";
+    };
+    readonly smoke: {
+        readonly id: "smoke";
+        readonly maxParticles: 200;
+        readonly duration: 0;
+        readonly looping: true;
+        readonly emission: {
+            readonly mode: "continuous";
+            readonly rateOverTime: {
+                readonly type: "constant";
+                readonly value: 20;
+            };
+        };
+        readonly shape: {
+            readonly type: "circle";
+            readonly radius: 0.3;
+        };
+        readonly startLifetime: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 2;
+                readonly max: 4;
+            };
+        };
+        readonly startSpeed: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 0.5;
+                readonly max: 1.5;
+            };
+        };
+        readonly startSize: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 0.5;
+                readonly max: 1;
+            };
+        };
+        readonly startColor: {
+            readonly type: "constant";
+            readonly color: {
+                readonly r: 0.3;
+                readonly g: 0.3;
+                readonly b: 0.3;
+                readonly a: 0.5;
+            };
+        };
+        readonly sizeOverLifetime: {
+            readonly type: "curve";
+            readonly curve: {
+                readonly keys: readonly [{
+                    readonly time: 0;
+                    readonly value: 1;
+                }, {
+                    readonly time: 1;
+                    readonly value: 3;
+                }];
+            };
+        };
+        readonly colorOverLifetime: {
+            readonly type: "gradient";
+            readonly gradient: {
+                readonly colorKeys: readonly [{
+                    readonly time: 0;
+                    readonly color: {
+                        readonly r: 0.3;
+                        readonly g: 0.3;
+                        readonly b: 0.3;
+                        readonly a: 1;
+                    };
+                }];
+                readonly alphaKeys: readonly [{
+                    readonly time: 0;
+                    readonly alpha: 0.5;
+                }, {
+                    readonly time: 1;
+                    readonly alpha: 0;
+                }];
+            };
+        };
+        readonly forces: readonly [{
+            readonly type: "gravity";
+            readonly direction: {
+                readonly x: 0;
+                readonly y: 1;
+                readonly z: 0;
+            };
+            readonly strength: 0.5;
+        }, {
+            readonly type: "wind";
+            readonly direction: {
+                readonly x: 1;
+                readonly y: 0;
+                readonly z: 0;
+            };
+            readonly strength: 0.3;
+        }];
+        readonly blendMode: "normal";
+    };
+    readonly explosion: {
+        readonly id: "explosion";
+        readonly maxParticles: 100;
+        readonly duration: 0.5;
+        readonly looping: false;
+        readonly emission: {
+            readonly mode: "burst";
+            readonly bursts: readonly [{
+                readonly time: 0;
+                readonly count: 100;
+            }];
+        };
+        readonly shape: {
+            readonly type: "sphere";
+            readonly radius: 0.1;
+            readonly emitFromShell: true;
+        };
+        readonly startLifetime: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 0.3;
+                readonly max: 0.8;
+            };
+        };
+        readonly startSpeed: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 5;
+                readonly max: 15;
+            };
+        };
+        readonly startSize: {
+            readonly type: "random";
+            readonly range: {
+                readonly min: 0.2;
+                readonly max: 0.5;
+            };
+        };
+        readonly startColor: {
+            readonly type: "gradient";
+            readonly gradient: {
+                readonly colorKeys: readonly [{
+                    readonly time: 0;
+                    readonly color: {
+                        readonly r: 1;
+                        readonly g: 1;
+                        readonly b: 0.5;
+                        readonly a: 1;
+                    };
+                }, {
+                    readonly time: 0.5;
+                    readonly color: {
+                        readonly r: 1;
+                        readonly g: 0.5;
+                        readonly b: 0.1;
+                        readonly a: 1;
+                    };
+                }];
+                readonly alphaKeys: readonly [{
+                    readonly time: 0;
+                    readonly alpha: 1;
+                }, {
+                    readonly time: 1;
+                    readonly alpha: 0;
+                }];
+            };
+        };
+        readonly forces: readonly [{
+            readonly type: "drag";
+            readonly coefficient: 2;
+        }];
+        readonly blendMode: "additive";
+    };
+};