@holoscript/engine 6.0.3 → 6.0.4

package/dist/index-CnRzWxi_.d.cts

@@ -0,0 +1,522 @@
+/**
+ * ParticleSystem.ts
+ *
+ * High-performance particle system with object pooling.
+ * Manages particle lifecycle: birth, update, death, recycling.
+ */
+interface Color4 {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+interface Particle$2 {
+    alive: boolean;
+    age: number;
+    lifetime: number;
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    ax: number;
+    ay: number;
+    az: number;
+    size: number;
+    sizeStart: number;
+    sizeEnd: number;
+    color: Color4;
+    colorStart: Color4;
+    colorEnd: Color4;
+    rotation: number;
+    rotationSpeed: number;
+}
+type EmitterShape = 'point' | 'sphere' | 'cone' | 'box';
+interface EmitterConfig$1 {
+    /** Shape of the emission volume */
+    shape: EmitterShape;
+    /** Particles emitted per second */
+    rate: number;
+    /** Burst: emit N particles instantly */
+    burst?: number;
+    /** Max active particles */
+    maxParticles: number;
+    /** Particle lifetime range [min, max] seconds */
+    lifetime: [number, number];
+    /** Initial speed range [min, max] */
+    speed: [number, number];
+    /** Initial size range [min, max] */
+    size: [number, number];
+    /** End size range [min, max] */
+    sizeEnd: [number, number];
+    /** Start color */
+    colorStart: Color4;
+    /** End color (interpolates over lifetime) */
+    colorEnd: Color4;
+    /** Emitter world position */
+    position: [number, number, number];
+    /** For cone shape: half-angle in radians */
+    coneAngle?: number;
+    /** For sphere/box: radius/extents */
+    radius?: number;
+    /** Rotation speed range [min, max] */
+    rotationSpeed?: [number, number];
+    /** Direction bias (normalized) */
+    direction?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+declare class ParticleSystem {
+    private pool;
+    private config;
+    private emitAccumulator;
+    private activeCount;
+    private _isEmitting;
+    private totalElapsed;
+    /** External affectors applied each frame */
+    private affectors;
+    constructor(config: EmitterConfig$1);
+    private createDeadParticle;
+    /**
+     * Add an affector function that runs on each particle per update.
+     */
+    addAffector(fn: (p: Particle$2, delta: number) => void): void;
+    /**
+     * Start/stop emitting new particles.
+     */
+    setEmitting(emitting: boolean): void;
+    isEmitting(): boolean;
+    /**
+     * Emit a burst of N particles immediately.
+     */
+    burst(count: number): void;
+    /**
+     * Update all particles. Call every frame.
+     */
+    update(delta: number): void;
+    private emitOne;
+    private sampleEmitterShape;
+    /**
+     * Get all alive particles (for rendering).
+     */
+    getAliveParticles(): Particle$2[];
+    /**
+     * Get active particle count.
+     */
+    getActiveCount(): number;
+    /**
+     * Get the config.
+     */
+    getConfig(): EmitterConfig$1;
+    /**
+     * Update emitter position.
+     */
+    setPosition(x: number, y: number, z: number): void;
+}
+
+/**
+ * ParticleAffectors.ts
+ *
+ * Reusable affector functions that modify particles each frame.
+ * Plug these into ParticleSystem.addAffector().
+ */
+
+/**
+ * Gravity: Constant downward acceleration.
+ */
+declare function gravity(strength?: number): (p: Particle$2, delta: number) => void;
+/**
+ * Wind: Constant force in a direction.
+ */
+declare function wind(x: number, y: number, z: number): (p: Particle$2, delta: number) => void;
+/**
+ * Turbulence: Random velocity perturbation based on pseudo-noise.
+ */
+declare function turbulence(strength?: number): (p: Particle$2, delta: number) => void;
+/**
+ * Drag: Velocity damping (air resistance).
+ */
+declare function drag(coefficient?: number): (p: Particle$2, delta: number) => void;
+/**
+ * Attractor: Pull particles toward a point.
+ */
+declare function attractor(x: number, y: number, z: number, strength?: number, minDist?: number): (p: Particle$2, delta: number) => void;
+/**
+ * Vortex: Spin particles around an axis.
+ */
+declare function vortex(axisX: number, axisY: number, axisZ: number, strength?: number): (p: Particle$2, delta: number) => void;
+/**
+ * Floor bounce: Bounce particles off a horizontal plane.
+ */
+declare function floorBounce(floorY?: number, bounciness?: number): (p: Particle$2, delta: number) => void;
+/**
+ * Size oscillation: Pulse size over lifetime.
+ */
+declare function sizeOscillate(frequency?: number, amplitude?: number): (p: Particle$2, delta: number) => void;
+
+/**
+ * ParticlePresets.ts
+ *
+ * Ready-to-use particle emitter configurations for common visual effects.
+ */
+
+declare const ParticlePresets: Record<string, EmitterConfig$1>;
+
+/**
+ * ParticleAttractor.ts
+ *
+ * Point/line/plane attractors for particle systems:
+ * inverse-square falloff, orbital motion, and kill radius.
+ *
+ * @module particles
+ */
+type AttractorShape = 'point' | 'line' | 'plane';
+interface Attractor {
+    id: string;
+    shape: AttractorShape;
+    position: [number, number, number];
+    direction: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    strength: number;
+    radius: number;
+    killRadius: number;
+    orbit: boolean;
+}
+interface Particle$1 {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    alive: boolean;
+}
+declare class ParticleAttractorSystem {
+    private attractors;
+    addAttractor(a: Attractor): void;
+    removeAttractor(id: string): void;
+    apply(particles: Particle$1[], dt: number): void;
+    getAttractorCount(): number;
+}
+
+/**
+ * ParticleEmitter.ts
+ *
+ * Particle emission system: shapes, lifetime, velocity,
+ * color/size over lifetime curves, and sub-emitters.
+ *
+ * @module particles
+ */
+interface IVector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface IColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+interface CurveKeyframe {
+    time: number;
+    value: number;
+}
+type EmissionShape = 'point' | 'sphere' | 'box' | 'cone' | 'circle' | 'line';
+interface EmitterConfig {
+    id: string;
+    maxParticles: number;
+    emissionRate: number;
+    emissionShape: EmissionShape;
+    shapeParams: {
+        radius?: number;
+        angle?: number;
+        extents?: IVector3;
+        length?: number;
+    };
+    lifetime: {
+        min: number;
+        max: number;
+    };
+    startSpeed: {
+        min: number;
+        max: number;
+    };
+    startSize: {
+        min: number;
+        max: number;
+    };
+    startColor: IColor;
+    endColor?: IColor;
+    gravity: number;
+    sizeOverLifetime?: CurveKeyframe[];
+    alphaOverLifetime?: CurveKeyframe[];
+    speedOverLifetime?: CurveKeyframe[];
+    worldSpace: boolean;
+    prewarm: boolean;
+}
+interface Particle {
+    position: IVector3;
+    velocity: IVector3;
+    color: IColor;
+    size: number;
+    age: number;
+    lifetime: number;
+    alive: boolean;
+    startSpeed: number;
+}
+interface EmitterState {
+    id: string;
+    playing: boolean;
+    elapsed: number;
+    emissionAccum: number;
+    aliveCount: number;
+    totalEmitted: number;
+}
+declare class ParticleEmitter {
+    readonly config: EmitterConfig;
+    private particles;
+    private state;
+    constructor(config: EmitterConfig);
+    play(): void;
+    pause(): void;
+    stop(): void;
+    isPlaying(): boolean;
+    getState(): EmitterState;
+    update(dt: number): Particle[];
+    private emit;
+    private sampleShape;
+    private randomDirection;
+    private createDeadParticle;
+    getAliveParticles(): Particle[];
+    getAliveCount(): number;
+    getCapacity(): number;
+}
+
+/**
+ * ParticleCollision.ts
+ *
+ * Particle collision: plane/sphere bounce, friction,
+ * lifetime reduction on impact, and sub-emitter spawning.
+ *
+ * @module particles
+ */
+interface CollisionPlane {
+    id: string;
+    nx: number;
+    ny: number;
+    nz: number;
+    d: number;
+    bounce: number;
+    friction: number;
+    lifetimeLoss: number;
+}
+interface CollisionSphere {
+    id: string;
+    cx: number;
+    cy: number;
+    cz: number;
+    radius: number;
+    bounce: number;
+    friction: number;
+}
+interface CollidableParticle {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    lifetime: number;
+    alive: boolean;
+}
+type SubEmitCallback = (x: number, y: number, z: number, count: number) => void;
+declare class ParticleCollisionSystem {
+    private planes;
+    private spheres;
+    private subEmitCallback;
+    private subEmitCount;
+    private collisionCount;
+    addPlane(plane: CollisionPlane): void;
+    addSphere(sphere: CollisionSphere): void;
+    onSubEmit(callback: SubEmitCallback, count?: number): void;
+    resolve(particles: CollidableParticle[]): void;
+    getCollisionCount(): number;
+}
+
+/**
+ * ParticleForces.ts
+ *
+ * Force field system for particles: gravity, wind, turbulence,
+ * point attractors, vortex fields, and drag.
+ *
+ * @module particles
+ */
+
+type ForceType = 'gravity' | 'wind' | 'turbulence' | 'attractor' | 'vortex' | 'drag';
+interface ForceFieldConfig {
+    id: string;
+    type: ForceType;
+    strength: number;
+    position?: IVector3;
+    direction?: IVector3;
+    radius?: number;
+    falloff?: 'linear' | 'quadratic' | 'none';
+    frequency?: number;
+    dragCoefficient?: number;
+}
+interface ForceField {
+    config: ForceFieldConfig;
+    enabled: boolean;
+}
+declare class ParticleForceSystem {
+    private fields;
+    private time;
+    addForce(config: ForceFieldConfig): void;
+    removeForce(id: string): void;
+    setEnabled(id: string, enabled: boolean): void;
+    getForce(id: string): ForceField | undefined;
+    getForceCount(): number;
+    /**
+     * Apply all force fields to a set of particles.
+     */
+    apply(particles: Particle[], dt: number): void;
+    private applyForce;
+    private applyGravity;
+    private applyWind;
+    private applyTurbulence;
+    private applyAttractor;
+    private applyVortex;
+    private applyDrag;
+    private getPositionalFalloff;
+}
+
+/**
+ * ParticleTurbulence.ts
+ *
+ * Turbulence fields for particles: curl noise approximation,
+ * vortex fields, time-varying strength, and frequency control.
+ *
+ * @module particles
+ */
+interface TurbulenceConfig {
+    strength: number;
+    frequency: number;
+    octaves: number;
+    time: number;
+}
+interface TurbParticle {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+}
+declare class ParticleTurbulence {
+    private config;
+    constructor(config?: Partial<TurbulenceConfig>);
+    setStrength(s: number): void;
+    setFrequency(f: number): void;
+    setTime(t: number): void;
+    getConfig(): TurbulenceConfig;
+    sampleCurl(x: number, y: number, z: number): {
+        fx: number;
+        fy: number;
+        fz: number;
+    };
+    apply(particles: TurbParticle[], dt: number): void;
+    tick(dt: number): void;
+}
+
+/**
+ * ParticleTrait.ts
+ *
+ * Declarative particle attachment for HoloScript+ nodes.
+ * Allows any node to emit particles via the trait system.
+ *
+ * @trait particles
+ */
+
+interface HSPlusNode {
+    id?: string;
+    properties?: Record<string, unknown>;
+}
+interface TraitHandler<TConfig> {
+    name: string;
+    defaultConfig: TConfig;
+    onAttach(node: HSPlusNode, config: TConfig, context: unknown): void;
+    onDetach(node: HSPlusNode, config: TConfig, context: unknown): void;
+    onUpdate(node: HSPlusNode, config: TConfig, context: unknown, delta: number): void;
+}
+interface ParticleTraitConfig {
+    /** Preset name (key from ParticlePresets) */
+    preset?: string;
+    /** Custom emitter config (overrides preset) */
+    emitter?: Partial<EmitterConfig$1>;
+    /** Affectors to apply */
+    affectors?: string[];
+    /** Whether to follow the node's position */
+    followNode: boolean;
+    /** Whether to auto-start emitting on attach */
+    autoStart: boolean;
+}
+declare const particleTraitHandler: TraitHandler<ParticleTraitConfig>;
+/**
+ * Get the ParticleSystem for a given node (for external control).
+ */
+declare function getNodeParticleSystem(nodeId: string): ParticleSystem | undefined;
+
+type index_Attractor = Attractor;
+type index_AttractorShape = AttractorShape;
+type index_CollidableParticle = CollidableParticle;
+type index_CollisionPlane = CollisionPlane;
+type index_CollisionSphere = CollisionSphere;
+type index_Color4 = Color4;
+type index_CurveKeyframe = CurveKeyframe;
+type index_EmissionShape = EmissionShape;
+type index_EmitterShape = EmitterShape;
+type index_EmitterState = EmitterState;
+type index_ForceField = ForceField;
+type index_ForceFieldConfig = ForceFieldConfig;
+type index_ForceType = ForceType;
+type index_HSPlusNode = HSPlusNode;
+type index_IColor = IColor;
+type index_ParticleAttractorSystem = ParticleAttractorSystem;
+declare const index_ParticleAttractorSystem: typeof ParticleAttractorSystem;
+type index_ParticleCollisionSystem = ParticleCollisionSystem;
+declare const index_ParticleCollisionSystem: typeof ParticleCollisionSystem;
+type index_ParticleEmitter = ParticleEmitter;
+declare const index_ParticleEmitter: typeof ParticleEmitter;
+type index_ParticleForceSystem = ParticleForceSystem;
+declare const index_ParticleForceSystem: typeof ParticleForceSystem;
+declare const index_ParticlePresets: typeof ParticlePresets;
+type index_ParticleSystem = ParticleSystem;
+declare const index_ParticleSystem: typeof ParticleSystem;
+type index_ParticleTraitConfig = ParticleTraitConfig;
+type index_ParticleTurbulence = ParticleTurbulence;
+declare const index_ParticleTurbulence: typeof ParticleTurbulence;
+type index_SubEmitCallback = SubEmitCallback;
+type index_TraitHandler<TConfig> = TraitHandler<TConfig>;
+type index_TurbulenceConfig = TurbulenceConfig;
+declare const index_attractor: typeof attractor;
+declare const index_drag: typeof drag;
+declare const index_floorBounce: typeof floorBounce;
+declare const index_getNodeParticleSystem: typeof getNodeParticleSystem;
+declare const index_gravity: typeof gravity;
+declare const index_particleTraitHandler: typeof particleTraitHandler;
+declare const index_sizeOscillate: typeof sizeOscillate;
+declare const index_turbulence: typeof turbulence;
+declare const index_vortex: typeof vortex;
+declare const index_wind: typeof wind;
+declare namespace index {
+  export { type index_Attractor as Attractor, type Particle$1 as AttractorParticle, type index_AttractorShape as AttractorShape, type index_CollidableParticle as CollidableParticle, type index_CollisionPlane as CollisionPlane, type index_CollisionSphere as CollisionSphere, type index_Color4 as Color4, type index_CurveKeyframe as CurveKeyframe, type index_EmissionShape as EmissionShape, type EmitterConfig$1 as EmitterConfig, type Particle as EmitterParticle, type index_EmitterShape as EmitterShape, type EmitterConfig as EmitterSourceConfig, type index_EmitterState as EmitterState, type IVector3 as EmitterVector3, type index_ForceField as ForceField, type index_ForceFieldConfig as ForceFieldConfig, type index_ForceType as ForceType, type index_HSPlusNode as HSPlusNode, type index_IColor as IColor, type Particle$2 as Particle, index_ParticleAttractorSystem as ParticleAttractorSystem, index_ParticleCollisionSystem as ParticleCollisionSystem, index_ParticleEmitter as ParticleEmitter, index_ParticleForceSystem as ParticleForceSystem, index_ParticlePresets as ParticlePresets, index_ParticleSystem as ParticleSystem, type index_ParticleTraitConfig as ParticleTraitConfig, index_ParticleTurbulence as ParticleTurbulence, type index_SubEmitCallback as SubEmitCallback, type index_TraitHandler as TraitHandler, type index_TurbulenceConfig as TurbulenceConfig, index_attractor as attractor, index_drag as drag, index_floorBounce as floorBounce, index_getNodeParticleSystem as getNodeParticleSystem, index_gravity as gravity, index_particleTraitHandler as particleTraitHandler, index_sizeOscillate as sizeOscillate, index_turbulence as turbulence, index_vortex as vortex, index_wind as wind };
+}
+
+export { type Attractor as A, floorBounce as B, type CollidableParticle as C, getNodeParticleSystem as D, type EmissionShape as E, type ForceField as F, gravity as G, type HSPlusNode as H, type IVector3 as I, particleTraitHandler as J, sizeOscillate as K, turbulence as L, vortex as M, wind as N, type Particle$1 as P, type SubEmitCallback as S, type TraitHandler as T, type AttractorShape as a, type CollisionPlane as b, type CollisionSphere as c, type Color4 as d, type CurveKeyframe as e, type EmitterConfig$1 as f, type Particle as g, type EmitterShape as h, index as i, type EmitterConfig as j, type EmitterState as k, type ForceFieldConfig as l, type ForceType as m, type IColor as n, type Particle$2 as o, ParticleAttractorSystem as p, ParticleCollisionSystem as q, ParticleEmitter as r, ParticleForceSystem as s, ParticlePresets as t, ParticleSystem as u, type ParticleTraitConfig as v, ParticleTurbulence as w, type TurbulenceConfig as x, attractor as y, drag as z };