littlejsengine 1.22.0 → 1.23.1

package/dist/littlejs.d.ts

@@ -216,6 +216,200 @@ declare module "littlejsengine" {
      * - What the game does when the level editor paints a tile
      */
     export type EditorTileCallback = (layer: TileLayer, pos: Vector2, tile: number | undefined) => any;
+    /**
+     * - What the level editor gives the callbacks of a tool of the game's own
+     */
+    export type EditorToolAt = {
+        /**
+         * - Where the mouse is in the level: a Vector2 in the 2D editor; in the 3D one a Vector3 on
+         * the level or the ground, undefined when the mouse is over the panel
+         */
+        pos: any;
+        /**
+         * - 2D: the tile cell under the mouse on the selected tile layer
+         */
+        cell: Vector2 | undefined;
+        /**
+         * - 3D: the mouse's Ray3D
+         */
+        ray: any;
+        /**
+         * - Is Shift held
+         */
+        shift: boolean;
+        /**
+         * - Is Ctrl held
+         */
+        ctrl: boolean;
+    };
+    /**
+     * - A tool of the game's own for the level editor, see LevelEditor.addTool
+     */
+    export type EditorTool = {
+        /**
+         * - The key that picks it, as addKey spells one
+         */
+        key?: string;
+        /**
+         * - The hint line while it is on
+         */
+        hint?: string;
+        /**
+         * - The left button went down in the level; returning false
+         * says the press was not the tool's
+         */
+        onPress?: (arg0: EditorToolAt) => any;
+        /**
+         * - Each frame it is held
+         */
+        onDrag?: (arg0: EditorToolAt) => any;
+        /**
+         * - It was let go
+         */
+        onRelease?: (arg0: EditorToolAt) => any;
+        /**
+         * - Each frame the tool is on, to draw its cursor or preview
+         */
+        onDraw?: (arg0: EditorToolAt) => any;
+    };
+    /**
+     * - The 2D level editor's edit functions, levelEditor.edit2D
+     */
+    export type EditorEdit2D = {
+        /**
+         * - The Tiled map of the selected layer
+         */
+        map: any | undefined;
+        /**
+         * - The selected tile layer, undefined on an object layer
+         */
+        layer: TileLayer | undefined;
+        /**
+         * - A copy of the selected object layer's objects, as Tiled has them
+         */
+        objects: Array<any>;
+        /**
+         * - The cell under the mouse on the selected tile layer
+         */
+        hover: Vector2 | undefined;
+        /**
+         * - The selected objects' ids
+         */
+        selection: Set<number>;
+        /**
+         * - Set a cell of the selected tile layer
+         * to a tile index, -1 erases, with a direction 0 to 3 and a mirror; false off the layer or with none
+         */
+        paint: (arg0: Vector2, arg1: number, ...args: any[]) => boolean;
+        /**
+         * - Edit a copy of the selected object
+         * layer's objects; false when nothing changed
+         */
+        changeObjects: (arg0: (arg0: Array<any>) => void) => boolean;
+        /**
+         * - End the edit: one undo step, and the autosave
+         */
+        strokeEnd: () => void;
+        /**
+         * - Take the edit being made back
+         */
+        strokeCancel: () => void;
+        /**
+         * - Many paints with one redraw a layer
+         */
+        bulk: (arg0: () => void) => void;
+        /**
+         * - Undo, or redo with true
+         */
+        undo: (...args: any[]) => any;
+        /**
+         * - The map as the text Save writes
+         */
+        toJSON: () => string;
+    };
+    /**
+     * - The 3D level editor's edit functions, levelEditor.edit3D; a position, a
+     *   rotation and a scale are Vector3, the rotation in degrees
+     */
+    export type EditorEdit3D = {
+        /**
+         * - The level object being edited
+         */
+        level: any | undefined;
+        /**
+         * - Its objects, the list in the level: read it, edit through change
+         */
+        objects: Array<any>;
+        /**
+         * - The selected objects' ids
+         */
+        selection: Set<number>;
+        /**
+         * - The selected objects
+         */
+        selected: () => Array<any>;
+        /**
+         * - What the game made for an object's id
+         */
+        made: (arg0: number) => any;
+        /**
+         * - Edit a copy of the object list; false
+         * when nothing changed
+         */
+        change: (arg0: (arg0: Array<any>) => void) => boolean;
+        /**
+         * - Edit the level's scene, voxels, terrain
+         * or prefabs block
+         */
+        changePart: (arg0: string, arg1: (arg0: any) => any) => boolean;
+        /**
+         * - End the edit: one undo step, and the autosave
+         */
+        strokeEnd: () => void;
+        /**
+         * - Take the edit being made back
+         */
+        strokeCancel: () => void;
+        /**
+         * - Add an object of a type at a position, selected;
+         * its id, undefined when there is no such type or the level can not be edited
+         */
+        place: (arg0: string, arg1: any) => number | undefined;
+        /**
+         * - Write a place, a rotation and a scale on an
+         * object of the list given to change; one left out is kept
+         */
+        setTransform: (arg0: any, ...args: any[]) => void;
+        /**
+         * - Write a property on an object of the list given
+         * to change, left out of the file when it is the type's default
+         */
+        setProperty: (arg0: any, arg1: string, arg2: any) => void;
+        /**
+         * - An object's position
+         */
+        pos: (arg0: any) => any;
+        /**
+         * - Its rotation, in degrees
+         */
+        rotation: (arg0: any) => any;
+        /**
+         * - Its scale
+         */
+        scale: (arg0: any) => any;
+        /**
+         * - Where the mouse is on the level or the ground, undefined over the panel
+         */
+        mousePoint: () => any;
+        /**
+         * - Undo, or redo with true
+         */
+        undo: (...args: any[]) => boolean;
+        /**
+         * - The level as the text Save writes
+         */
+        toJSON: () => string;
+    };
     /**
      * LittleJS - The Tiny Fast JavaScript Game Engine
      * MIT License - Copyright 2021 Frank Force
@@ -453,7 +647,234 @@ declare module "littlejsengine" {
     /** The level editor, levelEditor.open() to edit the level, levelEditor.close() to play on with the changes
      *  @type {LevelEditor}
      *  @memberof Editor */
-    export const levelEditor: LevelEditor;
+    export let levelEditor: LevelEditor;
+    /**
+     * LittleJS Level Editor
+     * - Paint the game's tile layers while it is paused, then keep playing with the changes
+     * - Press 0 while the debug overlay is open to edit, 0 again to play, or call levelEditor.open() and close()
+     * - Edits the Tiled map the game loaded, saves it back as Tiled JSON, and autosaves every change
+     * - Debug builds only, the release build has stubs for its names in engineRelease.js and none of its code
+     * @namespace Editor
+     */
+    /**
+     *  @callback EditorPlayFromCallback - Puts the player at a world position, for the level editor's Play from mouse
+     *  @param {Vector2} pos - Where to start playing
+     *  @memberof Editor
+     */
+    /**
+     *  @callback EditorRestartCallback - Rebuilds the level from the map the level editor changed
+     *  @memberof Editor
+     */
+    /**
+     *  @callback EditorTileCallback - What the game does when the level editor paints a tile
+     *  @param {TileLayer} layer - The layer painted
+     *  @param {Vector2} pos - The cell's position in the layer
+     *  @param {number|undefined} tile - The tile painted, undefined when erased
+     *  @memberof Editor
+     */
+    /**
+     *  @typedef {Object} EditorToolAt - What the level editor gives the callbacks of a tool of the game's own
+     *  @property {any} pos - Where the mouse is in the level: a Vector2 in the 2D editor; in the 3D one a Vector3 on
+     *    the level or the ground, undefined when the mouse is over the panel
+     *  @property {Vector2|undefined} cell - 2D: the tile cell under the mouse on the selected tile layer
+     *  @property {any} ray - 3D: the mouse's Ray3D
+     *  @property {boolean} shift - Is Shift held
+     *  @property {boolean} ctrl - Is Ctrl held
+     *  @memberof Editor
+     */
+    /**
+     *  @typedef {Object} EditorTool - A tool of the game's own for the level editor, see LevelEditor.addTool
+     *  @property {string} [key] - The key that picks it, as addKey spells one
+     *  @property {string} [hint] - The hint line while it is on
+     *  @property {function(EditorToolAt): any} [onPress] - The left button went down in the level; returning false
+     *    says the press was not the tool's
+     *  @property {function(EditorToolAt): any} [onDrag] - Each frame it is held
+     *  @property {function(EditorToolAt): any} [onRelease] - It was let go
+     *  @property {function(EditorToolAt): any} [onDraw] - Each frame the tool is on, to draw its cursor or preview
+     *  @memberof Editor
+     */
+    /**
+     *  @typedef {Object} EditorEdit2D - The 2D level editor's edit functions, levelEditor.edit2D
+     *  @property {Object|undefined} map - The Tiled map of the selected layer
+     *  @property {TileLayer|undefined} layer - The selected tile layer, undefined on an object layer
+     *  @property {Array<Object>} objects - A copy of the selected object layer's objects, as Tiled has them
+     *  @property {Vector2|undefined} hover - The cell under the mouse on the selected tile layer
+     *  @property {Set<number>} selection - The selected objects' ids
+     *  @property {function(Vector2, number, ...any): boolean} paint - Set a cell of the selected tile layer
+     *    to a tile index, -1 erases, with a direction 0 to 3 and a mirror; false off the layer or with none
+     *  @property {function(function(Array<Object>): void): boolean} changeObjects - Edit a copy of the selected object
+     *    layer's objects; false when nothing changed
+     *  @property {function(): void} strokeEnd - End the edit: one undo step, and the autosave
+     *  @property {function(): void} strokeCancel - Take the edit being made back
+     *  @property {function(function(): void): void} bulk - Many paints with one redraw a layer
+     *  @property {function(...any): any} undo - Undo, or redo with true
+     *  @property {function(): string} toJSON - The map as the text Save writes
+     *  @memberof Editor
+     */
+    /**
+     *  @typedef {Object} EditorEdit3D - The 3D level editor's edit functions, levelEditor.edit3D; a position, a
+     *    rotation and a scale are Vector3, the rotation in degrees
+     *  @property {Object|undefined} level - The level object being edited
+     *  @property {Array<Object>} objects - Its objects, the list in the level: read it, edit through change
+     *  @property {Set<number>} selection - The selected objects' ids
+     *  @property {function(): Array<Object>} selected - The selected objects
+     *  @property {function(number): any} made - What the game made for an object's id
+     *  @property {function(function(Array<Object>): void): boolean} change - Edit a copy of the object list; false
+     *    when nothing changed
+     *  @property {function(string, function(any): any): boolean} changePart - Edit the level's scene, voxels, terrain
+     *    or prefabs block
+     *  @property {function(): void} strokeEnd - End the edit: one undo step, and the autosave
+     *  @property {function(): void} strokeCancel - Take the edit being made back
+     *  @property {function(string, any): number|undefined} place - Add an object of a type at a position, selected;
+     *    its id, undefined when there is no such type or the level can not be edited
+     *  @property {function(Object, ...any): void} setTransform - Write a place, a rotation and a scale on an
+     *    object of the list given to change; one left out is kept
+     *  @property {function(Object, string, any): void} setProperty - Write a property on an object of the list given
+     *    to change, left out of the file when it is the type's default
+     *  @property {function(Object): any} pos - An object's position
+     *  @property {function(Object): any} rotation - Its rotation, in degrees
+     *  @property {function(Object): any} scale - Its scale
+     *  @property {function(): any} mousePoint - Where the mouse is on the level or the ground, undefined over the panel
+     *  @property {function(...any): boolean} undo - Undo, or redo with true
+     *  @property {function(): string} toJSON - The level as the text Save writes
+     *  @memberof Editor
+     */
+    /**
+     * The level editor, open it to pause the game and edit its level, close it to play on with the changes
+     * - One of it, levelEditor, 0 on the debug overlay opens and closes it too
+     * - A game makes it its own: it sets the hooks, adds keys, panel buttons and tools, or extends this class and
+     *   gives its own with setLevelEditor; the same calls work in the 2D editor and the 3D one, see EDITOR.md
+     * - In release builds LevelEditor is a stub that never opens: what a game adds is taken and never called
+     * @memberof Editor
+     * @example
+     * levelEditor.onRestart = ()=> loadLevel(); // adds a Restart button that rebuilds the level
+     * levelEditor.onTile = (layer, pos, tile)=> layer.setCollisionData(pos, tile === ladderTile ? -1 : tile ? 1 : 0);
+     * levelEditor.addKey('k', ()=> clearEnemies(), 'K: clear the enemies');
+     *
+     * // or as a class of the game's own
+     * class MyEditor extends LevelEditor
+     * {
+     *     onRestart() { loadLevel(); }
+     *     onDraw() { drawSpawnZones(); }
+     * }
+     * setLevelEditor(new MyEditor);
+     */
+    export class LevelEditor {
+        /** @property {Array<number>|undefined} - The tiles the palette shows, in its order, for a sheet that also holds
+         *  sprites and art that are not level tiles; undefined shows every tile of the sheet
+         *  @type {Array<number>|undefined} */
+        paletteTiles: Array<number> | undefined;
+        /** @property {boolean|undefined} - Which level editor opens: true the 3D one, false the 2D one, undefined the
+         *  3D one when a level was loaded with level3DLoad and there is a Render3DPlugin
+         *  @type {boolean|undefined} */
+        use3D: boolean | undefined;
+        /** @property {string|undefined} - The tool of the game's own that is on, one added with addTool, undefined
+         *  while a tool of the editor's is
+         *  @type {string|undefined} */
+        tool: string | undefined;
+        /** @type {Object<string, {action: function(boolean): any, help: string|undefined, warned: boolean}>} */
+        keys: {
+            [x: string]: {
+                action: (arg0: boolean) => any;
+                help: string | undefined;
+                warned: boolean;
+            };
+        };
+        /** @type {Array<{label: string, onClick: Function, title: string}>} */
+        buttons: Array<{
+            label: string;
+            onClick: Function;
+            title: string;
+        }>;
+        /** @type {Object<string, EditorTool>} */
+        tools: {
+            [x: string]: EditorTool;
+        };
+        /** What the game does when the 2D editor paints a tile, like setting its collision or its look the way the
+         *  game does when it loads the level; set it or override it, without one the collision layer gets collision 1
+         *  where there is a tile
+         *  @param {TileLayer} layer - The layer painted
+         *  @param {Vector2} pos - The cell's position in the layer
+         *  @param {number|undefined} tile - The tile painted, undefined when erased */
+        onTile(layer: TileLayer, pos: Vector2, tile: number | undefined): void;
+        /** Rebuild the level from what the editor changed; set it or override it and the editor has a Restart button,
+         *  which calls it after switching to play */
+        onRestart(): void;
+        /** Put the player at a position, a Vector2 in the 2D editor and a Vector3 in the 3D one; set it or override it
+         *  and the editor has Play from mouse, which starts play there
+         *  @param {any} pos */
+        onPlayFrom(pos: any): void;
+        /** Called when the editor opens, to set or override */
+        onOpen(): void;
+        /** Called when the editor closes and the game plays on, to set or override */
+        onClose(): void;
+        /** Called each frame while the editor is open, to set or override */
+        onUpdate(): void;
+        /** Called while the editor draws the level, to draw overlays of the game's own in it, to set or override */
+        onDraw(): void;
+        /** Called once when the editor's panel is made, with a box in it for the game's own controls, to set or override
+         *  @param {HTMLElement} element */
+        onPanel(element: HTMLElement): void;
+        /** Called by Save with the text of the file and its name; return true when the game kept it itself, and the
+         *  editor writes no file, to set or override; it may be async
+         *  @param {string} text
+         *  @param {string} fileName
+         *  @return {boolean|void|Promise<boolean|void>} */
+        onSave(text: string, fileName: string): boolean | void | Promise<boolean | void>;
+        /** True while the editor is open, the game is paused under it
+         *  @return {boolean} */
+        get isOpen(): boolean;
+        /** True when the editor in use is the 3D one, as use3D says or since a 3D level was loaded
+         *  @return {boolean} */
+        get is3D(): boolean;
+        /** The 2D editor's edit functions, for a key, a button or a tool of the game's own: map, the Tiled map; layer,
+         *  the selected TileLayer; objects, a copy of the selected object layer's; hover, the cell under the mouse;
+         *  selection, the selected objects' ids; paint(cell, tile, direction, mirror), a tile index, -1 erases;
+         *  changeObjects((list)=> ...); strokeEnd() and strokeCancel(); bulk(()=> ...); undo(redo); toJSON()
+         *  @return {EditorEdit2D} */
+        get edit2D(): EditorEdit2D;
+        /** The 3D editor's edit functions, undefined without the 3D plugins: level; objects; selection, a Set of ids;
+         *  selected(); made(id); change((list)=> ...); changePart(name, (part)=> ...); strokeEnd() and strokeCancel();
+         *  place(type, pos3D); setTransform(object, pos3D, rotationDegrees, scale3D); setProperty(object, name, value);
+         *  pos(object), rotation(object) and scale(object); mousePoint(); undo(redo); toJSON()
+         *  @return {EditorEdit3D|undefined} */
+        get edit3D(): EditorEdit3D;
+        /** Add a key of the game's own to the editor, the 2D and the 3D one
+         *  - Escape and 0 are the editor's own, to play and to exit, and Ctrl is the one modifier: Shift is given to
+         *    the action
+         *  @param {string} key - A letter or digit, 'k', or a key's name in any case, 'Delete', 'F2', 'Enter', 'Space';
+         *    'ctrl+k' with Ctrl or Cmd
+         *  @param {function(boolean): any} action - Called with whether Shift is held; returning false says it did
+         *    nothing, and the key is left to the browser
+         *  @param {string} [helpLine] - A line for the editor's help */
+        addKey(key: string, action: (arg0: boolean) => any, helpLine?: string): void;
+        /** Add a button of the game's own to the editor's panel
+         *  @param {string} label
+         *  @param {Function} onClick
+         *  @param {string} [title] - What it says when the mouse is over it */
+        addButton(label: string, onClick: Function, title?: string): void;
+        /** Add a tool of the game's own: a button in the panel by its name, and while it is on the left button in the
+         *  level is its, not the editor's own tools'
+         *  - Each callback is given {pos, cell, ray, shift, ctrl}: pos is where the mouse is in the level, a Vector2 in
+         *    2D and a Vector3 on the level or the ground in 3D; cell is the tile under it in 2D; ray is the mouse's
+         *    in 3D
+         *  - What the callbacks change through edit2D or edit3D is one undo: the editor ends the stroke at the release,
+         *    and takes it back when the right button or Escape ends the press
+         *  @param {string} name
+         *  @param {EditorTool} tool - {key, hint, onPress, onDrag, onRelease, onDraw}, each optional; onPress returning
+         *    false says the press was not the tool's */
+        addTool(name: string, tool: EditorTool): void;
+        /** Open the editor, pausing the game; until close(), Escape (the debug key) switches between playing and editing */
+        open(): any;
+        /** Close the editor and end its session, the game carries on with the changes and Escape opens the debug
+         *  overlay again */
+        close(): any;
+    }
+    /** Make a level editor of the game's own the one in use: an instance of a class that extends LevelEditor, with
+     *  the game's hooks as its methods; set it before the editor opens
+     *  @param {LevelEditor} editor
+     *  @memberof Editor */
+    export function setLevelEditor(editor: LevelEditor): void;
     /** Asserts if the expression is false, does nothing in release builds
      *  Halts execution if the assert fails and throws an error
      *  @param {*} assert - any value, the assert fails when it is falsy
@@ -806,6 +1227,14 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let touchGamepadPassthrough: boolean;
+    /** True if a pinch of two fingers turns the mouse wheel: touchPinch is added to mouseWheel, so what zooms with
+     *  the wheel zooms with a pinch, the mouse is between the two fingers, and a second finger lets go of the button
+     *  the first pressed, since a pinch is not a drag; turn it off for a game with its own use for two fingers, the
+     *  first finger stays the mouse and touchPinch can still be read
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let touchPinchWheel: boolean;
     /** Size of center button if touch gamepad should have start button in the center
      *  - Prevents activating when pressed near virtual stick or face buttons
      *  - When the game is paused, any touch will press the button
@@ -1096,6 +1525,10 @@ declare module "littlejsengine" {
      *  @param {boolean} passthrough
      *  @memberof Settings */
     export function setTouchGamepadPassthrough(passthrough: boolean): void;
+    /** Set if a pinch of two fingers turns the mouse wheel
+     *  @param {boolean} enable
+     *  @memberof Settings */
+    export function setTouchPinchWheel(enable: boolean): void;
     /** Set if touch gamepad should have start button in the center
      *  - Set size to enable the center button
      *  - When the game is paused, any touch will press the button
@@ -2267,6 +2700,11 @@ declare module "littlejsengine" {
         /** The clip showing now
          *  @return {SpriteAnimation} */
         get clip(): SpriteAnimation;
+        /** The clip showing now, once a clip that has ended has called its onEnd: the callback may switch clips, and a
+         *  read gives the clip it switched to, not the one that ended
+         *  @return {SpriteAnimation}
+         *  @ignore */
+        get settledClip(): SpriteAnimation;
         /** The tile of the frame showing now
          *  @return {TileInfo} */
         get tileInfo(): TileInfo;
@@ -2998,6 +3436,12 @@ declare module "littlejsengine" {
      *  @type {number}
      *  @memberof Input */
     export let mouseWheel: number;
+    /** Touch pinch delta this frame, in the mouse wheel's units: two fingers moving apart are negative, as the wheel
+     *  turned up is, and moving together positive, 1 for every 50 pixels; added to mouseWheel while touchPinchWheel
+     *  is on, so a game that zooms with the wheel zooms with a pinch
+     *  @type {number}
+     *  @memberof Input */
+    export let touchPinch: number;
     /** True if mouse was inside the document window, set to false when mouse leaves
      *  @type {boolean}
      *  @memberof Input */
@@ -3203,10 +3647,13 @@ declare module "littlejsengine" {
          *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
          */
         constructor(asset?: string | URL | any[], randomness?: number, range?: number, taper?: number, onloadCallback?: SoundLoadCallback);
-        /** @property {number} - World space max range of sound */
-        range: number;
+        loadedPercent: number;
+        set range(arg: number);
+        /** World space max range of sound, 0 for no limit; a range that is set is the sound's own, in 3D too
+         *  @type {number} */
+        get range(): number;
         /** @property {boolean} - No range was given, so it got soundDefaultRange; played in 3D such a sound is heard
-         *  to render3D.soundDefaultRange instead, which is further */
+         *  to render3D.soundDefaultRange instead, which is further; setting range makes it false */
         rangeIsDefault: boolean;
         /** @property {number} - At what percentage of range should it start tapering */
         taper: number;
@@ -3223,9 +3670,6 @@ declare module "littlejsengine" {
         /** @ignore
          *  @type {Array<Array<number>|Float32Array>|undefined} */
         _sampleChannels: Array<Array<number> | Float32Array> | undefined;
-        /** @property {number} - Percentage of this sound currently loaded, sounds
-         *  fetched from a url stay at 0 until decoding completes */
-        loadedPercent: number;
         /** @property {SoundLoadCallback|undefined} - function to call when sound is loaded
          *  @type {SoundLoadCallback|undefined} */
         onloadCallback: SoundLoadCallback | undefined;
@@ -3241,6 +3685,7 @@ declare module "littlejsengine" {
          *  playing a sound detaches the buffer's own channel arrays.
          *  @return {Array<Array<number>|Float32Array>|undefined} */
         get sampleChannels(): (number[] | Float32Array)[];
+        rangeValue: number;
         /** Move this sound's samples into an audio buffer that every play can share
          *  Does nothing if there is already a buffer or no samples to build one from */
         buildSampleBuffer(): void;
@@ -4871,6 +5316,8 @@ declare module "littlejsengine" {
     }
     /**
      * 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
      */
     /**
@@ -5304,8 +5751,7 @@ declare module "littlejsengine" {
          *  To end typing in a field, call its stopEditing(), which also fires its onChange and release sound
          *  @type {UIObject|undefined} */
         get keyInputObject(): UIObject;
-        /** Destroy and remove all objects
-        *  @memberof UISystem */
+        /** Destroy and remove all objects */
         destroyObjects(): void;
         /** Get all navigable UI objects sorted by navigationIndex
          *  @return {Array<UIObject>} */
@@ -7146,6 +7592,78 @@ declare module "littlejsengine" {
      *  @return {Scene|undefined}
      *  @memberof SceneSystem */
     export function getScene(): Scene | undefined;
+    /**
+     * LittleJS Parallax Plugin
+     * - A background layer that follows the camera by a part of its movement, so it looks far away
+     * - Repeats across the view, so a level of any width has a background
+     * - Draws mountains by default, or anything a game draws into it
+     * @namespace Parallax
+     */
+    /**
+     * A background layer with parallax: an image that follows the camera by a part of its movement and repeats across
+     * the view, drawn once into a canvas by a function, mountains when none is given
+     * - A far layer has a parallax near 1 and a low renderOrder, a near one a smaller parallax and a higher renderOrder
+     * - The image should meet itself at its left and right edges to repeat without a seam, as the mountains do
+     * @memberof Parallax
+     * @extends CanvasLayer
+     * @example
+     * // three ranges of mountains, the far ones lighter and slower
+     * for (let i = 3; i--;)
+     *     new ParallaxLayer(vec2(0, i*2), vec2(40, 20), .9 - i*.2, -1e3 + i,
+     *         parallaxMountains(hsl(.6, .3, .7 - i*.2), hsl(.6, .5, .2), i));
+     *
+     * // or draw your own image into the layer
+     * new ParallaxLayer(vec2(), vec2(40, 20), .5, -1e3, (context, size)=>
+     * {
+     *     context.fillStyle = '#fff';
+     *     context.fillRect(size.x/2 - 20, size.y/2 - 20, 40, 40);
+     * });
+     */
+    export class ParallaxLayer extends CanvasLayer {
+        /** Create a parallax layer and draw its image
+         *  @param {Vector2} [pos] - Where the middle of the image is in the world when the camera is there too
+         *  @param {Vector2} [size] - World size of one copy of the image
+         *  @param {number|Vector2} [parallax] - How much of the camera's movement it follows, 0 stays with the world
+         *    and 1 with the screen, a Vector2 to follow x and y by different amounts
+         *  @param {number} [renderOrder] - Low to draw behind the game, far layers lowest
+         *  @param {function(OffscreenCanvasRenderingContext2D, Vector2, ParallaxLayer): void} [drawFunction] - Draws
+         *    the image, given the canvas context, its size in pixels and the layer; mountains when not given
+         *  @param {Vector2} [canvasSize] - Size of the image in pixels */
+        constructor(pos?: Vector2, size?: Vector2, parallax?: number | Vector2, renderOrder?: number, drawFunction?: (arg0: OffscreenCanvasRenderingContext2D, arg1: Vector2, arg2: ParallaxLayer) => void, canvasSize?: Vector2);
+        /** @property {Vector2} - How much of the camera's movement it follows on each axis, 0 stays with the world
+         *  and 1 with the screen */
+        parallax: Vector2;
+        /** @property {boolean} - Repeat the image across the view, left and right */
+        wrapX: boolean;
+        /** @property {boolean} - Repeat the image up and down the view */
+        wrapY: boolean;
+        /** @property {number} - How much the camera's zoom changes its size on the screen: 1 like the world, 0 not
+         *  at all, the same on the screen at any zoom as it is at zoomScale */
+        zoomFollow: number;
+        /** @property {number} - The camera scale its size is given for, used when zoomFollow is under 1 */
+        zoomScale: number;
+        /** @property {function(OffscreenCanvasRenderingContext2D, Vector2, ParallaxLayer): void} - Draws the
+         *  image, redraw() after changing it */
+        drawFunction: (arg0: OffscreenCanvasRenderingContext2D, arg1: Vector2, arg2: ParallaxLayer) => void;
+        /** Draw the image again with drawFunction, after changing it or what it draws from */
+        redraw(): void;
+        zoomFactor(): number;
+        /** World size one copy of the image is drawn at now, its size unless zoomFollow is under 1
+         *  @return {Vector2} */
+        getDrawSize(): Vector2;
+        /** Where each copy of the image is drawn now, in the world: one place, or with wrapping every place that
+         *  shows in the view
+         *  @return {Array<Vector2>} */
+        getDrawPositions(): Array<Vector2>;
+    }
+    /** A draw function for a ParallaxLayer: a range of mountains across the image, shaded from the color of their
+     *  peaks down to the color of their feet, that repeats with no seam
+     *  @param {Color} [topColor] - Color at the peaks
+     *  @param {Color} [bottomColor] - Color at the bottom of the image
+     *  @param {number} [seed] - The same seed gives the same mountains, random when not given
+     *  @return {function(OffscreenCanvasRenderingContext2D, Vector2): void}
+     *  @memberof Parallax */
+    export function parallaxMountains(topColor?: Color, bottomColor?: Color, seed?: number): (arg0: OffscreenCanvasRenderingContext2D, arg1: Vector2) => void;
     /** Grid pathfinder using A* with two optional smoothing passes.
      *  @memberof PathFinding
      *  @example
@@ -8043,6 +8561,7 @@ declare module "littlejsengine" {
         /** @type {TextureInfo|undefined} */
         streamTileInfo: TextureInfo | undefined;
         streamState: any;
+        streamUnlit: boolean;
         /** @type {Mesh|undefined} */
         capture: Mesh | undefined;
         /** @type {Array<{distance: number, state: Object, draw: function(): void}>|undefined} */
@@ -9319,7 +9838,7 @@ declare module "littlejsengine" {
      * - intensity multiplies the color, above 1 for a light brighter than white
      * - 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 itself, add a glow with drawSoftDisc or a small emissive mesh if it should be seen
+     * - Draws nothing but its glow, when it has one; add a small emissive mesh if the lamp itself should be seen
      * @extends EngineObject3D
      * @memberof Render3D
      * @example
@@ -9357,7 +9876,7 @@ declare module "littlejsengine" {
      * - It shines from its position toward the origin, like a three.js DirectionalLight: only the direction to it
      *   counts, so moving it or its parent swings the light around; parent it to a sun in the sky and it follows
      * - It cannot sit on the origin, since that leaves no direction
-     * - Like every Light3D it casts no shadow, only the sun, render3D.sunDirection, does
+     * - It casts no shadow: the sun, render3D.sunDirection, does, or a spotlight set as render3D.shadowLight
      * @extends Light3D
      * @memberof Render3D
      * @example
@@ -9575,6 +10094,9 @@ declare module "littlejsengine" {
         trailData: Float32Array | undefined;
         /** @property {number} - Trail points kept per particle, from trailTime */
         trailMax: number;
+        /** @property {number} - How much a particle grips where it lands, 0 to 1: its speed along the surface is
+         *  cut by this much on each hit, on top of the friction, 1 stops it there */
+        stick: number;
         /** @property {Particle3DCallback|undefined} - Called with each particle as it is made
          *  @type {Particle3DCallback|undefined} */
         particleCreateCallback: Particle3DCallback | undefined;
@@ -9598,7 +10120,7 @@ declare module "littlejsengine" {
         /** Spawn one particle now */
         emitParticle(): void;
         particleCall(callback: any, k: any, level: any, pos: any): any;
-        particleCollide(k: any, x: any, y: any, z: any): void;
+        particleCollide(k: any, x: any, y: any, z: any): boolean;
     }
     /**
      * Trail3D - A ribbon through where the object has been, thinning and fading with age
@@ -9689,6 +10211,11 @@ declare module "littlejsengine" {
             color: Color;
             shape: string;
         }[];
+        /** @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
+         *  @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 */
@@ -9712,7 +10239,13 @@ declare module "littlejsengine" {
             color: Color;
             shape: string;
         }>;
-        /** Where the sun is on the screen, in pixels like mousePosScreen, undefined when it is behind the camera
+        flareSource(): {
+            direction: Vector3;
+            distance: number;
+            pos: Vector3;
+        };
+        /** 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
@@ -9724,7 +10257,8 @@ declare module "littlejsengine" {
             color: Color;
             shape: string;
         }>;
-        /** Is something between the camera and the sun: the level, or an object that is not see through
+        /** Is something between the camera and the sun, or the flare's light: the level, or an object that is not see
+         *  through
          *  @return {boolean} */
         isSunHidden(): boolean;
     }
@@ -10062,7 +10596,10 @@ declare module "littlejsengine" {
      *    returned, see level3DVoxelSetup for its sheet
      *  - A level may hold a terrain, in a terrain block: pos, its center, size, its size in the world along x and z,
      *    height, how tall a full height is, color, and heights, rows of 0 to 1 from -z to +z, each from -x to +x; it
-     *    is made a HeightMap, returned with what else was made
+     *    is made a HeightMap, returned with what else was made; paint, when it has it, colors its samples: colors, a
+     *    list, and cells, runs of a count and a color along the rows, 0 for the terrain's own and 1 the list's first
+     *  - A level may hold prefabs of its own, in a prefabs block, each by its name as level3DAddPrefab takes it; they
+     *    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
@@ -10071,9 +10608,85 @@ declare module "littlejsengine" {
      *  @return {Array<any>} - What each object's type made, a function that made nothing is left out
      *  @memberof Level3D */
     export function level3DLoad(level: any): Array<any>;
+    /** Add a prefab: a small level, its objects placed about its own origin, to place many times under one name
+     *  - It is a type from then on: a level's object of that type, the level editor's Place list and level3DSpawn make
+     *    an instance, a Prefab3D; an instance is made of the prefab as it is then, so the level editor, where a prefab
+     *    changes, makes its instances again
+     *  - The prefab is a level as the level editor saves it, {objects: [...]}, so the editor is the prefab editor too;
+     *    only its objects are used, and they may be of other prefabs
+     *  - With attached true in it the parts are children of the instance and move with it as one body, without
+     *    collision of their own, a prefab inside it too; its handle is at the middle of the box around them and its
+     *    size3D is that box, so setCollision makes the body solid where it is seen; otherwise each part is an object of its own in the world and collides as one placed
+     *    by hand does
+     *  - Adding a name again replaces it
+     *  @param {string} name - The type its instances have in a level
+     *  @param {Object} prefab - {objects, attached}
+     *  @memberof Level3D
+     *  @example
+     *  level3DAddPrefab('Tower', {objects: [{type: 'Box', pos: [0, 1, 0], scale: [2, 2, 2]},
+     *      {type: 'Cylinder', pos: [0, 3, 0]}]});
+     *  level3DLoad({objects: [{type: 'Tower', pos: [5, 0, 5]}, {type: 'Tower', pos: [-5, 0, 5], rotation: [0, 45, 0]}]}); */
+    export function level3DAddPrefab(name: string, prefab: any): void;
+    /** Load a prefab from a file the level editor saved and add it
+     *  @param {string} name - The type its instances have in a level
+     *  @param {string} url
+     *  @return {Promise<void>}
+     *  @memberof Level3D */
+    export function level3DLoadPrefab(name: string, url: string): Promise<void>;
+    /** Make one object of a type added with level3DAddType, level3DAddMesh or level3DAddPrefab, from code, with no
+     *  level: a prefab's instance, or a plain type
+     *  @param {string} type - The type's name
+     *  @param {Vector3} [pos3D]
+     *  @param {Vector3} [rotation3D] - In radians, as an object has it
+     *  @param {Vector3} [scale3D] - Times the scale the type makes it with
+     *  @param {Object} [properties] - Over the type's defaults
+     *  @return {any} - What the type made, a Prefab3D for a prefab, undefined when there is no such type
+     *  @memberof Level3D
+     *  @example
+     *  level3DAddPrefab('House', await fetchJSON('house.json'));
+     *  level3DSpawn('House', vec3(10, 0, 0), vec3(0, PI/2, 0)); */
+    export function level3DSpawn(type: string, pos3D?: Vector3, rotation3D?: Vector3, scale3D?: Vector3, properties?: any): any;
+    /**
+     * An instance of a prefab, what a prefab's type makes: a handle with no shape of its own, and its parts, what the
+     * prefab's objects made
+     * - Parts of a prefab that is not attached are objects of their own in the world: moving, turning or sizing the
+     *   handle puts them where it now says with its next update, or call placeParts; destroying it destroys them
+     * - Parts of an attached prefab are its children and move with it as one body
+     * @extends EngineObject3D
+     * @memberof Level3D
+     */
+    export class Prefab3D extends EngineObject3D {
+        /** Create an instance of a prefab, made by its type: place one with a level or level3DSpawn
+         *  @param {Vector3} [pos3D]
+         *  @param {string} [prefabName] - A prefab added with level3DAddPrefab */
+        constructor(pos3D?: Vector3, prefabName?: string);
+        /** @property {string} - The prefab it is an instance of */
+        prefabName: string;
+        /** @property {boolean} - Are its parts its children, moving with it as one body */
+        attached: boolean;
+        /** @property {Array<any>} - What the prefab's objects made, in the prefab's order */
+        parts: any[];
+        /** @property {Vector3} - From the prefab's origin to the handle, in the prefab's own space: nothing for
+         *  separate parts, and for an attached prefab the middle of the box around its parts, where its handle
+         *  is, as an object's place is the middle of its body */
+        originOffset: Vector3;
+        partObjects: any[];
+        partsPlaced: string;
+        partsMade: boolean;
+        /** Put the instance with its prefab's origin at a place, turned and sized as the handle is: where a level's
+         *  object or level3DSpawn says it goes; the handle of an attached prefab is then at the middle of its body
+         *  @param {Vector3} pos3D */
+        placeAt(pos3D: Vector3): void;
+        /** Put the parts where the handle is now, making them the first time; called by the handle's update when it
+         *  has moved, turned or changed size */
+        placeParts(): void;
+        placeKey(): string;
+        makeParts(): void;
+    }
     /** How a level's block map is made: the sheet its blocks show tiles of, and a function to set it up
      *  - A level's voxels block makes a VoxelMap when the level loads, with texture 0 and the default tile size unless
-     *    a sheet is given here; a block's type shows that tile of the sheet on every face
+     *    a sheet is given here; a block's type shows that tile of the sheet on every face; a game that has loaded no
+     *    image gets plain blocks, a color for each type
      *  - setup is called with each map a level makes, to give block types their own faces or make them see-through
      *  - Call it before level3DLoad; with no arguments the defaults are back
      *  @param {TileInfo} [tileInfo] - The sheet's first tile, as for a VoxelMap
@@ -10389,31 +11002,23 @@ declare module "littlejsengine" {
      *  - Attach it to an object with addChild to follow it
      *  @param {string|Object} nameOrEffect - A built-in or added effect's name, or an effect
      *  @param {Vector2} [pos]
-     *  @param {Object} [options]
-     *  @param {number} [options.scale] - Grows the whole effect, the built-ins fit a one unit object at 1
-     *  @param {number} [options.hue] - Turns its colors around the color wheel, 1 is all the way
-     *  @param {number} [options.saturation] - Multiplies its saturation, 0 is grey
-     *  @param {number} [options.angle] - Direction, 0 is up; the effect's own angle when not given
-     *  @param {TileInfo|TextureInfo} [options.tileInfo] - The game's own art to draw with in place of the effect's shape,
-     *    tinted by its colors; a whole texture draws as one tile
-     *  @param {*} [options.settings] - Any effect setting by its name, emitTime, emitRate, speed and the rest, replacing
-     *    the effect's own for this play
+     *  @param {Object} [options] - What to change for this play, each left out when not wanted:
+     *    scale grows the whole effect, the built-ins fit a one unit object at 1;
+     *    hue turns its colors around the color wheel, 1 is all the way;
+     *    saturation multiplies its saturation, 0 is grey;
+     *    angle is its direction, 0 is up, the effect's own angle when not given;
+     *    tileInfo, a TileInfo or a TextureInfo, is the game's own art to draw with in place of the effect's shape,
+     *    tinted by its colors, a whole texture drawn as one tile;
+     *    and any effect setting by its name, emitTime, emitRate, speed and the rest, replaces the effect's own
      *  @return {ParticleEmitter|undefined} - undefined when there is no such effect
      *  @memberof ParticleEffects */
-    export function particleEffect(nameOrEffect: string | any, pos?: Vector2, options?: {
-        scale?: number;
-        hue?: number;
-        saturation?: number;
-        angle?: number;
-        tileInfo?: TileInfo | TextureInfo;
-        settings?: any;
-    }): ParticleEmitter | undefined;
+    export function particleEffect(nameOrEffect: string | any, pos?: Vector2, options?: any): ParticleEmitter | undefined;
     /** Play an effect in 3D: a ParticleEmitter3D set to it, placed, scaled and recolored
      *  - The same effect data as particleEffect, so the look carries across: a circle spawn area becomes a sphere and a
      *    rectangle a box as deep as it is wide, both flat across the way it emits with options.flatten, a disc or a
      *    sheet; a trail becomes a streak of the same length, and the settings the 3D emitter lacks (particleConeAngle,
-     *    randomColorLinear, velocityInheritance, localSpace) are left out; the stick behavior becomes the friction a
-     *    particle lands with
+     *    randomColorLinear, velocityInheritance, localSpace) are left out; the stick behavior becomes the emitter's
+     *    stick, its grip where a particle lands
      *  @param {string|Object} nameOrEffect - A built-in or added effect's name, or an effect
      *  @param {Vector3} [pos3D]
      *  @param {Object} [options] - scale, hue, saturation, angle, tileInfo and any setting as particleEffect; angle turns it
@@ -10453,69 +11058,4 @@ declare module "littlejsengine" {
      *  @param {string} [description]
      *  @memberof ParticleEffects */
     export function particleEffectsAddBehavior(name: string, update: (arg0: Particle, arg1: number) => void, update3D?: (arg0: Particle3D, arg1: number) => void, min?: number, max?: number, value?: number, description?: string): void;
-    /**
-     * LittleJS Level Editor
-     * - Paint the game's tile layers while it is paused, then keep playing with the changes
-     * - Press 0 while the debug overlay is open to edit, 0 again to play, or call levelEditor.open() and close()
-     * - Edits the Tiled map the game loaded, saves it back as Tiled JSON, and autosaves every change
-     * - Debug builds only, the release build has stubs for its names in engineRelease.js and none of its code
-     * @namespace Editor
-     */
-    /**
-     *  @callback EditorPlayFromCallback - Puts the player at a world position, for the level editor's Play from mouse
-     *  @param {Vector2} pos - Where to start playing
-     *  @memberof Editor
-     */
-    /**
-     *  @callback EditorRestartCallback - Rebuilds the level from the map the level editor changed
-     *  @memberof Editor
-     */
-    /**
-     *  @callback EditorTileCallback - What the game does when the level editor paints a tile
-     *  @param {TileLayer} layer - The layer painted
-     *  @param {Vector2} pos - The cell's position in the layer
-     *  @param {number|undefined} tile - The tile painted, undefined when erased
-     *  @memberof Editor
-     */
-    /**
-     * The level editor, open it to pause the game and edit its level, close it to play on with the changes
-     * - One of it, levelEditor, 0 on the debug overlay opens and closes it too
-     * - In release builds levelEditor is a stub that never opens, and its hooks are never called
-     * @memberof Editor
-     * @example
-     * levelEditor.onRestart = ()=> loadLevel(); // adds a Restart button that rebuilds the level
-     * levelEditor.onTile = (layer, pos, tile)=> layer.setCollisionData(pos, tile === ladderTile ? -1 : tile ? 1 : 0);
-     */
-    class LevelEditor {
-        /** @property {EditorTileCallback|undefined} - What the game does when the editor paints a tile, like
-         *  setting its collision or its look the way the game does when it loads the level; without one, the
-         *  collision layer gets collision 1 where there is a tile
-         *  @type {EditorTileCallback|undefined} */
-        onTile: EditorTileCallback | undefined;
-        /** @property {Function|undefined} - Rebuild the level from the map the editor changed, a Restart button
-         *  calls it after switching to play; without one there is no Restart button
-         *  @type {EditorRestartCallback|undefined} */
-        onRestart: EditorRestartCallback | undefined;
-        /** @property {Function|undefined} - Put the player at a world position; with it, the editor's Advanced
-         *  section has Play from mouse, which starts play there, Escape at the mouse and Play at the view center
-         *  @type {EditorPlayFromCallback|undefined} */
-        onPlayFrom: EditorPlayFromCallback | undefined;
-        /** @property {Array<number>|undefined} - The tiles the palette shows, in its order, for a sheet that also holds
-         *  sprites and art that are not level tiles; undefined shows every tile of the sheet
-         *  @type {Array<number>|undefined} */
-        paletteTiles: Array<number> | undefined;
-        /** @property {boolean|undefined} - Which level editor opens: true the 3D one, false the 2D one, undefined the
-         *  3D one when a level was loaded with level3DLoad and there is a Render3DPlugin
-         *  @type {boolean|undefined} */
-        use3D: boolean | undefined;
-        /** True while the editor is open, the game is paused under it
-         *  @return {boolean} */
-        get isOpen(): boolean;
-        /** Open the editor, pausing the game; until close(), Escape (the debug key) switches between playing and editing */
-        open(): void;
-        /** Close the editor and end its session, the game carries on with the changes and Escape opens the debug
-         *  overlay again */
-        close(): void;
-    }
-    export {};
 }