littlejsengine 1.14.23 → 1.15.2

package/plugins/uiSystem.js

@@ -108,11 +108,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()
         {
@@ -145,12 +150,12 @@ class UISystemPlugin
     /** 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] */
-    drawRect(pos, size, color=uiSystem.defaultColor, lineWidth=uiSystem.defaultLineWidth, lineColor=uiSystem.defaultLineColor, cornerRadius=uiSystem.defaultCornerRadius, gradientColor=uiSystem.defaultGradientColor)
+    *  @param {Color}   [color]
+    *  @param {number}  [lineWidth]
+    *  @param {Color}   [lineColor]
+    *  @param {number}  [cornerRadius]
+    *  @param {Color}   [gradientColor] */
+    drawRect(pos, size, color=WHITE, lineWidth=0, lineColor=BLACK, cornerRadius=0, gradientColor)
     {
         ASSERT(isVector2(pos), 'pos must be a vec2');
         ASSERT(isVector2(size), 'size must be a vec2');
@@ -229,10 +234,14 @@ class UISystemPlugin
     *  @param {string}  [align]
     *  @param {string}  [font=uiSystem.defaultFont]
     *  @param {string}  [fontStyle]
-    *  @param {boolean} [applyMaxWidth=true] */
-    drawText(text, pos, size, color=uiSystem.defaultColor, lineWidth=uiSystem.defaultLineWidth, lineColor=uiSystem.defaultLineColor, align='center', font=uiSystem.defaultFont, fontStyle='', applyMaxWidth=true)
+    *  @param {boolean} [applyMaxWidth=true]
+    *  @param {Vector2} [textShadow]
+     */
+    drawText(text, pos, size, color=uiSystem.defaultColor, lineWidth=uiSystem.defaultLineWidth, lineColor=uiSystem.defaultLineColor, align='center', font=uiSystem.defaultFont, fontStyle='', applyMaxWidth=true, textShadow=undefined)
     {
-        drawTextScreen(text, pos, size.y, color, lineWidth, lineColor, align, font, fontStyle, applyMaxWidth ? size.x : undefined, uiSystem.uiContext);
+        if (textShadow)
+            drawTextScreen(text, pos.add(textShadow), size.y, BLACK, lineWidth, lineColor, align, font, fontStyle, applyMaxWidth ? size.x : undefined, 0, uiSystem.uiContext);
+        drawTextScreen(text, pos, size.y, color, lineWidth, lineColor, align, font, fontStyle, applyMaxWidth ? size.x : undefined, 0, uiSystem.uiContext);
     }
 
     /**
@@ -259,6 +268,34 @@ class UISystemPlugin
         setCallback(onDragLeave, 'dragleave');
         setCallback(onDragOver,  'dragover');
     }
+
+    /** Convert a screen space position to native UI position
+     *  @param {Vector2} pos
+     *  @return {Vector2}
+     */
+    screenToNative(pos)
+    {
+        if (!uiSystem.nativeHeight)
+            return pos;
+    
+        const s = mainCanvasSize.y / uiSystem.nativeHeight;
+        const sInv = 1/s;
+        const p = pos.copy();
+        p.x += s*mainCanvasSize.x/2;
+        p.x *= sInv;
+        p.y *= sInv;
+        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);
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -335,6 +372,9 @@ class UIObject
         /** @property {boolean} - True if this can be a hover object */
         this.canBeHover = true;
         uiSystem.uiObjects.push(this);
+        
+        /** @property {Vector2} - How much to offset the text shadow or undefined */
+        this.textShadow = undefined;
     }
 
     /** Add a child UIObject to this object
@@ -357,29 +397,41 @@ 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
      */
     isMouseOverlapping()
     {
+        if (!mouseInWindow) return false;
+
         const size = !isTouchDevice ? this.size :
                 this.size.add(vec2(this.extraTouchSize || 0));
-        if (!uiSystem.nativeHeight)
-            return isOverlapping(this.pos, size, mousePosScreen);
-
-        const s = mainCanvasSize.y / uiSystem.nativeHeight;
-        const sInv = 1/s;
-        let pos = mousePosScreen.copy();
-        pos.x += s*mainCanvasSize.x/2;
-        pos.x *= sInv;
-        pos.y *= sInv;
-        pos.x -= sInv*mainCanvasSize.x/2;
+        const pos = uiSystem.screenToNative(mousePosScreen);
         return isOverlapping(this.pos, size, pos);
     }
 
     /** Update the object, called automatically by plugin once each frame */
     update()
     {
+        // call the custom update callback
+        this.onUpdate();
+
         const wasHover = uiSystem.lastHoverObject === this;
         const isActive = this.isActiveObject();
         const mouseDown = mouseIsDown(0);
@@ -436,7 +488,7 @@ class UIObject
 
         const lineColor = this.interactive && this.isActiveObject() && !this.disabled ? this.color : this.lineColor;
         const color = this.disabled ? this.disabledColor : this.interactive ? this.isActiveObject() ? this.activeColor || this.color : this.isHoverObject() ? this.hoverColor : this.color : this.color;
-        uiSystem.drawRect(this.pos, this.size, color, this.lineWidth, lineColor, this.cornerRadius);
+        uiSystem.drawRect(this.pos, this.size, color, this.lineWidth, lineColor, this.cornerRadius, this.gradientColor);
     }
 
     /** Special update when object is not visible */
@@ -463,6 +515,9 @@ class UIObject
     /** @return {boolean} - Is the mouse held onto this element */
     isActiveObject() { return uiSystem.activeObject === this; }
 
+    /** Called each frame when object updates */
+    onUpdate() {}
+
     /** Called when the mouse enters the object */
     onEnter() {}
 
@@ -517,8 +572,9 @@ class UIText extends UIObject
     }
     render()
     {
+        // only render the text
         const textSize = this.getTextSize();
-        uiSystem.drawText(this.text, this.pos, textSize, this.textColor, this.lineWidth, this.lineColor, this.align, this.font, this.fontStyle);
+        uiSystem.drawText(this.text, this.pos, textSize, this.textColor, this.lineWidth, this.lineColor, this.align, this.font, this.fontStyle, true, this.textShadow);
     }
 }
 
@@ -594,7 +650,7 @@ class UIButton extends UIObject
         // draw the text scaled to fit
         const textSize = this.getTextSize();
         uiSystem.drawText(this.text, this.pos, textSize, 
-            this.textColor, 0, undefined, this.align, this.font, this.fontStyle);
+            this.textColor, 0, undefined, this.align, this.font, this.fontStyle, true, this.textShadow);
     }
 }
 
@@ -648,7 +704,7 @@ class UICheckbox extends UIObject
         const textSize = this.getTextSize();
         const pos = this.pos.add(vec2(this.size.x,0));
         uiSystem.drawText(this.text, pos, textSize, 
-            this.textColor, 0, undefined, 'left', this.font, this.fontStyle, false);
+            this.textColor, 0, undefined, 'left', this.font, this.fontStyle, false, this.textShadow);
     }
 }
 
@@ -703,9 +759,11 @@ class UIScrollbar extends UIObject
             const p1 = centerPos - handleWidth/2;
             const p2 = centerPos + handleWidth/2;
             const oldValue = this.value;
+
+            const p = uiSystem.screenToNative(mousePosScreen);
             this.value = isHorizontal ? 
-                percent(mousePosScreen.x, p1, p2) :
-                percent(mousePosScreen.y, p2, p1);
+                percent(p.x, p1, p2) :
+                percent(p.y, p2, p1);
             this.value === oldValue || this.onChange();
         }
     }
@@ -727,11 +785,155 @@ class UIScrollbar extends UIObject
             vec2(lerp(p1, p2, this.value), this.pos.y) :
             vec2(this.pos.x, lerp(p2, p1, this.value))
         const handleColor = this.disabled ? this.disabledColor : this.handleColor;
-        uiSystem.drawRect(handlePos, vec2(handleSize), handleColor, this.lineWidth, this.lineColor, this.cornerRadius);
+        uiSystem.drawRect(handlePos, vec2(handleSize), handleColor, this.lineWidth, this.lineColor, this.cornerRadius, this.gradientColor);
 
         // draw the text scaled to fit on the scrollbar
         const textSize = this.getTextSize();
         uiSystem.drawText(this.text, this.pos, textSize, 
-            this.textColor, 0, undefined, this.align, this.font, this.fontStyle);
+            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();
     }
 }

package/src/engine.js

@@ -30,7 +30,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.14.24';
+const engineVersion = '1.15.2';
 
 /** Frames per second to update
  *  @type {number}
@@ -131,7 +131,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
  */
 /**
@@ -161,7 +161,7 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored)
 async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources=[], rootElement=document.body)
 {
     ASSERT(!mainContext, 'engine already initialized');
-    ASSERT(Array.isArray(imageSources), 'pass in images as array');
+    ASSERT(isArray(imageSources), 'pass in images as array');
 
     // allow passing in empty functions
     gameInit       ||= ()=>{};
@@ -453,21 +453,24 @@ function engineObjectsUpdate()
     // recursive object update
     function updateObject(o)
     {
-        if (!o.destroyed)
-        {
-            o.update();
-            for (const child of o.children)
-                updateObject(child);
-        }
+        if (o.destroyed)
+            return;
+
+        o.update();
+        for (const child of o.children)
+            updateObject(child);
     }
     for (const o of engineObjects)
     {
+        if (o.parent)
+            continue;
+
         // update top level objects
-        if (!o.parent)
-        {
-            updateObject(o);
-            o.updateTransforms();
-        }
+        o.update();
+        o.updatePhysics();
+        for (const child of o.children)
+            updateObject(child);
+        o.updateTransforms();
     }
 
     // remove destroyed objects
@@ -484,10 +487,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)
 {
@@ -500,7 +503,7 @@ function engineObjectsCollect(pos, size, objects=engineObjects)
     else if (size instanceof Vector2)  // bounding box test
     {
         for (const o of objects)
-            isOverlapping(pos, size, o.pos, o.size) && collectedObjects.push(o);
+            o.isOverlapping(pos, size) && collectedObjects.push(o);
     }
     else  // circle test
     {

package/src/engineAudio.js

@@ -66,6 +66,10 @@ class Sound
     {
         if (!soundEnable || headlessMode) return;
 
+        ASSERT(!zzfxSound || isArray(zzfxSound), 'zzfxSound is invalid');
+        ASSERT(isNumber(range), 'range must be a number');
+        ASSERT(isNumber(taper), 'taper must be a number');
+
         /** @property {number} - World space max range of sound */
         this.range = range;
         /** @property {number} - At what percentage of range should it start tapering */
@@ -104,6 +108,12 @@ class Sound
      */
     play(pos, volume=1, pitch=1, randomnessScale=1, loop=false, paused=false)
     {
+        ASSERT(!pos || isVector2(pos), 'pos must be a vec2');
+        ASSERT(isNumber(volume), 'volume must be a number');
+        ASSERT(isNumber(pitch), 'pitch must be a number');
+        ASSERT(isNumber(randomnessScale), 'randomnessScale must be a number');
+
+
         if (!soundEnable || headlessMode) return;
         if (!this.sampleChannels) return;
 
@@ -149,6 +159,7 @@ class Sound
      */
     playNote(semitoneOffset=0, pos, volume)
     {
+        ASSERT(isNumber(semitoneOffset), 'semitoneOffset must be a number');
         const pitch = getNoteFrequency(semitoneOffset, 1);
         return this.play(pos, volume, pitch, 0);
     }
@@ -157,7 +168,7 @@ class Sound
      *  @return {number} - How long the sound is in seconds (undefined if loading)
      */
     getDuration()
-    { return this.sampleChannels && this.sampleChannels[0].length / this.sampleRate; }
+    { return this.sampleChannels && this.sampleRate ? this.sampleChannels[0].length / this.sampleRate : 0; }
 
     /** Check if sound is loaded, for sounds fetched from a url
      *  @return {boolean} - True if sound is loaded and ready to play
@@ -199,6 +210,7 @@ class SoundWave extends Sound
         super(undefined, range, taper);
         if (!soundEnable || headlessMode) return;
         ASSERT(!filename || isString(filename), 'filename must be a string');
+        ASSERT(isNumber(randomness), 'randomness must be a number');
 
         /** @property {SoundLoadCallback} - callback function to call when sound is loaded */
         this.onloadCallback = onloadCallback;
@@ -415,7 +427,7 @@ class SoundInstance
     /** Get the total duration of this sound
      *  @return {number} - Total duration in seconds
      */
-    getDuration() { return this.sound.getDuration() / this.rate; }
+    getDuration() { return this.rate ? this.sound.getDuration() / this.rate : 0; }
 
     /** Get source of this sound instance
      *  @return {AudioBufferSourceNode}

package/src/engineDebug.js

@@ -73,6 +73,12 @@ function LOG(...output) { console.log(...output); }
  *  @memberof Debug */
 function debugRect(pos, size=vec2(), color=WHITE, time=0, angle=0, fill=false)
 {
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isVector2(size), 'size must be a vec2');
+    ASSERT(isString(color) || isColor(color), 'color is invalid');
+    ASSERT(isNumber(time), 'time must be a number');
+    ASSERT(isNumber(angle), 'angle must be a number');
+
     if (typeof size === 'number')
         size = vec2(size); // allow passing in floats
     if (isColor(color))
@@ -93,6 +99,12 @@ function debugRect(pos, size=vec2(), color=WHITE, time=0, angle=0, fill=false)
  *  @memberof Debug */
 function debugPoly(pos, points, color=WHITE, time=0, angle=0, fill=false)
 {
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isArray(points), 'points must be an array');
+    ASSERT(isString(color) || isColor(color), 'color is invalid');
+    ASSERT(isNumber(time), 'time must be a number');
+    ASSERT(isNumber(angle), 'angle must be a number');
+
     if (isColor(color))
         color = color.toString();
     pos = pos.copy();
@@ -110,6 +122,11 @@ function debugPoly(pos, points, color=WHITE, time=0, angle=0, fill=false)
  *  @memberof Debug */
 function debugCircle(pos, size=0, color=WHITE, time=0, fill=false)
 {
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isNumber(size), 'size must be a number');
+    ASSERT(isString(color) || isColor(color), 'color is invalid');
+    ASSERT(isNumber(time), 'time must be a number');
+
     if (isColor(color))
         color = color.toString();
     pos = pos.copy();
@@ -135,6 +152,10 @@ function debugPoint(pos, color, time, angle)
  *  @memberof Debug */
 function debugLine(posA, posB, color, width=.1, time)
 {
+    ASSERT(isVector2(posA), 'posA must be a vec2');
+    ASSERT(isVector2(posB), 'posB must be sa vec2');
+    ASSERT(isNumber(width), 'width must be a number');
+
     const halfDelta = vec2((posB.x - posA.x)/2, (posB.y - posA.y)/2);
     const size = vec2(width, halfDelta.length()*2);
     debugRect(posA.add(halfDelta), size, color, time, halfDelta.angle(), true);
@@ -149,6 +170,11 @@ function debugLine(posA, posB, color, width=.1, time)
  *  @memberof Debug */
 function debugOverlap(posA, sizeA, posB, sizeB, color)
 {
+    ASSERT(isVector2(posA), 'posA must be a vec2');
+    ASSERT(isVector2(posB), 'posB must be a vec2');
+    ASSERT(isVector2(sizeA), 'sizeA must be a vec2');
+    ASSERT(isVector2(sizeB), 'sizeB must be a vec2');
+
     const minPos = vec2(
         min(posA.x - sizeA.x/2, posB.x - sizeB.x/2),
         min(posA.y - sizeA.y/2, posB.y - sizeB.y/2)
@@ -171,6 +197,14 @@ function debugOverlap(posA, sizeA, posB, sizeB, color)
  *  @memberof Debug */
 function debugText(text, pos, size=1, color=WHITE, time=0, angle=0, font='monospace')
 {
+    ASSERT(isString(text), 'text must be a string');
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isNumber(size), 'size must be a number');
+    ASSERT(isString(color) || isColor(color), 'color is invalid');
+    ASSERT(isNumber(time), 'time must be a number');
+    ASSERT(isNumber(angle), 'angle must be a number');
+    ASSERT(isString(font), 'font must be a string');
+
     if (isColor(color))
         color = color.toString();
     pos = pos.copy();
@@ -624,6 +658,9 @@ function debugVideoCaptureUpdate()
     debugVideoCaptureIcon.textContent = '● REC ' + formatTime(debugVideoCaptureTimer);
 }
 
+///////////////////////////////////////////////////////////////////////////////
+// debug utility functions
+
 // make color constants immutable with debug assertions
 function debugProtectConstant(obj)
 {