littlejsengine 1.14.11 → 1.14.19

package/dist/littlejs.release.js

@@ -33,7 +33,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.14.11';
+const engineVersion = '1.14.19';
 
 /** Frames per second to update
  *  @type {number}
@@ -94,29 +94,60 @@ let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
 ///////////////////////////////////////////////////////////////////////////////
 // plugin hooks
 
-const pluginUpdateList = [], pluginRenderList = [];
+const pluginList = [];
+class EnginePlugin
+{
+    constructor(update, render, glContextLost, glContextRestored)
+    {
+        this.update = update;
+        this.render = render;
+        this.glContextLost = glContextLost;
+        this.glContextRestored = glContextRestored;
+    }
+}
+
+/**
+ * @callback PluginCallback - Update or render function for a plugin
+ * @memberof Engine
+ */
 
 /** Add a new update function for a plugin
- *  @param {Function} [updateFunction]
- *  @param {Function} [renderFunction]
+ *  @param {PluginCallback} [update]
+ *  @param {PluginCallback} [render]
+ *  @param {PluginCallback} [glContextLost]
+ *  @param {PluginCallback} [glContextRestored]
  *  @memberof Engine */
-function engineAddPlugin(updateFunction, renderFunction)
+function engineAddPlugin(update, render, glContextLost, glContextRestored)
 {
-    ASSERT(!pluginUpdateList.includes(updateFunction));
-    ASSERT(!pluginRenderList.includes(renderFunction));
-    updateFunction && pluginUpdateList.push(updateFunction);
-    renderFunction && pluginRenderList.push(renderFunction);
+    // make sure plugin functions are unique
+    ASSERT(!pluginList.find(p=>
+        p.update === update && p.render === render &&
+        p.glContextLost === glContextLost &&
+        p.glContextRestored === glContextRestored));
+
+    const plugin = new EnginePlugin(update, render, glContextLost, glContextRestored);
+    pluginList.push(plugin);
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 // Main Engine Functions
 
+/**
+ * @callback GameInitCallback - Called after the engine starts, can be async
+ * @returns {void|Promise<void>}
+ * @memberof Engine
+ */
+/**
+ * @callback GameCallback - Update or render function for the game
+ * @memberof Engine
+ */
+
 /** Startup LittleJS engine with your callback functions
- *  @param {Function|function():Promise} gameInit - Called once after the engine starts up, can be async for loading
- *  @param {Function} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
- *  @param {Function} gameUpdatePost - Called after physics and objects are updated, even when paused, use for UI updates
- *  @param {Function} gameRender - Called before objects are rendered, use for drawing backgrounds/world elements
- *  @param {Function} gameRenderPost - Called after objects are rendered, use for drawing UI/overlays
+ *  @param {GameInitCallback} gameInit - Called once after the engine starts up, can be async for loading
+ *  @param {GameCallback} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
+ *  @param {GameCallback} gameUpdatePost - Called after physics and objects are updated, even when paused, use for UI updates
+ *  @param {GameCallback} gameRender - Called before objects are rendered, use for drawing backgrounds/world elements
+ *  @param {GameCallback} gameRenderPost - Called after objects are rendered, use for drawing UI/overlays
  *  @param {Array<string>} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png'])
  *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body
  *  @example
@@ -180,7 +211,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             wasUpdated = true;
             updateCanvas();
             inputUpdate();
-            pluginUpdateList.forEach(f=>f());
+            pluginList.forEach(plugin=>plugin.update?.());
 
             // update object transforms even when paused
             for (const o of engineObjects)
@@ -213,7 +244,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 updateCanvas();
                 inputUpdate();
                 gameUpdate();
-                pluginUpdateList.forEach(f=>f());
+                pluginList.forEach(plugin=>plugin.update?.());
                 engineObjectsUpdate();
 
                 // do post update
@@ -247,7 +278,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             for (const o of engineObjects)
                 o.destroyed || o.render();
             gameRenderPost();
-            pluginRenderList.forEach(f=>f());
+            pluginList.forEach(plugin=>plugin.render?.());
             touchGamepadRender();
             debugRender();
             glFlush();
@@ -368,11 +399,12 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     const promises = imageSources.map((src, textureIndex)=>
         new Promise(resolve =>
         {
+            ASSERT(isString(src), 'imageSources must be an array of strings');
+
             const image = new Image;
             image.onerror = image.onload = ()=>
             {
                 const textureInfo = new TextureInfo(image);
-                textureInfo.createWebGLTexture();
                 textureInfos[textureIndex] = textureInfo;
                 resolve();
             }
@@ -388,7 +420,6 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         {
             const textureInfo = new TextureInfo(new Image);
             textureInfos[0] = textureInfo;
-            textureInfo.createWebGLTexture();
             resolve();
         }));
     }
@@ -399,7 +430,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         promises.push(new Promise(resolve =>
         {
             let t = 0;
-            LOG(`${engineName} Engine v${engineVersion}`);
+            console.log(`${engineName} Engine v${engineVersion}`);
             updateSplash();
             function updateSplash()
             {
@@ -483,10 +514,16 @@ function engineObjectsCollect(pos, size, objects=engineObjects)
     return collectedObjects;
 }
 
+/**
+ * @callback ObjectCallbackFunction - Function that processes an object
+ * @param {EngineObject} uiObjects
+ *  @memberof Engine
+ */
+
 /** Triggers a callback for each 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 {Function} [callbackFunction]   - Calls this function on every object that passes the test
+ *  @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 {ObjectCallbackFunction} [callbackFunction] - Calls this function on every object that passes the test
  *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
  *  @memberof Engine */
 function engineObjectsCallback(pos, size, callbackFunction, objects=engineObjects)
@@ -950,6 +987,8 @@ function formatTime(t)
 async function fetchJSON(url)
 {
     const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch JSON from ${url}: ${response.status} ${response.statusText}`);
     return response.json();
 }
 
@@ -960,6 +999,13 @@ async function fetchJSON(url)
  * @memberof Utilities */
 function isNumber(n) { return typeof n === 'number' && !isNaN(n); }
 
+/**
+ * Check if object is a valid string or can be converted to one
+ * @param {any} s
+ * @return {boolean}
+ * @memberof Utilities */
+function isString(s) { return s !== undefined && s !== null && typeof s.toString() === 'string'; }
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Random global functions
@@ -1022,6 +1068,7 @@ function randColor(colorA=new Color, colorB=new Color(0,0,0,1), linear=false)
 /**
  * Seeded random number generator
  * - Can be used to create a deterministic random number sequence
+ * @memberof Engine
  * @example
  * let r = new RandomGenerator(123); // random number generator with seed 123
  * let a = r.float();                // random value between 0 and 1
@@ -1118,6 +1165,7 @@ function ASSERT_VECTOR2_NORMAL(v)
 /**
  * 2D Vector object with vector math library
  * - Functions do not change this so they can be chained together
+ * @memberof Engine
  * @example
  * let a = new Vector2(2, 3); // vector with coordinates (2, 3)
  * let b = new Vector2;       // vector with coordinates (0, 0)
@@ -1258,9 +1306,10 @@ class Vector2
         return new Vector2(this.x*c - this.y*s, this.x*s + this.y*c);
     }
 
-    /** Set the integer direction of this vector, corresponding to multiples of 90 degree rotation (0-3)
+    /** Sets this this vector to point in the specified integer direction (0-3), corresponding to multiples of 90 degree rotation
      * @param {number} [direction]
-     * @param {number} [length] */
+     * @param {number} [length]
+     * @return {Vector2} */
     setDirection(direction, length=1)
     {
         ASSERT_NUMBER_VALID(direction);
@@ -1268,8 +1317,10 @@ class Vector2
         direction = mod(direction, 4);
         ASSERT(direction===0 || direction===1 || direction===2 || direction===3,
             'Vector2.setDirection() direction must be an integer between 0 and 3.');
-        return vec2(direction%2 ? direction-1 ? -length : length : 0,
-            direction%2 ? 0 : direction ? -length : length);
+        
+        this.x = direction%2 ? direction-1 ? -length : length : 0;
+        this.y = direction%2 ? 0 : direction ? -length : length;
+        return this;
     }
 
     /** Returns the integer direction of this vector, corresponding to multiples of 90 degree rotation (0-3)
@@ -1365,6 +1416,7 @@ function ASSERT_COLOR_VALID(c) { ASSERT(isColor(c), 'Color is invalid.', c); }
 
 /**
  * Color object (red, green, blue, alpha) with some helpful functions
+ * @memberof Engine
  * @example
  * let a = new Color;              // white
  * let b = new Color(1, 0, 0);     // red
@@ -1542,7 +1594,8 @@ class Color
      * @return {Color} */
     setHex(hex)
     {
-        ASSERT(typeof hex === 'string' && hex[0] === '#', 'Color hex code must be a string starting with #');
+        ASSERT(isString(hex), 'Color hex code must be a string');
+        ASSERT(hex[0] === '#', 'Color hex code must start with #');
         ASSERT([4,5,7,9].includes(hex.length), 'Invalid hex');
 
         if (hex.length < 6)
@@ -1584,77 +1637,78 @@ class Color
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-// default colors
+// Default Colors
 
 /** Color - White #ffffff
  *  @type {Color}
  *  @memberof Utilities */
-const WHITE = rgb();
+const WHITE = protectEngineConstant(rgb());
 
-/** Color - Clear White #ffffff with 0 alpha
+/** Color - Clear White #757474ff with 0 alpha
  *  @type {Color}
  *  @memberof Utilities */
-const CLEAR_WHITE = rgb(1,1,1,0);
+const CLEAR_WHITE = protectEngineConstant(rgb(1,1,1,0));
 
 /** Color - Black #000000
  *  @type {Color}
  *  @memberof Utilities */
-const BLACK = rgb(0,0,0);
+const BLACK = protectEngineConstant(rgb(0,0,0));
 
 /** Color - Clear Black #000000 with 0 alpha
  *  @type {Color}
  *  @memberof Utilities */
-const CLEAR_BLACK = rgb(0,0,0,0);
+const CLEAR_BLACK = protectEngineConstant(rgb(0,0,0,0));
 
 /** Color - Gray #808080
  *  @type {Color}
  *  @memberof Utilities */
-const GRAY = rgb(.5,.5,.5);
+const GRAY = protectEngineConstant(rgb(.5,.5,.5));
 
 /** Color - Red #ff0000
  *  @type {Color}
  *  @memberof Utilities */
-const RED = rgb(1,0,0);
+const RED = protectEngineConstant(rgb(1,0,0));
 
 /** Color - Orange #ff8000
  *  @type {Color}
  *  @memberof Utilities */
-const ORANGE = rgb(1,.5,0);
+const ORANGE = protectEngineConstant(rgb(1,.5,0));
 
 /** Color - Yellow #ffff00
  *  @type {Color}
  *  @memberof Utilities */
-const YELLOW = rgb(1,1,0);
+const YELLOW = protectEngineConstant(rgb(1,1,0));
 
 /** Color - Green #00ff00
  *  @type {Color}
  *  @memberof Utilities */
-const GREEN = rgb(0,1,0);
+const GREEN = protectEngineConstant(rgb(0,1,0));
 
 /** Color - Cyan #00ffff
  *  @type {Color}
  *  @memberof Utilities */
-const CYAN = rgb(0,1,1);
+const CYAN = protectEngineConstant(rgb(0,1,1));
 
 /** Color - Blue #0000ff
  *  @type {Color}
  *  @memberof Utilities */
-const BLUE = rgb(0,0,1);
+const BLUE = protectEngineConstant(rgb(0,0,1));
 
 /** Color - Purple #8000ff
  *  @type {Color}
  *  @memberof Utilities */
-const PURPLE = rgb(.5,0,1);
+const PURPLE = protectEngineConstant(rgb(.5,0,1));
 
 /** Color - Magenta #ff00ff
  *  @type {Color}
  *  @memberof Utilities */
-const MAGENTA = rgb(1,0,1);
+const MAGENTA = protectEngineConstant(rgb(1,0,1));
 
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
  * Timer object tracks how long has passed since it was set
+ * @memberof Engine
  * @example
  * let a = new Timer;    // creates a timer that is not set
  * a.set(3);             // sets the timer to 3 seconds
@@ -1716,6 +1770,36 @@ class Timer
     /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
      * @return {number} */
     valueOf() { return this.get(); }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// Helper functions used by the engine
+
+// make color constants immutable with debug assertions
+function protectEngineConstant(obj)
+{
+    if (debug)
+    {
+        // get properties and store original values
+        const props = Object.keys(obj), values = {};
+        props.forEach(prop => values[prop] = obj[prop]);
+        
+        // replace with getters/setters that assert
+        props.forEach(prop =>
+        {
+            Object.defineProperty(obj, prop, {
+                get: () => values[prop],
+                set: (value) => 
+                {
+                    ASSERT(false, `Cannot modify engine constant. Attempted to set constant (${obj}) property '${prop}' to '${value}'.`);
+                },
+                enumerable: true
+            });
+        });
+    }
+    
+    // freeze the object to prevent adding new properties
+    return Object.freeze(obj);
 }
 /**
  * LittleJS Engine Settings
@@ -2023,7 +2107,7 @@ let medalsPreventUnlock = false;
 /** Set position of camera in world space
  *  @param {Vector2} pos
  *  @memberof Settings */
-function setCameraPos(pos) { cameraPos = pos; }
+function setCameraPos(pos) { cameraPos = pos.copy(); }
 
 /** Set angle of camera in world space
  *  @param {number} angle
@@ -2046,17 +2130,17 @@ function setCanvasColorTiles(colorTiles) { canvasColorTiles = colorTiles; }
 /** Set color to clear the canvas to before render
  *  @param {Color} color
  *  @memberof Settings */
-function setCanvasClearColor(color) { canvasClearColor = color; }
+function setCanvasClearColor(color) { canvasClearColor = color.copy(); }
 
 /** Set max size of the canvas
  *  @param {Vector2} size
  *  @memberof Settings */
-function setCanvasMaxSize(size) { canvasMaxSize = size; }
+function setCanvasMaxSize(size) { canvasMaxSize = size.copy(); }
 
 /** Set fixed size of the canvas
  *  @param {Vector2} size
  *  @memberof Settings */
-function setCanvasFixedSize(size) { canvasFixedSize = size; }
+function setCanvasFixedSize(size) { canvasFixedSize = size.copy(); }
 
 /** Use nearest scaling algorithm for canvas for more pixelated look
  *  - If enabled sets css image-rendering:pixelated
@@ -2121,7 +2205,7 @@ function setGLCircleSides(sides) { glCircleSides = sides; }
 /** Set default size of tiles in pixels
  *  @param {Vector2} size
  *  @memberof Settings */
-function setTileSizeDefault(size) { tileSizeDefault = size; }
+function setTileSizeDefault(size) { tileSizeDefault = size.copy(); }
 
 /** Set to prevent tile bleeding from neighbors in pixels
  *  @param {number} scale
@@ -2166,7 +2250,7 @@ function setObjectMaxSpeed(speed) { objectMaxSpeed = speed; }
 /** Set how much gravity to apply to objects
  *  @param {Vector2} newGravity
  *  @memberof Settings */
-function setGravity(newGravity) { gravity = newGravity; }
+function setGravity(newGravity) { gravity = newGravity.copy(); }
 
 /** Set to scales emit rate of particles
  *  @param {number} scale
@@ -2256,7 +2340,7 @@ function setMedalDisplaySlideTime(time) { medalDisplaySlideTime = time; }
 /** Set size of medal display
  *  @param {Vector2} size
  *  @memberof Settings */
-function setMedalDisplaySize(size) { medalDisplaySize = size; }
+function setMedalDisplaySize(size) { medalDisplaySize = size.copy(); }
 
 /** Set to stop medals from being unlockable
  *  @param {boolean} preventUnlock
@@ -2296,6 +2380,7 @@ function setDebugKey(key) { debugKey = key; }
  * - Collision for objects can be set to be solid to block other objects
  * - Objects may get pushed into overlapping other solid objects, if so they will push away
  * - Solid objects are more performance intensive and should be used sparingly
+ * @memberof Engine
  * @example
  * // create an engine object, normally you would first extend the class with your own
  * const pos = vec2(2,3);
@@ -2304,18 +2389,18 @@ function setDebugKey(key) { debugKey = key; }
 class EngineObject
 {
     /** Create an engine object and adds it to the list of objects
-     *  @param {Vector2}  [pos=(0,0)]       - World space position of the object
-     *  @param {Vector2}  [size=(1,1)]      - World space size of the object
-     *  @param {TileInfo} [tileInfo]        - Tile info to render object (undefined is untextured)
-     *  @param {number}   [angle]           - Angle the object is rotated by
-     *  @param {Color}    [color=(1,1,1,1)] - Color to apply to tile when rendered
-     *  @param {number}   [renderOrder]     - Objects sorted by renderOrder before being rendered
+     *  @param {Vector2}  [pos=(0,0)]   - World space position of the object
+     *  @param {Vector2}  [size=(1,1)]  - World space size of the object
+     *  @param {TileInfo} [tileInfo]    - Tile info to render object (undefined is untextured)
+     *  @param {number}   [angle]       - Angle the object is rotated by
+     *  @param {Color}    [color=WHITE] - Color to apply to tile when rendered
+     *  @param {number}   [renderOrder] - Objects sorted by renderOrder before being rendered
      */
-    constructor(pos=vec2(), size=vec2(1), tileInfo, angle=0, color=new Color, renderOrder=0)
+    constructor(pos=vec2(), size=vec2(1), tileInfo, angle=0, color=WHITE, renderOrder=0)
     {
         // check passed in params
-        ASSERT(isVector2(pos), 'object pos should be a vec2');
-        ASSERT(isVector2(size), 'object size should be a vec2');
+        ASSERT(isVector2(pos), 'object pos must be a vec2');
+        ASSERT(isVector2(size), 'object size must be a vec2');
         ASSERT(!tileInfo || tileInfo instanceof TileInfo, 'object tileInfo should be a TileInfo or undefined');
         ASSERT(typeof angle === 'number' && isFinite(angle), 'object angle should be a number');
         ASSERT(isColor(color), 'object color should be a valid rgba color');
@@ -2600,7 +2685,7 @@ class EngineObject
         drawTile(this.pos, this.drawSize || this.size, this.tileInfo, this.color, this.angle, this.mirror, this.additiveColor);
     }
 
-    /** Destroy this object, destroy its children, detach it's parent, and mark it for removal */
+    /** Destroy this object, destroy its children, detach its parent, and mark it for removal */
     destroy()
     {
         if (this.destroyed)
@@ -2674,6 +2759,8 @@ class EngineObject
     addChild(child, localPos=vec2(), localAngle=0)
     {
         ASSERT(!child.parent && !this.children.includes(child));
+        ASSERT(child instanceof EngineObject, 'child must be an EngineObject');
+        ASSERT(child !== this, 'cannot add self as child');
         this.children.push(child);
         child.parent = this;
         child.localPos = localPos.copy();
@@ -2685,6 +2772,7 @@ class EngineObject
     removeChild(child)
     {
         ASSERT(child.parent === this && this.children.includes(child));
+        ASSERT(child instanceof EngineObject, 'child must be an EngineObject');
         this.children.splice(this.children.indexOf(child), 1);
         child.parent = 0;
     }
@@ -2823,7 +2911,7 @@ let drawCount;
  * Create a tile info object using a grid based system
  * - This can take vecs or floats for easier use and conversion
  * - If an index is passed in, the tile size and index will determine the position
- * @param {Vector2|number} [pos=0] - Index of tile in sheet
+ * @param {Vector2|number} [pos=0] - Position of the tile in pixels, or tile index
  * @param {Vector2|number} [size=tileSizeDefault] - Size of tile in pixels
  * @param {number} [textureIndex] - Texture index to use
  * @param {number} [padding] - How many pixels padding around tiles
@@ -2868,6 +2956,7 @@ function tile(pos=new Vector2, size=tileSizeDefault, textureIndex=0, padding=0)
 
 /**
  * Tile Info - Stores info about how to draw a tile
+ * @memberof Draw
  */
 class TileInfo
 {
@@ -2912,48 +3001,54 @@ class TileInfo
     }
 
     /**
-     * Set this tile to use a full image
-     * @param {HTMLImageElement|OffscreenCanvas} image
-     * @param {WebGLTexture} [glTexture] - WebGL texture
+     * Set this tile to use a full image in a texture info
+     * @param {TextureInfo} textureInfo
      * @return {TileInfo}
      */
-    setFullImage(image, glTexture)
+    setFullImage(textureInfo)
     {
         this.pos = new Vector2;
-        this.size = new Vector2(image.width, image.height);
-        this.textureInfo = new TextureInfo(image, glTexture);
+        this.size = textureInfo.size.copy();
+        this.textureInfo = textureInfo;
         // do not use padding or bleed
         this.bleedScale = this.padding = 0;
         return this;
     }
 }
 
-/** Texture Info - Stores info about each texture */
+/**
+ * Tile Info - Stores info about each texture
+ * @memberof Draw
+ */
 class TextureInfo
 {
     /**
      * Create a TextureInfo, called automatically by the engine
      * @param {HTMLImageElement|OffscreenCanvas} image
-     * @param {WebGLTexture} [glTexture] - WebGL texture
+     * @param {boolean} [useWebGL] - Should use WebGL if available?
      */
-    constructor(image, glTexture)
+    constructor(image, useWebGL=true)
     {
-        /** @property {HTMLImageElement} - image source */
+        /** @property {HTMLImageElement|OffscreenCanvas} - image source */
         this.image = image;
         /** @property {Vector2} - size of the image */
-        this.size = vec2(image.width, image.height);
+        this.size = image ? vec2(image.width, image.height) : vec2();
         /** @property {Vector2} - inverse of the size, cached for rendering */
-        this.sizeInverse = vec2(1/image.width, 1/image.height);
+        this.sizeInverse = image ? vec2(1/image.width, 1/image.height) : vec2();
         /** @property {WebGLTexture} - WebGL texture */
-        this.glTexture = glTexture;
+        this.glTexture = undefined;
+        useWebGL && this.createWebGLTexture();
     }
 
-    createWebGLTexture()
-    {
-        ASSERT(!this.glTexture);
-        if (glEnable)
-            this.glTexture = glCreateTexture(this.image);
-    }
+    /** Creates the WebGL texture, updates if already created */
+    createWebGLTexture() { glRegisterTextureInfo(this); }
+
+    /** Destroys the WebGL texture */
+    destroyWebGLTexture() { glUnregisterTextureInfo(this); }
+
+    /** Check if the texture is webgl enabled
+     * @return {boolean} */
+    hasWebGL() { return !!this.glTexture; }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2974,10 +3069,11 @@ class TextureInfo
 function drawTile(pos, size=new Vector2(1), tileInfo, color=WHITE,
     angle=0, mirror, additiveColor, useWebGL=glEnable, screenSpace, context)
 {
-    ASSERT(isVector2(pos), 'drawTile pos should be a vec2');
-    ASSERT(isVector2(size), 'drawTile size should be a vec2');
-    ASSERT(isColor(color) && (!additiveColor || isColor(additiveColor)), 'drawTile color is invalid');
-    ASSERT(isNumber(angle), 'drawTile angle should be a number');
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isVector2(size), 'size must be a vec2');
+    ASSERT(isColor(color), 'color is invalid');
+    ASSERT(isNumber(angle), 'angle must be a number');
+    ASSERT(!additiveColor || isColor(additiveColor), 'additiveColor must be a color');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
 
     const textureInfo = tileInfo && tileInfo.textureInfo;
@@ -3072,10 +3168,10 @@ function drawRect(pos, size, color, angle, useWebGL, screenSpace, context)
  *  @memberof Draw */
 function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=BLACK, angle=0, useWebGL=glEnable, screenSpace=false, context)
 {
-    ASSERT(isVector2(pos), 'drawRectGradient pos should be a vec2');
-    ASSERT(isVector2(size), 'drawRectGradient size should be a vec2');
-    ASSERT(isColor(colorTop) && isColor(colorBottom), 'drawRectGradient color is invalid');
-    ASSERT(isNumber(angle), 'drawRectGradient angle should be a number');
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isVector2(size), 'size must be a vec2');
+    ASSERT(isColor(colorTop) && isColor(colorBottom), 'color is invalid');
+    ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
     if (useWebGL)
     {
@@ -3133,11 +3229,11 @@ function drawRectGradient(pos, size, colorTop=WHITE, colorBottom=BLACK, angle=0,
  *  @memberof Draw */
 function drawLineList(points, width=.1, color, wrap=false, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace, context)
 {
-    ASSERT(Array.isArray(points), 'drawLineList points should be an array');
-    ASSERT(isNumber(width), 'drawLineList width should be a number');
-    ASSERT(isColor(color), 'drawLineList color is invalid');
-    ASSERT(isVector2(pos), 'drawLineList pos should be a vec2');
-    ASSERT(isNumber(angle), 'drawLineList angle should be a number');
+    ASSERT(Array.isArray(points), 'points must be an array');
+    ASSERT(isNumber(width), 'width must be a number');
+    ASSERT(isColor(color), 'color is invalid');
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
     if (useWebGL)
     {
@@ -3208,8 +3304,8 @@ function drawLine(posA, posB, width=.1, color, pos=vec2(), angle=0, useWebGL, sc
  *  @memberof Draw */
 function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, lineColor=BLACK, angle=0, useWebGL=glEnable, screenSpace=false, context)
 {
-    ASSERT(isVector2(size), 'drawRegularPoly size should be a vec2');
-    ASSERT(isNumber(sides), 'drawRegularPoly sides should be a number');
+    ASSERT(isVector2(size), 'size must be a vec2');
+    ASSERT(isNumber(sides), 'sides must be a number');
 
     // build regular polygon points
     const points = [];
@@ -3235,12 +3331,13 @@ function drawRegularPoly(pos, size=vec2(1), sides=3, color=WHITE, lineWidth=0, l
  *  @memberof Draw */
 function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(), angle=0, useWebGL=glEnable, screenSpace=false, context=undefined)
 {
-    ASSERT(isVector2(pos), 'drawPoly pos should be a vec2');
-    ASSERT(Array.isArray(points), 'drawPoly points should be an array');
-    ASSERT(isColor(color) && isColor(lineColor), 'drawPoly color is invalid');
-    ASSERT(isNumber(lineWidth), 'drawPoly lineWidth should be a number');
-    ASSERT(isNumber(angle), 'drawPoly angle should be a number');
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(Array.isArray(points), 'points must be an array');
+    ASSERT(isColor(color) && isColor(lineColor), 'color is invalid');
+    ASSERT(isNumber(lineWidth), 'lineWidth must be a number');
+    ASSERT(isNumber(angle), 'angle must be a number');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
+
     if (useWebGL)
     {
         let scale = 1;
@@ -3287,13 +3384,14 @@ function drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos=vec2(),
  *  @memberof Draw */
 function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=false, context)
 {
-    ASSERT(isVector2(pos), 'drawEllipse pos should be a vec2');
-    ASSERT(isVector2(size), 'drawEllipse size should be a vec2');
-    ASSERT(isColor(color) && isColor(lineColor), 'drawEllipse color is invalid');
-    ASSERT(isNumber(angle), 'drawEllipse angle should be a number');
-    ASSERT(isNumber(lineWidth), 'drawEllipse lineWidth should be a number');
-    ASSERT(lineWidth >= 0 && lineWidth < size.x && lineWidth < size.y, 'drawEllipse invalid lineWidth');
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isVector2(size), 'size must be a vec2');
+    ASSERT(isColor(color) && isColor(lineColor), 'color is invalid');
+    ASSERT(isNumber(angle), 'angle must be a number');
+    ASSERT(isNumber(lineWidth), 'lineWidth must be a number');
+    ASSERT(lineWidth >= 0 && lineWidth < size.x && lineWidth < size.y, 'invalid lineWidth');
     ASSERT(!context || !useWebGL, 'context only supported in canvas 2D mode');
+
     if (useWebGL)
     {
         // draw as a regular polygon
@@ -3330,21 +3428,32 @@ function drawEllipse(pos, size=vec2(1), color=WHITE, angle=0, lineWidth=0, lineC
  *  @memberof Draw */
 function drawCircle(pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, useWebGL=glEnable, screenSpace=false, context)
 {
-    ASSERT(isNumber(size), 'drawCircle size should be a number');
+    ASSERT(isNumber(size), 'size must be a number');
     drawEllipse(pos, vec2(size), color, 0, lineWidth, lineColor, useWebGL, screenSpace, context);
 }
 
+/**
+ * @callback Canvas2DDrawFunction - A function that draws to a 2D canvas context
+ * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+ * @memberof Draw
+ */
+
 /** Draw directly to a 2d canvas context in world space
  *  @param {Vector2}  pos
  *  @param {Vector2}  size
  *  @param {number}   angle
  *  @param {boolean}  [mirror]
- *  @param {Function} [drawFunction]
+ *  @param {Canvas2DDrawFunction} [drawFunction]
  *  @param {boolean}  [screenSpace=false]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
  *  @memberof Draw */
 function drawCanvas2D(pos, size, angle=0, mirror=false, drawFunction, screenSpace=false, context=drawContext)
 {
+    ASSERT(isVector2(pos), 'pos must be a vec2');
+    ASSERT(isVector2(size), 'size must be a vec2');
+    ASSERT(isNumber(angle), 'angle must be a number');
+    ASSERT(typeof drawFunction === 'function', 'drawFunction must be a function');
+
     if (!screenSpace)
     {
         // transform from world space to screen space
@@ -3372,12 +3481,13 @@ function drawCanvas2D(pos, size, angle=0, mirror=false, drawFunction, screenSpac
  *  @param {Color}   [lineColor=(0,0,0,1)]
  *  @param {CanvasTextAlign}  [textAlign='center']
  *  @param {string}  [font=fontDefault]
+ *  @param {string}  [fontStyle]
  *  @param {number}  [maxWidth]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
  *  @memberof Draw */
-function drawText(text, pos, size=1, color, lineWidth=0, lineColor, textAlign, font, maxWidth, context=drawContext)
+function drawText(text, pos, size=1, color, lineWidth=0, lineColor, textAlign, font, fontStyle, maxWidth, context=drawContext)
 {
-    drawTextScreen(text, worldToScreen(pos), size*cameraScale, color, lineWidth*cameraScale, lineColor, textAlign, font, maxWidth, context);
+    drawTextScreen(text, worldToScreen(pos), size*cameraScale, color, lineWidth*cameraScale, lineColor, textAlign, font, fontStyle, maxWidth, context);
 }
 
 /** Draw text on overlay canvas in world space
@@ -3390,11 +3500,12 @@ function drawText(text, pos, size=1, color, lineWidth=0, lineColor, textAlign, f
  *  @param {Color}   [lineColor=(0,0,0,1)]
  *  @param {CanvasTextAlign}  [textAlign='center']
  *  @param {string}  [font=fontDefault]
+ *  @param {string}  [fontStyle]
  *  @param {number}  [maxWidth]
  *  @memberof Draw */
-function drawTextOverlay(text, pos, size=1, color, lineWidth=0, lineColor, textAlign, font, maxWidth)
+function drawTextOverlay(text, pos, size=1, color, lineWidth=0, lineColor, textAlign, font, fontStyle, maxWidth)
 {
-    drawText(text, pos, size, color, lineWidth, lineColor, textAlign, font, maxWidth, overlayContext);
+    drawText(text, pos, size, color, lineWidth, lineColor, textAlign, font, fontStyle, maxWidth, overlayContext);
 }
 
 /** Draw text on overlay canvas in screen space
@@ -3407,16 +3518,27 @@ function drawTextOverlay(text, pos, size=1, color, lineWidth=0, lineColor, textA
  *  @param {Color}   [lineColor=(0,0,0,1)]
  *  @param {CanvasTextAlign}  [textAlign]
  *  @param {string}  [font=fontDefault]
+ *  @param {string}  [fontStyle]
  *  @param {number}  [maxWidth]
  *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
  *  @memberof Draw */
-function drawTextScreen(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, textAlign='center', font=fontDefault, maxWidth, context=overlayContext)
-{
+function drawTextScreen(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, textAlign='center', font=fontDefault, fontStyle='', maxWidth, context=overlayContext)
+{
+    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(isColor(color), 'color must be a color');
+    ASSERT(isNumber(lineWidth), 'lineWidth must be a number');
+    ASSERT(isColor(lineColor), 'lineColor must be a color');
+    ASSERT(['left','center','right'].includes(textAlign), 'align must be left, center, or right');
+    ASSERT(isString(font), 'font must be a string');
+    ASSERT(isString(fontStyle), 'fontStyle must be a string');
+    
     context.fillStyle = color.toString();
     context.strokeStyle = lineColor.toString();
     context.lineWidth = lineWidth;
     context.textAlign = textAlign;
-    context.font = size + 'px '+ font;
+    context.font = fontStyle + ' ' + size + 'px '+ font;
     context.textBaseline = 'middle';
 
     const lines = (text+'').split('\n');
@@ -3613,6 +3735,7 @@ let engineFontImage;
  * - 96 characters (from space to tilde) are stored in an image
  * - Uses a default 8x8 font if none is supplied
  * - You can also use fonts from the main tile sheet
+ * @memberof Draw
  * @example
  * // use built in font
  * const font = new FontImage;
@@ -3623,11 +3746,11 @@ let engineFontImage;
 class FontImage
 {
     /** Create an image font
-     *  @param {HTMLImageElement} [image]    - Image for the font, if undefined default font is used
-     *  @param {Vector2} [tileSize=(8,8)]    - Size of the font source tiles
-     *  @param {Vector2} [paddingSize=(0,1)] - How much extra space to add between characters
+     *  @param {HTMLImageElement} [image] - Image for the font, default if undefined
+     *  @param {Vector2} [tileSize=(8,8)] - Size of the font source tiles
+     *  @param {Vector2} [paddingSize=(0,1)] - How much space between characters
      */
-    constructor(image, tileSize=vec2(8), paddingSize=vec2(0,1), context=overlayContext)
+    constructor(image, tileSize=vec2(8), paddingSize=vec2(0,1))
     {
         // load default font image
         if (!engineFontImage)
@@ -3669,7 +3792,7 @@ class FontImage
      *  @param {boolean} [center]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
      */
-    drawTextScreen(text, pos, scale=4, center, context=overlayContext)
+    drawTextScreen(text, pos, scale=4, center=true, context=overlayContext)
     {
         context.save();
         const size = this.tileSize;
@@ -4363,6 +4486,7 @@ function audioInit()
  * Sound Object - Stores a sound for later use and can be played positionally
  *
  * <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
+ * @memberof Audio
  * @example
  * // create a sound
  * const sound_example = new Sound([.5,.5]);
@@ -4457,12 +4581,12 @@ class Sound
 
     /** Play the sound as a musical note with a semitone offset
      *  This can be used to play music with chromatic scales
-     *  @param {number}  semitoneOffset - How many semitones to offset pitch
+     *  @param {number}  [semitoneOffset=0] - How many semitones to offset pitch
      *  @param {Vector2} [pos] - World space position to play the sound if any
      *  @param {number}  [volume=1] - How much to scale volume by
      *  @return {SoundInstance} - The audio source node
      */
-    playNote(semitoneOffset, pos, volume)
+    playNote(semitoneOffset=0, pos, volume)
     {
         const pitch = getNoteFrequency(semitoneOffset, 1);
         return this.play(pos, volume, pitch, 0);
@@ -4485,6 +4609,8 @@ class Sound
 /**
  * Sound Wave Object - Stores a wave sound for later use and can be played positionally
  * - this can be used to play wave, mp3, and ogg files
+ * @extends Sound
+ * @memberof Audio
  * @example
  * // create a sound
  * const sound_example = new SoundWave('sound.mp3');
@@ -4494,22 +4620,29 @@ class Sound
  */
 class SoundWave extends Sound
 {
+    /**
+     * @callback SoundLoadCallback - Function called when sound is loaded
+     * @param {SoundWave} sound
+     * @memberof Audio
+     */
+    
     /** Create a sound object and cache the wave file for later use
      *  @param {string} filename - Filename of audio file to load
      *  @param {number} [randomness] - How much to randomize frequency each time sound plays
      *  @param {number} [range=soundDefaultRange] - World space max range of sound
      *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
-     *  @param {Function} [onloadCallback] - callback function to call when sound is loaded
+     *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
      */
     constructor(filename, randomness=0, range, taper, onloadCallback)
     {
         super(undefined, range, taper);
         if (!soundEnable || headlessMode) return;
+        ASSERT(!filename || isString(filename), 'filename must be a string');
 
-        /** @property {Function} - callback function to call when sound is loaded */
+        /** @property {SoundLoadCallback} - callback function to call when sound is loaded */
         this.onloadCallback = onloadCallback;
         this.randomness = randomness;
-        this.loadSound(filename);
+        filename && this.loadSound(filename);
     }
 
     /** Loads a sound from a URL and decodes it into sample data. Must be used with await!
@@ -4518,6 +4651,8 @@ class SoundWave extends Sound
     async loadSound(filename)
     {
         const response = await fetch(filename);
+        if (!response.ok)
+            throw new Error(`Failed to load sound from ${filename}: ${response.status} ${response.statusText}`);
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
         
@@ -4553,7 +4688,7 @@ class SoundWave extends Sound
         this.sampleChannels = sampleChannels;
         this.loadedPercent = 1;
         if (this.onloadCallback)
-            this.onloadCallback();
+            this.onloadCallback(this);
     }
 }
 
@@ -4562,6 +4697,7 @@ class SoundWave extends Sound
 /** 
  * Sound Instance - Wraps an AudioBufferSourceNode for individual sound control
  * Represents a single playing instance of a sound with pause/resume capabilities
+ * @memberof Audio
  * @example
  * // Play a sound and get an instance for control
  * const jumpSound = new Sound([.5,.5,220]);
@@ -4627,8 +4763,16 @@ class SoundInstance
             this.stop();
         this.gainNode = audioContext.createGain();
         this.source = playSamples(this.sound.sampleChannels, this.volume, this.rate, this.pan, this.loop, this.sound.sampleRate, this.gainNode, offset, this.onendedCallback);
-        this.startTime = audioContext.currentTime - offset;
-        this.pausedTime = undefined;
+        if (this.source)
+        {
+            this.startTime = audioContext.currentTime - offset;
+            this.pausedTime = undefined;
+        }
+        else
+        {
+            this.startTime = undefined;
+            this.pausedTime = 0;
+        }
     }
 
     /** Set the volume of this sound instance
@@ -4761,6 +4905,12 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
 
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * @callback AudioEndedCallback - Function called when a sound ends
+ * @param {AudioBufferSourceNode} source
+ * @memberof Audio
+ */
+
 /** 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
@@ -4770,13 +4920,20 @@ function getNoteFrequency(semitoneOffset, rootFrequency=220)
  *  @param {number}   [sampleRate=44100] - Sample rate for the sound
  *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing
  *  @param {number}   [offset] - Offset in seconds to start playback from
- *  @param {Function} [onended] - Callback for when the sound ends
- *  @return {AudioBufferSourceNode} - The audio node of the sound played
+ *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
+ *  @return {AudioBufferSourceNode} - The source node of the sound played, may be undefined if play fails
  *  @memberof Audio */
 function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=audioDefaultSampleRate, gainNode, offset=0, onended)
 {
     if (!soundEnable || headlessMode) return;
 
+    if (!audioIsRunning())
+    {
+        // fix stalled audio, this sound won't be able to play
+        audioContext.resume();
+        return;
+    }
+
     // create buffer and source
     const channelCount = sampleChannels.length;
     const sampleLength = sampleChannels[0].length;
@@ -4802,13 +4959,6 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
     if (onended)
         source.addEventListener('ended', ()=> onended(source));
 
-    if (!audioIsRunning())
-    {
-        // fix stalled audio, this sound won't be able to play
-        audioContext.resume();
-        return;
-    }
-
     // play and return sound
     const startOffset = offset * rate;
     source.start(0, startOffset);
@@ -4976,7 +5126,7 @@ function zzfxG
  * - Unlimited numbers of layers, allocates canvases as needed
  * - Tile layers can be drawn to using their context with canvas2d
  * - Tile layers can also have collision with EngineObjects
- * @namespace TileCollision
+ * @namespace TileLayers
  */
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -4984,13 +5134,13 @@ function zzfxG
 
 /** Keep track of all tile layers with collision
  *  @type {Array<TileCollisionLayer>}
- *  @memberof TileCollision */
+ *  @memberof TileLayers */
 const tileCollisionLayers = [];
 
 /** Get tile collision data for a given cell in the grid
 *  @param {Vector2} pos
 *  @return {number}
-*  @memberof TileCollision */
+*  @memberof TileLayers */
 function tileCollisionGetData(pos)
 {
     // check all tile collision layers
@@ -5006,7 +5156,7 @@ function tileCollisionGetData(pos)
  *  @param {EngineObject} [object] - An object or undefined for generic test
  *  @param {boolean}      [solidOnly] - Only check solid layers if true
  *  @return {TileCollisionLayer}
- *  @memberof TileCollision */
+ *  @memberof TileLayers */
 function tileCollisionTest(pos, size=vec2(), object, solidOnly=true)
 {
     for (const layer of tileCollisionLayers)
@@ -5024,7 +5174,7 @@ function tileCollisionTest(pos, size=vec2(), object, solidOnly=true)
  *  @param {EngineObject} [object] - An object or undefined for generic test
  *  @param {boolean}      [solidOnly=true] - Only check solid layers if true
  *  @return {Vector2}
- *  @memberof TileCollision */
+ *  @memberof TileLayers */
 function tileCollisionRaycast(posStart, posEnd, object, solidOnly=true)
 {
     for (const layer of tileCollisionLayers)
@@ -5047,8 +5197,8 @@ function tileCollisionRaycast(posStart, posEnd, object, solidOnly=true)
  *  @param {number}   [collisionLayer] - Layer to use for collision if any
  *  @param {boolean}  [draw] - Should the layer be drawn automatically
  *  @return {Array<TileCollisionLayer>}
- *  @memberof TileCollision */
-function tileCollisionLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisionLayer, draw=true)
+ *  @memberof TileLayers */
+function tileLayersLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisionLayer, draw=true)
 {
     if (!tileMapData)
     {
@@ -5079,9 +5229,9 @@ function tileCollisionLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisio
         tileLayers[layerIndex] = tileLayer;
 
         // apply layer color
-        const layerColor = dataLayer.color || WHITE;
-        if (dataLayer.tintcolor)
-            layerColor.setHex(dataLayer.tintcolor);
+        const layerColor = dataLayer.tintcolor ?
+            new Color().setHex(dataLayer.tintcolor) :
+            dataLayer.color || WHITE;
         ASSERT(isColor(layerColor), 'layer color is not a color');
 
         for (let x=levelSize.x; x--;)
@@ -5108,6 +5258,7 @@ function tileCollisionLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisio
 ///////////////////////////////////////////////////////////////////////////////
 /**
  * Tile layer data object stores info about how to draw a tile
+ * @memberof TileLayers
  * @example
  * // create tile layer data with tile index 0 and random orientation and color
  * const tileIndex = 0;
@@ -5145,6 +5296,7 @@ class TileLayerData
  * - Contains an offscreen canvas that can be rendered to
  * - WebGL rendering is optional, call useWebGL to enable
  * @extends EngineObject
+ * @memberof TileLayers
  * @example
  * const canvasLayer = new CanvasLayer(vec2(), vec2(200,100));
  */
@@ -5159,15 +5311,19 @@ class CanvasLayer extends EngineObject
     */
     constructor(position, size, angle=0, renderOrder=0, canvasSize=vec2(512))
     {
+        ASSERT(isVector2(canvasSize), 'canvasSize must be a Vector2');
         super(position, size, undefined, angle, WHITE, renderOrder);
 
         /** @property {HTMLCanvasElement} - The canvas used by this layer */
         this.canvas = headlessMode ? undefined : new OffscreenCanvas(canvasSize.x, canvasSize.y);
         /** @property {OffscreenCanvasRenderingContext2D} - The 2D canvas context used by this layer */
-        this.context = headlessMode ? undefined : this.canvas.getContext('2d');
-        /** @property {WebGLTexture} - Texture if using WebGL for this layer, call useWebGL to enable */
-        this.glTexture = undefined;
-        this.gravityScale = 0; // disable gravity by default for canvas layers
+        this.context = this.canvas?.getContext('2d');
+        /** @property {TextureInfo} - Texture info to use for this object rendering */
+        const useWebGL = false; // do not use webgl by default
+        this.textureInfo = new TextureInfo(this.canvas, useWebGL);
+
+        // disable physics by default
+        this.mass = this.gravityScale = this.friction = this.restitution = 0;
     }
 
     /** Destroy this canvas layer */
@@ -5176,9 +5332,7 @@ class CanvasLayer extends EngineObject
         if (this.destroyed)
             return;
 
-        // free up the WebGL texture
-        if (this.glTexture)
-            glDeleteTexture(this.glTexture);
+        this.textureInfo.destroyWebGLTexture();
         super.destroy();
     }
 
@@ -5201,19 +5355,27 @@ class CanvasLayer extends EngineObject
     draw(pos, size, angle=0, color=WHITE, mirror=false, additiveColor, screenSpace=false, context)
     {
         // draw the canvas layer as a single tile that uses the whole texture
-        const useWebGL = glEnable && this.glTexture !== undefined;
-        const tileInfo = new TileInfo().setFullImage(this.canvas, this.glTexture);
+        const useWebGL = glEnable && this.textureInfo.hasWebGL();
+        const tileInfo = new TileInfo().setFullImage(this.textureInfo);
         drawTile(pos, size, tileInfo, color, angle, mirror, additiveColor, useWebGL, screenSpace, context);
     }
 
+    /**
+     * @callback Canvas2DDrawCallback - Function that draws to a canvas 2D context
+     * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+     * @memberof TileLayers
+     */
+
     /** Draw onto the layer canvas in world space (bypass WebGL)
      *  @param {Vector2}  pos
      *  @param {Vector2}  size
      *  @param {number}   angle
      *  @param {boolean}  mirror
-     *  @param {Function} drawFunction */
+     *  @param {Canvas2DDrawCallback} drawFunction */
     drawCanvas2D(pos, size, angle, mirror, drawFunction)
     {
+        if (!this.context) return;
+
         const context = this.context;
         context.save();
         pos = pos.subtract(this.pos).multiply(this.tileInfo.size);
@@ -5248,7 +5410,7 @@ class CanvasLayer extends EngineObject
             else
             {
                 // untextured
-                context.fillStyle = color;
+                context.fillStyle = color.toString();
                 context.fillRect(-.5, -.5, 1, 1);
             }
         });
@@ -5266,15 +5428,10 @@ class CanvasLayer extends EngineObject
      *  @param {boolean} [enable] - enable WebGL rendering and update the texture */
     useWebGL(enable=true)
     {
-        if (glEnable && enable)
-        {
-            if (this.glTexture)
-                glSetTextureData(this.glTexture, this.canvas);
-            else
-                this.glTexture = glCreateTexture(this.canvas);
-        }
+        if (enable)
+            this.textureInfo.createWebGLTexture();
         else
-            this.glTexture = undefined;
+            this.textureInfo.destroyWebGLTexture();
     }
 }
 
@@ -5285,7 +5442,9 @@ class CanvasLayer extends EngineObject
  * - To allow dynamic modifications, layers are rendered using canvas 2d
  * - Some devices like mobile phones are limited to 4k texture resolution
  * - For with 16x16 tiles this limits layers to 256x256 on mobile devices
+ * - Tile layers are centered on their corner, so normal levels are at (0,0)
  * @extends CanvasLayer
+ * @memberof TileLayers
  * @example
  * const tileLayer = new TileLayer(vec2(), vec2(200,100));
  */
@@ -5295,26 +5454,15 @@ class TileLayer extends CanvasLayer
     *  @param {Vector2}  position      - World space position
     *  @param {Vector2}  size          - World space size
     *  @param {TileInfo} [tileInfo]    - Default tile info for layer (used for size and texture)
-    *  @param {Vector2}  [scale=(1,1)] - How much to scale this layer when rendered
     *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
-    *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering
     */
-    constructor(position, size, tileInfo=tile(), scale=vec2(1), renderOrder=0, useWebGL=glEnable)
+    constructor(position, size, tileInfo=tile(), renderOrder=0)
     {
-        super(position, size, 0, renderOrder, size);
-        this.tileInfo = tileInfo;
-
         const canvasSize = size.multiply(tileInfo.size);
-        /** @property {HTMLCanvasElement} - The canvas used by this tile layer */
-        this.canvas = new OffscreenCanvas(canvasSize.x, canvasSize.y);
-        /** @property {OffscreenCanvasRenderingContext2D} - The 2D canvas context used by this tile layer */
-        this.context = this.canvas.getContext('2d');
-        /** @property {WebGLTexture} - Texture if using WebGL for this layer */
-        this.glTexture = useWebGL ? glCreateTexture(this.canvas) : undefined;
-        // set no friction by default, applied friction is max of both objects
-        this.friction = 0;
-        // set no restitution by default, applied restitution is max of both objects
-        this.restitution = 0;
+        super(position, size, 0, renderOrder, canvasSize);
+
+        // set tile info
+        this.tileInfo = tileInfo;
 
         // init tile data
         this.data = [];
@@ -5340,6 +5488,8 @@ class TileLayer extends CanvasLayer
      *  @param {boolean}       [redraw] - Force the tile to redraw if true */
     setData(layerPos, data, redraw=false)
     {
+        ASSERT(isVector2(layerPos), 'layerPos must be a Vector2');
+        ASSERT(data instanceof TileLayerData, 'data must be a TileLayerData');
         if (layerPos.arrayCheck(this.size))
         {
             this.data[(layerPos.y|0)*this.size.x+layerPos.x|0] = data;
@@ -5351,7 +5501,10 @@ class TileLayer extends CanvasLayer
      *  @param {Vector2} layerPos - Local position in array
      *  @return {TileLayerData} */
     getData(layerPos)
-    { return layerPos.arrayCheck(this.size) && this.data[(layerPos.y|0)*this.size.x+layerPos.x|0]; }
+    { 
+        ASSERT(isVector2(layerPos), 'layerPos must be a Vector2');
+        return layerPos.arrayCheck(this.size) && this.data[(layerPos.y|0)*this.size.x+layerPos.x|0]; 
+    }
 
     // Render the tile layer, called automatically by the engine
     render()
@@ -5359,10 +5512,11 @@ class TileLayer extends CanvasLayer
         ASSERT(drawContext !== this.context, 'must call redrawEnd() after drawing tiles!');
 
         // draw the tile layer as a single tile
-        const tileInfo = new TileInfo().setFullImage(this.canvas, this.glTexture);
-        const pos = this.pos.add(this.size.scale(.5));
-        const useWebGL = glEnable && this.glTexture !== undefined;
-        drawTile(pos, this.size, tileInfo, WHITE, 0, false, CLEAR_BLACK, useWebGL);
+        const tileInfo = new TileInfo().setFullImage(this.textureInfo);
+        const size = this.drawSize || this.size;
+        const pos = this.pos.add(size.scale(.5));
+        const useWebGL = glEnable && this.textureInfo.hasWebGL();
+        drawTile(pos, size, tileInfo, WHITE, 0, false, CLEAR_BLACK, useWebGL);
     }
 
     /** Draw all the tile data to an offscreen canvas
@@ -5374,8 +5528,7 @@ class TileLayer extends CanvasLayer
         for (let y = this.size.y; y--;)
             this.drawTileData(vec2(x,y), false);
         this.redrawEnd();
-        if (this.glTexture)
-            this.useWebGL(); // update WebGL texture
+        this.useWebGL();
     }
 
     /** Call to start the redraw process
@@ -5383,6 +5536,8 @@ class TileLayer extends CanvasLayer
      *  @param {boolean} [clear] - Should it clear the canvas before drawing */
     redrawStart(clear=false)
     {
+        if (!this.context) return;
+
         // save current render settings
         /** @type {[HTMLCanvasElement|OffscreenCanvas, CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D, Vector2, Vector2, number]} */
         this.savedRenderSettings = [drawCanvas, drawContext, mainCanvasSize, cameraPos, cameraScale];
@@ -5411,6 +5566,8 @@ class TileLayer extends CanvasLayer
     /** Call to end the redraw process */
     redrawEnd()
     {
+        if (!this.context) return;
+
         ASSERT(drawContext === this.context, 'must call redrawStart() before drawing tiles');
         glCopyToContext(drawContext);
         //debugSaveCanvas(this.canvas);
@@ -5427,6 +5584,8 @@ class TileLayer extends CanvasLayer
      */
     drawTileData(layerPos, clear=true)
     {
+        if (!this.context) return;
+        
         // clear out where the tile was, for full opaque tiles this can be skipped
         const s = this.tileInfo.size;
         if (clear)
@@ -5454,6 +5613,7 @@ class TileLayer extends CanvasLayer
  * - there can be multiple tile collision layers
  * - tile collision layers should not overlap each other
  * @extends TileLayer
+ * @memberof TileLayers
  */
 class TileCollisionLayer extends TileLayer
 {
@@ -5462,12 +5622,10 @@ class TileCollisionLayer extends TileLayer
     *  @param {Vector2}  size          - World space size
     *  @param {TileInfo} [tileInfo]    - Tile info for layer
     *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
-    *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering
     */
-    constructor(position, size, tileInfo=tile(), renderOrder=0, useWebGL=glEnable)
+    constructor(position, size, tileInfo=tile(), renderOrder=0)
     {
-        const scale = vec2(1); // collision layers are not scaled
-        super(position, size.floor(), tileInfo, scale, renderOrder, useWebGL);
+        super(position, size.floor(), tileInfo, renderOrder);
 
         /** @property {Array<number>} - The tile collision grid */
         this.collisionData = [];
@@ -5497,6 +5655,7 @@ class TileCollisionLayer extends TileLayer
     *  @param {Vector2} size - width and height of tile collision 2d grid */
     initCollision(size)
     {
+        ASSERT(isVector2(size), 'size must be a Vector2');
         this.size = size.floor();
         this.collisionData = [];
         this.collisionData.length = size.area();
@@ -5508,6 +5667,7 @@ class TileCollisionLayer extends TileLayer
     *  @param {number}  [data] */
     setCollisionData(gridPos, data=1)
     {
+        ASSERT(isVector2(gridPos), 'gridPos must be a Vector2');
         const i = (gridPos.y|0)*this.size.x + gridPos.x|0;
         gridPos.arrayCheck(this.size) && (this.collisionData[i] = data);
     }
@@ -5517,6 +5677,7 @@ class TileCollisionLayer extends TileLayer
     *  @return {number} */
     getCollisionData(gridPos)
     {
+        ASSERT(isVector2(gridPos), 'gridPos must be a Vector2');
         const i = (gridPos.y|0)*this.size.x + gridPos.x|0;
         return gridPos.arrayCheck(this.size) ? this.collisionData[i] : 0;
     }
@@ -5528,6 +5689,9 @@ class TileCollisionLayer extends TileLayer
     *  @return {boolean} */
     collisionTest(pos, size=new Vector2, object)
     {
+        ASSERT(isVector2(pos) && isVector2(size), 'pos and size must be Vector2s');
+        ASSERT(!object || object instanceof EngineObject, 'object must be an EngineObject');
+        
         // transform to local layer space
         const posX = pos.x - this.pos.x;
         const posY = pos.y - this.pos.y;
@@ -5558,6 +5722,9 @@ class TileCollisionLayer extends TileLayer
     *  @return {Vector2} */
     collisionRaycast(posStart, posEnd, object)
     {
+        ASSERT(isVector2(posStart) && isVector2(posEnd), 'positions must be Vector2s');
+        ASSERT(!object || object instanceof EngineObject, 'object must be an EngineObject');
+        
         // transform to local layer space
         const posStartX = posStart.x - this.pos.x;
         const posStartY = posStart.y - this.pos.y;
@@ -5607,9 +5774,16 @@ class TileCollisionLayer extends TileLayer
  * LittleJS Particle System
  */
 
+/**
+ *  @callback ParticleCallbackFunction - Function that processes a particle
+ *  @param {Particle} particle
+ *  @memberof Engine
+ */
+
 /**
  * Particle Emitter - Spawns particles with the given settings
  * @extends EngineObject
+ * @memberof Engine
  * @example
  * // create a particle emitter
  * let pos = vec2(2,3);
@@ -5619,7 +5793,7 @@ class TileCollisionLayer extends TileLayer
  *     tile(0, 16),                // tileInfo
  *     rgb(1,1,1,1), rgb(0,0,0,1), // colorStartA, colorStartB
  *     rgb(1,1,1,0), rgb(0,0,0,0), // colorEndA, colorEndB
- *     2, .2, .2, .1, .05,  // particleTime, sizeStart, sizeEnd, particleSpeed, particleAngleSpeed
+ *     1, .2, .2, .1, .05,  // particleTime, sizeStart, sizeEnd, particleSpeed, particleAngleSpeed
  *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleCone, fadeRate,
  *     .5, 1                // randomness, collide, additive, randomColorLinear, renderOrder
  * );
@@ -5634,10 +5808,10 @@ class ParticleEmitter extends EngineObject
      *  @param {number} [emitRate] - How many particles per second to spawn, does not emit if 0
      *  @param {number} [emitConeAngle=PI] - Local angle to apply velocity to particles from emitter
      *  @param {TileInfo} [tileInfo] - Tile info to render particles (undefined is untextured)
-     *  @param {Color} [colorStartA=(1,1,1,1)] - Color at start of life 1, randomized between start colors
-     *  @param {Color} [colorStartB=(1,1,1,1)] - Color at start of life 2, randomized between start colors
-     *  @param {Color} [colorEndA=(1,1,1,0)] - Color at end of life 1, randomized between end colors
-     *  @param {Color} [colorEndB=(1,1,1,0)] - Color at end of life 2, randomized between end colors
+     *  @param {Color} [colorStartA=WHITE] - Color at start of life 1, randomized between start colors
+     *  @param {Color} [colorStartB=WHITE] - Color at start of life 2, randomized between start colors
+     *  @param {Color} [colorEndA=CLEAR_WHITE] - Color at end of life 1, randomized between end colors
+     *  @param {Color} [colorEndB=CLEAR_WHITE] - Color at end of life 2, randomized between end colors
      *  @param {number} [particleTime]      - How long particles live
      *  @param {number} [sizeStart]         - How big are particles at start
      *  @param {number} [sizeEnd]           - How big are particles at end
@@ -5664,10 +5838,10 @@ class ParticleEmitter extends EngineObject
         emitRate = 100,
         emitConeAngle = PI,
         tileInfo,
-        colorStartA = new Color,
-        colorStartB = new Color,
-        colorEndA = new Color(1,1,1,0),
-        colorEndB = new Color(1,1,1,0),
+        colorStartA = WHITE,
+        colorStartB = WHITE,
+        colorEndA = CLEAR_WHITE,
+        colorEndB = CLEAR_WHITE,
         particleTime = .5,
         sizeStart = .1,
         sizeEnd = 1,
@@ -5690,7 +5864,8 @@ class ParticleEmitter extends EngineObject
 
         // emitter settings
         /** @property {number|Vector2} - World space size of the emitter (float for circle diameter, vec2 for rect) */
-        this.emitSize = emitSize
+        this.emitSize = emitSize instanceof Vector2 ? 
+            emitSize.copy() : emitSize;
         /** @property {number} - How long to stay alive (0 is forever) */
         this.emitTime = emitTime;
         /** @property {number} - How many particles per second to spawn, does not emit if 0 */
@@ -5700,13 +5875,13 @@ class ParticleEmitter extends EngineObject
 
         // color settings
         /** @property {Color} - Color at start of life 1, randomized between start colors */
-        this.colorStartA = colorStartA;
+        this.colorStartA = colorStartA.copy();
         /** @property {Color} - Color at start of life 2, randomized between start colors */
-        this.colorStartB = colorStartB;
+        this.colorStartB = colorStartB.copy();
         /** @property {Color} - Color at end of life 1, randomized between end colors */
-        this.colorEndA   = colorEndA;
+        this.colorEndA   = colorEndA.copy();
         /** @property {Color} - Color at end of life 2, randomized between end colors */
-        this.colorEndB   = colorEndB;
+        this.colorEndB   = colorEndB.copy();
         /** @property {boolean} - Should color be randomized linearly or across each component */
         this.randomColorLinear = randomColorLinear;
 
@@ -5741,9 +5916,9 @@ class ParticleEmitter extends EngineObject
         this.localSpace        = localSpace;
         /** @property {number} - If non zero the particle is drawn as a trail, stretched in the direction of velocity */
         this.trailScale        = 0;
-        /** @property {Function}   - Callback when particle is destroyed */
+        /** @property {ParticleCallbackFunction} - Callback when particle is destroyed */
         this.particleDestroyCallback = undefined;
-        /** @property {Function}   - Callback when particle is created */
+        /** @property {ParticleCallbackFunction} - Callback when particle is created */
         this.particleCreateCallback = undefined;
         /** @property {number} - Track particle emit time */
         this.emitTimeBuffer    = 0;
@@ -5844,6 +6019,7 @@ class ParticleEmitter extends EngineObject
 /**
  * Particle Object - Created automatically by Particle Emitters
  * @extends EngineObject
+ * @memberof Engine
  */
 class Particle extends EngineObject
 {
@@ -5862,7 +6038,7 @@ class Particle extends EngineObject
      * @param {boolean}  additive   - Does it use additive blend mode
      * @param {number}   trailScale - If a trail, how long to make it
      * @param {ParticleEmitter} [localSpaceEmitter] - Parent emitter if local space
-     * @param {Function} [destroyCallback] - Callback when particle dies
+     * @param {ParticleCallbackFunction} [destroyCallback] - Callback when particle dies
      */
     constructor(position, tileInfo, angle, colorStart, colorEnd, lifeTime, sizeStart, sizeEnd, fadeRate, additive, trailScale, localSpaceEmitter, destroyCallback
     )
@@ -5871,14 +6047,14 @@ class Particle extends EngineObject
 
         /** @property {Color} - Color at start of life */
         this.colorStart = colorStart;
-        /** @property {Color} - Calculated change in color */
-        this.colorEndDelta = colorEnd.subtract(colorStart);
+        /** @property {Color} - Color at end of life */
+        this.colorEnd = colorEnd;
         /** @property {number} - How long to live for */
         this.lifeTime = lifeTime;
         /** @property {number} - Size at start of life */
         this.sizeStart = sizeStart;
-        /** @property {number} - Calculated change in size */
-        this.sizeEndDelta = sizeEnd - sizeStart;
+        /** @property {number} - Size at end of life */
+        this.sizeEnd = sizeEnd;
         /** @property {number} - How quick to fade in/out */
         this.fadeRate = fadeRate;
         /** @property {boolean} - Is it additive */
@@ -5887,7 +6063,7 @@ class Particle extends EngineObject
         this.trailScale = trailScale;
         /** @property {ParticleEmitter} - Parent emitter if local space */
         this.localSpaceEmitter = localSpaceEmitter;
-        /** @property {Function} - Called when particle dies */
+        /** @property {ParticleCallbackFunction} - Called when particle dies */
         this.destroyCallback = destroyCallback;
         // particles do not clamp speed by default
         this.clampSpeed = false;
@@ -5914,54 +6090,58 @@ class Particle extends EngineObject
     /** Render the particle, automatically called each frame, sorted by renderOrder */
     render()
     {
-        // modulate size and color
-        const p = this.lifeTime > 0 ? min((time - this.spawnTime) / this.lifeTime, 1) : 1;
-        const radius = this.sizeStart + p * this.sizeEndDelta;
-        const size = vec2(radius);
+        // lerp color and size
+        const p1 = this.lifeTime > 0 ? min((time - this.spawnTime) / this.lifeTime, 1) : 1, p2 = 1-p1;
+        const radius = p2 * this.sizeStart + p1 * this.sizeEnd;
+        this.size.x = this.size.y = radius;
+        this.color.r = p2 * this.colorStart.r + p1 * this.colorEnd.r;
+        this.color.g = p2 * this.colorStart.g + p1 * this.colorEnd.g;
+        this.color.b = p2 * this.colorStart.b + p1 * this.colorEnd.b;
+        this.color.a = p2 * this.colorStart.a + p1 * this.colorEnd.a;
+            
+        // fade alpha
         const fadeRate = this.fadeRate/2;
-        const color = new Color(
-            this.colorStart.r + p * this.colorEndDelta.r,
-            this.colorStart.g + p * this.colorEndDelta.g,
-            this.colorStart.b + p * this.colorEndDelta.b,
-            (this.colorStart.a + p * this.colorEndDelta.a) *
-             (p < fadeRate ? p/fadeRate : p > 1-fadeRate ? (1-p)/fadeRate : 1)); // fade alpha
+        this.color.a *= p1 < fadeRate ? p1/fadeRate : 
+            p1 > 1-fadeRate ? (1-p1)/fadeRate : 1;
 
         // draw the particle
         this.additive && setBlendMode(true);
 
+        // update the position and angle for drawing
         let pos = this.pos, angle = this.angle;
         if (this.localSpaceEmitter)
         {
             // in local space of emitter
-            pos = this.localSpaceEmitter.pos.add(pos.rotate(-this.localSpaceEmitter.angle));
+            const a = this.localSpaceEmitter.angle;
+            const c = Math.cos(a), s = Math.sin(a);
+            pos = this.localSpaceEmitter.pos.add(
+                new Vector2(pos.x*c - pos.y*s, pos.x*s + pos.y*c));
             angle += this.localSpaceEmitter.angle;
         }
         if (this.trailScale)
         {
             // trail style particles
-            let velocity = this.velocity;
-            if (this.localSpaceEmitter)
-                velocity = velocity.rotate(-this.localSpaceEmitter.angle);
-            const speed = velocity.length();
+            const direction = this.localSpaceEmitter ? 
+                this.velocity.rotate(-this.localSpaceEmitter.angle) :
+                this.velocity;
+            const speed = direction.length();
             if (speed)
             {
-                const direction = velocity.scale(1/speed);
+                // stretch in direction of motion
                 const trailLength = speed * this.trailScale;
-                size.y = max(size.x, trailLength);
-                angle = direction.angle();
-                drawTile(pos.add(direction.multiply(vec2(0,-trailLength/2))), size, this.tileInfo, color, angle, this.mirror);
+                this.size.y = max(this.size.x, trailLength);
+                angle = Math.atan2(direction.x, direction.y);
+                drawTile(pos, this.size, this.tileInfo, this.color, angle, this.mirror);
             }
         }
         else
-            drawTile(pos, size, this.tileInfo, color, angle, this.mirror);
+            drawTile(pos, this.size, this.tileInfo, this.color, angle, this.mirror);
         this.additive && setBlendMode();
-        debugParticles && debugRect(pos, size, '#f005', 0, angle);
+        debugParticles && debugRect(pos, this.size, '#f005', 0, angle);
 
-        if (p === 1)
+        if (p1 === 1)
         {
-            // destroy particle when it's time runs out
-            this.color = color;
-            this.size = size;
+            // destroy particle when its time runs out
             this.destroyCallback && this.destroyCallback(this);
             this.destroyed = 1;
         }
@@ -6026,8 +6206,14 @@ function medalsInit(saveName)
     }
 }
 
+/**
+ *  @callback MedalCallbackFunction - Function that processes a medal
+ *  @param {Medal} medal
+ *  @memberof Medals
+ */
+
 /** Calls a function for each medal
- *  @param {Function} callback
+ *  @param {MedalCallbackFunction} callback
  *  @memberof Medals */
 function medalsForEach(callback)
 { Object.values(medals).forEach(medal=>callback(medal)); }
@@ -6036,6 +6222,7 @@ function medalsForEach(callback)
 
 /**
  * Medal - Tracks an unlockable medal
+ * @memberof Medals
  * @example
  * // create a medal
  * const medal_example = new Medal(0, 'Example Medal', 'More info about the medal goes here.', '🎖️');
@@ -6104,11 +6291,12 @@ class Medal
         const height = medalDisplaySize.y;
         const x = overlayCanvas.width - width;
         const y = -height*hidePercent;
+        const backgroundColor = hsl(0,0,.9);
 
         // draw containing rect and clip to that region
         context.save();
         context.beginPath();
-        context.fillStyle = new Color(.9,.9,.9).toString();
+        context.fillStyle = backgroundColor.toString();
         context.strokeStyle = BLACK.toString();
         context.lineWidth = 3;
         context.rect(x, y, width, height);
@@ -6179,7 +6367,7 @@ let glContext;
 let glAntialias = true;
 
 // WebGL internal variables not exposed to documentation
-let glShader, glPolyShader, glPolyMode, glAdditive, glBatchAdditive, glActiveTexture, glArrayBuffer, glGeometryBuffer, glPositionData, glColorData, glBatchCount;
+let glShader, glPolyShader, glPolyMode, glAdditive, glBatchAdditive, glActiveTexture, glArrayBuffer, glGeometryBuffer, glPositionData, glColorData, glBatchCount, glTextureInfos;
 
 // WebGL internal constants
 const gl_ARRAY_BUFFER_SIZE = 5e5;
@@ -6195,6 +6383,9 @@ const gl_MAX_POLY_VERTEXES = gl_ARRAY_BUFFER_SIZE / gl_POLY_VERTEX_BYTE_STRIDE |
 // Initialize WebGL, called automatically by the engine
 function glInit()
 {
+    // keep set of texture infos so they can be restored if context is lost
+    glTextureInfos = new Set;
+
     if (!glEnable || headlessMode) return;
 
     // create the canvas and textures
@@ -6212,68 +6403,101 @@ function glInit()
     // create the WebGL canvas
     const rootElement = mainCanvas.parentElement;
     rootElement.appendChild(glCanvas);
+    
+    // startup webgl
+    initWebGL();
+
+    // setup context lost and restore handlers
+    glCanvas.addEventListener('webglcontextlost', (e)=>
+    {
+        glEnable = false; // disable WebGL rendering
+        glCanvas.style.display = 'none'; // hide the gl canvas
+        e.preventDefault(); // prevent default to allow restoration
+        LOG('WebGL context lost! Switching to Canvas2d rendering.');
+
+        // remove WebGL textures
+        for (const info of glTextureInfos)
+            info.glTexture = undefined;
+        glActiveTexture = undefined;
+        pluginList.forEach(plugin=>plugin.glContextLost?.());
+    });
+    glCanvas.addEventListener('webglcontextrestored', ()=>
+    {
+        glEnable = true; // disable WebGL rendering
+        glCanvas.style.display = ''; // show the gl canvas
+        LOG('WebGL context restored, reinitializing...');
 
-    // setup instanced rendering shader program
-    glShader = glCreateProgram(
-        '#version 300 es\n' +     // specify GLSL ES version
-        'precision highp float;'+ // use highp for better accuracy
-        'uniform mat4 m;'+        // transform matrix
-        'in vec2 g;'+             // in: geometry
-        'in vec4 p,u,c,a;'+       // in: position/size, uvs, color, additiveColor
-        'in float r;'+            // in: rotation
-        'out vec2 v;'+            // out: uv
-        'out vec4 d,e;'+          // out: color, additiveColor
-        'void main(){'+           // shader entry point
-        'vec2 s=(g-.5)*p.zw;'+    // get size offset
-        'gl_Position=m*vec4(p.xy+s*cos(r)-vec2(-s.y,s)*sin(r),1,1);'+ // transform position
-        'v=mix(u.xw,u.zy,g);'+    // pass uv to fragment shader
-        'd=c;e=a;'+               // pass colors to fragment shader
-        '}'                       // end of shader
-        ,
-        '#version 300 es\n' +     // specify GLSL ES version
-        'precision highp float;'+ // use highp for better accuracy
-        'uniform sampler2D s;'+   // texture
-        'in vec2 v;'+             // in: uv
-        'in vec4 d,e;'+           // in: color, additiveColor
-        'out vec4 c;'+            // out: color
-        'void main(){'+           // shader entry point
-        'c=texture(s,v)*d+e;'+    // modulate texture by color plus additive
-        '}'                       // end of shader
-    );
+        // reinit WebGL and restore textures
+        initWebGL();
+        for (const info of glTextureInfos)
+            info.glTexture = glCreateTexture(info.image);
+        pluginList.forEach(plugin=>plugin.glContextRestored?.());
+    });
 
-    // setup poly rendering shaders
-    glPolyShader = glCreateProgram(
-        '#version 300 es\n' +     // specify GLSL ES version
-        'precision highp float;'+ // use highp for better accuracy
-        'uniform mat4 m;'+        // transform matrix
-        'in vec2 p;'+             // in: position
-        'in vec4 c;'+             // in: color
-        'out vec4 d;'+            // out: color
-        'void main(){'+           // shader entry point
-        'gl_Position=m*vec4(p,1,1);'+ // transform position
-        'd=c;'+                   // pass color to fragment shader
-        '}'                       // end of shader
-        ,
-        '#version 300 es\n' +     // specify GLSL ES version
-        'precision highp float;'+ // use highp for better accuracy
-        'in vec4 d;'+             // in: color
-        'out vec4 c;'+            // out: color
-        'void main(){'+           // shader entry point
-        'c=d;'+                   // set color
-        '}'                       // end of shader
-    );
+    function initWebGL()
+    {
+        // setup instanced rendering shader program
+        glShader = glCreateProgram(
+            '#version 300 es\n' +     // specify GLSL ES version
+            'precision highp float;'+ // use highp for better accuracy
+            'uniform mat4 m;'+        // transform matrix
+            'in vec2 g;'+             // in: geometry
+            'in vec4 p,u,c,a;'+       // in: position/size, uvs, color, additiveColor
+            'in float r;'+            // in: rotation
+            'out vec2 v;'+            // out: uv
+            'out vec4 d,e;'+          // out: color, additiveColor
+            'void main(){'+           // shader entry point
+            'vec2 s=(g-.5)*p.zw;'+    // get size offset
+            'gl_Position=m*vec4(p.xy+s*cos(r)-vec2(-s.y,s)*sin(r),1,1);'+ // transform position
+            'v=mix(u.xw,u.zy,g);'+    // pass uv to fragment shader
+            'd=c;e=a;'+               // pass colors to fragment shader
+            '}'                       // end of shader
+            ,
+            '#version 300 es\n' +     // specify GLSL ES version
+            'precision highp float;'+ // use highp for better accuracy
+            'uniform sampler2D s;'+   // texture
+            'in vec2 v;'+             // in: uv
+            'in vec4 d,e;'+           // in: color, additiveColor
+            'out vec4 c;'+            // out: color
+            'void main(){'+           // shader entry point
+            'c=texture(s,v)*d+e;'+    // modulate texture by color plus additive
+            '}'                       // end of shader
+        );
+
+        // setup poly rendering shaders
+        glPolyShader = glCreateProgram(
+            '#version 300 es\n' +     // specify GLSL ES version
+            'precision highp float;'+ // use highp for better accuracy
+            'uniform mat4 m;'+        // transform matrix
+            'in vec2 p;'+             // in: position
+            'in vec4 c;'+             // in: color
+            'out vec4 d;'+            // out: color
+            'void main(){'+           // shader entry point
+            'gl_Position=m*vec4(p,1,1);'+ // transform position
+            'd=c;'+                   // pass color to fragment shader
+            '}'                       // end of shader
+            ,
+            '#version 300 es\n' +     // specify GLSL ES version
+            'precision highp float;'+ // use highp for better accuracy
+            'in vec4 d;'+             // in: color
+            'out vec4 c;'+            // out: color
+            'void main(){'+           // shader entry point
+            'c=d;'+                   // set color
+            '}'                       // end of shader
+        );
 
-    // init buffers
-    const glInstanceData = new ArrayBuffer(gl_ARRAY_BUFFER_SIZE);
-    glPositionData = new Float32Array(glInstanceData);
-    glColorData = new Uint32Array(glInstanceData);
-    glArrayBuffer = glContext.createBuffer();
-    glGeometryBuffer = glContext.createBuffer();
+        // init buffers
+        const glInstanceData = new ArrayBuffer(gl_ARRAY_BUFFER_SIZE);
+        glPositionData = new Float32Array(glInstanceData);
+        glColorData = new Uint32Array(glInstanceData);
+        glArrayBuffer = glContext.createBuffer();
+        glGeometryBuffer = glContext.createBuffer();
 
-    // create the geometry buffer, triangle strip square
-    const geometry = new Float32Array([glBatchCount=0,0,1,0,0,1,1,1]);
-    glContext.bindBuffer(glContext.ARRAY_BUFFER, glGeometryBuffer);
-    glContext.bufferData(glContext.ARRAY_BUFFER, geometry, glContext.STATIC_DRAW);
+        // create the geometry buffer, triangle strip square
+        const geometry = new Float32Array([glBatchCount=0,0,1,0,0,1,1,1]);
+        glContext.bindBuffer(glContext.ARRAY_BUFFER, glGeometryBuffer);
+        glContext.bufferData(glContext.ARRAY_BUFFER, geometry, glContext.STATIC_DRAW);
+    }
 }
 
 function glSetInstancedMode()
@@ -6380,7 +6604,7 @@ function glPreRender()
     // start with additive blending off
     glAdditive = glBatchAdditive = false;
 
-    // force it to enter instanced mode
+    // force it to set instanced mode by first setting poly mode true
     glPolyMode = true;
     glSetInstancedMode();
 }
@@ -6521,6 +6745,41 @@ function glSetTextureData(texture, image)
     glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture); // rebind active texture
 }
 
+/** Tells WebGL to create or update the glTexture and start tracking it
+ *  @param {TextureInfo} textureInfo
+ *  @memberof WebGL */
+function glRegisterTextureInfo(textureInfo)
+{
+    if (headlessMode) return;
+
+    // add texture info to tracking list even if gl is not enabled
+    glTextureInfos.add(textureInfo);
+
+    if (!glContext) return;
+
+    // create or set the texture data
+    if (textureInfo.glTexture)
+        glSetTextureData(textureInfo.glTexture, textureInfo.image);
+    else
+        textureInfo.glTexture = glCreateTexture(textureInfo.image);
+}
+
+/** Tells WebGL to destroy the glTexture and stop tracking it
+ *  @param {TextureInfo} textureInfo
+ *  @memberof WebGL */
+function glUnregisterTextureInfo(textureInfo)
+{
+    if (headlessMode) return;
+
+    // delete texture info from tracking list even if gl is not enabled
+    glTextureInfos.delete(textureInfo);
+
+    // unset and destroy the texture
+    const glTexture = textureInfo.glTexture;
+    textureInfo.glTexture = undefined;
+    glDeleteTexture(glTexture);
+}
+
 /** Draw all sprites and clear out the buffer, called automatically by the system whenever necessary
  *  @memberof WebGL */
 function glFlush()
@@ -6910,24 +7169,25 @@ function glPolyStrip(points)
     return strip;
 }
 /** 
- * LittleJS Newgrounds API
+ * LittleJS Newgrounds Plugin
  * - NewgroundsMedal extends Medal with Newgrounds API functionality
- * - Call new NewgroundsPlugin() to setup Newgrounds
+ * - Call new NewgroundsPlugin(app_id) to setup Newgrounds
  * - Uses CryptoJS for encryption if optional cipher is provided
+ * - provides functions to interact with medals scoreboards
  * - Keeps connection alive and logs views
- * - Functions to interact with scoreboards
- * - Functions to unlock medals
+ * @namespace Newgrounds
  */
 
 /** Global Newgrounds object
  *  @type {NewgroundsPlugin}
- *  @memberof Medal */
+ *  @memberof Newgrounds */
 let newgrounds;
 
 ///////////////////////////////////////////////////////////////////////////////
 /**
  * Newgrounds medal auto unlocks in newgrounds API
  * @extends Medal
+ * @memberof Newgrounds
  */
 class NewgroundsMedal extends Medal
 {
@@ -6952,6 +7212,7 @@ class NewgroundsMedal extends Medal
 ///////////////////////////////////////////////////////////////////////////////
 /** 
  * Newgrounds API object
+ * @memberof Newgrounds
  */
 class NewgroundsPlugin
 {
@@ -7087,99 +7348,119 @@ class NewgroundsPlugin
 /**
  * LittleJS Post Processing Plugin
  * - Supports shadertoy style post processing shaders
- * - call new new PostProcessPlugin() to setup post processing
+ * - call new PostProcessPlugin() to setup post processing
  * - can be enabled to pass other canvases through a final shader
+ * @namespace PostProcess
  */
 
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Global Post Process plugin object
- *  @type {PostProcessPlugin} */
+ *  @type {PostProcessPlugin}
+ *  @memberof PostProcess */
 let postProcess;
 
 /////////////////////////////////////////////////////////////////////////
 /** 
  * UI System Global Object
+ * @memberof PostProcess
  */
 class PostProcessPlugin
 {
     /** Create global post processing shader
     *  @param {string} shaderCode
     *  @param {boolean} [includeOverlay]
+    *  @param {boolean} [includeMainCanvas]
      *  @example
      *  // create the post process plugin object
      *  new PostProcessPlugin(shaderCode);
      */
-    constructor(shaderCode, includeOverlay=false)
+    constructor(shaderCode, includeOverlay=false, includeMainCanvas=true)
     {
         ASSERT(!postProcess, 'Post process already initialized');
         postProcess = this;
 
-        if (headlessMode) return;
-
-        if (!glEnable)
-        {
-            console.warn('PostProcessPlugin: WebGL not enabled!');
-            return;
-        }
-
         if (!shaderCode) // default shader pass through
             shaderCode = 'void mainImage(out vec4 c,vec2 p){c=texture(iChannel0,p/iResolution.xy);}';
 
         /** @property {WebGLProgram} - Shader for post processing */
-        this.shader = 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
-        );
+        this.shader = undefined;
 
         /** @property {WebGLTexture} - Texture for post processing */
-        this.texture = glCreateTexture();
+        this.texture = undefined;
 
-        /** @property {boolean} - Should overlay canvas be included in post processing */
-        this.includeOverlay = includeOverlay;
+        // setup the post processing plugin
+        initPostProcess();
+        engineAddPlugin(undefined, postProcessRender, postProcessContextLost, postProcessContextRestored);
 
-        // Render the post processing shader, called automatically by the engine
-        engineAddPlugin(undefined, postProcessRender);
-        function postProcessRender()
+        function initPostProcess()
         {
             if (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
+
+            if (!glEnable)
             {
-                // set the viewport
-                glContext.viewport(0, 0, glCanvas.width = drawCanvas.width, glCanvas.height = drawCanvas.height);
+                console.warn('PostProcessPlugin: WebGL not enabled!');
+                return;
             }
 
-            if (postProcess.includeOverlay)
+            // create resources
+            postProcess.texture = glCreateTexture();
+            postProcess.shader = 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
+            );
+        }
+        function postProcessContextLost()
+        {
+            postProcess.shader = undefined;
+            postProcess.texture = undefined;
+            LOG('PostProcessPlugin: WebGL context lost');
+        }
+        function postProcessContextRestored()
+        {
+            initPostProcess();
+            LOG('PostProcessPlugin: WebGL context restored');
+        }
+        function postProcessRender()
+        {
+            if (headlessMode) return;
+
+            if (!glEnable)
+                return;
+            
+            // clear out the buffer
+            glFlush();
+            
+            if (includeMainCanvas || includeOverlay)
             {
-                // copy overlay canvas so it will be included in post processing
-                mainContext.drawImage(overlayCanvas, 0, 0);
-                overlayCanvas.width |= 0;
+                // copy WebGL to the main canvas
+                mainContext.drawImage(glCanvas, 0, 0);
+
+                if (includeOverlay)
+                {
+                    // copy overlay canvas so it will be included in post processing
+                    mainContext.drawImage(overlayCanvas, 0, 0);
+                    overlayCanvas.width |= 0; // clear overlay canvas
+                }
             }
 
-            // setup shader program to draw one triangle
+            // setup shader program to draw a quad
             glContext.useProgram(postProcess.shader);
             glContext.bindBuffer(glContext.ARRAY_BUFFER, glGeometryBuffer);
             glContext.pixelStorei(glContext.UNPACK_FLIP_Y_WEBGL, 1);
@@ -7188,7 +7469,10 @@ class PostProcessPlugin
             // set textures, pass in the 2d canvas and gl canvas in separate texture channels
             glContext.activeTexture(glContext.TEXTURE0);
             glContext.bindTexture(glContext.TEXTURE_2D, postProcess.texture);
-            glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA, glContext.RGBA, glContext.UNSIGNED_BYTE, mainCanvas);
+            if (includeMainCanvas || includeOverlay)
+            {
+                glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA, glContext.RGBA, glContext.UNSIGNED_BYTE, mainCanvas);
+            }
 
             // set vertex position attribute
             const vertexByteStride = 8;
@@ -7207,12 +7491,15 @@ class PostProcessPlugin
 }
 /**
  * LittleJS ZzFXM Plugin
+ * @namespace ZzFXM
  */
 
 /**
  * Music Object - Stores a zzfx music track for later use
  * 
  * <a href=https://keithclark.github.io/ZzFXM/>Create music with the ZzFXM tracker.</a>
+ * @extends Sound
+ * @memberof ZzFXM
  * @example
  * // create some music
  * const music_example = new Music(
@@ -7271,7 +7558,8 @@ class ZzFXMusic extends Sound
  *  @param {Array} patterns - Array of pattern data
  *  @param {Array} sequence - Array of pattern indexes
  *  @param {number} [BPM] - Playback speed of the song in BPM
- *  @return {Array} - Left and right channel sample data */
+ *  @return {Array} - Left and right channel sample data
+ *  @memberof ZzFXM */
 function zzfxM(instruments, patterns, sequence, BPM = 125) 
 {
   let i, j, k;
@@ -7374,17 +7662,20 @@ function zzfxM(instruments, patterns, sequence, BPM = 125)
  * - Buttons
  * - Checkboxes
  * - Images
+ * @namespace UISystem
  */
 
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Global UI system plugin object
- *  @type {UISystemPlugin} */
+ *  @type {UISystemPlugin}
+ *  @memberof UISystem */
 let uiSystem;
 
 ///////////////////////////////////////////////////////////////////////////////
 /** 
  * UI System Global Object
+ * @memberof UISystem
  */
 class UISystemPlugin
 {
@@ -7411,6 +7702,8 @@ class UISystemPlugin
         this.defaultHoverColor = hsl(0,0,.9);
         /** @property {Color} - Default color for disabled UI elements */
         this.defaultDisabledColor = hsl(0,0,.3);
+        /** @property {Color} - Uses a gradient fill combined with color */
+        this.defaultGradientColor = undefined;
         /** @property {number} - Default line width for UI elements */
         this.defaultLineWidth = 4;
         /** @property {number} - Default rounded rect corner radius for UI elements */
@@ -7418,7 +7711,7 @@ class UISystemPlugin
         /** @property {number} - Default scale to use for fitting text to object */
         this.defaultTextScale = .8;
         /** @property {string} - Default font for UI elements */
-        this.defaultFont = 'arial';
+        this.defaultFont = fontDefault;
         /** @property {Sound} - Default sound when interactive UI element is pressed */
         this.defaultSoundPress = undefined;
         /** @property {Sound} - Default sound when interactive UI element is released */
@@ -7429,11 +7722,15 @@ class UISystemPlugin
         this.uiObjects = [];
         /** @property {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} - Context to render UI elements to */
         this.uiContext = context;
-        /** @property {UIObject} - Top most object user is over */
-        this.hoverObject = undefined;
         /** @property {UIObject} - Object user is currently interacting with */
         this.activeObject = undefined;
-            
+        /** @property {UIObject} - Top most object user is over */
+        this.hoverObject = undefined;
+        /** @property {UIObject} - Hover object at start of update */
+        this.lastHoverObject = undefined;
+        /** @property {number} - If set ui coords will be renormalized to this canvas height */
+        this.nativeHeight = 0;
+
         engineAddPlugin(uiUpdate, uiRender);
 
         // setup recursive update and render
@@ -7463,6 +7760,7 @@ class UISystemPlugin
                     updateInvisibleObject(o);
             }
             // reset hover object at start of update
+            uiSystem.lastHoverObject = uiSystem.hoverObject;
             uiSystem.hoverObject = undefined;
             for (let i = uiSystem.uiObjects.length; i--;)
             {
@@ -7472,6 +7770,17 @@ class UISystemPlugin
         }
         function uiRender()
         {
+            const context = uiSystem.uiContext;
+            context.save();
+            if (uiSystem.nativeHeight)
+            {
+                // convert to native height
+                const s = mainCanvasSize.y / uiSystem.nativeHeight;
+                context.translate(-s*mainCanvasSize.x/2,0);
+                context.scale(s,s);
+                context.translate(mainCanvasSize.x/2/s,0);
+            }
+
             function renderObject(o)
             {
                 if (!o.visible)
@@ -7483,6 +7792,7 @@ class UISystemPlugin
                     renderObject(c);
             }
             uiSystem.uiObjects.forEach(o=> o.parent || renderObject(o));
+            context.restore();
         }
     }
 
@@ -7492,11 +7802,30 @@ class UISystemPlugin
     *  @param {Color}   [color=uiSystem.defaultColor]
     *  @param {number}  [lineWidth=uiSystem.defaultLineWidth]
     *  @param {Color}   [lineColor=uiSystem.defaultLineColor]
-    *  @param {number}  [cornerRadius=uiSystem.defaultCornerRadius] */
-    drawRect(pos, size, color=uiSystem.defaultColor, lineWidth=uiSystem.defaultLineWidth, lineColor=uiSystem.defaultLineColor, cornerRadius=uiSystem.defaultCornerRadius)
-    {
+    *  @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)
+    {
+        ASSERT(isVector2(pos), 'pos must be a vec2');
+        ASSERT(isVector2(size), 'size must be a vec2');
+        ASSERT(isColor(color), 'color must be a color');
+        ASSERT(isNumber(lineWidth), 'lineWidth must be a number');
+        ASSERT(isColor(lineColor), 'lineColor must be a color');
+        ASSERT(isNumber(cornerRadius), 'cornerRadius must be a number');
+        
         const context = uiSystem.uiContext;
-        context.fillStyle = color.toString();
+        if (gradientColor)
+        {
+            const g = context.createLinearGradient(
+                pos.x, pos.y-size.y/2, pos.x, pos.y+size.y/2);
+            const c = color.toString();
+            g.addColorStop(0, c);
+            g.addColorStop(.5, gradientColor.toString());
+            g.addColorStop(1, c);
+            context.fillStyle = g;
+        }
+        else
+            context.fillStyle = color.toString();
         context.beginPath();
         if (cornerRadius && context['roundRect'])
             context['roundRect'](pos.x-size.x/2, pos.y-size.y/2, size.x, size.y, cornerRadius);
@@ -7518,6 +7847,11 @@ class UISystemPlugin
     *  @param {Color}   [lineColor=uiSystem.defaultLineColor] */
     drawLine(posA, posB, lineWidth=uiSystem.defaultLineWidth, lineColor=uiSystem.defaultLineColor)
     {
+        ASSERT(isVector2(posA), 'posA must be a vec2');
+        ASSERT(isVector2(posB), 'posB must be a vec2');
+        ASSERT(isNumber(lineWidth), 'lineWidth must be a number');
+        ASSERT(isColor(lineColor), 'lineColor must be a color');
+
         const context = uiSystem.uiContext;
         context.strokeStyle = lineColor.toString();
         context.lineWidth = lineWidth;
@@ -7548,17 +7882,43 @@ class UISystemPlugin
     *  @param {Color}   [lineColor=uiSystem.defaultLineColor]
     *  @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, applyMaxWidth=true)
+    drawText(text, pos, size, color=uiSystem.defaultColor, lineWidth=uiSystem.defaultLineWidth, lineColor=uiSystem.defaultLineColor, align='center', font=uiSystem.defaultFont, fontStyle='', applyMaxWidth=true)
+    {
+        drawTextScreen(text, pos, size.y, color, lineWidth, lineColor, align, font, fontStyle, applyMaxWidth ? size.x : undefined, uiSystem.uiContext);
+    }
+
+    /**
+     * @callback DragAndDropCallback - Callback for drag and drop events
+     * @param {DragEvent} event - The drag event
+     * @memberof UISystem
+     */
+
+    /** Setup drag and drop event handlers
+    *  Automatically prevents defaults and calls the given functions
+    *  @param {DragAndDropCallback} [onDrop] - when a file is dropped
+    *  @param {DragAndDropCallback} [onDragEnter] - when a file is dragged onto the window
+    *  @param {DragAndDropCallback} [onDragLeave] - when a file is dragged off the window
+    *  @param {DragAndDropCallback} [onDragOver] - continously when dragging over */
+    setupDragAndDrop(onDrop, onDragEnter, onDragLeave, onDragOver)
     {
-        drawTextScreen(text, pos, size.y, color, lineWidth, lineColor, align, font, applyMaxWidth ? size.x : undefined, uiSystem.uiContext);
+        function setCallback(callback, listenerType)
+        {
+            function listener(e) { e.preventDefault(); callback && callback(e); }
+            document.addEventListener(listenerType, listener);
+        }
+        setCallback(onDrop,      'drop');
+        setCallback(onDragEnter, 'dragenter');
+        setCallback(onDragLeave, 'dragleave');
+        setCallback(onDragOver,  'dragover');
     }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 /** 
  * UI Object - Base level object for all UI elements
- */
+ * @memberof UISystem */
 class UIObject
 {
     /** Create a UIObject
@@ -7567,6 +7927,9 @@ class UIObject
      */
     constructor(pos=vec2(), size=vec2())
     {
+        ASSERT(isVector2(pos), 'ui object pos must be a vec2');
+        ASSERT(isVector2(size), 'ui object size must be a vec2');
+
         /** @property {Vector2} - Local position of the object */
         this.localPos = pos.copy();
         /** @property {Vector2} - Screen space position of the object */
@@ -7574,27 +7937,31 @@ class UIObject
         /** @property {Vector2} - Screen space size of the object */
         this.size = size.copy();
         /** @property {Color} - Color of the object */
-        this.color = uiSystem.defaultColor;
+        this.color = uiSystem.defaultColor.copy();
         /** @property {Color} - Color of the object when active, uses color if undefined */
         this.activeColor = undefined;
         /** @property {string} - Text for this ui object */
         this.text = undefined;
         /** @property {Color} - Color when disabled */
-        this.disabledColor = uiSystem.defaultDisabledColor;
+        this.disabledColor = uiSystem.defaultDisabledColor.copy();
         /** @property {boolean} - Is this object disabled? */
         this.disabled = false;
         /** @property {Color} - Color for text */
-        this.textColor = uiSystem.defaultTextColor;
+        this.textColor = uiSystem.defaultTextColor.copy();
         /** @property {Color} - Color used when hovering over the object */
-        this.hoverColor = uiSystem.defaultHoverColor;
+        this.hoverColor = uiSystem.defaultHoverColor.copy();
         /** @property {Color} - Color for line drawing */
-        this.lineColor = uiSystem.defaultLineColor;
+        this.lineColor = uiSystem.defaultLineColor.copy();
+        /** @property {Color} - Uses a gradient fill combined with color */
+        this.gradientColor = uiSystem.defaultGradientColor ? uiSystem.defaultGradientColor.copy() : undefined;
         /** @property {number} - Width for line drawing */
         this.lineWidth = uiSystem.defaultLineWidth;
         /** @property {number} - Corner radius for rounded rects */
         this.cornerRadius = uiSystem.defaultCornerRadius;
         /** @property {string} - Font for this objecct */
         this.font = uiSystem.defaultFont;
+        /** @property {string} - Font style for this object or undefined */
+        this.fontStyle = undefined;
         /** @property {number} - Override for text width */
         this.textWidth = undefined;
         /** @property {number} - Override for text height */
@@ -7619,6 +7986,8 @@ class UIObject
         this.interactive = false;
         /** @property {boolean} - Activate when dragged over with mouse held down */
         this.dragActivate = false;
+        /** @property {boolean} - True if this can be a hover object */
+        this.canBeHover = true;
         uiSystem.uiObjects.push(this);
     }
 
@@ -7642,31 +8011,47 @@ class UIObject
         child.parent = undefined;
     }
 
+    /** Check if the mouse is overlapping a box in screen space
+     *  @return {boolean} - True if overlapping
+     */
+    isMouseOverlapping()
+    {
+        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;
+        return isOverlapping(this.pos, size, pos);
+    }
+
     /** Update the object, called automatically by plugin once each frame */
     update()
     {
-        const wasHover = this.isHoverObject();
+        const wasHover = uiSystem.lastHoverObject === this;
         const isActive = this.isActiveObject();
         const mouseDown = mouseIsDown(0);
         const mousePress = this.dragActivate ? mouseDown : mouseWasPressed(0);
-        if (!uiSystem.hoverObject)
+        if (this.canBeHover)
         if (mousePress || isActive || (!mouseDown && !isTouchDevice))
-        {
-            const size = this.size.add(vec2(isTouchDevice && this.extraTouchSize || 0));
-            if (isOverlapping(this.pos, size, mousePosScreen))
-                uiSystem.hoverObject = this;
-        }
+        if (!uiSystem.hoverObject && this.isMouseOverlapping())
+            uiSystem.hoverObject = this;
         if (this.isHoverObject())
         {
-            if (mousePress)
-                inputClearKey(0,0,0,1,0); // clear mouse was pressed state
             if (!this.disabled)
             {
                 if (mousePress)
                 {
                     if (this.interactive)
                     {
-                        this.onPress();
+                        if (!this.dragActivate || (!wasHover || mouseWasPressed(0)))
+                            this.onPress();
                         if (this.soundPress)
                             this.soundPress.play();
                         if (uiSystem.activeObject && !isActive)
@@ -7674,13 +8059,15 @@ class UIObject
                         uiSystem.activeObject = this;
                     }
                 }
-                if (!mouseDown && uiSystem.activeObject === this && this.interactive)
+                if (!mouseDown && this.isActiveObject() && this.interactive)
                 {
                     this.onClick();
                     if (this.soundClick)
                         this.soundClick.play();
                 }
             }
+            // clear mouse was pressed state even when disabled
+            mousePress && inputClearKey(0,0,0,1,0);
         }
         if (isActive)
         if (!mouseDown || (this.dragActivate && !this.isHoverObject()))
@@ -7691,6 +8078,7 @@ class UIObject
             uiSystem.activeObject = undefined;
         }
 
+        // call enter/leave events
         if (this.isHoverObject() !== wasHover)
             this.isHoverObject() ? this.onEnter() : this.onLeave();
     }
@@ -7701,7 +8089,7 @@ class UIObject
         if (!this.size.x || !this.size.y) return;
 
         const lineColor = this.interactive && this.isActiveObject() && !this.disabled ? this.color : this.lineColor;
-        const color = this.interactive ? this.disabled ? this.disabledColor : this.isActiveObject() ? this.activeColor || this.color : this.isHoverObject() ? this.hoverColor : this.color : this.color;
+        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);
     }
 
@@ -7752,6 +8140,7 @@ class UIObject
 /** 
  * UIText - A UI object that displays text
  * @extends UIObject
+ * @memberof UISystem
  */
 class UIText extends UIObject
 {
@@ -7766,6 +8155,10 @@ class UIText extends UIObject
     {
         super(pos, size);
 
+        ASSERT(isString(text), 'ui text must be a string');
+        ASSERT(['left','center','right'].includes(align), 'ui text align must be left, center, or right');
+        ASSERT(isString(font), 'ui text font must be a string');
+
         // set properties
         this.text = text;
         this.align = align;
@@ -7773,11 +8166,13 @@ class UIText extends UIObject
 
         // make text not outlined by default
         this.lineWidth = 0;
+        // text can not be a hover object by default
+        this.canBeHover = false;
     }
     render()
     {
         const textSize = this.getTextSize();
-        uiSystem.drawText(this.text, this.pos, textSize, this.textColor, this.lineWidth, this.lineColor, this.align, this.font);
+        uiSystem.drawText(this.text, this.pos, textSize, this.textColor, this.lineWidth, this.lineColor, this.align, this.font, this.fontStyle);
     }
 }
 
@@ -7785,6 +8180,7 @@ class UIText extends UIObject
 /** 
  * UITile - A UI object that displays a tile image
  * @extends UIObject
+ * @memberof UISystem
  */
 class UITile extends UIObject
 {
@@ -7799,15 +8195,19 @@ class UITile extends UIObject
     constructor(pos, size, tileInfo, color=WHITE, angle=0, mirror=false)
     {
         super(pos, size);
+
+        ASSERT(tileInfo instanceof TileInfo, 'ui tile tileInfo must be a TileInfo');
+        ASSERT(isColor(color), 'ui tile color must be a color');
+        ASSERT(isNumber(angle), 'ui tile angle must be a number');
+
         /** @property {TileInfo} - Tile image to use */
         this.tileInfo = tileInfo;
         /** @property {number} - Angle to rotate in radians */
         this.angle = angle;
         /** @property {boolean} - Should it be mirrored? */
         this.mirror = mirror;
-        
         // set properties
-        this.color = color;
+        this.color = color.copy();
     }
     render()
     {
@@ -7819,6 +8219,7 @@ class UITile extends UIObject
 /** 
  * UIButton - A UI object that acts as a button
  * @extends UIObject
+ * @memberof UISystem
  */
 class UIButton extends UIObject
 {
@@ -7832,9 +8233,12 @@ class UIButton extends UIObject
     {
         super(pos, size);
 
+        ASSERT(isString(text), 'ui button must be a string');
+        ASSERT(isColor(color), 'ui button color must be a color');
+
         // set properties
         this.text = text;
-        this.color = color;
+        this.color = color.copy();
         this.interactive = true;
     }
     render()
@@ -7844,7 +8248,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.textColor, 0, undefined, this.align, this.font, this.fontStyle);
     }
 }
 
@@ -7852,6 +8256,7 @@ class UIButton extends UIObject
 /** 
  * UICheckbox - A UI object that acts as a checkbox
  * @extends UIObject
+ * @memberof UISystem
  */
 class UICheckbox extends UIObject
 {
@@ -7865,12 +8270,15 @@ class UICheckbox extends UIObject
     constructor(pos, size, checked=false, text='', color=uiSystem.defaultButtonColor)
     {
         super(pos, size);
+
+        ASSERT(isString(text), 'ui checkbox must be a string');
+        ASSERT(isColor(color), 'ui checkbox color must be a color');
+
         /** @property {boolean} - Current percentage value of this scrollbar 0-1 */
         this.checked = checked;
-
         // set properties
         this.text = text;
-        this.color = color;
+        this.color = color.copy();
         this.interactive = true;
     }
     onClick()
@@ -7894,7 +8302,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, false);
+            this.textColor, 0, undefined, 'left', this.font, this.fontStyle, false);
     }
 }
 
@@ -7902,6 +8310,7 @@ class UICheckbox extends UIObject
 /** 
  * UIScrollbar - A UI object that acts as a scrollbar
  * @extends UIObject
+ * @memberof UISystem
  */
 class UIScrollbar extends UIObject
 {
@@ -7917,14 +8326,19 @@ class UIScrollbar extends UIObject
     {
         super(pos, size);
 
+        ASSERT(isNumber(value), 'ui scrollbar value must be a number');
+        ASSERT(isString(text), 'ui scrollbar must be a string');
+        ASSERT(isColor(color), 'ui scrollbar color must be a color');
+        ASSERT(isColor(handleColor), 'ui scrollbar handleColor must be a color');
+
         /** @property {number} - Current percentage value of this scrollbar 0-1 */
         this.value = value;
         /** @property {Color} - Color for the handle part of the scrollbar */
-        this.handleColor = handleColor;
+        this.handleColor = handleColor.copy();
 
         // set properties
         this.text = text;
-        this.color = color;
+        this.color = color.copy();
         this.interactive = true;
     }
     update()
@@ -7932,34 +8346,47 @@ class UIScrollbar extends UIObject
         super.update();
         if (this.isActiveObject() && this.interactive)
         {
+            // handle horizontal or vertical scrollbar
+            const isHorizontal = this.size.x > this.size.y;
+            const handleSize = isHorizontal ? this.size.y : this.size.x;
+            const barSize = isHorizontal ? this.size.x : this.size.y;
+            const centerPos = isHorizontal ? this.pos.x : this.pos.y;
+
             // check if value changed
-            const handleSize = vec2(this.size.y);
-            const handleWidth = this.size.x - handleSize.x;
-            const p1 = this.pos.x - handleWidth/2;
-            const p2 = this.pos.x + handleWidth/2;
+            const handleWidth = barSize - handleSize;
+            const p1 = centerPos - handleWidth/2;
+            const p2 = centerPos + handleWidth/2;
             const oldValue = this.value;
-            this.value = percent(mousePosScreen.x, p1, p2);
+            this.value = isHorizontal ? 
+                percent(mousePosScreen.x, p1, p2) :
+                percent(mousePosScreen.y, p2, p1);
             this.value === oldValue || this.onChange();
         }
     }
     render()
     {
         super.render();
-    
+
+        // handle horizontal or vertical scrollbar
+        const isHorizontal = this.size.x > this.size.y;
+        const handleSize = isHorizontal ? this.size.y : this.size.x;
+        const barSize = isHorizontal ? this.size.x : this.size.y;
+        const centerPos = isHorizontal ? this.pos.x : this.pos.y;
+        
         // draw the scrollbar handle
-        const handleSize = vec2(this.size.y);
-        const handleWidth = this.size.x - handleSize.x;
-        const p1 = this.pos.x - handleWidth/2;
-        const p2 = this.pos.x + handleWidth/2;
-        const handlePos = vec2(lerp(p1, p2, this.value), this.pos.y);
-        const handleColor = this.disabled ? this.disabledColor : 
-            this.interactive && this.isActiveObject() ? this.color : this.handleColor;
-        uiSystem.drawRect(handlePos, handleSize, handleColor, this.lineWidth, this.lineColor, this.cornerRadius);
+        const handleWidth = barSize - handleSize;
+        const p1 = centerPos - handleWidth/2;
+        const p2 = centerPos + handleWidth/2;
+        const handlePos = isHorizontal ? 
+            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);
 
         // 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.textColor, 0, undefined, this.align, this.font, this.fontStyle);
     }
 }
 /**
@@ -8001,6 +8428,7 @@ function box2dSetDebug(enable) { box2dDebug = enable; }
  * - Each object has a Box2D body which can have multiple fixtures and joints
  * - Provides interface for Box2D body and fixture functions
  * @extends EngineObject
+ * @memberof Box2D
  */
 class Box2dObject extends EngineObject 
 {
@@ -8012,7 +8440,7 @@ class Box2dObject extends EngineObject
      *  @param {Color}    [color]
      *  @param {number}   [bodyType]
      *  @param {number}   [renderOrder] */
-    constructor(pos=vec2(), size, tileInfo, angle=0, color, bodyType=box2d.bodyTypeDynamic, renderOrder=0)
+    constructor(pos, size, tileInfo, angle=0, color, bodyType=box2d.bodyTypeDynamic, renderOrder=0)
     {
         super(pos, size, tileInfo, angle, color, renderOrder);
 
@@ -8026,7 +8454,7 @@ class Box2dObject extends EngineObject
         this.lineColor = BLACK;
     }
 
-    /** Destroy this object and it's physics body */
+    /** Destroy this object and its physics body */
     destroy()
     {
         // destroy physics body, fixtures, and joints
@@ -8510,6 +8938,7 @@ class Box2dRaycastResult
  * Box2D Joint
  * - Base class for Box2D joints 
  * - A joint is used to connect objects together
+ * @memberof Box2D
  */
 class Box2dJoint
 {
@@ -8565,6 +8994,7 @@ class Box2dJoint
  * - This a soft constraint with a max force
  * - This allows the constraint to stretch and without applying huge forces
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dTargetJoint extends Box2dJoint
 {
@@ -8614,6 +9044,7 @@ class Box2dTargetJoint extends Box2dJoint
  * - Constrains two points on two objects to remain at a fixed distance
  * - You can view this as a massless, rigid rod
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dDistanceJoint extends Box2dJoint
 {
@@ -8677,6 +9108,7 @@ class Box2dDistanceJoint extends Box2dJoint
  * Box2D Pin Joint
  * - Pins two objects together at a point
  * @extends Box2dDistanceJoint
+ * @memberof Box2D
  */
 class Box2dPinJoint extends Box2dDistanceJoint
 {
@@ -8696,6 +9128,7 @@ class Box2dPinJoint extends Box2dDistanceJoint
  * Box2D Rope Joint
  * - Enforces a maximum distance between two points on two objects
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dRopeJoint extends Box2dJoint
 {
@@ -8748,6 +9181,7 @@ class Box2dRopeJoint extends Box2dJoint
  * - You can use a motor to drive the relative rotation about the shared point
  * - A maximum motor torque is provided so that infinite forces are not generated
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dRevoluteJoint extends Box2dJoint
 {
@@ -8849,6 +9283,7 @@ class Box2dRevoluteJoint extends Box2dJoint
  * - Either joint can be a revolute or prismatic joint
  * - You specify a gear ratio to bind the motions together
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dGearJoint extends Box2dJoint
 {
@@ -8897,6 +9332,7 @@ class Box2dGearJoint extends Box2dJoint
  * - You can use a joint limit to restrict the range of motion
  * - You can use a joint motor to drive the motion or to model joint friction
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dPrismaticJoint extends Box2dJoint
 {
@@ -9006,6 +9442,7 @@ class Box2dPrismaticJoint extends Box2dJoint
  * - You can use a joint motor to drive the motion or to model joint friction
  * - This joint is designed for vehicle suspensions
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dWheelJoint extends Box2dJoint
 {
@@ -9101,6 +9538,7 @@ class Box2dWheelJoint extends Box2dJoint
  * Box2D Weld Joint
  * - Glues two objects together
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dWeldJoint extends Box2dJoint
 {
@@ -9159,6 +9597,7 @@ class Box2dWeldJoint extends Box2dJoint
  * - Used to apply top-down friction
  * - Provides 2D translational friction and angular friction
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dFrictionJoint extends Box2dJoint
 {
@@ -9213,6 +9652,7 @@ class Box2dFrictionJoint extends Box2dJoint
  * - The pulley supports a ratio such that: length1 + ratio * length2 <= constant
  * - The force transmitted is scaled by the ratio
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dPulleyJoint extends Box2dJoint
 {
@@ -9280,6 +9720,7 @@ class Box2dPulleyJoint extends Box2dJoint
  * - Controls the relative motion between two objects
  * - Typical usage is to control the movement of a object with respect to the ground
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dMotorJoint extends Box2dJoint
 {
@@ -9343,6 +9784,7 @@ class Box2dMotorJoint extends Box2dJoint
 /** 
  * Box2D Global Object
  * - Wraps Box2d world and provides global functions
+ * @memberof Box2D
  */
 class Box2dPlugin
 {