@neutrinoparticles/js-v1.1-phaser 1.0.0

package/dist/neutrinoparticles.js-v1.1-phaser.d.ts

@@ -0,0 +1,481 @@
+// Generated by dts-bundle v0.7.3
+// Dependencies for this module:
+//   index.d.ts
+
+declare module '@neutrinoparticles/js-v1.1-phaser' {
+    import Phaser from 'phaser';
+    import { GamePlugin } from '@neutrinoparticles/js-v1.1-phaser/GamePlugin';
+    import { NeutrinoFileConfig } from '@neutrinoparticles/js-v1.1-phaser/File';
+    import { Effect, EffectOptions } from '@neutrinoparticles/js-v1.1-phaser/Effect';
+    import { EffectModel } from '@neutrinoparticles/js-v1.1-phaser/EffectModel';
+    export * from '@neutrinoparticles/js-v1.1-phaser/types';
+    export * from '@neutrinoparticles/js-v1.1-phaser/GamePlugin';
+    export * from '@neutrinoparticles/js-v1.1-phaser/NeutrinoContext';
+    export * from '@neutrinoparticles/js-v1.1-phaser/NeutrinoRenderer';
+    export * from '@neutrinoparticles/js-v1.1-phaser/DataTextureManager';
+    export * from '@neutrinoparticles/js-v1.1-phaser/Effect';
+    export * from '@neutrinoparticles/js-v1.1-phaser/EffectModel';
+    export * from '@neutrinoparticles/js-v1.1-phaser/File';
+    export * from '@neutrinoparticles/js-v1.1-phaser/PerspectiveProjection';
+    declare module '@neutrinoparticles/js-v1.1-phaser/index//phaser' {
+        namespace Loader {
+            interface LoaderPlugin {
+                neutrino(key: string | NeutrinoFileConfig | NeutrinoFileConfig[], url?: string, options?: {
+                    atlases?: string[];
+                }, xhrSettings?: Phaser.Types.Loader.XHRSettingsObject): this;
+            }
+        }
+        namespace GameObjects {
+            interface GameObjectFactory {
+                neutrino(effectModel: EffectModel, options?: EffectOptions): Effect;
+            }
+            interface GameObjectCreator {
+                neutrino(config: {
+                    effectModel: EffectModel;
+                } & EffectOptions & {
+                    add?: boolean;
+                }): Effect;
+            }
+        }
+    }
+    /**
+      * Installs the NeutrinoParticles plugin into Phaser's global registries:
+      * - Loader file type:     scene.load.neutrino(key, url, options)
+      * - GameObjectFactory:    scene.add.neutrino(effectModel, options)
+      * - GameObjectCreator:    scene.make.neutrino(config)
+      */
+    export function installPlugin(): void;
+    export { GamePlugin };
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/GamePlugin' {
+    import Phaser from 'phaser';
+    import { NeutrinoContext } from '@neutrinoparticles/js-v1.1-phaser/NeutrinoContext';
+    export interface GamePluginOptions {
+        texturesBasePath?: string;
+        generateNoise?: boolean;
+    }
+    /**
+      * Main NeutrinoParticles plugin for Phaser (JS v1.1 runtime).
+      *
+      * Owns the shared {@link NeutrinoContext} (shader/index-buffer GL state) and
+      * the neutrino simulation context, and manages noise generation. A WebGL
+      * renderer is required — the v1.1 data-texture renderer has no Canvas
+      * fallback. Both WebGL2 and WebGL1 contexts are supported; the render path is
+      * selected automatically by {@link NeutrinoContext}.
+      */
+    export class GamePlugin extends Phaser.Plugins.BasePlugin {
+        game: Phaser.Game;
+        neutrino: any;
+        ctx: NeutrinoContext;
+        texturesBasePath: string;
+        init(options?: GamePluginOptions): void;
+        start(): void;
+        stop(): void;
+        destroy(): void;
+        loadNoise(path: string, success?: () => void, fail?: () => void): void;
+        generateNoise(): void;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/File' {
+    import Phaser from 'phaser';
+    export interface NeutrinoFileConfig {
+        key: string;
+        url: string;
+        options?: {
+            atlases?: string[];
+        };
+        xhrSettings?: Phaser.Types.Loader.XHRSettingsObject;
+    }
+    /**
+      * Custom Phaser loader file type for NeutrinoParticles effects (.js export).
+      * Parses the exported source into an {@link EffectModel} stored in the binary cache.
+      */
+    export class NeutrinoFile extends Phaser.Loader.File {
+        constructor(loader: Phaser.Loader.LoaderPlugin, config: NeutrinoFileConfig);
+        onProcess(): void;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/Effect' {
+    import Phaser from 'phaser';
+    import { Pause, Vec2, Vec3 } from '@neutrinoparticles/js-v1.1-phaser/types';
+    import { GamePlugin } from '@neutrinoparticles/js-v1.1-phaser/GamePlugin';
+    import { EffectModel } from '@neutrinoparticles/js-v1.1-phaser/EffectModel';
+    import { NeutrinoSystem } from '@neutrinoparticles/js-v1.1-phaser/types';
+    export interface EffectOptions {
+        position?: Vec3;
+        angle?: number;
+        scale?: number;
+        pause?: Pause;
+        generatorsPaused?: boolean;
+    }
+    /**
+      * A NeutrinoParticles effect on a Phaser scene (JS v1.1 runtime).
+      *
+      * Simulation runs in preUpdate(); rendering happens in renderWebGL() via a raw
+      * WebGL data-texture draw (WebGL2 or the WebGL1 variant, chosen by the shared
+      * NeutrinoContext). Phaser's active pipeline is flushed before and rebound
+      * after the draw so its state machine stays consistent.
+      */
+    export class Effect extends Phaser.GameObjects.GameObject {
+        gamePlugin: GamePlugin;
+        effectModel: EffectModel;
+        effect: NeutrinoSystem | null;
+        x: number;
+        y: number;
+        z: number;
+        angle: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+        scrollFactorX: number;
+        scrollFactorY: number;
+        alpha: number;
+        depth: number;
+        blendMode: number;
+        constructor(effectModel: EffectModel, scene: Phaser.Scene, options?: EffectOptions);
+        get ready(): boolean;
+        preUpdate(_time: number, ms: number): void;
+        renderWebGL(renderer: Phaser.Renderer.WebGL.WebGLRenderer, _src: Effect, camera: Phaser.Cameras.Scene2D.Camera): void;
+        restart(options?: {
+            position?: Vec3;
+            angle?: number;
+            rotation?: number;
+        }): void;
+        resetPosition(options?: {
+            position?: Vec3;
+            angle?: number;
+            rotation?: number;
+        }): void;
+        pause(): void;
+        unpause(): void;
+        get paused(): boolean;
+        pauseGenerators(): void;
+        unpauseGenerators(): void;
+        get generatorsPaused(): boolean;
+        setPropertyInAllEmitters(name: string, value: Vec3 | Vec2 | number): void;
+        getNumParticles(): number;
+        setScrollFactor(x: number, y?: number): this;
+        setAlpha(topLeft?: number, _topRight?: number, _bottomLeft?: number, _bottomRight?: number): this;
+        destroy(fromScene?: boolean): void;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/EffectModel' {
+    import Phaser from 'phaser';
+    import { GamePlugin } from '@neutrinoparticles/js-v1.1-phaser/GamePlugin';
+    import { NeutrinoEffectModel, NeutrinoSubRect } from '@neutrinoparticles/js-v1.1-phaser/types';
+    /**
+      * Wraps a neutrinoparticles.js v1.1 effect model for Phaser. Loads textures from
+      * standalone files or atlases via Phaser's loader, and computes atlas UV remaps
+      * as plain {x,y,width,height} objects (the v1.1 renderer reads them directly).
+      */
+    export class EffectModel {
+        readonly gamePlugin: GamePlugin;
+        readonly scene: Phaser.Scene;
+        readonly effectModel: NeutrinoEffectModel;
+        textureFrames: Array<Phaser.Textures.Frame | null>;
+        texturesRemap: Array<NeutrinoSubRect | null>;
+        constructor(scene: Phaser.Scene, scriptText: string, options?: {
+            atlases?: string[];
+        });
+        get ready(): boolean;
+        /** Raw WebGL texture handle for a given texture index (or null). */
+        glTexture(index: number): WebGLTexture | null;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/types' {
+    export type Vec2 = [number, number];
+    export type Vec3 = [number, number, number];
+    export type Vec4 = [number, number, number, number];
+    export type Quat = [number, number, number, number];
+    export type Mat3x2 = [number, number, number, number, number, number];
+    export enum Pause {
+        NO = 0,
+        BEFORE_UPDATE_OR_RENDER = 1,
+        YES = 2
+    }
+    export interface RenderInstruction {
+        startParticleIndex: number;
+        numParticles: number;
+        renderStyleIndex: number;
+        blendMode: number;
+    }
+    export interface RenderStyle {
+        materialIndex: number;
+        textureIndices: number[];
+    }
+    export interface NeutrinoEffectModel {
+        textures: string[];
+        materials: number[];
+        renderStyles: RenderStyle[];
+        totalParticles: number;
+        createInstance(position: Vec3, rotation: Quat, options: object): NeutrinoSystem;
+    }
+    export interface NeutrinoSystem {
+        model: NeutrinoEffectModel;
+        particleDataUint32: Uint32Array;
+        particleDataBuffer: ArrayBuffer;
+        particleDataView: DataView;
+        dataTextureWidth: number;
+        dataTextureHeight: number;
+        renderInstructions: RenderInstruction[] & {
+            _totalParticles: number;
+        };
+        update(dt: number, position?: Vec3 | null, rotation?: Quat | null): void;
+        construct(cameraDir?: Vec3): void;
+        restart(position?: Vec3, rotation?: Quat, options?: object): void;
+        resetPosition(position?: Vec3, rotation?: Quat): void;
+        pauseAllEmitters(): void;
+        unpauseAllEmitters(): void;
+        areAllEmittersPaused(): boolean;
+        pauseGeneratorsInAllEmitters(): void;
+        unpauseGeneratorsInAllEmitters(): void;
+        areGeneratorsInAllEmittersPaused(): boolean;
+        getNumParticles(): number;
+        setPropertyInAllEmitters(name: string, value: number | Vec2 | Vec3): void;
+    }
+    export interface NeutrinoRuntimeContext {
+        initializeNoise(path: string, success: () => void, fail: () => void): void;
+        NoiseGenerator: new () => {
+            step(): boolean;
+            progress: number;
+        };
+        axisangle2quat_(axis: Vec3, angleDeg: number): Quat;
+    }
+    export interface NeutrinoSubRect {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/NeutrinoContext' {
+    import { NeutrinoRuntimeContext as INeutrinoContext } from '@neutrinoparticles/js-v1.1-phaser/types';
+    /**
+        * Engine-agnostic WebGL state for the NeutrinoParticles data-texture renderer:
+        * the shader program, a static quad index buffer + VAO (WebGL2) or aId vertex
+        * stream (WebGL1), and uniform locations.
+        *
+        * This is the Phaser counterpart of the pixi adapters' Context, but it holds no
+        * reference to a host renderer — it works purely off a WebGL context. Owned by
+        * {@link GamePlugin} and shared by every effect in the game.
+        *
+        * The render path is selected automatically (TDD_js-v1.1-webgl1.md): a WebGL2
+        * context uses the texelFetch/gl_VertexID renderer unchanged; a WebGL1 context
+        * with the required capabilities (probed here, §4.2) uses the two-texture +
+        * static-aId variant; anything else throws a capability-specific Error.
+        */
+    export class NeutrinoContext {
+            readonly neutrino: INeutrinoContext;
+            readonly gl: WebGL2RenderingContext;
+            static readonly MAX_BATCH_TEXTURES = 8;
+            constructor(gl: WebGL2RenderingContext, neutrino: INeutrinoContext);
+            initializeNoise(path: string, success: () => void, fail: () => void): void;
+            generateNoise(): void;
+            get shaderProgram(): WebGLProgram;
+            get isWebGL1(): boolean;
+            /**
+                * Textures usable in one batch. 8 on WebGL2; on WebGL1 reduced when the
+                * combined texture-unit budget is tight (the vertex stage takes 2 units).
+                * A lower cap only produces more batches, never wrong output.
+                */
+            get maxBatchTextures(): number;
+            get uDataTexture(): WebGLUniformLocation | null;
+            get uDataTextureWidth(): WebGLUniformLocation | null;
+            get uMetaTexture(): WebGLUniformLocation | null;
+            get uDataTexSize(): WebGLUniformLocation | null;
+            get uCameraRight(): WebGLUniformLocation | null;
+            get uCameraUp(): WebGLUniformLocation | null;
+            get uCameraDir(): WebGLUniformLocation | null;
+            get uViewProjMatrix(): WebGLUniformLocation | null;
+            get uModelMatrix(): WebGLUniformLocation | null;
+            get uViewportAspect(): WebGLUniformLocation | null;
+            get uWorldAlpha(): WebGLUniformLocation | null;
+            get uTextures(): (WebGLUniformLocation | null)[];
+            get uTexRemaps(): (WebGLUniformLocation | null)[];
+            ensureIndexBuffer(maxParticles: number): void;
+            get vao(): WebGLVertexArrayObject;
+            get indexBuffer(): WebGLBuffer;
+            get aIdBuffer(): WebGLBuffer;
+            get aIdLocation(): number;
+            get indexType(): number;
+            /** Unbind any VAO (incl. OES on WebGL1) before raw attribute setup. */
+            unbindVao(): void;
+            destroy(): void;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/NeutrinoRenderer' {
+    import { NeutrinoContext } from "@neutrinoparticles/js-v1.1-phaser/NeutrinoContext";
+    import { DataTextureManager } from "@neutrinoparticles/js-v1.1-phaser/DataTextureManager";
+    import { DataTextureManagerGL1 } from "@neutrinoparticles/js-v1.1-phaser/gl1/DataTextureManagerGL1";
+    import { NeutrinoSubRect } from "@neutrinoparticles/js-v1.1-phaser/types";
+    export interface RenderParams {
+            /** Effect world transform (2x3) already including world scale. */
+            model: {
+                    a: number;
+                    b: number;
+                    c: number;
+                    d: number;
+                    tx: number;
+                    ty: number;
+            };
+            /** Canvas pixel dimensions, for the ortho projection. */
+            viewportWidth: number;
+            viewportHeight: number;
+            /** Camera scroll (subtracted in pixel space) and zoom. */
+            scrollX: number;
+            scrollY: number;
+            zoom: number;
+            /** Host scene-graph world alpha, multiplied into each particle's alpha. */
+            worldAlpha: number;
+            /** Per-particle GL textures (one per render-style texture index). */
+            glTextures: (WebGLTexture | null)[];
+            remaps: Array<NeutrinoSubRect | null>;
+            renderStyles: Array<{
+                    materialIndex: number;
+                    textureIndices: number[];
+            }>;
+            materials: number[];
+    }
+    /**
+        * Raw WebGL data-texture renderer for the Phaser integration.
+        *
+        * Mirrors the pixi adapters: builds blend-mode batches (≤maxBatchTextures each),
+        * patches the per-particle texture-slot byte, uploads the data texture and draws
+        * each batch with gl.drawElements. On WebGL1 the u32-packed fields travel via an
+        * RGBA8 meta texture and the slot patch goes there instead of the float buffer
+        * (TDD_js-v1.1-webgl1.md §4.3/§4.6). Because Phaser owns the GL state machine,
+        * the caller is responsible for flushing Phaser's batch and restoring pipeline
+        * state around a render() call (see Effect.renderWebGL).
+        */
+    export class NeutrinoRenderer {
+            constructor();
+            render(ctx: NeutrinoContext, dtm: DataTextureManager | DataTextureManagerGL1, dataView: DataView, dataUint32: Uint32Array, instructions: any[], numParticles: number, params: RenderParams): void;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/DataTextureManager' {
+    /**
+        * Manages a small ring of RGBA32F WebGL textures that hold the runtime's flat
+        * particle data buffer. Each frame the current texture is re-uploaded (zero-copy
+        * from the runtime-owned Uint32Array via a Float32 view) and the ring advances,
+        * which avoids GPU pipeline stalls from re-uploading into a texture still in use.
+        *
+        * Unlike the pixi7 adapter this owns raw GL textures directly (no PIXI texture
+        * system), so the exact same class works for both the PIXI v8 and Phaser
+        * integrations, which both do their own raw WebGL2 draw.
+        */
+    export class DataTextureManager {
+            readonly textureWidth: number;
+            readonly textureHeight: number;
+            /**
+                * @param gl - WebGL2 context (from the host renderer)
+                * @param data - Uint32Array from the runtime. A Float32Array view over the
+                *   same buffer is uploaded as RGBA32F — bit patterns (incl. NaN/Inf) pass
+                *   through unchanged.
+                * @param textureWidth - from runtime (system.dataTextureWidth)
+                * @param textureHeight - from runtime (system.dataTextureHeight)
+                */
+            constructor(gl: WebGL2RenderingContext, data: Uint32Array, textureWidth: number, textureHeight: number);
+            get currentTexture(): WebGLTexture;
+            /** Bind the current texture to a unit and upload the latest particle data. */
+            uploadAndBind(unit: number): void;
+            advance(): void;
+            destroy(): void;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/PerspectiveProjection' {
+    /**
+        * The class implements perspective projection transformation.
+        *
+        * @example
+        * // Create effect instance using loaded model
+        * let effect = new PIXINeutrino.Effect(resources.effectModel, {
+        *   position: [400, 300, 0],
+        *   projection: new PIXINeutrino.PerspectiveProjection(60.0)
+        * });
+        *
+        * @param {number} [horizontalAngle] Horizontal angle of the perspective projection in degrees.
+        */
+    import { Vec2, Vec3 } from "@neutrinoparticles/js-v1.1-phaser/types";
+    export interface ScreenFrame {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+    }
+    export class PerspectiveProjection {
+            set horizontalAngle(value: number);
+            constructor(horizontalAngle: number);
+            /**
+                * Sets rendering frame for the projection.
+                *
+                * This method shouldn't be called manually when the class is used with effects. It is called
+                * on every render call for each effect automatically.
+                * @param {ScreenFrame} frame Rendering frame.
+                */
+            setScreenFrame(frame: ScreenFrame): void;
+            /**
+                * Transforms 3D point accordingly to the projection.
+                *
+                * Basically, point's position X and Y components are simply scaled dependently on Z position. The method
+                * is used in WebGL and Canvas rendering.
+                *
+                * @param {Array} out [x, y] Transformed position.
+                * @param {Array} pos [x, y, z] Untransformed input vertex position.
+                * @returns false, if a particle is on the back side of the camera and should be discarded. Otherwise - true.
+                */
+            transformPosition(out: Vec2, pos: Vec3): boolean;
+            /**
+                * Transforms 2D size of a particle accordingly to the projection.
+                *
+                * Basically, size is simply scaled dependently on Z position of a particle. The method is used
+                * only in Canvas rendering.
+                *
+                * @param {Array} outSize [width, height] Transformed size.
+                * @param {Array} pos [x, y, z] Untransformed particle position.
+                * @param {Array} size [width, height] Untransformed size.
+                */
+            transformSize(outSize: Vec2, pos: Vec3, size: Vec2): void;
+            _getScale(pos: Vec3): number;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/gl1/DataTextureManagerGL1' {
+    import { MetaTextureManager } from "@neutrinoparticles/js-v1.1-phaser/gl1/MetaTextureManager";
+    export class DataTextureManagerGL1 {
+        readonly textureWidth: number;
+        readonly textureHeight: number;
+        readonly meta: MetaTextureManager;
+        constructor(gl: WebGLRenderingContext, data: Uint32Array, textureWidth: number, textureHeight: number);
+        get currentDataTexture(): WebGLTexture;
+        get currentMetaTexture(): WebGLTexture;
+        /**
+          * Upload the rows covering `numParticles` into the current ring textures,
+          * leaving them bound to `dataUnit` / `metaUnit`. The caller invalidates
+          * PIXI's bound-texture bookkeeping for those units.
+          */
+        upload(numParticles: number, dataUnit: number, metaUnit: number): void;
+        advance(): void;
+        destroy(): void;
+    }
+}
+
+declare module '@neutrinoparticles/js-v1.1-phaser/gl1/MetaTextureManager' {
+    export class MetaTextureManager {
+        readonly bytes: Uint8Array;
+        constructor(textureWidth: number, textureHeight: number);
+        /** Repack the packed-u32 record fields for the first `numParticles` records. */
+        build(dataUint32: Uint32Array, numParticles: number): void;
+        /** Write the batch texture slot into byte0 of M0 (flags) per particle. */
+        patchSlot(startParticle: number, count: number, slot: number): void;
+    }
+}
+