littlejsengine 1.9.6 → 1.9.8

package/dist/littlejs.js

@@ -80,6 +80,20 @@ function debugRect(pos, size=vec2(), color='#fff', time=0, angle=0, fill=false)
     debugPrimitives.push({pos, size:vec2(size), color, time:new Timer(time), angle, fill});
 }
 
+/** Draw a debug poly in world space
+ *  @param {Vector2} pos
+ *  @param {Array}   points
+ *  @param {String}  [color]
+ *  @param {Number}  [time]
+ *  @param {Number}  [angle]
+ *  @param {Boolean} [fill]
+ *  @memberof Debug */
+function debugPoly(pos, points, color='#fff', time=0, angle=0, fill=false)
+{
+    ASSERT(typeof color == 'string', 'pass in css color strings'); 
+    debugPrimitives.push({pos, points, color, time:new Timer(time), angle, fill});
+}
+
 /** Draw a debug circle in world space
  *  @param {Vector2} pos
  *  @param {Number}  [radius]
@@ -89,7 +103,7 @@ function debugRect(pos, size=vec2(), color='#fff', time=0, angle=0, fill=false)
  *  @memberof Debug */
 function debugCircle(pos, radius=0, color='#fff', time=0, fill=false)
 {
-    ASSERT(typeof color == 'string', 'pass in css color strings');
+    ASSERT(typeof color == 'string', 'pass in css color strings'); 
     debugPrimitives.push({pos, size:radius, color, time:new Timer(time), angle:0, fill});
 }
 
@@ -99,7 +113,11 @@ function debugCircle(pos, radius=0, color='#fff', time=0, fill=false)
  *  @param {Number}  [time]
  *  @param {Number}  [angle]
  *  @memberof Debug */
-function debugPoint(pos, color, time, angle) {debugRect(pos, undefined, color, time, angle);}
+function debugPoint(pos, color, time, angle)
+{
+    ASSERT(typeof color == 'string', 'pass in css color strings'); 
+    debugRect(pos, undefined, color, time, angle);
+}
 
 /** Draw a debug line in world space
  *  @param {Vector2} posA
@@ -110,19 +128,20 @@ function debugPoint(pos, color, time, angle) {debugRect(pos, undefined, color, t
  *  @memberof Debug */
 function debugLine(posA, posB, color, thickness=.1, time)
 {
+    ASSERT(typeof color == 'string', 'pass in css color strings'); 
     const halfDelta = vec2((posB.x - posA.x)/2, (posB.y - posA.y)/2);
     const size = vec2(thickness, halfDelta.length()*2);
     debugRect(posA.add(halfDelta), size, color, time, halfDelta.angle(), true);
 }
 
-/** Draw a debug axis aligned bounding box in world space
+/** Draw a debug combined axis aligned bounding box in world space
  *  @param {Vector2} pA - position A
  *  @param {Vector2} sA - size A
  *  @param {Vector2} pB - position B
  *  @param {Vector2} sB - size B
  *  @param {String}  [color]
  *  @memberof Debug */
-function debugAABB(pA, sA, pB, sB, color)
+function debugOverlap(pA, sA, pB, sB, color)
 {
     const minPos = vec2(min(pA.x - sA.x/2, pB.x - sB.x/2), min(pA.y - sA.y/2, pB.y - sB.y/2));
     const maxPos = vec2(max(pA.x + sA.x/2, pB.x + sB.x/2), max(pA.y + sA.y/2, pB.y + sB.y/2));
@@ -140,7 +159,7 @@ function debugAABB(pA, sA, pB, sB, color)
  *  @memberof Debug */
 function debugText(text, pos, size=1, color='#fff', time=0, angle=0, font='monospace')
 {
-    ASSERT(typeof color == 'string', 'pass in css color strings');
+    ASSERT(typeof color == 'string', 'pass in css color strings'); 
     debugPrimitives.push({text, pos, size, color, time:new Timer(time), angle, font});
 }
 
@@ -239,7 +258,7 @@ function debugRender()
                 const stickScale = 1;
                 const buttonScale = .2;
                 const centerPos = cameraPos;
-                const sticks = stickData[i];
+                const sticks = gamepadStickData[i];
                 for (let j = sticks.length; j--;)
                 {
                     const drawPos = centerPos.add(vec2(j*stickScale*2, i*stickScale*3));
@@ -259,6 +278,7 @@ function debugRender()
         }
     }
 
+    let debugObject;
     if (debugOverlay)
     {
         const saveContext = mainContext;
@@ -269,11 +289,13 @@ function debugRender()
         debugRect(cameraPos, cameraSize.subtract(vec2(.1)), '#f008');
 
         // mouse pick
-        let bestDistance = Infinity, bestObject;
+        let bestDistance = Infinity;
         for (const o of engineObjects)
         {
             if (o.canvas || o.destroyed)
                 continue;
+
+            o.renderDebugInfo();
             if (!o.size.x || !o.size.y)
                 continue;
 
@@ -281,33 +303,15 @@ function debugRender()
             if (distance < bestDistance)
             {
                 bestDistance = distance;
-                bestObject = o;
+                debugObject = o;
             }
-
-            // show object info
-            const size = vec2(max(o.size.x, .2), max(o.size.y, .2));
-            const color1 = new Color(o.collideTiles?1:0, o.collideSolidObjects?1:0, o.isSolid?1:0, o.parent?.2:.5);
-            const color2 = o.parent ? new Color(1,1,1,.5) : new Color(0,0,0,.8);
-            drawRect(o.pos, size, color1, o.angle, false);
-            drawRect(o.pos, size.scale(.8), color2, o.angle, false);
-            o.parent && drawLine(o.pos, o.parent.pos, .1, new Color(0,0,1,.5), false);
-        }
-        
-        if (bestObject)
-        {
-            const raycastHitPos = tileCollisionRaycast(bestObject.pos, mousePos);
-            raycastHitPos && drawRect(raycastHitPos.floor().add(vec2(.5)), vec2(1), new Color(0,1,1,.3));
-            drawRect(mousePos.floor().add(vec2(.5)), vec2(1), new Color(0,0,1,.5), 0, false);
-            drawLine(mousePos, bestObject.pos, .1, raycastHitPos ? new Color(1,0,0,.5) : new Color(0,1,0,.5), false);
-
-            const debugText = 'mouse pos = ' + mousePos + 
-                '\nmouse collision = ' + getTileCollisionData(mousePos) + 
-                '\n\n--- object info ---\n' +
-                bestObject.toString();
-            drawTextScreen(debugText, mousePosScreen, 24, new Color, .05, undefined, 'center', 'monospace');
         }
 
-        glCopyToContext(mainContext = saveContext);
+        if (tileCollisionSize.x > 0 && tileCollisionSize.y > 0)
+            drawRect(mousePos.floor().add(vec2(.5)), vec2(1), rgb(0,0,1,.5), 0, false);
+        mainContext = saveContext;
+
+        //glCopyToContext(mainContext = saveContext);
     }
 
     {
@@ -322,6 +326,7 @@ function debugRender()
             const pos = worldToScreen(p.pos);
             overlayContext.translate(pos.x|0, pos.y|0);
             overlayContext.rotate(p.angle);
+            overlayContext.scale(1, -1);
             overlayContext.fillStyle = overlayContext.strokeStyle = p.color;
 
             if (p.text != undefined)
@@ -331,7 +336,20 @@ function debugRender()
                 overlayContext.textBaseline = 'middle';
                 overlayContext.fillText(p.text, 0, 0);
             }
-            else if (p.size == 0 || p.size.x === 0 && p.size.y === 0 )
+            else if (p.points != undefined)
+            {
+                // poly
+                overlayContext.beginPath();
+                for (const point of p.points)
+                {
+                    const p2 = point.scale(cameraScale).floor();
+                    overlayContext.lineTo(p2.x, p2.y);
+                }
+                overlayContext.closePath();
+                p.fill && overlayContext.fill();
+                overlayContext.stroke();
+            }
+            else if (p.size == 0 || p.size.x === 0 && p.size.y === 0)
             {
                 // point
                 overlayContext.fillRect(-pointSize/2, -1, pointSize, 3);
@@ -340,7 +358,8 @@ function debugRender()
             else if (p.size.x != undefined)
             {
                 // rect
-                const w = p.size.x*cameraScale|0, h = p.size.y*cameraScale|0;
+                const s = p.size.scale(cameraScale).floor();
+                const w = s.x, h = s.y;
                 p.fill && overlayContext.fillRect(-w/2|0, -h/2|0, w, h);
                 overlayContext.strokeRect(-w/2|0, -h/2|0, w, h);
             }
@@ -359,6 +378,22 @@ function debugRender()
         // remove expired primitives
         debugPrimitives = debugPrimitives.filter(r=>r.time<0);
     }
+    
+    if (debugObject)
+    {
+        const saveContext = mainContext;
+        mainContext = overlayContext;
+        const raycastHitPos = tileCollisionRaycast(debugObject.pos, mousePos);
+        raycastHitPos && drawRect(raycastHitPos.floor().add(vec2(.5)), vec2(1), rgb(0,1,1,.3));
+        drawLine(mousePos, debugObject.pos, .1, raycastHitPos ? rgb(1,0,0,.5) : rgb(0,1,0,.5), false);
+
+        const debugText = 'mouse pos = ' + mousePos + 
+            '\nmouse collision = ' + getTileCollisionData(mousePos) + 
+            '\n\n--- object info ---\n' +
+            debugObject.toString();
+        drawTextScreen(debugText, mousePosScreen, 24, rgb(), .05, undefined, 'center', 'monospace');
+        mainContext = saveContext;
+    }
 
     {
         // draw debug overlay
@@ -721,7 +756,7 @@ class RandomGenerator
  */
 function vec2(x=0, y)
 {
-    return typeof x === 'number' ? 
+    return typeof x == 'number' ? 
         new Vector2(x, y == undefined? x : y) : 
         new Vector2(x.x, x.y);
 }
@@ -750,13 +785,19 @@ class Vector2
      *  @param {Number} [y] - Y axis location */
     constructor(x=0, y=0)
     {
-        ASSERT(typeof x === 'number' && typeof y === 'number');
+        ASSERT(typeof x == 'number' && typeof y == 'number');
         /** @property {Number} - X axis location */
         this.x = x;
         /** @property {Number} - Y axis location */
         this.y = y;
     }
 
+    /** Sets values of this vector and returns self
+     *  @param {Number} [x] - X axis location
+     *  @param {Number} [y] - Y axis location
+     *  @return {Vector2} */
+    set(x=0, y=0) { this.x=x; this.y=y; return this; }
+
     /** Returns a new vector that is a copy of this
      *  @return {Vector2} */
     copy() { return new Vector2(this.x, this.y); }
@@ -1008,6 +1049,15 @@ class Color
         this.a = a;
     }
 
+    /** Sets values of this color and returns self
+     *  @param {Number} [r] - red
+     *  @param {Number} [g] - green
+     *  @param {Number} [b] - blue
+     *  @param {Number} [a] - alpha
+     *  @return {Color} */
+    set(r=1, g=1, b=1, a=1)
+    { this.r=r; this.g=g; this.b=b; this.a=a; return this; }
+
     /** Returns a new color that is a copy of this
      * @return {Color} */
     copy() { return new Color(this.r, this.g, this.b, this.a); }
@@ -1135,14 +1185,15 @@ class Color
         ).clamp();
     }
 
-    /** Returns this color expressed as a rgb color code
+    /** Returns this color expressed as a hex color code
      * @param {Boolean} [useAlpha] - if alpha should be included in result
      * @return {String} */
-    toString(useAlpha = true)
-    {
-        return `rgb(${this.r*255},${this.g*255},${this.b*255},${useAlpha ? this.a : 0})`;
+    toString(useAlpha = true)      
+    { 
+        const toHex = (c)=> ((c=c*255|0)<16 ? '0' : '') + c.toString(16);
+        return '#' + toHex(this.r) + toHex(this.g) + toHex(this.b) + (useAlpha ? toHex(this.a) : '');
     }
-
+    
     /** Set this color from a hex code
      * @param {String} hex - html hex code
      * @return {Color} */
@@ -1168,6 +1219,64 @@ class Color
     }
 }
 
+///////////////////////////////////////////////////////////////////////////////
+// default colors
+
+/** Color - White
+ *  @type {Color}
+ *  @memberof Utilities */
+const WHITE = rgb();
+
+/** Color - Black
+ *  @type {Color}
+ *  @memberof Utilities */
+const BLACK = rgb(0,0,0);
+
+/** Color - Gray
+ *  @type {Color}
+ *  @memberof Utilities */
+const GRAY = rgb(.5,.5,.5);
+
+/** Color - Red
+ *  @type {Color}
+ *  @memberof Utilities */
+const RED = rgb(1,0,0);
+
+/** Color - Orange
+ *  @type {Color}
+ *  @memberof Utilities */
+const ORANGE = rgb(1,.5,0);
+
+/** Color - Yellow
+ *  @type {Color}
+ *  @memberof Utilities */
+const YELLOW = rgb(1,1,0);
+
+/** Color - Green
+ *  @type {Color}
+ *  @memberof Utilities */
+const GREEN = rgb(0,1,0);
+
+/** Color - Cyan
+ *  @type {Color}
+ *  @memberof Utilities */
+const CYAN = rgb(0,1,1);
+
+/** Color - Blue
+ *  @type {Color}
+ *  @memberof Utilities */
+const BLUE = rgb(0,0,1);
+
+/** Color - Purple
+ *  @type {Color}
+ *  @memberof Utilities */
+const PURPLE = rgb(.5,0,1);
+
+/** Color - Magenta
+ *  @type {Color}
+ *  @memberof Utilities */
+const MAGENTA = rgb(1,0,1);
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -1248,9 +1357,9 @@ let cameraScale = 32;
 
 /** The max size of the canvas, centered if window is larger
  *  @type {Vector2}
- *  @default Vector2(1920,1200)
+ *  @default Vector2(1920,1080)
  *  @memberof Settings */
-let canvasMaxSize = vec2(1920, 1200);
+let canvasMaxSize = vec2(1920, 1080);
 
 /** 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
@@ -1639,7 +1748,12 @@ function setSoundEnable(enable) { soundEnable = enable; }
 /** Set volume scale to apply to all sound, music and speech
  *  @param {Number} volume
  *  @memberof Settings */
-function setSoundVolume(volume) { soundVolume = volume; }
+function setSoundVolume(volume)
+{
+    soundVolume = volume;
+    if (soundEnable && !headlessMode && audioGainNode)
+        audioGainNode.gain.value = volume; // update gain immediatly
+}
 
 /** Set default range where sound no longer plays
  *  @param {Number} range
@@ -1772,6 +1886,8 @@ class EngineObject
         this.spawnTime = time;
         /** @property {Array}   - List of children of this object */
         this.children = [];
+        /** @property {Boolean}  - Limit object speed using linear or circular math */
+        this.clampSpeedLinear = true;
 
         // parent child system
         /** @property {EngineObject} - Parent of object if in local space  */
@@ -1820,8 +1936,21 @@ class EngineObject
             return;
 
         // limit max speed to prevent missing collisions
-        this.velocity.x = clamp(this.velocity.x, -objectMaxSpeed, objectMaxSpeed);
-        this.velocity.y = clamp(this.velocity.y, -objectMaxSpeed, objectMaxSpeed);
+        if (this.clampSpeedLinear)
+        {
+            this.velocity.x = clamp(this.velocity.x, -objectMaxSpeed, objectMaxSpeed);
+            this.velocity.y = clamp(this.velocity.y, -objectMaxSpeed, objectMaxSpeed);
+        }
+        else
+        {
+            const length2 = this.velocity.lengthSquared();
+            if (length2 > objectMaxSpeed*objectMaxSpeed)
+            {
+                const s = objectMaxSpeed / length2**.5;
+                this.velocity.x *= s;
+                this.velocity.y *= s;
+            }
+        }
 
         // apply physics
         const oldPos = this.pos.copy();
@@ -1877,7 +2006,7 @@ class EngineObject
                     if (o.mass) // push away if not fixed
                         o.velocity = o.velocity.subtract(velocity);
                         
-                    debugOverlay && debugPhysics && debugAABB(this.pos, this.size, o.pos, o.size, '#f00');
+                    debugOverlay && debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f00');
                     continue;
                 }
 
@@ -1939,7 +2068,7 @@ class EngineObject
                     else // bounce if other object is fixed
                         this.velocity.x *= -elasticity;
                 }
-                debugOverlay && debugPhysics && debugAABB(this.pos, this.size, o.pos, o.size, '#f0f');
+                debugOverlay && debugPhysics && debugOverlap(this.pos, this.size, o.pos, o.size, '#f0f');
             }
         }
         if (this.collideTiles)
@@ -2000,6 +2129,22 @@ class EngineObject
         for (const child of this.children)
             child.destroy(child.parent = 0);
     }
+
+    /** Convert from local space to world space
+     *  @param {Vector2} pos - local space point */
+    localToWorld(pos) { return this.pos.add(pos.rotate(-this.angle)); }
+
+    /** Convert from world space to local space
+     *  @param {Vector2} pos - world space point */
+    worldToLocal(pos) { return pos.subtract(this.pos).rotate(this.angle); }
+
+    /** Convert from local space to world space for a vector (rotation only)
+     *  @param {Vector2} vec - local space vector */
+    localToWorldVector(vec) { return vec.rotate(this.angle); }
+
+    /** Convert from world space to local space for a vector (rotation only)
+     *  @param {Vector2} vec - world space vector */
+    worldToLocalVector(vec) { return vec.rotate(-this.angle); }
     
     /** Called to check if a tile collision should be resolved
      *  @param {Number}  tileData - the value of the tile at the position
@@ -2086,6 +2231,18 @@ class EngineObject
             return text;
         }
     }
+
+    /** Render debug info for this object  */
+    renderDebugInfo()
+    {
+        // show object info for debugging
+        const size = vec2(max(this.size.x, .2), max(this.size.y, .2));
+        const color1 = rgb(this.collideTiles?1:0, this.collideSolidObjects?1:0, this.isSolid?1:0, this.parent?.2:.5);
+        const color2 = this.parent ? rgb(1,1,1,.5) : rgb(0,0,0,.8);
+        drawRect(this.pos, size, color1, this.angle, false);
+        drawRect(this.pos, size.scale(.8), color2, this.angle, false);
+        this.parent && drawLine(this.pos, this.parent.pos, .1, rgb(0,0,1,.5), false);
+    }
 }
 /** 
  * LittleJS Drawing System
@@ -2409,7 +2566,7 @@ function drawCanvas2D(pos, size, angle, mirror, drawFunction, screenSpace, conte
     context.save();
     context.translate(pos.x+.5, pos.y+.5);
     context.rotate(angle);
-    context.scale(mirror ? -size.x : size.x, size.y);
+    context.scale(mirror ? -size.x : size.x, -size.y);
     drawFunction(context);
     context.restore();
 }
@@ -3104,6 +3261,32 @@ function touchGamepadRender()
 
 
 
+/** Audio context used by the engine
+ *  @type {AudioContext}
+ *  @memberof Audio */
+let audioContext;
+
+/** Master gain node for all audio to pass through
+ *  @type {GainNode}
+ *  @memberof Audio */
+let audioGainNode;
+
+function audioInit()
+{
+    if (!soundEnable || headlessMode) return;
+    
+    // create audio context
+    audioContext = new AudioContext;
+
+    // create and connect gain node
+    // (createGain is more widely spported then GainNode construtor)
+    audioGainNode = audioContext.createGain();
+    audioGainNode.connect(audioContext.destination);
+    setSoundVolume(soundVolume); // update gain volume
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
 /** 
  * Sound Object - Stores a sound for later use and can be played positionally
  * 
@@ -3155,7 +3338,8 @@ class Sound
      */
     play(pos, volume=1, pitch=1, randomnessScale=1, loop=false)
     {
-        if (!soundEnable || !this.sampleChannels || headlessMode) return;
+        if (!soundEnable || headlessMode) return;
+        if (!this.sampleChannels) return;
 
         let pan;
         if (pos)
@@ -3178,7 +3362,17 @@ class Sound
 
         // play the sound
         const playbackRate = pitch + pitch * this.randomness*randomnessScale*rand(-1,1);
-        return this.source = playSamples(this.sampleChannels, volume, playbackRate, pan, loop, this.sampleRate);
+        this.gainNode = audioContext.createGain();
+        return this.source = playSamples(this.sampleChannels, volume, playbackRate, pan, loop, this.sampleRate, this.gainNode);
+    }
+
+    /** Set the sound volume
+     *  @param {Number}  [volume] - How much to scale volume by
+     */
+    setVolume(volume=1)
+    {
+        if (this.gainNode)
+            this.gainNode.gain.value = volume;
     }
 
     /** Stop the last instance of this sound that was played */
@@ -3232,16 +3426,14 @@ class SoundWave extends Sound
      *  @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 {Function} [onloadCallback] - callback function to call when sound is loaded
      */
-    constructor(filename, randomness=0, range, taper)
+    constructor(filename, randomness=0, range, taper, onloadCallback)
     {
         super(undefined, range, taper);
-        this.randomness = randomness;
-
         if (!soundEnable || headlessMode) return;
-        if (!audioContext)
-            audioContext = new AudioContext; // create audio context
 
+        this.randomness = randomness;
         fetch(filename)
         .then(response => response.arrayBuffer())
         .then(arrayBuffer => audioContext.decodeAudioData(arrayBuffer))
@@ -3251,10 +3443,23 @@ class SoundWave extends Sound
             for (let i = audioBuffer.numberOfChannels; i--;)
                 this.sampleChannels[i] = Array.from(audioBuffer.getChannelData(i));
             this.sampleRate = audioBuffer.sampleRate;
-        });
+        }).then(() => onloadCallback && onloadCallback(this));
     }
 }
 
+/** Play an mp3, ogg, or wav audio from a local file or url
+ *  @param {String}  filename - Location of sound file to play
+ *  @param {Number}  [volume] - How much to scale volume by
+ *  @param {Boolean} [loop] - True if the music should loop
+ *  @return {SoundWave} - The sound object for this file
+ *  @memberof Audio */
+function playAudioFile(filename, volume=1, loop=false)
+{
+    if (!soundEnable || headlessMode) return;
+
+    return new SoundWave(filename,0,0,0, s=>s.play(undefined, volume, 1, 1, loop));
+}
+
 /**
  * Music Object - Stores a zzfx music track for later use
  * 
@@ -3309,23 +3514,6 @@ class Music extends Sound
     { return super.play(undefined, volume, 1, 1, loop); }
 }
 
-/** Play an mp3, ogg, or wav audio from a local file or url
- *  @param {String}  filename - Location of sound file to play
- *  @param {Number}  [volume] - How much to scale volume by
- *  @param {Boolean} [loop] - True if the music should loop
- *  @return {HTMLAudioElement} - The audio element for this sound
- *  @memberof Audio */
-function playAudioFile(filename, volume=1, loop=false)
-{
-    if (!soundEnable || headlessMode) return;
-
-    const audio = new Audio(filename);
-    audio.volume = soundVolume * volume;
-    audio.loop = loop;
-    audio.play();
-    return audio;
-}
-
 /** Speak text with passed in settings
  *  @param {String} text - The text to speak
  *  @param {String} [language] - The language/accent to use (examples: en, it, ru, ja, zh)
@@ -3336,7 +3524,8 @@ function playAudioFile(filename, volume=1, loop=false)
  *  @memberof Audio */
 function speak(text, language='', volume=1, rate=1, pitch=1)
 {
-    if (!soundEnable || !speechSynthesis || headlessMode) return;
+    if (!soundEnable || headlessMode) return;
+    if (!speechSynthesis) return;
 
     // common languages (not supported by all browsers)
     // en - english,  it - italian, fr - french,  de - german, es - spanish
@@ -3366,30 +3555,23 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
 
 ///////////////////////////////////////////////////////////////////////////////
 
-/** Audio context used by the engine
- *  @type {AudioContext}
- *  @memberof Audio */
-let audioContext;
-
-/** Keep track if audio was suspended when last sound was played
- *  @type {Boolean}
- *  @memberof Audio */
+// internal tracking if audio was suspended when last sound was played
+// allows first suspended sound to play when audio is resumed
 let audioSuspended = false;
 
 /** Play cached audio samples with given settings
- *  @param {Array}   sampleChannels - Array of arrays of samples to play (for stereo playback)
- *  @param {Number}  [volume] - How much to scale volume by
- *  @param {Number}  [rate] - The playback rate to use
- *  @param {Number}  [pan] - How much to apply stereo panning
- *  @param {Boolean} [loop] - True if the sound should loop when it reaches the end
- *  @param {Number}  [sampleRate=44100] - Sample rate for the sound
+ *  @param {Array}    sampleChannels - Array of arrays of samples to play (for stereo playback)
+ *  @param {Number}   [volume] - How much to scale volume by
+ *  @param {Number}   [rate] - The playback rate to use
+ *  @param {Number}   [pan] - How much to apply stereo panning
+ *  @param {Boolean}  [loop] - True if the sound should loop when it reaches the end
+ *  @param {Number}   [sampleRate=44100] - Sample rate for the sound
+ *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing
  *  @return {AudioBufferSourceNode} - The audio node of the sound played
  *  @memberof Audio */
-function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=zzfxR) 
+function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=zzfxR, gainNode) 
 {
     if (!soundEnable || headlessMode) return;
-    if (!audioContext)
-        audioContext = new AudioContext; // create audio context
 
     // prevent sounds from building up if they can't be played
     const audioWasSuspended = audioSuspended;
@@ -3413,10 +3595,10 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
     source.playbackRate.value = rate;
     source.loop = loop;
 
-    // create and connect gain node (createGain is more widely spported then GainNode construtor)
-    const gainNode = audioContext.createGain();
-    gainNode.gain.value = soundVolume*volume;
-    gainNode.connect(audioContext.destination);
+    // create and connect gain node
+    gainNode = gainNode || audioContext.createGain();
+    gainNode.gain.value = volume;
+    gainNode.connect(audioGainNode);
 
     // connect source to stereo panner and gain
     source.connect(new StereoPannerNode(audioContext, {'pan':clamp(pan, -1, 1)})).connect(gainNode);
@@ -4323,6 +4505,9 @@ class Particle extends EngineObject
         this.localSpaceEmitter = localSpaceEmitter;
         /** @property {Function} - Called when particle dies */
         this.destroyCallback = destroyCallback;
+
+        // particles use circular clamped speed
+        this.clampSpeedLinear = false;
     }
 
     /** Render the particle, automatically called each frame, sorted by renderOrder */
@@ -4392,9 +4577,9 @@ class Particle extends EngineObject
 
 
 /** List of all medals
- *  @type {Array}
+ *  @type {Object}
  *  @memberof Medals */
-const medals = [];
+const medals = {};
 
 // Engine internal variables not exposed to documentation
 let medalsDisplayQueue = [], medalsSaveName, medalsDisplayTimeLast;
@@ -4410,9 +4595,45 @@ function medalsInit(saveName)
 {
     // check if medals are unlocked
     medalsSaveName = saveName;
-    debugMedals || medals.forEach(medal=> medal.unlocked = (localStorage[medal.storageKey()] | 0));
+    if (!debugMedals)
+        medalsForEach(medal=> medal.unlocked = (localStorage[medal.storageKey()] | 0));
+
+    // engine automatically renders medals
+    addPluginRender(function()
+    {
+        if (!medalsDisplayQueue.length)
+            return;
+        
+        // update first medal in queue
+        const medal = medalsDisplayQueue[0];
+        const time = timeReal - medalsDisplayTimeLast;
+        if (!medalsDisplayTimeLast)
+            medalsDisplayTimeLast = timeReal;
+        else if (time > medalDisplayTime)
+        {
+            medalsDisplayTimeLast = 0;
+            medalsDisplayQueue.shift();
+        }
+        else
+        {
+            // slide on/off medals
+            const slideOffTime = medalDisplayTime - medalDisplaySlideTime;
+            const hidePercent = 
+                time < medalDisplaySlideTime ? 1 - time / medalDisplaySlideTime :
+                time > slideOffTime ? (time - slideOffTime) / medalDisplaySlideTime : 0;
+            medal.render(hidePercent);
+        }
+    });
 }
 
+/** Calls a function for each medal
+ *  @param {Function} callback
+ *  @memberof Medals */
+function medalsForEach(callback)
+{ Object.values(medals).forEach(medal=>callback(medal)); }
+
+///////////////////////////////////////////////////////////////////////////////
+
 /** 
  * Medal - Tracks an unlockable medal 
  * @example
@@ -4457,7 +4678,6 @@ class Medal
         ASSERT(medalsSaveName, 'save name must be set');
         localStorage[this.storageKey()] = this.unlocked = 1;
         medalsDisplayQueue.push(this);
-        newgrounds && newgrounds.unlockMedal(this.id);
     }
 
     /** Render a medal
@@ -4505,173 +4725,6 @@ class Medal
  
     // Get local storage key used by the medal
     storageKey() { return medalsSaveName + '_' + this.id; }
-}
-
-// engine automatically renders medals
-function medalsRender()
-{
-    if (!medalsDisplayQueue.length)
-        return;
-    
-    // update first medal in queue
-    const medal = medalsDisplayQueue[0];
-    const time = timeReal - medalsDisplayTimeLast;
-    if (!medalsDisplayTimeLast)
-        medalsDisplayTimeLast = timeReal;
-    else if (time > medalDisplayTime)
-    {
-        medalsDisplayTimeLast = 0;
-        medalsDisplayQueue.shift();
-    }
-    else
-    {
-        // slide on/off medals
-        const slideOffTime = medalDisplayTime - medalDisplaySlideTime;
-        const hidePercent = 
-            time < medalDisplaySlideTime ? 1 - time / medalDisplaySlideTime :
-            time > slideOffTime ? (time - slideOffTime) / medalDisplaySlideTime : 0;
-        medal.render(hidePercent);
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-// global Newgrounds object
-let newgrounds;
-
-/** This can used to enable Newgrounds functionality
- *  @param {Number} app_id   - The newgrounds App ID
- *  @param {String} [cipher] - The encryption Key (AES-128/Base64)
- *  @param {Object} [cryptoJS] - An instance of CryptoJS, if there is a cipher
- *  @memberof Medals */
-function newgroundsInit(app_id, cipher, cryptoJS)
-{ newgrounds = new Newgrounds(app_id, cipher, cryptoJS); }
-
-/** 
- * Newgrounds API wrapper object
- * @example
- * // create a newgrounds object, replace the app id with your own
- * const app_id = '53123:1ZuSTQ9l';
- * newgrounds = new Newgrounds(app_id);
- */
-class Newgrounds
-{
-    /** Create a newgrounds object
-     *  @param {Number} app_id   - The newgrounds App ID
-     *  @param {String} [cipher] - The encryption Key (AES-128/Base64)
-     *  @param {Object} [cryptoJS] - An instance of CryptoJS, if there is a cipher */
-    constructor(app_id, cipher, cryptoJS)
-    {
-        ASSERT(!newgrounds && app_id>0, 'there can only be one newgrounds object');
-        ASSERT(!cipher || cryptoJS, 'must provide cryptojs if there is a cipher');
-
-        this.app_id = app_id;
-        this.cipher = cipher;
-        this.cryptoJS = cryptoJS;
-        this.host = location ? location.hostname : '';
-
-        // get session id from url search params
-        const url = new URL(location.href);
-        this.session_id = url.searchParams.get('ngio_session_id');
-
-        if (!this.session_id)
-            return; // only use newgrounds when logged in
-
-        // get medals
-        const medalsResult = this.call('Medal.getList');
-        this.medals = medalsResult ? medalsResult.result.data['medals'] : [];
-        debugMedals && console.log(this.medals);
-        for (const newgroundsMedal of this.medals)
-        {
-            const medal = medals[newgroundsMedal['id']];
-            if (medal)
-            {
-                // copy newgrounds medal data
-                medal.image =       new Image;
-                medal.image.src =   newgroundsMedal['icon'];
-                medal.name =        newgroundsMedal['name'];
-                medal.description = newgroundsMedal['description'];
-                medal.unlocked =    newgroundsMedal['unlocked'];
-                medal.difficulty =  newgroundsMedal['difficulty'];
-                medal.value =       newgroundsMedal['value'];
-
-                if (medal.value)
-                    medal.description = medal.description + ' (' + medal.value + ')';
-            }
-        }
-    
-        // get scoreboards
-        const scoreboardResult = this.call('ScoreBoard.getBoards');
-        this.scoreboards = scoreboardResult ? scoreboardResult.result.data.scoreboards : [];
-        debugMedals && console.log(this.scoreboards);
-
-        const keepAliveMS = 5 * 60 * 1e3;
-        setInterval(()=>this.call('Gateway.ping', 0, true), keepAliveMS);
-    }
-
-    /** Send message to unlock a medal by id
-     * @param {Number} id - The medal id */
-    unlockMedal(id) { return this.call('Medal.unlock', {'id':id}, true); }
-
-    /** Send message to post score
-     * @param {Number} id    - The scoreboard id
-     * @param {Number} value - The score value */
-    postScore(id, value) { return this.call('ScoreBoard.postScore', {'id':id, 'value':value}, true); }
-
-    /** Get scores from a scoreboard
-     * @param {Number} id       - The scoreboard id
-     * @param {String} [user]   - A user's id or name
-     * @param {Number} [social] - If true, only social scores will be loaded
-     * @param {Number} [skip]   - Number of scores to skip before start
-     * @param {Number} [limit]  - Number of scores to include in the list
-     * @return {Object}         - The response JSON object
-     */
-    getScores(id, user, social=0, skip=0, limit=10)
-    { return this.call('ScoreBoard.getScores', {'id':id, 'user':user, 'social':social, 'skip':skip, 'limit':limit}); }
-
-    /** Send message to log a view */
-    logView() { return this.call('App.logView', {'host':this.host}, true); }
-
-    /** Send a message to call a component of the Newgrounds API
-     * @param {String}  component    - Name of the component
-     * @param {Object}  [parameters] - Parameters to use for call
-     * @param {Boolean} [async]      - If true, don't wait for response before continuing
-     * @return {Object}              - The response JSON object
-     */
-    call(component, parameters, async=false)
-    {
-        const call = {'component':component, 'parameters':parameters};
-        if (this.cipher)
-        {
-            // encrypt using AES-128 Base64 with cryptoJS
-            const cryptoJS = this.cryptoJS;
-            const aesKey = cryptoJS['enc']['Base64']['parse'](this.cipher);
-            const iv = cryptoJS['lib']['WordArray']['random'](16);
-            const encrypted = cryptoJS['AES']['encrypt'](JSON.stringify(call), aesKey, {'iv':iv});
-            call['secure'] = cryptoJS['enc']['Base64']['stringify'](iv.concat(encrypted['ciphertext']));
-            call['parameters'] = 0;
-        }
-
-        // build the input object
-        const input =
-        {
-            'app_id':     this.app_id,
-            'session_id': this.session_id,
-            'call':       call
-        };
-
-        // build post data
-        const formData = new FormData();
-        formData.append('input', JSON.stringify(input));
-        
-        // send post data
-        const xmlHttp = new XMLHttpRequest();
-        const url = 'https://newgrounds.io/gateway_v3.php';
-        xmlHttp.open('POST', url, !debugMedals && async);
-        xmlHttp.send(formData);
-        debugMedals && console.log(xmlHttp.responseText);
-        return xmlHttp.responseText && JSON.parse(xmlHttp.responseText);
-    }
 }
 /**
  * LittleJS WebGL Interface
@@ -4762,7 +4815,7 @@ function glPreRender()
 
     // clear and set to same size as main canvas
     glContext.viewport(0, 0, glCanvas.width=mainCanvas.width, glCanvas.height=mainCanvas.height);
-    //glContext.clear(gl_COLOR_BUFFER_BIT); // auto cleared when size is set
+    glContext.clear(gl_COLOR_BUFFER_BIT);
 
     // set up the shader
     glContext.useProgram(glShader);
@@ -4945,99 +4998,6 @@ function glDraw(x, y, sizeX, sizeY, angle, uv0X, uv0Y, uv1X, uv1Y, rgba, rgbaAdd
     glInstanceCount++;
 }
 
-///////////////////////////////////////////////////////////////////////////////
-// post processing - can be enabled to pass other canvases through a final shader
-
-let glPostShader, glPostTexture, glPostIncludeOverlay;
-
-/** Set up a post processing shader
- *  @param {String} shaderCode
- *  @param {Boolean} includeOverlay
- *  @memberof WebGL */
-function glInitPostProcess(shaderCode, includeOverlay=false)
-{
-    ASSERT(!glPostShader, 'can only have 1 post effects shader');
-    if (headlessMode) return;
-    if (!shaderCode) // default shader pass through
-        shaderCode = 'void mainImage(out vec4 c,vec2 p){c=texture(iChannel0,p/iResolution.xy);}';
-
-    // create the shader
-    glPostShader = glCreateProgram(
-        '#version 300 es\n' +            // specify GLSL ES version
-        'precision highp float;'+        // use highp for better accuracy
-        'in vec2 p;'+                    // position
-        'void main(){'+                  // shader entry point
-        'gl_Position=vec4(p+p-1.,1,1);'+ // set position
-        '}'                              // end of shader
-        ,
-        '#version 300 es\n' +            // specify GLSL ES version
-        'precision highp float;'+        // use highp for better accuracy
-        'uniform sampler2D iChannel0;'+  // input texture
-        'uniform vec3 iResolution;'+     // size of output texture
-        'uniform float iTime;'+          // time
-        'out vec4 c;'+                   // out color
-        '\n' + shaderCode + '\n'+        // insert custom shader code
-        'void main(){'+                  // shader entry point
-        'mainImage(c,gl_FragCoord.xy);'+ // call post process function
-        'c.a=1.;'+                       // always use full alpha
-        '}'                              // end of shader
-    );
-
-    // create buffer and texture
-    glPostTexture = glCreateTexture(undefined);
-    glPostIncludeOverlay = includeOverlay;
-
-    // hide the original 2d canvas
-    mainCanvas.style.visibility = 'hidden';
-    if (glPostIncludeOverlay)
-        overlayCanvas.style.visibility = 'hidden';
-}
-
-// Render the post processing shader, called automatically by the engine
-function glRenderPostProcess()
-{
-    if (!glPostShader || headlessMode) return;
-    
-    // prepare to render post process shader
-    if (glEnable)
-    {
-        glFlush(); // clear out the buffer
-        mainContext.drawImage(glCanvas, 0, 0); // copy to the main canvas
-    }
-    else
-    {
-        // set the viewport
-        glContext.viewport(0, 0, glCanvas.width = mainCanvas.width, glCanvas.height = mainCanvas.height);
-    }
-
-    // copy overlay canvas so it will be included in post processing
-    glPostIncludeOverlay && mainContext.drawImage(overlayCanvas, 0, 0);
-
-    // setup shader program to draw one triangle
-    glContext.useProgram(glPostShader);
-    glContext.bindBuffer(gl_ARRAY_BUFFER, glGeometryBuffer);
-    glContext.pixelStorei(gl_UNPACK_FLIP_Y_WEBGL, 1);
-    glContext.disable(gl_BLEND);
-
-    // set textures, pass in the 2d canvas and gl canvas in separate texture channels
-    glContext.activeTexture(gl_TEXTURE0);
-    glContext.bindTexture(gl_TEXTURE_2D, glPostTexture);
-    glContext.texImage2D(gl_TEXTURE_2D, 0, gl_RGBA, gl_RGBA, gl_UNSIGNED_BYTE, mainCanvas);
-
-    // set vertex position attribute
-    const vertexByteStride = 8;
-    const pLocation = glContext.getAttribLocation(glPostShader, 'p');
-    glContext.enableVertexAttribArray(pLocation);
-    glContext.vertexAttribPointer(pLocation, 2, gl_FLOAT, false, vertexByteStride, 0);
-
-    // set uniforms and draw
-    const uniformLocation = (name)=>glContext.getUniformLocation(glPostShader, name);
-    glContext.uniform1i(uniformLocation('iChannel0'), 0);
-    glContext.uniform1f(uniformLocation('iTime'), time);
-    glContext.uniform3f(uniformLocation('iResolution'), mainCanvas.width, mainCanvas.height, 1);
-    glContext.drawArrays(gl_TRIANGLE_STRIP, 0, 4);
-}
-
 ///////////////////////////////////////////////////////////////////////////////
 // store gl constants as integers so their name doesn't use space in minifed
 const
@@ -5102,7 +5062,7 @@ const engineName = 'LittleJS';
  *  @type {String}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.9.6';
+const engineVersion = '1.9.8';
 
 /** Frames per second to update
  *  @type {Number}
@@ -5156,6 +5116,22 @@ function setPaused(isPaused) { paused = isPaused; }
 let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
 
 ///////////////////////////////////////////////////////////////////////////////
+// plugin hooks
+
+const pluginUpdateList = [], pluginRenderList = [];
+
+/** Add a new update function for a plugin
+ *  @param {Function} updateFunction
+ *  @memberof Engine */
+function addPluginUpdate(updateFunction) { pluginUpdateList.push(updateFunction); }
+
+/** Add a new render function for a plugin
+ *  @param {Function} renderFunction
+ *  @memberof Engine */
+function addPluginRender(renderFunction) { pluginRenderList.push(renderFunction); }
+
+///////////////////////////////////////////////////////////////////////////////
+// Main engine functions
 
 /** Startup LittleJS engine with your callback functions
  *  @param {Function} gameInit       - Called once after the engine starts up, setup the game
@@ -5231,6 +5207,7 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
                 // update game and objects
                 inputUpdate();
                 gameUpdate();
+                pluginUpdateList.forEach(f=>f());
                 engineObjectsUpdate();
 
                 // do post update
@@ -5252,8 +5229,7 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
             for (const o of engineObjects)
                 o.destroyed || o.render();
             gameRenderPost();
-            glRenderPostProcess();
-            medalsRender();
+            pluginRenderList.forEach(f=>f());
             touchGamepadRender();
             debugRender();
             glCopyToContext(mainContext);
@@ -5335,6 +5311,7 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
 
     // init stuff and start engine
     inputInit();
+    audioInit();
     debugInit();
     glInit();
 
@@ -5542,21 +5519,23 @@ function drawEngineSplashScreen(t)
     x.setLineDash([99*p2,99]);
 
     // cab top
-    rect(7,17,18,-8,color(2,2));
-    rect(7,9,18,4,color(2,3));
-    rect(25,9,8,8,color(2,1));
-    rect(25,9,-18,8);
-    rect(25,9,8,8);
+    rect(7,16,18,-8,color(2,2));
+    rect(7,8,18,4,color(2,3));
+    rect(25,8,8,8,color(2,1));
+    rect(25,8,-18,8);
+    rect(25,8,8,8);
 
     // cab
-    rect(25,17,7,22,color());
-    rect(11,40,14,-23,color(1,1));
-    rect(11,17,14,17,color(1,2));
-    rect(11,17,14,9,color(1,3));
-    rect(15,31,6,-9,color(2,2));
-    circle(15,23,5,0,PI/2,color(2,4),1);
-    rect(25,17,-14,23);
-    rect(21,22,-6,9);
+    rect(25,16,7,23,color());
+    rect(11,39,14,-23,color(1,1));
+    rect(11,16,14,18,color(1,2));
+    rect(11,16,14,8,color(1,3));
+    rect(25,16,-14,24);
+
+    // cab window
+    rect(15,29,6,-9,color(2,2));
+    circle(15,21,5,0,PI/2,color(2,4),1);
+    rect(21,21,-6,9);
 
     // little stack
     rect(37,14,9,6,color(3,2));
@@ -5564,16 +5543,16 @@ function drawEngineSplashScreen(t)
     rect(37,14,9,6);
 
     // big stack
-    rect(50,20,10,-8,color(0,1))
-    rect(50,20,6.5,-8,color(0,2))
-    rect(50,20,3.5,-8,color(0,3))
-    rect(50,20,10,-8)
-    circle(55,2,11.4,.5,PI-.5,color(3,3))
-    circle(55,2,11.4,.5,PI/2,color(3,2),1)
-    circle(55,2,11.4,.5,PI-.5)
-    rect(45,7,20,-7,color(0,2))
-    rect(45,-1,20,4,color(0,3))
-    rect(45,-1,20,8)
+    rect(50,20,10,-8,color(0,1));
+    rect(50,20,6.5,-8,color(0,2));
+    rect(50,20,3.5,-8,color(0,3));
+    rect(50,20,10,-8);
+    circle(55,2,11.4,.5,PI-.5,color(3,3));
+    circle(55,2,11.4,.5,PI/2,color(3,2),1);
+    circle(55,2,11.4,.5,PI-.5);
+    rect(45,7,20,-7,color(0,2));
+    rect(45,-1,20,4,color(0,3));
+    rect(45,-1,20,8);
 
     // engine
     for (let i=5; i--;)