littlejsengine 1.15.8 → 1.16.1

package/dist/littlejs.d.ts

@@ -133,6 +133,7 @@ declare module "littlejsengine" {
      *  @memberof Engine */
     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
+     * can be called manually if objects need to be updated outside of main loop
      *  @memberof Engine */
     export function engineObjectsUpdate(): void;
     /** Destroy and remove all objects
@@ -198,7 +199,7 @@ declare module "littlejsengine" {
      *  @type {boolean}
      *  @default
      *  @memberof Debug */
-    export let showWatermark: boolean;
+    export let debugWatermark: 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
@@ -348,6 +349,18 @@ declare module "littlejsengine" {
      *  @default Vector2(1920,1080)
      *  @memberof Settings */
     export let canvasMaxSize: Vector2;
+    /** Minimum aspect ratio of the canvas (width/height), unused if 0
+     *  Can be used with canvasMaxAspect to limit aspect ratio
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let canvasMinAspect: number;
+    /** Maximum aspect ratio of the canvas (width/height), unused if 0
+     *  Can be used with canvasMinAspect to limit aspect ratio
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let canvasMaxAspect: number;
     /** Fixed size of the canvas, if enabled canvas size never changes
      * - you may also need to set mainCanvasSize if using screen space coords in startup
      *  @type {Vector2}
@@ -360,13 +373,6 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let canvasPixelated: boolean;
-    /** Use nearest canvas scaling for more pixelated look
-     *  - If enabled sets css image-rendering:pixelated
-     *  - This defaults to false because text looks better with smoothing
-     *  @type {boolean}
-     *  @default
-     *  @memberof Settings */
-    export let overlayCanvasPixelated: boolean;
     /** Disables texture filtering for crisper pixel art
      *  @type {boolean}
      *  @default
@@ -391,12 +397,17 @@ declare module "littlejsengine" {
      *  @type {Vector2}
      *  @default Vector2(16,16)
      *  @memberof Settings */
-    export let tileSizeDefault: Vector2;
-    /** How many pixels smaller to draw tiles to prevent bleeding from neighbors
+    export let tileDefaultSize: Vector2;
+    /** Default padding pixels around tiles
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let tileDefaultPadding: number;
+    /** Default amount of pixels smaller to draw tiles to prevent neighbor bleeding
      *  @type {number}
      *  @default
      *  @memberof Settings */
-    export let tileFixBleedScale: number;
+    export let tileDefaultBleed: number;
     /** Enable physics solver for collisions between objects
      *  @type {boolean}
      *  @default
@@ -557,21 +568,22 @@ declare module "littlejsengine" {
      *  @param {Vector2} size
      *  @memberof Settings */
     export function setCanvasMaxSize(size: Vector2): void;
+    /** Set minimum aspect ratio of the canvas (width/height), unused if 0
+     *  @param {number} aspect
+     *  @memberof Settings */
+    export function setCanvasMinAspect(aspect: number): void;
+    /** Set maximum aspect ratio of the canvas (width/height), unused if 0
+     *  @param {number} aspect
+     *  @memberof Settings */
+    export function setCanvasMaxAspect(aspect: number): void;
     /** Set fixed size of the canvas
      *  @param {Vector2} size
      *  @memberof Settings */
     export function setCanvasFixedSize(size: Vector2): void;
     /** Use nearest scaling algorithm for canvas for more pixelated look
-     *  - If enabled sets css image-rendering:pixelated
      *  @param {boolean} pixelated
      *  @memberof Settings */
     export function setCanvasPixelated(pixelated: boolean): void;
-    /** Use nearest scaling algorithm for canvas for more pixelated look
-     *  - If enabled sets css image-rendering:pixelated
-     *  - This defaults to false because text looks better with smoothing
-     *  @param {boolean} pixelated
-     *  @memberof Settings */
-    export function setOverlayCanvasPixelated(pixelated: boolean): void;
     /** Disables texture filtering for crisper pixel art
      *  @param {boolean} pixelated
      *  @memberof Settings */
@@ -595,11 +607,15 @@ declare module "littlejsengine" {
     /** Set default size of tiles in pixels
      *  @param {Vector2} size
      *  @memberof Settings */
-    export function setTileSizeDefault(size: Vector2): void;
-    /** Set to prevent tile bleeding from neighbors in pixels
-     *  @param {number} scale
+    export function setTileDefaultSize(size: Vector2): void;
+    /** Default padding pixels around tiles
+     *  @param {number} padding
+     *  @memberof Settings */
+    export function setTileDefaultPadding(padding: number): void;
+    /** Default amount of pixels smaller to draw tiles to prevent neighbor bleeding
+     *  @param {number} bleed
      *  @memberof Settings */
-    export function setTileFixBleedScale(scale: number): void;
+    export function setTileDefaultBleed(bleed: number): void;
     /** Set if collisions between objects are enabled
      *  @param {boolean} enable
      *  @memberof Settings */
@@ -716,7 +732,7 @@ declare module "littlejsengine" {
     /** Set if watermark with FPS should be shown
      *  @param {boolean} show
      *  @memberof Debug */
-    export function setShowWatermark(show: boolean): void;
+    export function setDebugWatermark(show: boolean): void;
     /** Set key code used to toggle debug mode, Esc by default
      *  @param {string} key
      *  @memberof Debug */
@@ -1411,7 +1427,7 @@ declare module "littlejsengine" {
      * - 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] - Position of the tile in pixels, or tile index
-     * @param {Vector2|number} [size=tileSizeDefault] - Size of tile in pixels
+     * @param {Vector2|number} [size] - Size of tile in pixels
      * @param {number} [textureIndex] - Texture index to use
      * @param {number} [padding] - How many pixels padding around tiles
      * @return {TileInfo}
@@ -1428,13 +1444,13 @@ declare module "littlejsengine" {
      */
     export class TileInfo {
         /** Create a tile info object
-         *  @param {Vector2} [pos=(0,0)]            - Top left corner of tile in pixels
-         *  @param {Vector2} [size=tileSizeDefault] - Size of tile in pixels
-         *  @param {number}  [textureIndex]         - Texture index to use
-         *  @param {number}  [padding]              - How many pixels padding around tiles
-         *  @param {number}  [bleedScale]           - How many pixels smaller to draw tiles
+         *  @param {Vector2} [pos=(0,0)] - Top left corner of tile in pixels
+         *  @param {Vector2} [size] - Size of tile in pixels
+         *  @param {number}  [textureIndex] - Texture index to use
+         *  @param {number}  [padding] - How many pixels padding around tiles
+         *  @param {number}  [bleed] - How many pixels smaller to draw tiles
          */
-        constructor(pos?: Vector2, size?: Vector2, textureIndex?: number, padding?: number, bleedScale?: number);
+        constructor(pos?: Vector2, size?: Vector2, textureIndex?: number, padding?: number, bleed?: number);
         /** @property {Vector2} - Top left corner of tile in pixels */
         pos: Vector2;
         /** @property {Vector2} - Size of tile in pixels */
@@ -1446,7 +1462,7 @@ declare module "littlejsengine" {
         /** @property {TextureInfo} - The texture info for this tile */
         textureInfo: TextureInfo;
         /** @property {number} - Shrinks tile by this many pixels to prevent neighbors bleeding */
-        bleedScale: number;
+        bleed: number;
         /** Returns a copy of this tile offset by a vector
         *  @param {Vector2} offset - Offset to apply in pixels
         *  @return {TileInfo}
@@ -1503,7 +1519,6 @@ declare module "littlejsengine" {
      * There are 3 canvas/contexts available to draw to...
      * mainCanvas - 2D background canvas, non WebGL stuff like tile layers are drawn here.
      * glCanvas - Used by the accelerated WebGL batch rendering system.
-     * overlayCanvas - Another 2D canvas that appears on top of the other 2 canvases.
      *
      * The WebGL rendering system is very fast with some caveats...
      * - Switching blend modes (additive) or textures causes another draw call which is expensive in excess
@@ -1528,14 +1543,22 @@ declare module "littlejsengine" {
      *  @type {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D}
      *  @memberof Draw */
     export let drawContext: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
-    /** A canvas that appears on top of everything the same size as mainCanvas
-     *  @type {HTMLCanvasElement}
+    /** Offscreen canvas that can be used for image processing
+     *  @type {OffscreenCanvas}
      *  @memberof Draw */
-    export let overlayCanvas: HTMLCanvasElement;
-    /** 2d context for overlayCanvas
-     *  @type {CanvasRenderingContext2D}
+    export let workCanvas: OffscreenCanvas;
+    /** Offscreen canvas that can be used for image processing
+     *  @type {OffscreenCanvasRenderingContext2D}
+     *  @memberof Draw */
+    export let workContext: OffscreenCanvasRenderingContext2D;
+    /** Offscreen canvas with willReadFrequently that can be used for image processing
+     *  @type {OffscreenCanvas}
+     *  @memberof Draw */
+    export let workReadCanvas: OffscreenCanvas;
+    /** Offscreen canvas with willReadFrequently that can be used for image processing
+     *  @type {OffscreenCanvasRenderingContext2D}
      *  @memberof Draw */
-    export let overlayContext: CanvasRenderingContext2D;
+    export let workReadContext: OffscreenCanvasRenderingContext2D;
     /** The size of the main canvas (and other secondary canvases)
      *  @type {Vector2}
      *  @memberof Draw */
@@ -1692,22 +1715,7 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
      *  @memberof Draw */
     export function drawText(text: string | number, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number, angle?: number, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
-    /** Draw text on overlay canvas in world space
-     *  Automatically splits new lines into rows
-     *  @param {string|number}  text
-     *  @param {Vector2} pos
-     *  @param {number}  [size]
-     *  @param {Color}   [color=(1,1,1,1)]
-     *  @param {number}  [lineWidth]
-     *  @param {Color}   [lineColor=(0,0,0,1)]
-     *  @param {CanvasTextAlign}  [textAlign='center']
-     *  @param {string}  [font=fontDefault]
-     *  @param {string}  [fontStyle]
-     *  @param {number}  [maxWidth]
-     *  @param {number}  [angle]
-     *  @memberof Draw */
-    export function drawTextOverlay(text: string | number, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number, angle?: number): void;
-    /** Draw text on overlay canvas in screen space
+    /** Draw text in screen space
      *  Automatically splits new lines into rows
      *  @param {string|number}  text
      *  @param {Vector2} pos
@@ -1720,7 +1728,7 @@ declare module "littlejsengine" {
      *  @param {string}  [fontStyle]
      *  @param {number}  [maxWidth]
      *  @param {number}  [angle]
-     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=mainContext]
      *  @memberof Draw */
     export function drawTextScreen(text: string | number, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number, angle?: number, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
     /** Enable normal or additive blend mode
@@ -1728,8 +1736,8 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
      *  @memberof Draw */
     export function setBlendMode(additive?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
-    /** Combines all LittleJS canvases onto the main canvas and clears them
-     *  This is necessary for things like saving a screenshot
+    /** Combines LittleJS canvases onto the main canvas
+     *  This is necessary for things like screenshots and video
      *  @memberof Draw */
     export function combineCanvases(): void;
     export let engineFontImage: any;
@@ -1764,14 +1772,7 @@ declare module "littlejsengine" {
          *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
          */
         drawText(text: string | number, pos: Vector2, scale?: number, center?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
-        /** Draw text on overlay canvas in world space using the image font
-         *  @param {string|number}  text
-         *  @param {Vector2} pos
-         *  @param {number}  [scale]
-         *  @param {boolean} [center]
-         */
-        drawTextOverlay(text: string | number, pos: Vector2, scale?: number, center?: boolean): void;
-        /** Draw text on overlay canvas in screen space using the image font
+        /** Draw text in screen space using the image font
          *  @param {string|number}  text
          *  @param {Vector2} pos
          *  @param {number}  [scale]
@@ -1807,7 +1808,7 @@ declare module "littlejsengine" {
      * - Supports shadertoy style post processing shaders via plugin
      * @namespace WebGL
      */
-    /** The WebGL canvas which appears above the main canvas and below the overlay canvas
+    /** The WebGL canvas which appears below the main canvas
      *  @type {HTMLCanvasElement}
      *  @memberof WebGL */
     export let glCanvas: HTMLCanvasElement;
@@ -2172,12 +2173,12 @@ declare module "littlejsengine" {
         isLoaded(): boolean;
     }
     /**
-     * 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
+     * Sound Wave Object - Loads and stores an audio file for later use
+     * - this can be used to load and play wave, mp3, and ogg files
      * @extends Sound
      * @memberof Audio
      * @example
-     * // create a sound
+     * // load an audio asset file
      * const sound_example = new SoundWave('sound.mp3');
      *
      * // play the sound
@@ -2503,11 +2504,12 @@ declare module "littlejsengine" {
         /** Get the direction of the mirror
          *  @return {number} -1 if this.mirror is true, or 1 if not mirrored */
         getMirrorSign(): number;
-        /** Attaches a child to this with a given local transform
+        /** Attaches a child to this with a local transform, returns child for chaining
          *  @param {EngineObject} child
          *  @param {Vector2}      [localPos=(0,0)]
-         *  @param {number}       [localAngle] */
-        addChild(child: EngineObject, localPos?: Vector2, localAngle?: number): void;
+         *  @param {number}       [localAngle]
+         *  @return {EngineObject} The child object added */
+        addChild(child: EngineObject, localPos?: Vector2, localAngle?: number): EngineObject;
         /** Removes a child from this one
          *  @param {EngineObject} child */
         removeChild(child: EngineObject): void;
@@ -2721,8 +2723,8 @@ declare module "littlejsengine" {
          *  @param {Vector2} layerPos - Local position in array
          *  @return {TileLayerData} */
         getData(layerPos: Vector2): TileLayerData;
-        /** @type {[HTMLCanvasElement|OffscreenCanvas, CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D, Vector2, Vector2, number]} */
-        savedRenderSettings: [HTMLCanvasElement | OffscreenCanvas, CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, Vector2, Vector2, number];
+        /** @type {[HTMLCanvasElement|OffscreenCanvas, CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D, Vector2, Vector2, number, Color]} */
+        savedRenderSettings: [HTMLCanvasElement | OffscreenCanvas, CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, Vector2, Vector2, number, Color];
     }
     /**
      * Tile Collision Layer - a tile layer with collision
@@ -3071,13 +3073,12 @@ declare module "littlejsengine" {
     export class PostProcessPlugin {
         /** Create global post processing shader
         *  @param {string} shaderCode
-        *  @param {boolean} [includeOverlay]
         *  @param {boolean} [includeMainCanvas]
          *  @example
          *  // create the post process plugin object
          *  new PostProcessPlugin(shaderCode);
          */
-        constructor(shaderCode: string, includeOverlay?: boolean, includeMainCanvas?: boolean);
+        constructor(shaderCode: string, includeMainCanvas?: boolean);
         /** @property {WebGLProgram} - Shader for post processing */
         shader: any;
         /** @property {WebGLTexture} - Texture for post processing */
@@ -3172,6 +3173,8 @@ declare module "littlejsengine" {
          *  new UISystemPlugin;
          */
         constructor(context?: CanvasRenderingContext2D);
+        /** @property {boolean} - Activate when mouse is pressed down instead of clicked */
+        activateOnPress: boolean;
         /** @property {Color} - Default fill color for UI elements */
         defaultColor: Color;
         /** @property {Color} - Default outline color for UI elements */
@@ -3210,8 +3213,6 @@ declare module "littlejsengine" {
         nativeHeight: number;
         /** @property {UIObject} - Object currently selected by navigation (gamepad or keyboard) */
         navigationObject: any;
-        /** @property {number} - Gamepad index to use for UI navigation */
-        navigationGamepadIndex: number;
         /** @property {Timer} - Cooldown timer for navigation inputs */
         navigationTimer: Timer;
         /** @property {number} - Time between navigation inputs in seconds */
@@ -3402,9 +3403,10 @@ declare module "littlejsengine" {
         navigationIndex: any;
         /** @property {boolean} - Should this be auto selected by navigation? Must also have valid navigation index. */
         navigationAutoSelect: boolean;
-        /** Add a child UIObject to this object
-         *  @param {UIObject} child */
-        addChild(child: UIObject): void;
+        /** Add a child UIObject to this object, returns child for chaining
+         *  @param {UIObject} child
+         *  @return {UIObject} The child object added */
+        addChild(child: UIObject): UIObject;
         /** Remove a child UIObject from this object
          *  @param {UIObject} child */
         removeChild(child: UIObject): void;
@@ -4556,8 +4558,8 @@ declare module "littlejsengine" {
      * - Nine slice and three slice drawing
      * @namespace DrawUtilities
      */
-    /** Draw a scalable nine-slice UI element to the overlay canvas in screen space
-     *  This function can not apply color because it draws using the overlay 2d context
+    /** Draw a scalable nine-slice UI element to the main canvas in screen space
+     *  This function can not apply color because it draws using the 2d context
      *  @param {Vector2} pos - Screen space position
      *  @param {Vector2} size - Screen space size
      *  @param {TileInfo} startTile - Starting tile for the nine-slice pattern
@@ -4581,8 +4583,8 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D} [context] - Canvas context to use
      *  @memberof DrawUtilities */
     export function drawThreeSlice(pos: Vector2, size: Vector2, startTile: TileInfo, color?: Color, borderSize?: number, additiveColor?: Color, extraSpace?: number, angle?: number, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D): void;
-    /** Draw a scalable three-slice UI element to the overlay canvas in screen space
-     *  This function can not apply color because it draws using the overlay 2d context
+    /** Draw a scalable three-slice UI element to the main canvas in screen space
+     *  This function can not apply color because it draws using the 2d context
      *  @param {Vector2} pos - Screen space position
      *  @param {Vector2} size - Screen space size
      *  @param {TileInfo} startTile - Starting tile for the three-slice pattern