littlejsengine 1.11.17 → 1.12.6

package/dist/littlejs.d.ts

@@ -72,7 +72,7 @@ declare module "littlejsengine" {
      *  @param {Array<string>} [imageSources=[]] - List of images to load
      *  @param {HTMLElement} [rootElement] - Root element to attach to, the document body by default
      *  @memberof Engine */
-    export function engineInit(gameInit: Function | (() => Promise<any>), gameUpdate: Function, gameUpdatePost: Function, gameRender: Function, gameRenderPost: Function, imageSources?: Array<string>, rootElement?: HTMLElement): void;
+    export function engineInit(gameInit: Function | (() => Promise<any>), gameUpdate: Function, gameUpdatePost: Function, gameRender: Function, gameRenderPost: Function, imageSources?: Array<string>, rootElement?: HTMLElement): Promise<void>;
     /** Update each engine object, remove destroyed objects, and update time
      *  @memberof Engine */
     export function engineObjectsUpdate(): void;
@@ -254,7 +254,7 @@ declare module "littlejsengine" {
      *  @default Vector2()
      *  @memberof Settings */
     export let canvasFixedSize: Vector2;
-    /** Use nearest neighbor scaling algorithm for canvas for more pixelated look
+    /** Use nearest neighbor canvas scaling for more pixelated look
      *  - Must be set before startup to take effect
      *  - If enabled sets css image-rendering:pixelated
      *  @type {boolean}
@@ -327,11 +327,11 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let objectMaxSpeed: number;
-    /** How much gravity to apply to objects along the Y axis, negative is down
-     *  @type {number}
+    /** How much gravity to apply to objects, negative Y is down
+     *  @type {Vector2}
      *  @default
      *  @memberof Settings */
-    export let gravity: number;
+    export let gravity: Vector2;
     /** Scales emit rate of particles, useful for low graphics mode (0 disables particle emitters)
      *  @type {number}
      *  @default
@@ -506,10 +506,10 @@ declare module "littlejsengine" {
      *  @param {number} speed
      *  @memberof Settings */
     export function setObjectMaxSpeed(speed: number): void;
-    /** Set how much gravity to apply to objects along the Y axis
-     *  @param {number} newGravity
+    /** Set how much gravity to apply to objects
+     *  @param {Vector2} newGravity
      *  @memberof Settings */
-    export function setGravity(newGravity: number): void;
+    export function setGravity(newGravity: Vector2): void;
     /** Set to scales emit rate of particles
      *  @param {number} scale
      *  @memberof Settings */
@@ -719,6 +719,11 @@ declare module "littlejsengine" {
      *  @return {string}
      *  @memberof Utilities */
     export function formatTime(t: number): string;
+    /** Fetches a JSON file from a URL and returns the parsed JSON object. Must be used with await!
+     *  @param {string} url - URL of JSON file
+     *  @return {Promise<object>}
+     *  @memberof Utilities */
+    export function fetchJSON(url: string): Promise<object>;
     /** Random global functions
      *  @namespace Random */
     /** Returns a random value between the two values passed in
@@ -785,6 +790,11 @@ declare module "littlejsengine" {
         /** Randomly returns either -1 or 1 deterministically
         *  @return {number} */
         sign(): number;
+        /** Returns a seeded random value between the two values passed in with a random sign
+        *  @param {number} [valueA]
+        *  @param {number} [valueB]
+        *  @return {number} */
+        floatSign(valueA?: number, valueB?: number): number;
     }
     /**
      * 2D Vector object with vector math library
@@ -1549,33 +1559,24 @@ declare module "littlejsengine" {
     /** Clears all input
      *  @memberof Input */
     export function clearInput(): void;
-    /**
-     * LittleJS Input System
-     * - Tracks keyboard down, pressed, and released
-     * - Tracks mouse buttons, position, and wheel
-     * - Tracks multiple analog gamepads
-     * - Touch input is handled as mouse input
-     * - Virtual gamepad for touch devices
-     * @namespace Input
-     */
-    /** Returns true if device key is down
-     *  @param {string|number} key
-     *  @param {number} [device]
+    /** Returns true if mouse button is down
+     *  @function
+     *  @param {number} button
      *  @return {boolean}
      *  @memberof Input */
-    export function mouseIsDown(key: string | number, device?: number): boolean;
-    /** Returns true if device key was pressed this frame
-     *  @param {string|number} key
-     *  @param {number} [device]
+    export function mouseIsDown(button: number): boolean;
+    /** Returns true if mouse button was pressed
+     *  @function
+     *  @param {number} button
      *  @return {boolean}
      *  @memberof Input */
-    export function mouseWasPressed(key: string | number, device?: number): boolean;
-    /** Returns true if device key was released this frame
-     *  @param {string|number} key
-     *  @param {number} [device]
+    export function mouseWasPressed(button: number): boolean;
+    /** Returns true if mouse button was released
+     *  @function
+     *  @param {number} button
      *  @return {boolean}
      *  @memberof Input */
-    export function mouseWasReleased(key: string | number, device?: number): boolean;
+    export function mouseWasReleased(button: number): boolean;
     /** Mouse pos in world space
      *  @type {Vector2}
      *  @memberof Input */
@@ -1650,13 +1651,13 @@ declare module "littlejsengine" {
     export class Sound {
         /** Create a sound object and cache the zzfx samples for later use
          *  @param {Array}  zzfxSound - Array of zzfx parameters, ex. [.5,.5]
-         *  @param {number} [range=soundDefaultRange] - World space max range of sound, will not play if camera is farther away
+         *  @param {number} [range=soundDefaultRange] - World space max range of sound
          *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
          */
         constructor(zzfxSound: any[], range?: number, taper?: number);
-        /** @property {number} - World space max range of sound, will not play if camera is farther away */
+        /** @property {number} - World space max range of sound */
         range: number;
-        /** @property {number} - At what percentage of range should it start tapering off */
+        /** @property {number} - At what percentage of range should it start tapering */
         taper: number;
         /** @property {number} - How much to randomize frequency each time sound plays */
         randomness: any;
@@ -1713,11 +1714,17 @@ declare module "littlejsengine" {
         /** 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, will not play if camera is farther away
-         *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering off
+         *  @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
          */
         constructor(filename: string, randomness?: number, range?: number, taper?: number, onloadCallback?: Function);
+        /** @property {Function} - callback function to call when sound is loaded */
+        onloadCallback: Function;
+        /** Loads a sound from a URL and decodes it into sample data. Must be used with await!
+        *  @param {string} filename
+        *  @return {Promise<void>} */
+        loadSound(filename: string): Promise<void>;
     }
     /** Play an mp3, ogg, or wav audio from a local file or url
      *  @param {string}  filename - Location of sound file to play
@@ -1885,7 +1892,7 @@ declare module "littlejsengine" {
         /** @property {boolean}  - Limit object speed using linear or circular math */
         clampSpeedLinear: boolean;
         /** @property {EngineObject} - Object we are standing on, if any  */
-        groundObject: any;
+        groundObject: EngineObject | TileCollisionLayer;
         /** @property {EngineObject} - Parent of object if in local space  */
         parent: any;
         /** @property {Vector2}      - Local position if child */
@@ -1967,42 +1974,27 @@ declare module "littlejsengine" {
      * LittleJS Tile Layer System
      * - Caches arrays of tiles to off screen canvas for fast rendering
      * - Unlimited numbers of layers, allocates canvases as needed
-     * - Interfaces with EngineObject for collision
-     * - Collision layer is separate from visible layers
-     * - It is recommended to have a visible layer that matches the collision
      * - Tile layers can be drawn to using their context with canvas2d
      * - Drawn directly to the main canvas without using WebGL
+     * - Tile layers can also have collision with EngineObjects
      * @namespace TileCollision
      */
-    /** The tile collision layer grid, use setTileCollisionData and getTileCollisionData to access
-     *  @type {Array<number>}
-     *  @memberof TileCollision */
-    export let tileCollision: Array<number>;
-    /** Size of the tile collision layer 2d grid
-     *  @type {Vector2}
-     *  @memberof TileCollision */
-    export let tileCollisionSize: Vector2;
-    /** Clear and initialize tile collision
-     *  @param {Vector2} size - width and height of tile collision 2d grid
-     *  @memberof TileCollision */
-    export function initTileCollision(size: Vector2): void;
-    /** Set tile collision data for a given cell in the grid
-     *  @param {Vector2} pos
-     *  @param {number}  [data]
+    /** Keep track of all tile layers with collision
+     *  @type {Array<TileCollisionLayer>}
      *  @memberof TileCollision */
-    export function setTileCollisionData(pos: Vector2, data?: number): void;
+    export let tileCollisionLayers: Array<TileCollisionLayer>;
     /** Get tile collision data for a given cell in the grid
-     *  @param {Vector2} pos
-     *  @return {number}
-     *  @memberof TileCollision */
+    *  @param {Vector2} pos
+    *  @return {number}
+    *  @memberof TileCollision */
     export function getTileCollisionData(pos: Vector2): number;
-    /** Check if collision with another object should occur
+    /** Check if a tile layer collides with another object
      *  @param {Vector2}      pos
      *  @param {Vector2}      [size=(0,0)]
      *  @param {EngineObject} [object]
-     *  @return {boolean}
+     *  @return {TileCollisionLayer}
      *  @memberof TileCollision */
-    export function tileCollisionTest(pos: Vector2, size?: Vector2, object?: EngineObject): boolean;
+    export function tileCollisionTest(pos: Vector2, size?: Vector2, object?: EngineObject): 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.
      *  @param {Vector2}      posStart
@@ -2012,7 +2004,7 @@ declare module "littlejsengine" {
      *  @memberof TileCollision */
     export function tileCollisionRaycast(posStart: Vector2, posEnd: Vector2, object?: EngineObject): Vector2;
     /**
-     * Tile layer data object stores info about how to render a tile
+     * Tile layer data object stores info about how to draw a tile
      * @example
      * // create tile layer data with tile index 0 and random orientation and color
      * const tileIndex = 0;
@@ -2044,20 +2036,18 @@ declare module "littlejsengine" {
      * - Each Tile layer is rendered to an off screen canvas
      * - To allow dynamic modifications, layers are rendered using canvas 2d
      * - Some devices like mobile phones are limited to 4k texture resolution
-     * - So with 16x16 tiles this limits layers to 256x256 on mobile devices
+     * - For with 16x16 tiles this limits layers to 256x256 on mobile devices
      * @extends EngineObject
      * @example
-     * // create tile collision and visible tile layer
-     * initTileCollision(vec2(200,100));
-     * const tileLayer = new TileLayer();
+     * const tileLayer = new TileLayer(vec2(), vec2(200,100));
      */
     export class TileLayer extends EngineObject {
         /** Create a tile layer object
-        *  @param {Vector2}  [position=(0,0)]     - World space position
-        *  @param {Vector2}  [size=tileCollisionSize] - World space size
-        *  @param {TileInfo} [tileInfo]    - Tile info for layer
-        *  @param {Vector2}  [scale=(1,1)] - How much to scale this layer when rendered
-        *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
+        *  @param {Vector2}  [position=(0,0)] - World space position
+        *  @param {Vector2}  [size=(1,1)]     - World space size
+        *  @param {TileInfo} [tileInfo]       - Tile info for layer
+        *  @param {Vector2}  [scale=(1,1)]    - How much to scale this layer when rendered
+        *  @param {number}   [renderOrder]    - Objects are sorted by renderOrder
         */
         constructor(position?: Vector2, size?: Vector2, tileInfo?: TileInfo, scale?: Vector2, renderOrder?: number);
         /** @property {HTMLCanvasElement} - The canvas used by this tile layer */
@@ -2118,6 +2108,48 @@ declare module "littlejsengine" {
          *  @param {number}  [angle=0] */
         drawRect(pos: Vector2, size?: Vector2, color?: Color, angle?: number): void;
     }
+    /**
+     * Tile Collision Layer - a tile layer with collision
+     * - adds collision data and functions to TileLayer
+     * - there can be multiple tile collision layers
+     * - tile collison layers should not overlap each other
+     * @extends TileLayer
+     */
+    export class TileCollisionLayer extends TileLayer {
+        /** Create a tile layer object
+        *  @param {Vector2}  [position=(0,0)] - World space position
+        *  @param {Vector2}  [size=(0,0)]     - World space size
+        *  @param {TileInfo} [tileInfo]       - Tile info for layer
+        *  @param {number}   [renderOrder]    - Objects are sorted by renderOrder
+        */
+        constructor(position?: Vector2, size?: Vector2, tileInfo?: TileInfo, renderOrder?: number);
+        /** @property {Array<number>} - The tile collision grid */
+        collisionData: any[];
+        /** Clear and initialize tile collision to new size
+        *  @param {Vector2} size - width and height of tile collision 2d grid */
+        initCollision(size: Vector2): void;
+        /** Set tile collision data for a given cell in the grid
+        *  @param {Vector2} pos
+        *  @param {number}  [data] */
+        setCollisionData(pos: Vector2, data?: number): void;
+        /** Get tile collision data for a given cell in the grid
+        *  @param {Vector2} pos
+        *  @return {number} */
+        getCollisionData(pos: Vector2): number;
+        /** Check if collision with another object should occur
+        *  @param {Vector2}      pos
+        *  @param {Vector2}      [size=(0,0)]
+        *  @param {EngineObject} [object]
+        *  @return {boolean} */
+        collisionTest(pos: Vector2, size?: Vector2, object?: EngineObject): boolean;
+        /** 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.
+        *  @param {Vector2}      posStart
+        *  @param {Vector2}      posEnd
+        *  @param {EngineObject} [object]
+        *  @return {Vector2} */
+        collisionRaycast(posStart: Vector2, posEnd: Vector2, object?: EngineObject): Vector2;
+    }
     /**
      * LittleJS Particle System
      */
@@ -2330,6 +2362,15 @@ declare module "littlejsengine" {
         renderIcon(pos: Vector2, size: number): void;
         storageKey(): string;
     }
+    /**
+     * LittleJS Newgrounds API
+     * - NewgroundsMedal extends Medal with Newgrounds API functionality
+     * - Call new NewgroundsPlugin() to setup Newgrounds
+     * - Uses CryptoJS for encryption if optional cipher is provided
+     * - Keeps connection alive and logs views
+     * - Functions to interact with scoreboards
+     * - Functions to unlock medals
+     */
     /** Global Newgrounds object
      *  @type {NewgroundsPlugin}
      *  @memberof Medal */
@@ -2387,6 +2428,12 @@ declare module "littlejsengine" {
      */
     export class NewgroundsMedal extends Medal {
     }
+    /**
+     * LittleJS Post Processing Plugin
+     * - Supports shadertoy style post processing shaders
+     * - call new new PostProcessPlugin() to setup post processing
+     * - can be enabled to pass other canvases through a final shader
+     */
     /** Global Post Process plugin object
      *  @type {PostProcessPlugin} */
     export let postProcess: PostProcessPlugin;
@@ -2409,6 +2456,9 @@ declare module "littlejsengine" {
         /** @property {boolean} - Should overlay canvas be included in post processing */
         includeOverlay: boolean;
     }
+    /**
+     * LittleJS ZzFXM Plugin
+     */
     /**
      * Music Object - Stores a zzfx music track for later use
      *
@@ -2452,6 +2502,15 @@ declare module "littlejsengine" {
          */
         playMusic(volume?: number, loop?: boolean): AudioBufferSourceNode;
     }
+    /**
+     * LittleJS User Interface Plugin
+     * - call new UISystemPlugin() to setup the UI system
+     * - Nested Menus
+     * - Text
+     * - Buttons
+     * - Checkboxes
+     * - Images
+     */
     /** Global UI system plugin object
      *  @type {UISystemPlugin} */
     export let uiSystem: UISystemPlugin;
@@ -2543,6 +2602,8 @@ declare module "littlejsengine" {
         lineWidth: number;
         /** @property {string} */
         font: string;
+        /** @property {number} - override for text height */
+        textHeight: any;
         /** @property {boolean} */
         visible: boolean;
         /** @property {Array<UIObject>} */
@@ -2662,22 +2723,38 @@ declare module "littlejsengine" {
         text: string;
         handleColor: Color;
     }
+    /**
+     * LittleJS Box2D Physics Plugin
+     * - Box2dObject extends EngineObject with Box2D physics
+     * - Call box2dInit() before engineInit() to enable
+     * - You will also need to include box2d.wasm.js
+     * - Uses a super fast web assembly port of Box2D
+     * - More info: https://github.com/kripken/box2d.js
+     * - Functions to create polygon, circle, and edge shapes
+     * - Contact begin and end callbacks
+     * - Wraps b2Vec2 type to/from Vector2
+     * - Raycasting and querying
+     * - Every type of joint
+     * - Debug physics drawing
+     * @namespace Box2D
+     */
     /** Global Box2d Plugin object
-     *  @type {Box2dPlugin} */
+     *  @type {Box2dPlugin}
+     *  @memberof Box2D */
     export let box2d: Box2dPlugin;
     /** Enable Box2D debug drawing
      *  @type {boolean}
-     *  @default */
+     *  @default
+     *  @memberof Box2D */
     export let box2dDebug: boolean;
-    /** Box2d Init - Startup LittleJS engine with your callback functions
-     *  @param {Function|function():Promise} gameInit - Called once after the engine starts up
-     *  @param {Function} gameUpdate - Called every frame before objects are updated
-     *  @param {Function} gameUpdatePost - Called after physics and objects are updated, even when paused
-     *  @param {Function} gameRender - Called before objects are rendered, for drawing the background
-     *  @param {Function} gameRenderPost - Called after objects are rendered, useful for drawing UI
-     *  @param {Array<string>} [imageSources=[]] - List of images to load
-     *  @param {HTMLElement} [rootElement] - Root element to attach to, the document body by default */
-    export function box2dEngineInit(gameInit: Function | (() => Promise<any>), gameUpdate: Function, gameUpdatePost: Function, gameRender: Function, gameRenderPost: Function, imageSources?: Array<string>, rootElement?: HTMLElement): void;
+    /** Enable Box2D debug drawing
+     *  @param {boolean} enable
+     *  @memberof Box2D */
+    export function box2dSetDebug(enable: boolean): void;
+    /** Box2d Init - Call with await before starting LittleJS to init box2d
+     *  @return {Promise<Box2dPlugin>}
+     *  @memberof Box2D */
+    export function box2dInit(): Promise<Box2dPlugin>;
     /**
      * Box2D Global Object
      * - Wraps Box2d world and provides global functions