littlejsengine 1.14.28 → 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
@@ -1229,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
@@ -1256,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;
@@ -3204,6 +3212,9 @@ declare module "littlejsengine" {
          *  @return {Vector2}
          */
         screenToNative(pos: Vector2): Vector2;
+        /** Destroy and remove all objects
+        *  @memberof Engine */
+        destroyObjects(): void;
     }
     /**
      * UI Object - Base level object for all UI elements
@@ -3282,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
          */
@@ -3408,6 +3422,67 @@ 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

package/dist/littlejs.esm.js

@@ -33,7 +33,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.15.0';
+const engineVersion = '1.15.2';
 
 /** Frames per second to update
  *  @type {number}
@@ -134,7 +134,7 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored)
 
 /**
  * @callback GameInitCallback - Called after the engine starts, can be async
- * @returns {void|Promise<void>}
+ * @return {void|Promise<void>}
  * @memberof Engine
  */
 /**
@@ -490,10 +490,10 @@ function engineObjectsDestroy()
 }
 
 /** 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 */
 function engineObjectsCollect(pos, size, objects=engineObjects)
 {
@@ -1555,7 +1555,7 @@ function percentLerp(value, percentA, percentB, lerpA, lerpB)
  *  @param {number} valueA
  *  @param {number} valueB
  *  @param {number} [wrapSize]
- *  @returns {number}
+ *  @return {number}
  *  @memberof Utilities */
 function distanceWrap(valueA, valueB, wrapSize=1)
 { const d = (valueA - valueB) % wrapSize; return d*2 % wrapSize - d; }
@@ -1565,7 +1565,7 @@ function distanceWrap(valueA, valueB, wrapSize=1)
  *  @param {number} valueB
  *  @param {number} percent
  *  @param {number} [wrapSize]
- *  @returns {number}
+ *  @return {number}
  *  @memberof Utilities */
 function lerpWrap(valueA, valueB, percent, wrapSize=1)
 {
@@ -1577,7 +1577,7 @@ function lerpWrap(valueA, valueB, percent, wrapSize=1)
 /** Returns signed wrapped distance between the two angles passed in
  *  @param {number} angleA
  *  @param {number} angleB
- *  @returns {number}
+ *  @return {number}
  *  @memberof Utilities */
 function distanceAngle(angleA, angleB) { return distanceWrap(angleA, angleB, 2*PI); }
 
@@ -1585,7 +1585,7 @@ function distanceAngle(angleA, angleB) { return distanceWrap(angleA, angleB, 2*P
  *  @param {number} angleA
  *  @param {number} angleB
  *  @param {number} percent
- *  @returns {number}
+ *  @return {number}
  *  @memberof Utilities */
 function lerpAngle(angleA, angleB, percent) { return lerpWrap(angleA, angleB, percent, 2*PI); }
 
@@ -2554,11 +2554,14 @@ const MAGENTA = debugProtectConstant(rgb(1,0,1));
 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)
+     *  @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, useRealTime=false)
     {
         ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Constructed Timer is invalid.', timeLeft);
-        this.time = timeLeft === undefined ? undefined : time + timeLeft;
+        this.useRealTime = useRealTime;
+        const globalTime = this.getGlobalTime();
+        this.time = timeLeft === undefined ? undefined : globalTime + timeLeft;
         this.setTime = timeLeft;
     }
 
@@ -2567,10 +2570,19 @@ class Timer
     set(timeLeft=0)
     {
         ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
-        this.time = time + timeLeft;
+        const globalTime = this.getGlobalTime();
+        this.time = globalTime + timeLeft;
         this.setTime = timeLeft;
     }
 
+    /** Set if the timer should keep running even when the game is paused
+     *  @param {boolean} [useRealTime] */
+    setUseRealTime(useRealTime=true)
+    {
+        ASSERT(!this.isSet(), 'Cannot change global time setting while timer is set.');
+        this.useRealTime = useRealTime;
+    }
+
     /** Unset the timer */
     unset() { this.time = undefined; }
 
@@ -2580,24 +2592,28 @@ class Timer
 
     /** Returns true if set and has not elapsed
      * @return {boolean} */
-    active() { return time < this.time; }
+    active() { return this.getGlobalTime() < this.time; }
 
     /** Returns true if set and elapsed
      * @return {boolean} */
-    elapsed() { return time >= this.time; }
+    elapsed() { return this.getGlobalTime() >= this.time; }
 
     /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
      * @return {number} */
-    get() { return this.isSet()? time - this.time : 0; }
+    get() { return this.isSet()? this.getGlobalTime() - this.time : 0; }
 
     /** Get percentage elapsed based on time it was set to, returns 0 if not set
      * @return {number} */
-    getPercent() { return this.isSet()? 1-percent(this.time - time, 0, this.setTime) : 0; }
+    getPercent() { return this.isSet()? 1-percent(this.time - this.getGlobalTime(), 0, this.setTime) : 0; }
 
     /** Get the time this timer was set to, returns 0 if not set
      * @return {number} */
     getSetTime() { return this.isSet() ? this.setTime : 0; }
 
+    /** Get the current global time this timer is based on
+     * @return {number} */
+    getGlobalTime() { return this.useRealTime ? timeReal : time; }
+
     /** Returns this timer expressed as a string
      * @return {string} */
     toString() { return this.isSet() ? abs(this.get()) + ' seconds ' + (this.get()<0 ? 'before' : 'after' ) : 'unset'; }
@@ -3991,7 +4007,7 @@ function drawTile(pos, size=new Vector2(1), tileInfo, color=WHITE,
     {
         // normal canvas 2D rendering method (slower)
         ++drawCount;
-        size = new Vector2(size.x, -size.y); // fix upside down sprites
+        size = new Vector2(size.x, -size.y); // flip upside down sprites
         drawCanvas2D(pos, size, angle, mirror, (context)=>
         {
             if (textureInfo)
@@ -6882,6 +6898,9 @@ class ParticleEmitter extends EngineObject
         this.previousPos = this.pos.copy();
     }
 
+    /** Emitters do not have physics */
+    updatePhysics() {}
+
     /** Update the emitter to spawn particles, called automatically by engine once each frame */
     update()
     {
@@ -8735,11 +8754,16 @@ class UISystemPlugin
             // reset hover object at start of update
             uiSystem.lastHoverObject = uiSystem.hoverObject;
             uiSystem.hoverObject = undefined;
+
+            // update in reverse order so topmost objects get priority
             for (let i = uiSystem.uiObjects.length; i--;)
             {
                 const o = uiSystem.uiObjects[i];
                 o.parent || updateObject(o)
             }
+
+            // remove destroyed objects
+            uiSystem.uiObjects = uiSystem.uiObjects.filter(o=>!o.destroyed);
         }
         function uiRender()
         {
@@ -8909,6 +8933,15 @@ class UISystemPlugin
         p.x -= sInv*mainCanvasSize.x/2;
         return p;
     }
+
+    /** Destroy and remove all objects
+    *  @memberof Engine */
+    destroyObjects()
+    {
+        for (const o of this.uiObjects)
+            o.parent || o.destroy();
+        this.uiObjects = this.uiObjects.filter(o=>!o.destroyed);
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -9010,6 +9043,22 @@ class UIObject
         child.parent = undefined;
     }
 
+
+    /** Destroy this object, destroy its children, detach its parent, and mark it for removal */
+    destroy()
+    {
+        if (this.destroyed)
+            return;
+
+        // disconnect from parent and destroy children
+        this.destroyed = 1;
+        this.parent && this.parent.removeChild(this);
+        for (const child of this.children)
+        {
+            child.parent = 0;
+            child.destroy();
+        }
+    }
     /** Check if the mouse is overlapping a box in screen space
      *  @return {boolean} - True if overlapping
      */
@@ -9389,6 +9438,150 @@ class UIScrollbar extends UIObject
         uiSystem.drawText(this.text, this.pos, textSize, 
             this.textColor, 0, undefined, this.align, this.font, this.fontStyle, true, this.textShadow);
     }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/** 
+ * 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
+ */
+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, size, src, autoplay=false, loop=false, volume=1)
+    {
+        super(pos, size || vec2());
+        
+        ASSERT(isString(src), 'video src must be a string');
+        ASSERT(isNumber(volume), 'video volume must be a number');
+
+        this.color = BLACK; // default to black background
+        this.cornerRadius = 0; // default to no corner radius
+
+        /** @property {float} - The video volume */
+        this.volume = volume;
+
+        // create video element
+        /** @property {HTMLVideoElement} - The video player */
+        this.video = document.createElement('video');
+        this.video.loop = loop;
+        this.video.volume = clamp(volume * soundVolume);
+        this.video.muted = !soundEnable;
+        this.video.style.display = 'none';
+        this.video.src = src;
+        document.body.appendChild(this.video);
+        autoplay && this.play();
+    }
+    
+    /** Play or resume the video
+     *  @return {Promise} Promise that resolves when playback starts */
+    play()
+    {
+        // try to play the video, catch any errors (autoplay may be blocked)
+        const promise = this.video.play();
+        promise?.catch(()=>{});
+        return promise;
+    }
+    
+    /** Pause the video */
+    pause() { this.video.pause(); }
+    
+    /** Stop and reset the video */
+    stop() { this.video.pause(); this.video.currentTime = 0; }
+    
+    /** Check if video is currently loading
+     *  @return {boolean} */
+    isLoadng()
+    { return this.video.readyState < this.video.HAVE_CURRENT_DATA; }
+    
+    /** Check if video is currently paused
+     *  @return {boolean} */
+    isPaused() { return this.video.paused; }
+    
+    /** Check if video is currently playing
+     *  @return {boolean} */
+    isPlaying()
+    { return !this.isPaused() && !this.hasEnded() && !this.isLoadng(); }
+    
+    /** Check if video has ended playing
+     *  @return {boolean} */
+    hasEnded() { return this.video.ended; }
+    
+    /** Set volume (0-1)
+     *  @param {number} volume - Volume level (0-1) */
+    setVolume(volume)
+    {
+        this.volume = volume;
+        this.video.volume = clamp(volume * soundVolume);
+    }
+    
+    /** Set playback speed
+     *  @param {number} rate - Playback rate multiplier */
+    setPlaybackRate(rate) { this.video.playbackRate = rate; }
+    
+    /** Get current time in seconds
+     *  @return {number} Current playback time */
+    getCurrentTime() { return this.video.currentTime || 0; }
+    
+    /** Get duration in seconds
+     *  @return {number} Total video duration */
+    getDuration() { return this.video.duration || 0; }
+    
+    /** Get the native video dimensions 
+     *  @return {Vector2} Video dimensions (may be 0,0 if metadata not loaded) */
+    getVideoSize()
+    { return vec2(this.video.videoWidth, this.video.videoHeight); }
+    
+    /** Seek to time in seconds
+     *  @param {number} time - Time in seconds to seek to */
+    setTime(time)
+    { this.video.currentTime = clamp(time, 0, this.getDuration()); }
+
+    update()
+    {
+        super.update();
+
+        // update volume based on global sound volume
+        this.video.volume = clamp(this.volume * soundVolume);
+    }
+    
+    /** Render video to UI canvas */
+    render()
+    {
+        super.render();
+
+        if (this.isLoadng())
+            return;
+        const context = uiSystem.uiContext;
+        const s = this.size;
+        context.save();
+        context.translate(this.pos.x, this.pos.y);
+        context.drawImage(this.video, -s.x/2, -s.y/2, s.x, s.y);
+        context.restore();
+    }
+    
+    /** Clean up video on destroy */
+    destroy()
+    {
+        if (this.destroyed)
+            return;
+
+        this.video.pause();
+        this.video.remove();
+        super.destroy();
+    }
 }
 /**
  * LittleJS Box2D Physics Plugin
@@ -11819,6 +12012,7 @@ export
     UIButton,
     UICheckbox,
     UIScrollbar,
+    UIVideo,
 
     // Box2D Physics
     box2d,