littlejsengine 1.14.11 → 1.14.16

package/dist/littlejs.d.ts

@@ -1,4 +1,36 @@
 declare module "littlejsengine" {
+    /**
+     * - Update or render function for a plugin
+     */
+    export type PluginCallback = () => any;
+    /**
+     * - Called after the engine starts, can be async
+     */
+    export type GameInitCallback = () => void | Promise<void>;
+    /**
+     * - Update or render function for the game
+     */
+    export type GameCallback = () => any;
+    /**
+     * - Function that processes an object
+     */
+    export type ObjectCallbackFunction = (uiObjects: EngineObject) => any;
+    /**
+     * - A function that draws to a 2D canvas context
+     */
+    export type Canvas2DDrawFunction = (context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => any;
+    /**
+     * - Function called when a sound ends
+     */
+    export type AudioEndedCallback = (source: AudioBufferSourceNode) => any;
+    /**
+     * - Function that processes a medal
+     */
+    export type MedalCallbackFunction = (medal: Medal) => any;
+    /**
+     * - Function that processes a particle
+     */
+    export type ParticleCallbackFunction = (particle: Particle) => any;
     /**
      * LittleJS - The Tiny Fast JavaScript Game Engine
      * MIT License - Copyright 2021 Frank Force
@@ -67,12 +99,21 @@ declare module "littlejsengine" {
      *  @param {boolean} [isPaused]
      *  @memberof Engine */
     export function setPaused(isPaused?: boolean): void;
+    /**
+     * @callback GameInitCallback - Called after the engine starts, can be async
+     * @returns {void|Promise<void>}
+     * @memberof Engine
+     */
+    /**
+     * @callback GameCallback - Update or render function for the game
+     * @memberof Engine
+     */
     /** Startup LittleJS engine with your callback functions
-     *  @param {Function|function():Promise} gameInit - Called once after the engine starts up, can be async for loading
-     *  @param {Function} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
-     *  @param {Function} gameUpdatePost - Called after physics and objects are updated, even when paused, use for UI updates
-     *  @param {Function} gameRender - Called before objects are rendered, use for drawing backgrounds/world elements
-     *  @param {Function} gameRenderPost - Called after objects are rendered, use for drawing UI/overlays
+     *  @param {GameInitCallback} gameInit - Called once after the engine starts up, can be async for loading
+     *  @param {GameCallback} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
+     *  @param {GameCallback} gameUpdatePost - Called after physics and objects are updated, even when paused, use for UI updates
+     *  @param {GameCallback} gameRender - Called before objects are rendered, use for drawing backgrounds/world elements
+     *  @param {GameCallback} gameRenderPost - Called after objects are rendered, use for drawing UI/overlays
      *  @param {Array<string>} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png'])
      *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body
      *  @example
@@ -86,7 +127,7 @@ declare module "littlejsengine" {
      *    ['tiles.png', 'tilesLevel.png']       // images to load
      *  );
      *  @memberof Engine */
-    export function engineInit(gameInit: Function | (() => Promise<any>), gameUpdate: Function, gameUpdatePost: Function, gameRender: Function, gameRenderPost: Function, imageSources?: Array<string>, rootElement?: HTMLElement): Promise<void>;
+    export function engineInit(gameInit: GameInitCallback, gameUpdate: GameCallback, gameUpdatePost: GameCallback, gameRender: GameCallback, gameRenderPost: GameCallback, imageSources?: Array<string>, rootElement?: HTMLElement): Promise<void>;
     /** Update each engine object, remove destroyed objects, and update time
      *  @memberof Engine */
     export function engineObjectsUpdate(): void;
@@ -100,13 +141,18 @@ declare module "littlejsengine" {
      *  @return {Array<EngineObject>}                        - List of collected objects
      *  @memberof Engine */
     export function engineObjectsCollect(pos?: Vector2, size?: Vector2 | number, objects?: Array<EngineObject>): Array<EngineObject>;
+    /**
+     * @callback ObjectCallbackFunction - Function that processes an object
+     * @param {EngineObject} uiObjects
+     *  @memberof Engine
+     */
     /** Triggers a callback for each object within a given area
-     *  @param {Vector2} [pos]                 - Center of test area, or undefined for all objects
-     *  @param {Vector2|number} [size]         - Radius of circle if float, rectangle size if Vector2
-     *  @param {Function} [callbackFunction]   - Calls this function on every object that passes the test
+     *  @param {Vector2} [pos] - Center of test area, or undefined for all objects
+     *  @param {Vector2|number} [size] - Radius of circle if float, rectangle size if Vector2
+     *  @param {ObjectCallbackFunction} [callbackFunction] - Calls this function on every object that passes the test
      *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
      *  @memberof Engine */
-    export function engineObjectsCallback(pos?: Vector2, size?: Vector2 | number, callbackFunction?: Function, objects?: Array<EngineObject>): void;
+    export function engineObjectsCallback(pos?: Vector2, size?: Vector2 | number, callbackFunction?: ObjectCallbackFunction, objects?: Array<EngineObject>): void;
     /** Return a list of objects intersecting a ray
      *  @param {Vector2} start
      *  @param {Vector2} end
@@ -114,11 +160,15 @@ declare module "littlejsengine" {
      *  @return {Array<EngineObject>} - List of objects hit
      *  @memberof Engine */
     export function engineObjectsRaycast(start: Vector2, end: Vector2, objects?: Array<EngineObject>): Array<EngineObject>;
+    /**
+     * @callback PluginCallback - Update or render function for a plugin
+     * @memberof Engine
+     */
     /** Add a new update function for a plugin
-     *  @param {Function} [updateFunction]
-     *  @param {Function} [renderFunction]
+     *  @param {PluginCallback} [updateFunction]
+     *  @param {PluginCallback} [renderFunction]
      *  @memberof Engine */
-    export function engineAddPlugin(updateFunction?: Function, renderFunction?: Function): void;
+    export function engineAddPlugin(updateFunction?: PluginCallback, renderFunction?: PluginCallback): void;
     /**
      * LittleJS Debug System
      * - Press Esc to show debug overlay with mouse pick
@@ -144,6 +194,7 @@ declare module "littlejsengine" {
      *  @memberof Debug */
     export let showWatermark: boolean;
     /** Asserts if the expression is false, does nothing in release builds
+     *  Halts execution if the assert fails and throws an error
      *  @param {boolean} assert
      *  @param {...Object} [output] - error message output
      *  @memberof Debug */
@@ -155,62 +206,62 @@ declare module "littlejsengine" {
     /** Draw a debug rectangle in world space
      *  @param {Vector2} pos
      *  @param {Vector2} [size=Vector2()]
-     *  @param {string}  [color]
-     *  @param {number}  [time]
-     *  @param {number}  [angle]
+     *  @param {Color|string} [color]
+     *  @param {number} [time]
+     *  @param {number} [angle]
      *  @param {boolean} [fill]
      *  @memberof Debug */
-    export function debugRect(pos: Vector2, size?: Vector2, color?: string, time?: number, angle?: number, fill?: boolean): void;
+    export function debugRect(pos: Vector2, size?: Vector2, color?: Color | string, time?: number, angle?: number, fill?: boolean): void;
     /** Draw a debug poly in world space
      *  @param {Vector2} pos
      *  @param {Array<Vector2>} points
-     *  @param {string}  [color]
-     *  @param {number}  [time]
-     *  @param {number}  [angle]
+     *  @param {Color|string} [color]
+     *  @param {number} [time]
+     *  @param {number} [angle]
      *  @param {boolean} [fill]
      *  @memberof Debug */
-    export function debugPoly(pos: Vector2, points: Array<Vector2>, color?: string, time?: number, angle?: number, fill?: boolean): void;
+    export function debugPoly(pos: Vector2, points: Array<Vector2>, color?: Color | string, time?: number, angle?: number, fill?: boolean): void;
     /** Draw a debug circle in world space
      *  @param {Vector2} pos
-     *  @param {number}  [size] - diameter
-     *  @param {string}  [color]
-     *  @param {number}  [time]
+     *  @param {number} [size] - diameter
+     *  @param {Color|string} [color]
+     *  @param {number} [time]
      *  @param {boolean} [fill]
      *  @memberof Debug */
-    export function debugCircle(pos: Vector2, size?: number, color?: string, time?: number, fill?: boolean): void;
+    export function debugCircle(pos: Vector2, size?: number, color?: Color | string, time?: number, fill?: boolean): void;
     /** Draw a debug point in world space
      *  @param {Vector2} pos
-     *  @param {string}  [color]
-     *  @param {number}  [time]
-     *  @param {number}  [angle]
+     *  @param {Color|string} [color]
+     *  @param {number} [time]
+     *  @param {number} [angle]
      *  @memberof Debug */
-    export function debugPoint(pos: Vector2, color?: string, time?: number, angle?: number): void;
+    export function debugPoint(pos: Vector2, color?: Color | string, time?: number, angle?: number): void;
     /** Draw a debug line in world space
      *  @param {Vector2} posA
      *  @param {Vector2} posB
-     *  @param {string}  [color]
-     *  @param {number}  [width]
-     *  @param {number}  [time]
+     *  @param {Color|string} [color]
+     *  @param {number} [width]
+     *  @param {number} [time]
      *  @memberof Debug */
-    export function debugLine(posA: Vector2, posB: Vector2, color?: string, width?: number, time?: number): void;
+    export function debugLine(posA: Vector2, posB: Vector2, color?: Color | string, width?: number, time?: number): void;
     /** Draw a debug combined axis aligned bounding box in world space
      *  @param {Vector2} posA
      *  @param {Vector2} sizeA
      *  @param {Vector2} posB
      *  @param {Vector2} sizeB
-     *  @param {string}  [color]
+     *  @param {Color|string} [color]
      *  @memberof Debug */
-    export function debugOverlap(posA: Vector2, sizeA: Vector2, posB: Vector2, sizeB: Vector2, color?: string): void;
+    export function debugOverlap(posA: Vector2, sizeA: Vector2, posB: Vector2, sizeB: Vector2, color?: Color | string): void;
     /** Draw a debug axis aligned bounding box in world space
-     *  @param {string}  text
+     *  @param {string} text
      *  @param {Vector2} pos
-     *  @param {number}  [size]
-     *  @param {string}  [color]
-     *  @param {number}  [time]
-     *  @param {number}  [angle]
-     *  @param {string}  [font]
+     *  @param {number} [size]
+     *  @param {Color|string} [color]
+     *  @param {number} [time]
+     *  @param {number} [angle]
+     *  @param {string} [font]
      *  @memberof Debug */
-    export function debugText(text: string, pos: Vector2, size?: number, color?: string, time?: number, angle?: number, font?: string): void;
+    export function debugText(text: string, pos: Vector2, size?: number, color?: Color | string, time?: number, angle?: number, font?: string): void;
     /** Clear all debug primitives in the list
      *  @memberof Debug */
     export function debugClear(): void;
@@ -234,7 +285,9 @@ declare module "littlejsengine" {
      *  @param {string}     filename
      *  @memberof Debug */
     export function debugSaveDataURL(dataURL: string, filename: string): void;
-    /** Show error as full page of red text
+    /** Breaks on all asserts/errors, hides the canvas, and shows message in plain text
+     *  This is a good function to call at the start of your game to catch all errors
+     *  In release builds this function has no effect
      *  @memberof Debug */
     export function debugShowErrors(): void;
     /** Check if video capture is active
@@ -812,6 +865,7 @@ declare module "littlejsengine" {
     /**
      * Seeded random number generator
      * - Can be used to create a deterministic random number sequence
+     * @memberof Engine
      * @example
      * let r = new RandomGenerator(123); // random number generator with seed 123
      * let a = r.float();                // random value between 0 and 1
@@ -859,6 +913,7 @@ declare module "littlejsengine" {
     /**
      * 2D Vector object with vector math library
      * - Functions do not change this so they can be chained together
+     * @memberof Engine
      * @example
      * let a = new Vector2(2, 3); // vector with coordinates (2, 3)
      * let b = new Vector2;       // vector with coordinates (0, 0)
@@ -949,9 +1004,10 @@ declare module "littlejsengine" {
          * @param {number} angle
          * @return {Vector2} */
         rotate(angle: number): Vector2;
-        /** Set the integer direction of this vector, corresponding to multiples of 90 degree rotation (0-3)
+        /** Sets this this vector to point in the specified integer direction (0-3), corresponding to multiples of 90 degree rotation
          * @param {number} [direction]
-         * @param {number} [length] */
+         * @param {number} [length]
+         * @return {Vector2} */
         setDirection(direction?: number, length?: number): Vector2;
         /** Returns the integer direction of this vector, corresponding to multiples of 90 degree rotation (0-3)
          * @return {number} */
@@ -988,6 +1044,7 @@ declare module "littlejsengine" {
     }
     /**
      * Color object (red, green, blue, alpha) with some helpful functions
+     * @memberof Engine
      * @example
      * let a = new Color;              // white
      * let b = new Color(1, 0, 0);     // red
@@ -1081,6 +1138,7 @@ declare module "littlejsengine" {
     }
     /**
      * Timer object tracks how long has passed since it was set
+     * @memberof Engine
      * @example
      * let a = new Timer;    // creates a timer that is not set
      * a.set(3);             // sets the timer to 3 seconds
@@ -1172,11 +1230,17 @@ declare module "littlejsengine" {
      * @return {boolean}
      * @memberof Utilities */
     export function isNumber(n: any): boolean;
+    /**
+     * Check if object is a valid string or can be converted to one
+     * @param {any} s
+     * @return {boolean}
+     * @memberof Utilities */
+    export function isString(s: any): boolean;
     /** Color - White #ffffff
      *  @type {Color}
      *  @memberof Utilities */
     export const WHITE: Color;
-    /** Color - Clear White #ffffff with 0 alpha
+    /** Color - Clear White #757474ff with 0 alpha
      *  @type {Color}
      *  @memberof Utilities */
     export const CLEAR_WHITE: Color;
@@ -1228,7 +1292,7 @@ declare module "littlejsengine" {
      * Create a tile info object using a grid based system
      * - This can take vecs or floats for easier use and conversion
      * - If an index is passed in, the tile size and index will determine the position
-     * @param {Vector2|number} [pos=0] - Index of tile in sheet
+     * @param {Vector2|number} [pos=0] - Position of the tile in pixels, or tile index
      * @param {Vector2|number} [size=tileSizeDefault] - Size of tile in pixels
      * @param {number} [textureIndex] - Texture index to use
      * @param {number} [padding] - How many pixels padding around tiles
@@ -1242,6 +1306,7 @@ declare module "littlejsengine" {
     export function tile(pos?: Vector2 | number, size?: Vector2 | number, textureIndex?: number, padding?: number): TileInfo;
     /**
      * Tile Info - Stores info about how to draw a tile
+     * @memberof Draw
      */
     export class TileInfo {
         /** Create a tile info object
@@ -1282,7 +1347,10 @@ declare module "littlejsengine" {
          */
         setFullImage(image: HTMLImageElement | OffscreenCanvas, glTexture?: WebGLTexture): TileInfo;
     }
-    /** Texture Info - Stores info about each texture */
+    /**
+     * Tile Info - Stores info about each texture
+     * @memberof Draw
+     */
     export class TextureInfo {
         /**
          * Create a TextureInfo, called automatically by the engine
@@ -1460,16 +1528,21 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
      *  @memberof Draw */
     export function drawCircle(pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    /**
+     * @callback Canvas2DDrawFunction - A function that draws to a 2D canvas context
+     * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+     * @memberof Draw
+     */
     /** Draw directly to a 2d canvas context in world space
      *  @param {Vector2}  pos
      *  @param {Vector2}  size
      *  @param {number}   angle
      *  @param {boolean}  [mirror]
-     *  @param {Function} [drawFunction]
+     *  @param {Canvas2DDrawFunction} [drawFunction]
      *  @param {boolean}  [screenSpace=false]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
      *  @memberof Draw */
-    export function drawCanvas2D(pos: Vector2, size: Vector2, angle?: number, mirror?: boolean, drawFunction?: Function, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    export function drawCanvas2D(pos: Vector2, size: Vector2, angle?: number, mirror?: boolean, drawFunction?: Canvas2DDrawFunction, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
     /** Draw text on main canvas in world space
      *  Automatically splits new lines into rows
      *  @param {string}  text
@@ -1526,6 +1599,7 @@ declare module "littlejsengine" {
      * - 96 characters (from space to tilde) are stored in an image
      * - Uses a default 8x8 font if none is supplied
      * - You can also use fonts from the main tile sheet
+     * @memberof Draw
      * @example
      * // use built in font
      * const font = new FontImage;
@@ -1876,6 +1950,7 @@ declare module "littlejsengine" {
      * Sound Object - Stores a sound for later use and can be played positionally
      *
      * <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
+     * @memberof Audio
      * @example
      * // create a sound
      * const sound_example = new Sound([.5,.5]);
@@ -1921,12 +1996,12 @@ declare module "littlejsengine" {
         playMusic(volume?: number, loop?: boolean, paused?: boolean): SoundInstance;
         /** Play the sound as a musical note with a semitone offset
          *  This can be used to play music with chromatic scales
-         *  @param {number}  semitoneOffset - How many semitones to offset pitch
+         *  @param {number}  [semitoneOffset=0] - How many semitones to offset pitch
          *  @param {Vector2} [pos] - World space position to play the sound if any
          *  @param {number}  [volume=1] - How much to scale volume by
          *  @return {SoundInstance} - The audio source node
          */
-        playNote(semitoneOffset: number, pos?: Vector2, volume?: number): SoundInstance;
+        playNote(semitoneOffset?: number, pos?: Vector2, volume?: number): SoundInstance;
         /** Get how long this sound is in seconds
          *  @return {number} - How long the sound is in seconds (undefined if loading)
          */
@@ -1939,6 +2014,8 @@ declare module "littlejsengine" {
     /**
      * Sound Wave Object - Stores a wave sound for later use and can be played positionally
      * - this can be used to play wave, mp3, and ogg files
+     * @extends Sound
+     * @memberof Audio
      * @example
      * // create a sound
      * const sound_example = new SoundWave('sound.mp3');
@@ -1947,16 +2024,21 @@ declare module "littlejsengine" {
      * sound_example.play();
      */
     export class SoundWave extends Sound {
+        /**
+         * @callback SoundLoadCallback - Function called when sound is loaded
+         * @param {SoundWave} sound
+         * @memberof Audio
+         */
         /** Create a sound object and cache the wave file for later use
          *  @param {string} filename - Filename of audio file to load
          *  @param {number} [randomness] - How much to randomize frequency each time sound plays
          *  @param {number} [range=soundDefaultRange] - World space max range of sound
          *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
-         *  @param {Function} [onloadCallback] - callback function to call when sound is loaded
+         *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
          */
-        constructor(filename: string, randomness?: number, range?: number, taper?: number, onloadCallback?: Function);
-        /** @property {Function} - callback function to call when sound is loaded */
-        onloadCallback: Function;
+        constructor(filename: string, randomness?: number, range?: number, taper?: number, onloadCallback?: (sound: SoundWave) => SoundWave);
+        /** @property {SoundLoadCallback} - callback function to call when sound is loaded */
+        onloadCallback: (sound: SoundWave) => SoundWave;
         /** Loads a sound from a URL and decodes it into sample data. Must be used with await!
         *  @param {string} filename
         *  @return {Promise<void>} */
@@ -1965,6 +2047,7 @@ declare module "littlejsengine" {
     /**
      * Sound Instance - Wraps an AudioBufferSourceNode for individual sound control
      * Represents a single playing instance of a sound with pause/resume capabilities
+     * @memberof Audio
      * @example
      * // Play a sound and get an instance for control
      * const jumpSound = new Sound([.5,.5,220]);
@@ -2056,6 +2139,11 @@ declare module "littlejsengine" {
      *  @return {number} - The frequency of the note
      *  @memberof Audio */
     export function getNoteFrequency(semitoneOffset: number, rootFrequency?: number): number;
+    /**
+     * @callback AudioEndedCallback - Function called when a sound ends
+     * @param {AudioBufferSourceNode} source
+     * @memberof Audio
+     */
     /** Play cached audio samples with given settings
      *  @param {Array}    sampleChannels - Array of arrays of samples to play (for stereo playback)
      *  @param {number}   [volume] - How much to scale volume by
@@ -2065,10 +2153,10 @@ declare module "littlejsengine" {
      *  @param {number}   [sampleRate=44100] - Sample rate for the sound
      *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing
      *  @param {number}   [offset] - Offset in seconds to start playback from
-     *  @param {Function} [onended] - Callback for when the sound ends
+     *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
      *  @return {AudioBufferSourceNode} - The audio node of the sound played
      *  @memberof Audio */
-    export function playSamples(sampleChannels: any[], volume?: number, rate?: number, pan?: number, loop?: boolean, sampleRate?: number, gainNode?: GainNode, offset?: number, onended?: Function): AudioBufferSourceNode;
+    export function playSamples(sampleChannels: any[], volume?: number, rate?: number, pan?: number, loop?: boolean, sampleRate?: number, gainNode?: GainNode, offset?: number, onended?: AudioEndedCallback): AudioBufferSourceNode;
     /** Generate and play a ZzFX sound
      *
      *  <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
@@ -2124,6 +2212,7 @@ declare module "littlejsengine" {
      * - Collision for objects can be set to be solid to block other objects
      * - Objects may get pushed into overlapping other solid objects, if so they will push away
      * - Solid objects are more performance intensive and should be used sparingly
+     * @memberof Engine
      * @example
      * // create an engine object, normally you would first extend the class with your own
      * const pos = vec2(2,3);
@@ -2131,12 +2220,12 @@ declare module "littlejsengine" {
      */
     export class EngineObject {
         /** Create an engine object and adds it to the list of objects
-         *  @param {Vector2}  [pos=(0,0)]       - World space position of the object
-         *  @param {Vector2}  [size=(1,1)]      - World space size of the object
-         *  @param {TileInfo} [tileInfo]        - Tile info to render object (undefined is untextured)
-         *  @param {number}   [angle]           - Angle the object is rotated by
-         *  @param {Color}    [color=(1,1,1,1)] - Color to apply to tile when rendered
-         *  @param {number}   [renderOrder]     - Objects sorted by renderOrder before being rendered
+         *  @param {Vector2}  [pos=(0,0)]   - World space position of the object
+         *  @param {Vector2}  [size=(1,1)]  - World space size of the object
+         *  @param {TileInfo} [tileInfo]    - Tile info to render object (undefined is untextured)
+         *  @param {number}   [angle]       - Angle the object is rotated by
+         *  @param {Color}    [color=WHITE] - Color to apply to tile when rendered
+         *  @param {number}   [renderOrder] - Objects sorted by renderOrder before being rendered
          */
         constructor(pos?: Vector2, size?: Vector2, tileInfo?: TileInfo, angle?: number, color?: Color, renderOrder?: number);
         /** @property {Vector2} - World space position of the object */
@@ -2201,7 +2290,7 @@ declare module "littlejsengine" {
         update(): void;
         /** Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder */
         render(): void;
-        /** Destroy this object, destroy its children, detach it's parent, and mark it for removal */
+        /** Destroy this object, destroy its children, detach its parent, and mark it for removal */
         destroy(): void;
         destroyed: number;
         /** Convert from local space to world space
@@ -2267,16 +2356,16 @@ declare module "littlejsengine" {
      * - Unlimited numbers of layers, allocates canvases as needed
      * - Tile layers can be drawn to using their context with canvas2d
      * - Tile layers can also have collision with EngineObjects
-     * @namespace TileCollision
+     * @namespace TileLayers
      */
     /** Keep track of all tile layers with collision
      *  @type {Array<TileCollisionLayer>}
-     *  @memberof TileCollision */
+     *  @memberof TileLayers */
     export const tileCollisionLayers: Array<TileCollisionLayer>;
     /** Get tile collision data for a given cell in the grid
     *  @param {Vector2} pos
     *  @return {number}
-    *  @memberof TileCollision */
+    *  @memberof TileLayers */
     export function tileCollisionGetData(pos: Vector2): number;
     /** Check if a tile layer collides with another object
      *  @param {Vector2}      pos
@@ -2284,7 +2373,7 @@ declare module "littlejsengine" {
      *  @param {EngineObject} [object] - An object or undefined for generic test
      *  @param {boolean}      [solidOnly] - Only check solid layers if true
      *  @return {TileCollisionLayer}
-     *  @memberof TileCollision */
+     *  @memberof TileLayers */
     export function tileCollisionTest(pos: Vector2, size?: Vector2, object?: EngineObject, solidOnly?: boolean): TileCollisionLayer;
     /** Return the center of first tile hit, undefined if nothing was hit.
      *  This does not return the exact intersection, but the center of the tile hit.
@@ -2293,7 +2382,7 @@ declare module "littlejsengine" {
      *  @param {EngineObject} [object] - An object or undefined for generic test
      *  @param {boolean}      [solidOnly=true] - Only check solid layers if true
      *  @return {Vector2}
-     *  @memberof TileCollision */
+     *  @memberof TileLayers */
     export function tileCollisionRaycast(posStart: Vector2, posEnd: Vector2, object?: EngineObject, solidOnly?: boolean): Vector2;
     /**
      * Load tile layers from exported data
@@ -2303,10 +2392,11 @@ declare module "littlejsengine" {
      *  @param {number}   [collisionLayer] - Layer to use for collision if any
      *  @param {boolean}  [draw] - Should the layer be drawn automatically
      *  @return {Array<TileCollisionLayer>}
-     *  @memberof TileCollision */
-    export function tileCollisionLoad(tileMapData: any, tileInfo?: TileInfo, renderOrder?: number, collisionLayer?: number, draw?: boolean): Array<TileCollisionLayer>;
+     *  @memberof TileLayers */
+    export function tileLayersLoad(tileMapData: any, tileInfo?: TileInfo, renderOrder?: number, collisionLayer?: number, draw?: boolean): Array<TileCollisionLayer>;
     /**
      * Tile layer data object stores info about how to draw a tile
+     * @memberof TileLayers
      * @example
      * // create tile layer data with tile index 0 and random orientation and color
      * const tileIndex = 0;
@@ -2338,6 +2428,7 @@ declare module "littlejsengine" {
      * - Contains an offscreen canvas that can be rendered to
      * - WebGL rendering is optional, call useWebGL to enable
      * @extends EngineObject
+     * @memberof TileLayers
      * @example
      * const canvasLayer = new CanvasLayer(vec2(), vec2(200,100));
      */
@@ -2367,13 +2458,18 @@ declare module "littlejsengine" {
         *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
         *  @memberof Draw */
         draw(pos: Vector2, size?: Vector2, angle?: number, color?: Color, mirror?: boolean, additiveColor?: Color, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+        /**
+         * @callback Canvas2DDrawCallback - Function that draws to a canvas 2D context
+         * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+         * @memberof TileLayers
+         */
         /** Draw onto the layer canvas in world space (bypass WebGL)
          *  @param {Vector2}  pos
          *  @param {Vector2}  size
          *  @param {number}   angle
          *  @param {boolean}  mirror
-         *  @param {Function} drawFunction */
-        drawCanvas2D(pos: Vector2, size: Vector2, angle: number, mirror: boolean, drawFunction: Function): void;
+         *  @param {Canvas2DDrawCallback} drawFunction */
+        drawCanvas2D(pos: Vector2, size: Vector2, angle: number, mirror: boolean, drawFunction: (context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => any): void;
         /** Draw a tile onto the layer canvas in world space
          *  @param {Vector2}  pos
          *  @param {Vector2}  [size=(1,1)]
@@ -2398,7 +2494,9 @@ declare module "littlejsengine" {
      * - To allow dynamic modifications, layers are rendered using canvas 2d
      * - Some devices like mobile phones are limited to 4k texture resolution
      * - For with 16x16 tiles this limits layers to 256x256 on mobile devices
+     * - Tile layers are centered on their corner, so normal levels are at (0,0)
      * @extends CanvasLayer
+     * @memberof TileLayers
      * @example
      * const tileLayer = new TileLayer(vec2(), vec2(200,100));
      */
@@ -2407,11 +2505,10 @@ declare module "littlejsengine" {
         *  @param {Vector2}  position      - World space position
         *  @param {Vector2}  size          - World space size
         *  @param {TileInfo} [tileInfo]    - Default tile info for layer (used for size and texture)
-        *  @param {Vector2}  [scale=(1,1)] - How much to scale this layer when rendered
         *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
         *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering
         */
-        constructor(position: Vector2, size: Vector2, tileInfo?: TileInfo, scale?: Vector2, renderOrder?: number, useWebGL?: boolean);
+        constructor(position: Vector2, size: Vector2, tileInfo?: TileInfo, renderOrder?: number, useWebGL?: boolean);
         data: TileLayerData[];
         /** Draw all the tile data to an offscreen canvas
          *  - This may be slow in some browsers but only needs to be done once */
@@ -2447,16 +2544,9 @@ declare module "littlejsengine" {
      * - there can be multiple tile collision layers
      * - tile collision layers should not overlap each other
      * @extends TileLayer
+     * @memberof TileLayers
      */
     export class TileCollisionLayer extends TileLayer {
-        /** Create a tile layer object
-        *  @param {Vector2}  position      - World space position
-        *  @param {Vector2}  size          - World space size
-        *  @param {TileInfo} [tileInfo]    - Tile info for layer
-        *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
-        *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering
-        */
-        constructor(position: Vector2, size: Vector2, tileInfo?: TileInfo, renderOrder?: number, useWebGL?: boolean);
         /** @property {Array<number>} - The tile collision grid */
         collisionData: any[];
         /** Clear and initialize tile collision to new size
@@ -2487,9 +2577,15 @@ declare module "littlejsengine" {
     /**
      * LittleJS Particle System
      */
+    /**
+     *  @callback ParticleCallbackFunction - Function that processes a particle
+     *  @param {Particle} particle
+     *  @memberof Engine
+     */
     /**
      * Particle Emitter - Spawns particles with the given settings
      * @extends EngineObject
+     * @memberof Engine
      * @example
      * // create a particle emitter
      * let pos = vec2(2,3);
@@ -2513,10 +2609,10 @@ declare module "littlejsengine" {
          *  @param {number} [emitRate] - How many particles per second to spawn, does not emit if 0
          *  @param {number} [emitConeAngle=PI] - Local angle to apply velocity to particles from emitter
          *  @param {TileInfo} [tileInfo] - Tile info to render particles (undefined is untextured)
-         *  @param {Color} [colorStartA=(1,1,1,1)] - Color at start of life 1, randomized between start colors
-         *  @param {Color} [colorStartB=(1,1,1,1)] - Color at start of life 2, randomized between start colors
-         *  @param {Color} [colorEndA=(1,1,1,0)] - Color at end of life 1, randomized between end colors
-         *  @param {Color} [colorEndB=(1,1,1,0)] - Color at end of life 2, randomized between end colors
+         *  @param {Color} [colorStartA=WHITE] - Color at start of life 1, randomized between start colors
+         *  @param {Color} [colorStartB=WHITE] - Color at start of life 2, randomized between start colors
+         *  @param {Color} [colorEndA=CLEAR_WHITE] - Color at end of life 1, randomized between end colors
+         *  @param {Color} [colorEndB=CLEAR_WHITE] - Color at end of life 2, randomized between end colors
          *  @param {number} [particleTime]      - How long particles live
          *  @param {number} [sizeStart]         - How big are particles at start
          *  @param {number} [sizeEnd]           - How big are particles at end
@@ -2575,9 +2671,9 @@ declare module "littlejsengine" {
         localSpace: boolean;
         /** @property {number} - If non zero the particle is drawn as a trail, stretched in the direction of velocity */
         trailScale: number;
-        /** @property {Function}   - Callback when particle is destroyed */
+        /** @property {ParticleCallbackFunction} - Callback when particle is destroyed */
         particleDestroyCallback: any;
-        /** @property {Function}   - Callback when particle is created */
+        /** @property {ParticleCallbackFunction} - Callback when particle is created */
         particleCreateCallback: any;
         /** @property {number} - Track particle emit time */
         emitTimeBuffer: number;
@@ -2588,6 +2684,7 @@ declare module "littlejsengine" {
     /**
      * Particle Object - Created automatically by Particle Emitters
      * @extends EngineObject
+     * @memberof Engine
      */
     export class Particle extends EngineObject {
         /**
@@ -2605,19 +2702,19 @@ declare module "littlejsengine" {
          * @param {boolean}  additive   - Does it use additive blend mode
          * @param {number}   trailScale - If a trail, how long to make it
          * @param {ParticleEmitter} [localSpaceEmitter] - Parent emitter if local space
-         * @param {Function} [destroyCallback] - Callback when particle dies
+         * @param {ParticleCallbackFunction} [destroyCallback] - Callback when particle dies
          */
-        constructor(position: Vector2, tileInfo: TileInfo, angle: number, colorStart: Color, colorEnd: Color, lifeTime: number, sizeStart: number, sizeEnd: number, fadeRate: number, additive: boolean, trailScale: number, localSpaceEmitter?: ParticleEmitter, destroyCallback?: Function);
+        constructor(position: Vector2, tileInfo: TileInfo, angle: number, colorStart: Color, colorEnd: Color, lifeTime: number, sizeStart: number, sizeEnd: number, fadeRate: number, additive: boolean, trailScale: number, localSpaceEmitter?: ParticleEmitter, destroyCallback?: ParticleCallbackFunction);
         /** @property {Color} - Color at start of life */
         colorStart: Color;
-        /** @property {Color} - Calculated change in color */
-        colorEndDelta: Color;
+        /** @property {Color} - Color at end of life */
+        colorEnd: Color;
         /** @property {number} - How long to live for */
         lifeTime: number;
         /** @property {number} - Size at start of life */
         sizeStart: number;
-        /** @property {number} - Calculated change in size */
-        sizeEndDelta: number;
+        /** @property {number} - Size at end of life */
+        sizeEnd: number;
         /** @property {number} - How quick to fade in/out */
         fadeRate: number;
         /** @property {boolean} - Is it additive */
@@ -2626,8 +2723,8 @@ declare module "littlejsengine" {
         trailScale: number;
         /** @property {ParticleEmitter} - Parent emitter if local space */
         localSpaceEmitter: ParticleEmitter;
-        /** @property {Function} - Called when particle dies */
-        destroyCallback: Function;
+        /** @property {ParticleCallbackFunction} - Called when particle dies */
+        destroyCallback: ParticleCallbackFunction;
     }
     /**
      * LittleJS Medal System
@@ -2653,6 +2750,7 @@ declare module "littlejsengine" {
     export function medalsInit(saveName: string): void;
     /**
      * Medal - Tracks an unlockable medal
+     * @memberof Medals
      * @example
      * // create a medal
      * const medal_example = new Medal(0, 'Example Medal', 'More info about the medal goes here.', '🎖️');
@@ -2697,20 +2795,21 @@ declare module "littlejsengine" {
         storageKey(): string;
     }
     /**
-     * LittleJS Newgrounds API
+     * LittleJS Newgrounds Plugin
      * - NewgroundsMedal extends Medal with Newgrounds API functionality
-     * - Call new NewgroundsPlugin() to setup Newgrounds
+     * - Call new NewgroundsPlugin(app_id) to setup Newgrounds
      * - Uses CryptoJS for encryption if optional cipher is provided
+     * - provides functions to interact with medals scoreboards
      * - Keeps connection alive and logs views
-     * - Functions to interact with scoreboards
-     * - Functions to unlock medals
+     * @namespace Newgrounds
      */
     /** Global Newgrounds object
      *  @type {NewgroundsPlugin}
-     *  @memberof Medal */
+     *  @memberof Newgrounds */
     export let newgrounds: NewgroundsPlugin;
     /**
      * Newgrounds API object
+     * @memberof Newgrounds
      */
     export class NewgroundsPlugin {
         /** Create the global newgrounds object
@@ -2759,20 +2858,24 @@ declare module "littlejsengine" {
     /**
      * Newgrounds medal auto unlocks in newgrounds API
      * @extends Medal
+     * @memberof Newgrounds
      */
     export class NewgroundsMedal extends Medal {
     }
     /**
      * LittleJS Post Processing Plugin
      * - Supports shadertoy style post processing shaders
-     * - call new new PostProcessPlugin() to setup post processing
+     * - call new PostProcessPlugin() to setup post processing
      * - can be enabled to pass other canvases through a final shader
+     * @namespace PostProcess
      */
     /** Global Post Process plugin object
-     *  @type {PostProcessPlugin} */
+     *  @type {PostProcessPlugin}
+     *  @memberof PostProcess */
     export let postProcess: PostProcessPlugin;
     /**
      * UI System Global Object
+     * @memberof PostProcess
      */
     export class PostProcessPlugin {
         /** Create global post processing shader
@@ -2792,11 +2895,14 @@ declare module "littlejsengine" {
     }
     /**
      * LittleJS ZzFXM Plugin
+     * @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 Music(
@@ -2844,12 +2950,15 @@ declare module "littlejsengine" {
      * - Buttons
      * - Checkboxes
      * - Images
+     * @namespace UISystem
      */
     /** Global UI system plugin object
-     *  @type {UISystemPlugin} */
+     *  @type {UISystemPlugin}
+     *  @memberof UISystem */
     export let uiSystem: UISystemPlugin;
     /**
      * UI System Global Object
+     * @memberof UISystem
      */
     export class UISystemPlugin {
         /** Create the global UI system object
@@ -2889,10 +2998,12 @@ declare module "littlejsengine" {
         uiObjects: any[];
         /** @property {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} - Context to render UI elements to */
         uiContext: CanvasRenderingContext2D;
-        /** @property {UIObject} - Top most object user is over */
-        hoverObject: any;
         /** @property {UIObject} - Object user is currently interacting with */
         activeObject: any;
+        /** @property {UIObject} - Top most object user is over */
+        hoverObject: any;
+        /** @property {UIObject} - Hover object at start of update */
+        lastHoverObject: any;
         /** Draw a rectangle to the UI context
         *  @param {Vector2} pos
         *  @param {Vector2} size
@@ -2926,10 +3037,22 @@ declare module "littlejsengine" {
         *  @param {string}  [font=uiSystem.defaultFont]
         *  @param {boolean} [applyMaxWidth=true] */
         drawText(text: string, pos: Vector2, size: Vector2, color?: Color, lineWidth?: number, lineColor?: Color, align?: string, font?: string, applyMaxWidth?: boolean): void;
+        /**
+         * @callback DragAndDropCallback - Callback for drag and drop events
+         * @param {DragEvent} event - The drag event
+         * @memberof UISystem
+         */
+        /** Setup drag and drop event handlers
+        *  Automatically prevents defaults and calls the given functions
+        *  @param {DragAndDropCallback} [onDrop] - when a file is dropped
+        *  @param {DragAndDropCallback} [onDragEnter] - when a file is dragged onto the window
+        *  @param {DragAndDropCallback} [onDragLeave] - when a file is dragged off the window
+        *  @param {DragAndDropCallback} [onDragOver] - continously when dragging over */
+        setupDragAndDrop(onDrop?: (event: DragEvent) => any, onDragEnter?: (event: DragEvent) => any, onDragLeave?: (event: DragEvent) => any, onDragOver?: (event: DragEvent) => any): void;
     }
     /**
      * UI Object - Base level object for all UI elements
-     */
+     * @memberof UISystem */
     export class UIObject {
         /** Create a UIObject
          *  @param {Vector2}  [pos=(0,0)]
@@ -3026,6 +3149,7 @@ declare module "littlejsengine" {
     /**
      * UIText - A UI object that displays text
      * @extends UIObject
+     * @memberof UISystem
      */
     export class UIText extends UIObject {
         /** Create a UIText object
@@ -3042,6 +3166,7 @@ declare module "littlejsengine" {
     /**
      * UITile - A UI object that displays a tile image
      * @extends UIObject
+     * @memberof UISystem
      */
     export class UITile extends UIObject {
         /** Create a UITile object
@@ -3063,6 +3188,7 @@ declare module "littlejsengine" {
     /**
      * UIButton - A UI object that acts as a button
      * @extends UIObject
+     * @memberof UISystem
      */
     export class UIButton extends UIObject {
         /** Create a UIButton object
@@ -3077,6 +3203,7 @@ declare module "littlejsengine" {
     /**
      * UICheckbox - A UI object that acts as a checkbox
      * @extends UIObject
+     * @memberof UISystem
      */
     export class UICheckbox extends UIObject {
         /** Create a UICheckbox object
@@ -3094,6 +3221,7 @@ declare module "littlejsengine" {
     /**
      * UIScrollbar - A UI object that acts as a scrollbar
      * @extends UIObject
+     * @memberof UISystem
      */
     export class UIScrollbar extends UIObject {
         /** Create a UIScrollbar object
@@ -3148,6 +3276,7 @@ declare module "littlejsengine" {
     /**
      * Box2D Global Object
      * - Wraps Box2d world and provides global functions
+     * @memberof Box2D
      */
     export class Box2dPlugin {
         /** Create the global UI system object
@@ -3227,6 +3356,7 @@ declare module "littlejsengine" {
      * - Each object has a Box2D body which can have multiple fixtures and joints
      * - Provides interface for Box2D body and fixture functions
      * @extends EngineObject
+     * @memberof Box2D
      */
     export class Box2dObject extends EngineObject {
         /** Create a LittleJS object with Box2d physics
@@ -3456,6 +3586,7 @@ declare module "littlejsengine" {
      * Box2D Joint
      * - Base class for Box2D joints
      * - A joint is used to connect objects together
+     * @memberof Box2D
      */
     export class Box2dJoint {
         /** Create a box2d joint, the base class is not intended to be used directly
@@ -3497,6 +3628,7 @@ declare module "littlejsengine" {
      * - This a soft constraint with a max force
      * - This allows the constraint to stretch and without applying huge forces
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dTargetJoint extends Box2dJoint {
         /** Create a target joint
@@ -3528,6 +3660,7 @@ declare module "littlejsengine" {
      * - Constrains two points on two objects to remain at a fixed distance
      * - You can view this as a massless, rigid rod
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dDistanceJoint extends Box2dJoint {
         /** Create a distance joint
@@ -3566,6 +3699,7 @@ declare module "littlejsengine" {
      * Box2D Pin Joint
      * - Pins two objects together at a point
      * @extends Box2dDistanceJoint
+     * @memberof Box2D
      */
     export class Box2dPinJoint extends Box2dDistanceJoint {
         /** Create a pin joint
@@ -3579,6 +3713,7 @@ declare module "littlejsengine" {
      * Box2D Rope Joint
      * - Enforces a maximum distance between two points on two objects
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dRopeJoint extends Box2dJoint {
         /** Create a rope joint
@@ -3610,6 +3745,7 @@ declare module "littlejsengine" {
      * - You can use a motor to drive the relative rotation about the shared point
      * - A maximum motor torque is provided so that infinite forces are not generated
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dRevoluteJoint extends Box2dJoint {
         /** Create a revolute joint
@@ -3678,6 +3814,7 @@ declare module "littlejsengine" {
      * - Either joint can be a revolute or prismatic joint
      * - You specify a gear ratio to bind the motions together
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dGearJoint extends Box2dJoint {
         /** Create a gear joint
@@ -3709,6 +3846,7 @@ declare module "littlejsengine" {
      * - You can use a joint limit to restrict the range of motion
      * - You can use a joint motor to drive the motion or to model joint friction
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dPrismaticJoint extends Box2dJoint {
         /** Create a prismatic joint
@@ -3782,6 +3920,7 @@ declare module "littlejsengine" {
      * - You can use a joint motor to drive the motion or to model joint friction
      * - This joint is designed for vehicle suspensions
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dWheelJoint extends Box2dJoint {
         /** Create a wheel joint
@@ -3844,6 +3983,7 @@ declare module "littlejsengine" {
      * Box2D Weld Joint
      * - Glues two objects together
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dWeldJoint extends Box2dJoint {
         /** Create a weld joint
@@ -3879,6 +4019,7 @@ declare module "littlejsengine" {
      * - Used to apply top-down friction
      * - Provides 2D translational friction and angular friction
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dFrictionJoint extends Box2dJoint {
         /** Create a friction joint
@@ -3912,6 +4053,7 @@ declare module "littlejsengine" {
      * - The pulley supports a ratio such that: length1 + ratio * length2 <= constant
      * - The force transmitted is scaled by the ratio
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dPulleyJoint extends Box2dJoint {
         /** Create a pulley joint
@@ -3951,6 +4093,7 @@ declare module "littlejsengine" {
      * - Controls the relative motion between two objects
      * - Typical usage is to control the movement of a object with respect to the ground
      * @extends Box2dJoint
+     * @memberof Box2D
      */
     export class Box2dMotorJoint extends Box2dJoint {
         /** Create a motor joint