littlejsengine 1.23.1 → 1.24.0

package/dist/littlejs.d.ts

@@ -194,6 +194,36 @@ declare module "littlejsengine" {
      * - Decides whether a particle stops where it hits the level, a filter as in 2D
      */
     export type Particle3DCollideCallback = (particle: Particle3D, level: EngineObject3D, pos: Vector3) => boolean | void;
+    /**
+     * A part of a lens flare
+     */
+    export type LensFlareElement = {
+        /**
+         * - Where along the line: 0 the sun, 1 the middle of the screen, 2 as far past it
+         */
+        at: number;
+        /**
+         * - How big across, as a part of the screen's height, a vector for a part wider
+         * than it is tall
+         */
+        size: number | Vector2;
+        /**
+         * - Its color, the alpha how bright
+         */
+        color: Color;
+        /**
+         * - glow, disc, ring, hex, streak or star, a glow when left out
+         */
+        shape?: string;
+        /**
+         * - A tile of the game's own to draw in place of a shape, best white on clear
+         */
+        tileInfo?: TileInfo;
+        /**
+         * - How far it is turned, in radians
+         */
+        angle?: number;
+    };
     /**
      * What VoxelMap.raycast finds: how far along the ray, the block's cell and type, and the normal of the face it comes in
      * through
@@ -3579,7 +3609,7 @@ declare module "littlejsengine" {
      * - 2D spatial audio based on camera position with distance-based falloff
      * - Sound instance management (pause, resume, stop)
      * - Speech synthesis for text-to-speech
-     * - Music playback with ZzFXM support
+     * - Music playback from audio files, looping by default
      * - Web Audio API integration with master gain control
      * - Sounds and the master bus can route through effects, see the audio effects plugin
      * @namespace Audio
@@ -4239,6 +4269,10 @@ declare module "littlejsengine" {
      * Load tile layers from exported data
      * - Tiled maps come in as they are, flipped and turned tiles included, from one tileset image (a second tileset's
      *   tiles continue its numbering), finite maps in the CSV or array layer format; layer offsets and parallax are not read
+     * - A tileset kept in the map with a margin or a spacing, a sheet with gaps between its tiles, is read where its
+     *   tiles are, whatever padding the tile info has; one in a file of its own (a tsx) is not read, pass a tile info
+     *   with its padding
+     * - An LDtk level loads through tileLayersFromLDtk, which makes it a map like these
      * - Group layers are flattened in order, each replaced by the layers inside it, so the layer indices
      *   (collisionLayer and the returned array) count that flattened list; a group's tint, opacity and
      *   visibility carry to the layers inside it
@@ -4253,6 +4287,28 @@ declare module "littlejsengine" {
      *  @return {Array<TileCollisionLayer>}
      *  @memberof TileLayers */
     export function tileLayersLoad(tileMapData: any, tileInfo?: TileInfo, renderOrder?: number, collisionLayer?: number, draw?: boolean): Array<TileCollisionLayer>;
+    /**
+     * Make a Tiled map of a level of an LDtk project, to load with tileLayersLoad and objectLayersLoad
+     * - Each Tiles, AutoLayer and IntGrid layer is a tile layer, the bottom one first as in Tiled, so the last layer
+     *   of the LDtk file is layer 0; where LDtk stacks tiles in a cell, an edge over a fill, each tile over another
+     *   goes in a layer of its own just above, named with (2), (3) and so on, so a layer of the first tiles has one
+     *   wherever the LDtk layer has any, which makes it the one for collision
+     * - An IntGrid layer with no tiles is a hidden layer of its values, for collision: pass its index as collisionLayer
+     * - An Entities layer is an object layer: an entity's name is its type for objectLayersAddType, it is placed at
+     *   its middle, and its Int, Float, Bool, String, Color and FilePath fields are its properties (an enum is a string)
+     * - The tileset is the first tile layer's, with its padding and spacing; give tileLayersLoad a tile info of its image
+     * - The level is in the project file (not saved as separate level files), its layers of one grid size; a layer of
+     *   another grid size or another tileset is left out, with a warning in debug builds
+     * - The level editor edits the map this returns, and saves it as a Tiled map
+     * @param {Object} ldtk - The LDtk project, its JSON
+     * @param {number|string} [level] - Which level, by its index or its identifier
+     * @return {Object} - A Tiled map: width, height, tilewidth, tileheight, tilesets and layers
+     * @example
+     * const map = tileLayersFromLDtk(await fetchJSON('world.ldtk'), 'Level_0');
+     * const layers = tileLayersLoad(map, tile(0, 16), 0, 1); // layer 1 is solid
+     * objectLayersLoad(map);
+     * @memberof TileLayers */
+    export function tileLayersFromLDtk(ldtk: any, level?: number | string): any;
     /** Add a type of object, so objectLayersLoad makes one wherever a map's object layer has an object of that type
      *  - The name is the object's type in Tiled (its class in Tiled 1.9); it is a string because minified builds
      *    rename classes
@@ -5314,58 +5370,6 @@ declare module "littlejsengine" {
          *  called by LightSystemPlugin after the lightmap is applied */
         renderGlow(): void;
     }
-    /**
-     * LittleJS ZzFXM Plugin
-     * - A port of ZzFXM, the Zuper Zmall Zound Zynth music player, by Keith Clark and Frank Force, MIT licensed,
-     *   https://github.com/keithclark/ZzFXM; its notice is in COPYRIGHT.txt
-     * @namespace ZzFXM
-     */
-    /**
-     * Music Object - Stores a zzfx music track for later use
-     *
-     * <a href=https://keithclark.github.io/ZzFXM/>Create music with the ZzFXM tracker.</a>
-     * @extends Sound
-     * @memberof ZzFXM
-     * @example
-     * // create some music
-     * const music_example = new ZzFXMusic(
-     * [
-     *     [                         // instruments
-     *       [,0,400]                // simple note
-     *     ],
-     *     [                         // patterns
-     *         [                     // pattern 1
-     *             [                 // channel 0
-     *                 0, -1,        // instrument 0, left speaker
-     *                 1, 0, 9, 1    // channel notes
-     *             ],
-     *             [                 // channel 1
-     *                 0, 1,         // instrument 0, right speaker
-     *                 0, 12, 17, -1 // channel notes
-     *             ]
-     *         ],
-     *     ],
-     *     [0, 0, 0, 0], // sequence, play pattern 0 four times
-     *     90            // BPM
-     * ]);
-     *
-     * // play the music on a loop
-     * music_example.playMusic();
-     */
-    export class ZzFXMusic extends Sound {
-        /** Create a music object and cache the zzfx music samples for later use
-         *  @param {[Array, Array, Array, number?, ...any[]]} zzfxMusic - Array of zzfx music parameters: instruments, patterns, sequence, and an optional BPM; anything after it, like the tracker's metadata, is ignored
-         */
-        constructor(zzfxMusic: [any[], any[], any[], number?, ...any[]]);
-    }
-    /** Generate samples for a ZzFM song with given parameters
-     *  @param {Array} instruments - Array of ZzFX sound parameters
-     *  @param {Array} patterns - Array of pattern data
-     *  @param {Array} sequence - Array of pattern indexes
-     *  @param {number} [BPM] - Playback speed of the song in BPM
-     *  @return {Array} - Left and right channel sample data
-     *  @memberof ZzFXM */
-    export function zzfxM(instruments: any[], patterns: any[], sequence: any[], BPM?: number): any[];
     /**
      * LittleJS Audio Effects Plugin
      * - Web Audio effects with a wet/dry mix: filter, reverb, delay, distortion, compressor
@@ -8682,8 +8686,8 @@ declare module "littlejsengine" {
          *  @return {Vector3|undefined} - undefined when the ray misses the plane */
         screenToGround(screenPos: Vector2, groundHeight?: number, canvasSize?: Vector2): Vector3 | undefined;
         /** Find the nearest object under a screen position or along a ray, for clicking on things
-         *  - Each object is tested as the box around its mesh in its own space, or a sprite as the quad it draws,
-         *    not triangle by triangle
+         *  - A mesh is hit on its triangles, the ones that face the ray as they are drawn, both sides of a doubleSided
+         *    mesh; a sprite is hit as the quad it draws, and a height map or a voxel map on its surface
          *  - engineObjectsRaycast3D is the other half of this, every object along a ray instead of the nearest
          *  @param {Vector2|Ray3D} from - A screen position like mousePosScreen, or a ray to look along
          *  @param {Array<EngineObject>} [objects] - Defaults to every object; only those with a mesh or a sprite count
@@ -9839,10 +9843,12 @@ declare module "littlejsengine" {
      * - radius is a world distance, so scale3D does not change it
      * - An alpha, an intensity or a radius of 0 switches it off, and a light that is off takes none of those slots
      * - Draws nothing but its glow, when it has one; add a small emissive mesh if the lamp itself should be seen
+     * - addFlare gives it a lens flare, see LensFlare3D
      * @extends EngineObject3D
      * @memberof Render3D
      * @example
      * const torch = new Light3D(vec3(0, 3, 0), 10, hsl(.1, 1, .65));
+     * torch.addFlare();   // light in the lens when the torch is in view
      */
     export class Light3D extends EngineObject3D {
         /** Create a point light
@@ -9870,6 +9876,22 @@ declare module "littlejsengine" {
         /** @property {number} - How fast the glow fades from its middle: 1 by default, .5 a wide haze, 2 a tight
          *  bright core */
         glowFalloff: number;
+        /** @type {LensFlare3D|undefined} */
+        flareObject: LensFlare3D | undefined;
+        /** Give the light a lens flare, made with the arguments of LensFlare3D, in place of the one it had
+         *  @param {number} [size] - Scales every part of it
+         *  @param {number} [count] - How many ghosts there are, besides the glow at the light
+         *  @param {number} [intensity] - How bright it is
+         *  @param {number} [saturation] - How colorful the ghosts are
+         *  @return {LensFlare3D} - The flare, to change: light.addFlare().shapes = ['hex'] */
+        addFlare(size?: number, count?: number, intensity?: number, saturation?: number): LensFlare3D;
+        set flare(arg: LensFlare3D);
+        /** The light's lens flare, undefined for none: addFlare makes it, or set a LensFlare3D of your own, and
+         *  destroying the flare takes it away
+         *  - The flare is the light's: it is attached to the light as its child, so it stays through a scene change
+         *    when the light does, and is destroyed with the light or when another takes its place
+         *  @type {LensFlare3D|undefined} */
+        get flare(): LensFlare3D;
     }
     /**
      * DirectionalLight3D - A Light3D that shines from far away with no falloff, like sunlight
@@ -10165,16 +10187,31 @@ declare module "littlejsengine" {
         clear(): void;
         worldPos3D: Vector3;
     }
+    /**
+     * A part of a lens flare
+     * @typedef {Object} LensFlareElement
+     * @property {number} at - Where along the line: 0 the sun, 1 the middle of the screen, 2 as far past it
+     * @property {number|Vector2} size - How big across, as a part of the screen's height, a vector for a part wider
+     *  than it is tall
+     * @property {Color} color - Its color, the alpha how bright
+     * @property {string} [shape] - glow, disc, ring, hex, streak or star, a glow when left out
+     * @property {TileInfo} [tileInfo] - A tile of the game's own to draw in place of a shape, best white on clear
+     * @property {number} [angle] - How far it is turned, in radians
+     * @memberof Render3D
+     */
     /**
      * LensFlare3D - The sun's lens flare, the old kind: a glow at the sun and a row of discs and rings of different
      * sizes along the line from the sun through the middle of the screen
      * - Make one and it shows, over the 3D scene and under what the game draws after, a HUD; destroy it to take it away
      * - It follows render3D.sunDirection, and fades out as the sun leaves the screen or goes behind something
+     * - A Light3D gets one of its own with light.addFlare()
      * - flareSize, count, intensity and saturation set its look, seed picks another arrangement, and its color tints it,
-     *   with the sun's own color; or give it elements of your own
-     * - visible is how much of the sun shows, 0 to 1, eased over fadeTime, there for a game to read
+     *   with the sun's own color; shapes says what its ghosts are, glowSize and ghostSize how big its parts are; or
+     *   give it elements of your own, which may be tiles of the game's
+     * - visible is how much of the sun shows, 0 to 1, eased over fadeTime, there for a game to read; it is 0 while the
+     *   sun is off the screen, where nothing is tested
      * - What hides the sun is found with a ray from the camera, against the level and every object that is not see
-     *   through, each as the box around its mesh, see render3D.pick; turn it off with occlusion
+     *   through, each on the triangles of its mesh, see render3D.pick; turn it off with occlusion
      * - It needs WebGL, and it draws nothing in the shadow of renderAfter2D
      * @extends EngineObject3D
      * @memberof Render3D
@@ -10200,67 +10237,73 @@ declare module "littlejsengine" {
         saturation: number;
         /** @property {number} - Picks the arrangement of the ghosts, another seed is another flare */
         seed: number;
-        /** @property {Array<{at: number, size: number, color: Color, shape: string}>|undefined} - The parts of the
-         *  flare, to set your own in place of the ones made from count, seed and saturation: at is where along the
-         *  line, 0 the sun, 1 the middle of the screen, 2 as far past it; size is across, as a part of the screen's
-         *  height; shape is glow, disc or ring
-         *  @type {Array<{at: number, size: number, color: Color, shape: string}>|undefined} */
-        elements: {
-            at: number;
-            size: number;
-            color: Color;
-            shape: string;
-        }[];
+        /** @property {Array<string>|undefined} - The shapes the ghosts are picked from, glow, disc, ring, hex,
+         *  streak or star: ['hex'] makes every ghost a hexagon, and a shape listed twice is picked twice as often;
+         *  discs, rings and glows when not set
+         *  @type {Array<string>|undefined} */
+        shapes: Array<string> | undefined;
+        /** @property {number} - Scales the glow at the sun, 0 for none */
+        glowSize: number;
+        /** @property {number} - Scales the ghosts */
+        ghostSize: number;
+        /** @property {Array<LensFlareElement>|undefined} - The parts of the flare, to set your own in place of the
+         *  ones made from count, seed, saturation, shapes, glowSize and ghostSize
+         *  @type {Array<LensFlareElement>|undefined} */
+        elements: Array<LensFlareElement> | undefined;
         /** @property {Light3D|undefined} - A light the flare is of in place of the sun, a lamp or a spotlight: the
          *  flare is at the light and in its color, smaller from farther than the light reaches, hidden by what is
-         *  in front of the light, and a spotlight's shows from inside its beam only
+         *  in front of the light, and a spotlight's shows from inside its beam only; a DirectionalLight3D's is far
+         *  away where it shines from, like the sun's; the flare is destroyed when its light is; light.addFlare
+         *  sets this
          *  @type {Light3D|undefined} */
         light: Light3D | undefined;
         /** @property {boolean} - Fade out when something is between the camera and the sun */
         occlusion: boolean;
         /** @property {number} - Seconds the flare takes to fade out or in when the sun is hidden or shows again */
         fadeTime: number;
-        /** @property {number} - How much of the sun shows, 0 hidden or behind the camera to 1 in plain view, eased */
+        /** @property {number} - How much of the sun shows, 0 hidden, off the screen or behind the camera to 1 in
+         *  plain view, eased */
         visible: number;
         madeKey: string;
-        /** @type {Array<{at: number, size: number, color: Color, shape: string}>} */
-        made: {
-            at: number;
-            size: number;
-            color: Color;
-            shape: string;
-        }[];
-        /** The parts of the flare: the elements set by hand, or the ones made from count, seed and saturation, a glow
-         *  and a core at the sun and the ghosts, made again when one of those changes
-         *  @return {Array<{at: number, size: number, color: Color, shape: string}>} */
-        getElements(): Array<{
-            at: number;
-            size: number;
-            color: Color;
-            shape: string;
-        }>;
+        /** @type {Array<LensFlareElement>} */
+        made: Array<LensFlareElement>;
+        /** The parts of the flare: the elements set by hand, or the ones made from count, seed, saturation, shapes,
+         *  glowSize and ghostSize, a glow and a core at the sun and the ghosts, made again when one of those changes
+         *  @return {Array<LensFlareElement>} */
+        getElements(): Array<LensFlareElement>;
         flareSource(): {
             direction: Vector3;
             distance: number;
             pos: Vector3;
         };
+        flareLook(): {
+            sun: Vector2;
+            center: Vector2;
+            strength: number;
+            tint: Color;
+            height: number;
+        };
         /** Where the sun, or the flare's light, is on the screen, in pixels like mousePosScreen, undefined when it is
          *  behind the camera
          *  @return {Vector2|undefined} */
-        getSunScreenPos(): Vector2 | undefined;
-        /** The parts of the flare as they are drawn now: each one's place on the screen, its size in pixels and its
-         *  color, dimmed by how much of the sun shows; empty when there is nothing to draw
-         *  @return {Array<{pos: Vector2, size: number, color: Color, shape: string}>} */
+        getScreenPos(): Vector2 | undefined;
+        /** The parts of the flare as they are drawn now: each one's place on the screen, its size in pixels, a vector
+         *  when the element's is, and its color, dimmed by how much of the sun shows; empty when there is nothing to draw
+         *  @return {Array<{pos: Vector2, size: number|Vector2, color: Color, shape: string|undefined,
+         *      tileInfo: TileInfo|undefined, angle: number}>} */
         getScreenElements(): Array<{
             pos: Vector2;
-            size: number;
+            size: number | Vector2;
             color: Color;
-            shape: string;
+            shape: string | undefined;
+            tileInfo: TileInfo | undefined;
+            angle: number;
         }>;
         /** Is something between the camera and the sun, or the flare's light: the level, or an object that is not see
-         *  through
+         *  through, hit on its triangles as render3D.pick hits it, so a mesh the camera is inside hides nothing unless
+         *  it is doubleSided
          *  @return {boolean} */
-        isSunHidden(): boolean;
+        isHidden(): boolean;
     }
     /**
      * Collect the EngineObject3D objects whose boxes overlap a sphere or a box, the 3D twin of engineObjectsCollect
@@ -10602,8 +10645,9 @@ declare module "littlejsengine" {
      *    are added before its objects are made, one the game added itself keeps its place
      *  - A level may set the scene too, in a scene block beside its objects: sky, three colors for straight up, the
      *    horizon and straight down, ambient, how much of them lights the scene, .5 when not given, sunDirection and
-     *    sunColor, fog, its start and end, fogColor, the horizon color when not given, and shadows; what the block
-     *    leaves out stays as the game set it, and a level with no block changes nothing
+     *    sunColor, fog, its start and end, fogColor, the horizon color when not given, shadows, and lensFlare, the
+     *    sun's lens flare; what the block leaves out stays as the game set it, and a level with no block changes
+     *    nothing
      *  @param {Object} level - The level, the level editor edits this same object
      *  @return {Array<any>} - What each object's type made, a function that made nothing is left out
      *  @memberof Level3D */