littlejsengine 1.14.23 → 1.15.2

package/dist/littlejs.d.ts

@@ -105,7 +105,7 @@ declare module "littlejsengine" {
     export function setPaused(isPaused?: boolean): void;
     /**
      * @callback GameInitCallback - Called after the engine starts, can be async
-     * @returns {void|Promise<void>}
+     * @return {void|Promise<void>}
      * @memberof Engine
      */
     /**
@@ -139,10 +139,10 @@ declare module "littlejsengine" {
      *  @memberof Engine */
     export function engineObjectsDestroy(): void;
     /** Collects all 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 {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 {Array<EngineObject>} [objects=engineObjects] - List of objects to check
-     *  @return {Array<EngineObject>}                        - List of collected objects
+     *  @return {Array<EngineObject>} - List of collected objects
      *  @memberof Engine */
     export function engineObjectsCollect(pos?: Vector2, size?: Vector2 | number, objects?: Array<EngineObject>): Array<EngineObject>;
     /**
@@ -813,7 +813,7 @@ declare module "littlejsengine" {
      *  @param {number} valueA
      *  @param {number} valueB
      *  @param {number} [wrapSize]
-     *  @returns {number}
+     *  @return {number}
      *  @memberof Utilities */
     export function distanceWrap(valueA: number, valueB: number, wrapSize?: number): number;
     /** Linearly interpolates between values passed in with wrapping
@@ -821,20 +821,20 @@ declare module "littlejsengine" {
      *  @param {number} valueB
      *  @param {number} percent
      *  @param {number} [wrapSize]
-     *  @returns {number}
+     *  @return {number}
      *  @memberof Utilities */
     export function lerpWrap(valueA: number, valueB: number, percent: number, wrapSize?: number): number;
     /** Returns signed wrapped distance between the two angles passed in
      *  @param {number} angleA
      *  @param {number} angleB
-     *  @returns {number}
+     *  @return {number}
      *  @memberof Utilities */
     export function distanceAngle(angleA: number, angleB: number): number;
     /** Linearly interpolates between the angles passed in with wrapping
      *  @param {number} angleA
      *  @param {number} angleB
      *  @param {number} percent
-     *  @returns {number}
+     *  @return {number}
      *  @memberof Utilities */
     export function lerpAngle(angleA: number, angleB: number, percent: number): number;
     /** Linearly interpolates between values passed in using percent
@@ -904,6 +904,11 @@ declare module "littlejsengine" {
      *  @return {number}
      *  @memberof Random */
     export function randInt(valueA: number, valueB?: number): number;
+    /** Randomly returns true or false given the chance of true passed in
+     *  @param {number} [chance]
+     *  @return {boolean}
+     *  @memberof Random */
+    export function randBool(chance?: number): boolean;
     /** Randomly returns either -1 or 1
      *  @return {number}
      *  @memberof Random */
@@ -1224,13 +1229,18 @@ declare module "littlejsengine" {
      */
     export class Timer {
         /** Create a timer object set time passed in
-         *  @param {number} [timeLeft] - How much time left before the timer elapses in seconds */
-        constructor(timeLeft?: number);
+         *  @param {number} [timeLeft] - How much time left before the timer
+         *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
+        constructor(timeLeft?: number, useRealTime?: boolean);
+        useRealTime: boolean;
         time: number;
         setTime: number;
         /** Set the timer with seconds passed in
          *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds */
         set(timeLeft?: number): void;
+        /** Set if the timer should keep running even when the game is paused
+         *  @param {boolean} [useRealTime] */
+        setUseRealTime(useRealTime?: boolean): void;
         /** Unset the timer */
         unset(): void;
         /** Returns true if set
@@ -1251,6 +1261,9 @@ declare module "littlejsengine" {
         /** Get the time this timer was set to, returns 0 if not set
          * @return {number} */
         getSetTime(): number;
+        /** Get the current global time this timer is based on
+         * @return {number} */
+        getGlobalTime(): number;
         /** Returns this timer expressed as a string
          * @return {string} */
         toString(): string;
@@ -1312,6 +1325,12 @@ declare module "littlejsengine" {
      * @return {boolean}
      * @memberof Utilities */
     export function isString(s: any): boolean;
+    /**
+     * Check if object is an array
+     * @param {any} a
+     * @return {boolean}
+     * @memberof Utilities */
+    export function isArray(a: any): boolean;
     /** Color - White #ffffff
      *  @type {Color}
      *  @memberof Utilities */
@@ -1646,9 +1665,10 @@ declare module "littlejsengine" {
      *  @param {string}  [font=fontDefault]
      *  @param {string}  [fontStyle]
      *  @param {number}  [maxWidth]
+     *  @param {number}  [angle]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
      *  @memberof Draw */
-    export function drawText(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    export function drawText(text: string, 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}  text
@@ -1661,8 +1681,9 @@ declare module "littlejsengine" {
      *  @param {string}  [font=fontDefault]
      *  @param {string}  [fontStyle]
      *  @param {number}  [maxWidth]
+     *  @param {number}  [angle]
      *  @memberof Draw */
-    export function drawTextOverlay(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number): void;
+    export function drawTextOverlay(text: string, 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
      *  Automatically splits new lines into rows
      *  @param {string}  text
@@ -1675,9 +1696,10 @@ declare module "littlejsengine" {
      *  @param {string}  [font=fontDefault]
      *  @param {string}  [fontStyle]
      *  @param {number}  [maxWidth]
+     *  @param {number}  [angle]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
      *  @memberof Draw */
-    export function drawTextScreen(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    export function drawTextScreen(text: string, 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
      *  @param {boolean} [additive]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
@@ -1960,6 +1982,10 @@ declare module "littlejsengine" {
      *  @type {number}
      *  @memberof Input */
     export let mouseWheel: number;
+    /** True if mouse was inside the document window, set to false when mouse leaves
+     *  @type {boolean}
+     *  @memberof Input */
+    export let mouseInWindow: boolean;
     /** Returns true if user is using gamepad (has more recently pressed a gamepad button)
      *  @type {boolean}
      *  @memberof Input */
@@ -2381,6 +2407,8 @@ declare module "littlejsengine" {
         /** Update the object transform, called automatically by engine even when paused */
         updateTransforms(): void;
         /** Update the object physics, called automatically by engine once each frame */
+        updatePhysics(): void;
+        /** Update the object, called automatically by engine once each frame. Does nothing by default. */
         update(): void;
         /** Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder */
         render(): void;
@@ -2420,6 +2448,9 @@ declare module "littlejsengine" {
         /** How long since the object was created
          *  @return {number} */
         getAliveTime(): number;
+        /** Get the speed of this object
+         *  @return {number} */
+        getSpeed(): number;
         /** Apply acceleration to this object (adjust velocity, not affected by mass)
          *  @param {Vector2} acceleration */
         applyAcceleration(acceleration: Vector2): void;
@@ -2440,6 +2471,16 @@ declare module "littlejsengine" {
         /** Removes a child from this one
          *  @param {EngineObject} child */
         removeChild(child: EngineObject): void;
+        /** Check if overlapping another engine object
+         *  Collisions are resoloved to prevent overlaps
+         *  @param {EngineObject} object
+         *  @return {boolean} */
+        isOverlappingObject(object: EngineObject): boolean;
+        /** Check if overlapping a point or aligned bounding box
+         *  @param {Vector2} pos          - Center of box
+         *  @param {Vector2} [size=(0,0)] - Size of box, uses a point if undefined
+         *  @return {boolean} */
+        isOverlapping(pos: Vector2, size?: Vector2): boolean;
         /** Set how this object collides
          *  @param {boolean} [collideSolidObjects] - Does it collide with solid objects?
          *  @param {boolean} [isSolid]             - Does it collide with and block other objects? (expensive in large numbers)
@@ -2478,6 +2519,7 @@ declare module "littlejsengine" {
      *  @memberof TileLayers */
     export function tileCollisionTest(pos: Vector2, size?: Vector2, object?: EngineObject, solidOnly?: boolean): TileCollisionLayer;
     /** Return the exact position of the boudnary of first tile hit, undefined if nothing was hit.
+     *  The point will be inside the colliding tile if it hits (may have a tiny shift)
      *  @param {Vector2}      posStart
      *  @param {Vector2}      posEnd
      *  @param {EngineObject} [object] - An object or undefined for generic test
@@ -2671,6 +2713,7 @@ declare module "littlejsengine" {
         *  @return {boolean} */
         collisionTest(pos: Vector2, size?: Vector2, object?: EngineObject): boolean;
         /** Return the exact position of the boudnary of first tile hit, undefined if nothing was hit.
+        *  The point will be inside the colliding tile if it hits (may have a tiny shift)
         *  @param {Vector2}      posStart
         *  @param {Vector2}      posEnd
         *  @param {EngineObject} [object] - An object or undefined for generic test
@@ -3118,11 +3161,11 @@ declare module "littlejsengine" {
         /** Draw a rectangle to the UI context
         *  @param {Vector2} pos
         *  @param {Vector2} size
-        *  @param {Color}   [color=uiSystem.defaultColor]
-        *  @param {number}  [lineWidth=uiSystem.defaultLineWidth]
-        *  @param {Color}   [lineColor=uiSystem.defaultLineColor]
-        *  @param {number}  [cornerRadius=uiSystem.defaultCornerRadius]
-        *  @param {Color}   [gradientColor=uiSystem.defaultGradientColor] */
+        *  @param {Color}   [color]
+        *  @param {number}  [lineWidth]
+        *  @param {Color}   [lineColor]
+        *  @param {number}  [cornerRadius]
+        *  @param {Color}   [gradientColor] */
         drawRect(pos: Vector2, size: Vector2, color?: Color, lineWidth?: number, lineColor?: Color, cornerRadius?: number, gradientColor?: Color): void;
         /** Draw a line to the UI context
         *  @param {Vector2} posA
@@ -3148,8 +3191,10 @@ declare module "littlejsengine" {
         *  @param {string}  [align]
         *  @param {string}  [font=uiSystem.defaultFont]
         *  @param {string}  [fontStyle]
-        *  @param {boolean} [applyMaxWidth=true] */
-        drawText(text: string, pos: Vector2, size: Vector2, color?: Color, lineWidth?: number, lineColor?: Color, align?: string, font?: string, fontStyle?: string, applyMaxWidth?: boolean): void;
+        *  @param {boolean} [applyMaxWidth=true]
+        *  @param {Vector2} [textShadow]
+         */
+        drawText(text: string, pos: Vector2, size: Vector2, color?: Color, lineWidth?: number, lineColor?: Color, align?: string, font?: string, fontStyle?: string, applyMaxWidth?: boolean, textShadow?: Vector2): void;
         /**
          * @callback DragAndDropCallback - Callback for drag and drop events
          * @param {DragEvent} event - The drag event
@@ -3162,6 +3207,14 @@ declare module "littlejsengine" {
         *  @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;
+        /** Convert a screen space position to native UI position
+         *  @param {Vector2} pos
+         *  @return {Vector2}
+         */
+        screenToNative(pos: Vector2): Vector2;
+        /** Destroy and remove all objects
+        *  @memberof Engine */
+        destroyObjects(): void;
     }
     /**
      * UI Object - Base level object for all UI elements
@@ -3230,6 +3283,8 @@ declare module "littlejsengine" {
         dragActivate: boolean;
         /** @property {boolean} - True if this can be a hover object */
         canBeHover: boolean;
+        /** @property {Vector2} - How much to offset the text shadow or undefined */
+        textShadow: any;
         /** Add a child UIObject to this object
          *  @param {UIObject} child
          */
@@ -3238,6 +3293,9 @@ declare module "littlejsengine" {
          *  @param {UIObject} child
          */
         removeChild(child: UIObject): void;
+        /** Destroy this object, destroy its children, detach its parent, and mark it for removal */
+        destroy(): void;
+        destroyed: number;
         /** Check if the mouse is overlapping a box in screen space
          *  @return {boolean} - True if overlapping
          */
@@ -3256,6 +3314,8 @@ declare module "littlejsengine" {
         isHoverObject(): boolean;
         /** @return {boolean} - Is the mouse held onto this element */
         isActiveObject(): boolean;
+        /** Called each frame when object updates */
+        onUpdate(): void;
         /** Called when the mouse enters the object */
         onEnter(): void;
         /** Called when the mouse leaves the object */
@@ -3362,12 +3422,73 @@ declare module "littlejsengine" {
         handleColor: Color;
         text: string;
     }
+    /**
+     * VideoPlayerUIObject - A UI object that plays video
+     * @extends UIObject
+     * @example
+     * // Create a video player UI object
+     * const video = new VideoPlayerUIObject(vec2(400, 300), vec2(320, 240), 'cutscene.mp4', true);
+     * video.play();
+     * @memberof UISystem
+     */
+    export class UIVideo extends UIObject {
+        /** Create a video player UI object
+         *  @param {Vector2} [pos]
+         *  @param {Vector2} [size]
+         *  @param {string} src - Video file path or URL
+         *  @param {boolean} [autoplay=false] - Start playing immediately?
+         *  @param {boolean} [loop=false] - Loop the video?
+         *  @param {number} [volume=1] - Volume percent scaled by global volume (0-1)
+         */
+        constructor(pos?: Vector2, size?: Vector2, src: string, autoplay?: boolean, loop?: boolean, volume?: number);
+        /** @property {float} - The video volume */
+        volume: number;
+        /** @property {HTMLVideoElement} - The video player */
+        video: HTMLVideoElement;
+        /** Play or resume the video
+         *  @return {Promise} Promise that resolves when playback starts */
+        play(): Promise<any>;
+        /** Pause the video */
+        pause(): void;
+        /** Stop and reset the video */
+        stop(): void;
+        /** Check if video is currently loading
+         *  @return {boolean} */
+        isLoadng(): boolean;
+        /** Check if video is currently paused
+         *  @return {boolean} */
+        isPaused(): boolean;
+        /** Check if video is currently playing
+         *  @return {boolean} */
+        isPlaying(): boolean;
+        /** Check if video has ended playing
+         *  @return {boolean} */
+        hasEnded(): boolean;
+        /** Set volume (0-1)
+         *  @param {number} volume - Volume level (0-1) */
+        setVolume(volume: number): void;
+        /** Set playback speed
+         *  @param {number} rate - Playback rate multiplier */
+        setPlaybackRate(rate: number): void;
+        /** Get current time in seconds
+         *  @return {number} Current playback time */
+        getCurrentTime(): number;
+        /** Get duration in seconds
+         *  @return {number} Total video duration */
+        getDuration(): number;
+        /** Get the native video dimensions
+         *  @return {Vector2} Video dimensions (may be 0,0 if metadata not loaded) */
+        getVideoSize(): Vector2;
+        /** Seek to time in seconds
+         *  @param {number} time - Time in seconds to seek to */
+        setTime(time: number): void;
+    }
     /**
      * LittleJS Box2D Physics Plugin
      * - Box2dObject extends EngineObject with Box2D physics
-     * - Call box2dInit() before engineInit() to enable
+     * - Call box2dInit() to enable
      * - You will also need to include box2d.wasm.js
-     * - Uses a super fast web assembly port of Box2D
+     * - Uses a super fast web assembly port of Box2D v2.3.1
      * - More info: https://github.com/kripken/box2d.js
      * - Functions to create polygon, circle, and edge shapes
      * - Contact begin and end callbacks
@@ -3407,6 +3528,7 @@ declare module "littlejsengine" {
         constructor(instance: any);
         instance: any;
         world: any;
+        objects: any[];
         /** @property {number} - Velocity iterations per update*/
         velocityIterations: number;
         /** @property {number} - Position iterations per update*/
@@ -3462,7 +3584,7 @@ declare module "littlejsengine" {
         vec2From(v: any): Vector2;
         /** converts a box2d vec2 pointer to a Vector2
          *  @param {Object} v */
-        vec2FromPointer(v: any): Vector2;
+        vec2FromPointer(vp: any): Vector2;
         /** converts a Vector2 to a box2 vec2
          *  @param {Vector2} v */
         vec2dTo(v: Vector2): any;
@@ -3475,9 +3597,9 @@ declare module "littlejsengine" {
     }
     /**
      * Box2D Object - extend with your own custom physics objects
-     * - A LittleJS object with Box2D physics
-     * - Each object has a Box2D body which can have multiple fixtures and joints
+     * - A LittleJS object with Box2D physics, dynamic by default
      * - Provides interface for Box2D body and fixture functions
+     * - Each object can have multiple fixtures and joints
      * @extends EngineObject
      * @memberof Box2D
      */
@@ -3493,6 +3615,8 @@ declare module "littlejsengine" {
         constructor(pos?: Vector2, size?: Vector2, tileInfo?: TileInfo, angle?: number, color?: Color, bodyType?: number, renderOrder?: number);
         body: any;
         lineColor: Color;
+        edgeLists: any[];
+        edgeLoops: any[];
         /** Draws all this object's fixtures
          *  @param {Color}  [color]
          *  @param {Color}  [lineColor]
@@ -3559,20 +3683,20 @@ declare module "littlejsengine" {
          *  @param {number}  [restitution]
          *  @param {boolean} [isSensor] */
         addEdge(point1: Vector2, point2: Vector2, density?: number, friction?: number, restitution?: number, isSensor?: boolean): any;
-        /** Add an edge loop to the body, an edge loop connects the end points
+        /** Add an edge list to the body
          *  @param {Array<Vector2>} points
          *  @param {number}  [density]
          *  @param {number}  [friction]
          *  @param {number}  [restitution]
          *  @param {boolean} [isSensor] */
-        addEdgeLoop(points: Array<Vector2>, density?: number, friction?: number, restitution?: number, isSensor?: boolean): any[];
-        /** Add an edge list to the body
+        addEdgeList(points: Array<Vector2>, density?: number, friction?: number, restitution?: number, isSensor?: boolean): any[];
+        /** Add an edge loop to the body, an edge loop connects the end points
          *  @param {Array<Vector2>} points
          *  @param {number}  [density]
          *  @param {number}  [friction]
          *  @param {number}  [restitution]
          *  @param {boolean} [isSensor] */
-        addEdgeList(points: Array<Vector2>, density?: number, friction?: number, restitution?: number, isSensor?: boolean): any[];
+        addEdgeLoop(points: Array<Vector2>, density?: number, friction?: number, restitution?: number, isSensor?: boolean): any[];
         /** Gets the center of mass
          *  @return {Vector2} */
         getCenterOfMass(): Vector2;
@@ -3619,7 +3743,7 @@ declare module "littlejsengine" {
         /** Sets the gravity scale
          *  @param {number} [scale] */
         setGravityScale(scale?: number): void;
-        /** Should this body be treated like a bullet for continuous collision detection?
+        /** Should be like a bullet for continuous collision detection?
          *  @param {boolean} [isBullet] */
         setBullet(isBullet?: boolean): void;
         /** Set the sleep state of the body
@@ -3682,6 +3806,36 @@ declare module "littlejsengine" {
          *  @return {Array<Object>} */
         getJointList(): Array<any>;
     }
+    /**
+     * Box2D Static Object - Box2d with a static physics body
+     * @extends Box2dObject
+     * @memberof Box2D
+     */
+    export class Box2dStaticObject extends Box2dObject {
+        /** Create a LittleJS object with Box2d physics
+         *  @param {Vector2}  [pos]
+         *  @param {Vector2}  [size]
+         *  @param {TileInfo} [tileInfo]
+         *  @param {number}   [angle]
+         *  @param {Color}    [color]
+         *  @param {number}   [renderOrder] */
+        constructor(pos?: Vector2, size?: Vector2, tileInfo?: TileInfo, angle?: number, color?: Color, renderOrder?: number);
+    }
+    /**
+     * Box2D Kiematic Object - Box2d with a kinematic physics body
+     * @extends Box2dObject
+     * @memberof Box2D
+     */
+    export class Box2dKiematicObject extends Box2dObject {
+        /** Create a LittleJS object with Box2d physics
+         *  @param {Vector2}  [pos]
+         *  @param {Vector2}  [size]
+         *  @param {TileInfo} [tileInfo]
+         *  @param {number}   [angle]
+         *  @param {Color}    [color]
+         *  @param {number}   [renderOrder] */
+        constructor(pos?: Vector2, size?: Vector2, tileInfo?: TileInfo, angle?: number, color?: Color, renderOrder?: number);
+    }
     /**
      * Box2D Raycast Result
      * - Holds results from a box2d raycast queries