littlejsengine 1.14.11 → 1.14.16

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.16';
 
 /** Frames per second to update
  *  @type {number}
@@ -96,9 +96,14 @@ let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
 
 const pluginUpdateList = [], pluginRenderList = [];
 
+/**
+ * @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} [updateFunction]
+ *  @param {PluginCallback} [renderFunction]
  *  @memberof Engine */
 function engineAddPlugin(updateFunction, renderFunction)
 {
@@ -111,12 +116,22 @@ function engineAddPlugin(updateFunction, renderFunction)
 ///////////////////////////////////////////////////////////////////////////////
 // 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
@@ -368,6 +383,8 @@ 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 = ()=>
             {
@@ -399,7 +416,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 +500,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 +973,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 +985,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 +1054,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 +1151,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 +1292,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 +1303,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 +1402,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 +1580,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 +1623,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 +1756,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 +2093,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 +2116,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 +2191,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 +2236,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 +2326,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 +2366,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 +2375,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 +2671,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 +2745,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 +2758,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 +2897,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 +2942,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
 {
@@ -2928,7 +3003,10 @@ class TileInfo
     }
 }
 
-/** Texture Info - Stores info about each texture */
+/**
+ * Tile Info - Stores info about each texture
+ * @memberof Draw
+ */
 class TextureInfo
 {
     /**
@@ -2974,10 +3052,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 +3151,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 +3212,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 +3287,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 +3314,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 +3367,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 +3411,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
@@ -3412,6 +3504,16 @@ function drawTextOverlay(text, pos, size=1, color, lineWidth=0, lineColor, textA
  *  @memberof Draw */
 function drawTextScreen(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK, textAlign='center', font=fontDefault, 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(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');
+    
     context.fillStyle = color.toString();
     context.strokeStyle = lineColor.toString();
     context.lineWidth = lineWidth;
@@ -3613,6 +3715,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;
@@ -3669,7 +3772,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 +4466,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 +4561,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 +4589,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 +4600,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 +4631,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 +4668,7 @@ class SoundWave extends Sound
         this.sampleChannels = sampleChannels;
         this.loadedPercent = 1;
         if (this.onloadCallback)
-            this.onloadCallback();
+            this.onloadCallback(this);
     }
 }
 
@@ -4562,6 +4677,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]);
@@ -4761,6 +4877,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,7 +4892,7 @@ 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
+ *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
  *  @return {AudioBufferSourceNode} - The audio node of the sound played
  *  @memberof Audio */
 function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sampleRate=audioDefaultSampleRate, gainNode, offset=0, onended)
@@ -4802,16 +4924,14 @@ function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=false, sample
     if (onended)
         source.addEventListener('ended', ()=> onended(source));
 
+    const startOffset = offset * rate;
     if (!audioIsRunning())
     {
-        // fix stalled audio, this sound won't be able to play
-        audioContext.resume();
-        return;
+        // fix stalled audio and start
+        audioContext.resume().then(()=>source.start(0, startOffset));
     }
-
-    // play and return sound
-    const startOffset = offset * rate;
-    source.start(0, startOffset);
+    else
+        source.start(0, startOffset);
     return source;
 }
 
@@ -4976,7 +5096,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 +5104,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 +5126,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 +5144,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 +5167,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 +5199,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 +5228,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 +5266,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,6 +5281,7 @@ 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 */
@@ -5206,12 +5329,18 @@ class CanvasLayer extends EngineObject
         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)
     {
         const context = this.context;
@@ -5248,7 +5377,7 @@ class CanvasLayer extends EngineObject
             else
             {
                 // untextured
-                context.fillStyle = color;
+                context.fillStyle = color.toString();
                 context.fillRect(-.5, -.5, 1, 1);
             }
         });
@@ -5285,7 +5414,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,15 +5426,14 @@ 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, useWebGL=glEnable)
     {
         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);
@@ -5340,6 +5470,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 +5483,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()
@@ -5360,9 +5495,10 @@ class TileLayer extends CanvasLayer
 
         // 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 size = this.drawSize || this.size;
+        const pos = this.pos.add(size.scale(.5));
         const useWebGL = glEnable && this.glTexture !== undefined;
-        drawTile(pos, this.size, tileInfo, WHITE, 0, false, CLEAR_BLACK, useWebGL);
+        drawTile(pos, size, tileInfo, WHITE, 0, false, CLEAR_BLACK, useWebGL);
     }
 
     /** Draw all the tile data to an offscreen canvas
@@ -5454,6 +5590,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
 {
@@ -5466,8 +5603,7 @@ class TileCollisionLayer extends TileLayer
     */
     constructor(position, size, tileInfo=tile(), renderOrder=0, useWebGL=glEnable)
     {
-        const scale = vec2(1); // collision layers are not scaled
-        super(position, size.floor(), tileInfo, scale, renderOrder, useWebGL);
+        super(position, size.floor(), tileInfo, renderOrder, useWebGL);
 
         /** @property {Array<number>} - The tile collision grid */
         this.collisionData = [];
@@ -5497,6 +5633,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 +5645,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 +5655,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 +5667,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 +5700,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 +5752,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);
@@ -5634,10 +5786,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 +5816,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 +5842,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 +5853,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 +5894,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 +5997,7 @@ class ParticleEmitter extends EngineObject
 /**
  * Particle Object - Created automatically by Particle Emitters
  * @extends EngineObject
+ * @memberof Engine
  */
 class Particle extends EngineObject
 {
@@ -5862,7 +6016,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 +6025,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 +6041,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 +6068,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 +6184,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 +6200,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 +6269,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);
@@ -6910,24 +7076,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 +7119,7 @@ class NewgroundsMedal extends Medal
 ///////////////////////////////////////////////////////////////////////////////
 /** 
  * Newgrounds API object
+ * @memberof Newgrounds
  */
 class NewgroundsPlugin
 {
@@ -7087,19 +7255,22 @@ 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
 {
@@ -7207,12 +7378,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 +7445,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 +7549,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
 {
@@ -7429,10 +7607,12 @@ 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;
             
         engineAddPlugin(uiUpdate, uiRender);
 
@@ -7463,6 +7643,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--;)
             {
@@ -7495,6 +7676,13 @@ class UISystemPlugin
     *  @param {number}  [cornerRadius=uiSystem.defaultCornerRadius] */
     drawRect(pos, size, color=uiSystem.defaultColor, lineWidth=uiSystem.defaultLineWidth, lineColor=uiSystem.defaultLineColor, cornerRadius=uiSystem.defaultCornerRadius)
     {
+        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();
         context.beginPath();
@@ -7518,6 +7706,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;
@@ -7553,12 +7746,37 @@ class UISystemPlugin
     {
         drawTextScreen(text, pos, size.y, color, lineWidth, lineColor, align, font, 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)
+    {
+        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 +7785,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,21 +7795,21 @@ 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 {number} - Width for line drawing */
         this.lineWidth = uiSystem.defaultLineWidth;
         /** @property {number} - Corner radius for rounded rects */
@@ -7645,7 +7866,7 @@ class UIObject
     /** 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);
@@ -7658,15 +7879,14 @@ class UIObject
         }
         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 +7894,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 +7913,7 @@ class UIObject
             uiSystem.activeObject = undefined;
         }
 
+        // call enter/leave events
         if (this.isHoverObject() !== wasHover)
             this.isHoverObject() ? this.onEnter() : this.onLeave();
     }
@@ -7701,7 +7924,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 +7975,7 @@ class UIObject
 /** 
  * UIText - A UI object that displays text
  * @extends UIObject
+ * @memberof UISystem
  */
 class UIText extends UIObject
 {
@@ -7766,6 +7990,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;
@@ -7785,6 +8013,7 @@ class UIText extends UIObject
 /** 
  * UITile - A UI object that displays a tile image
  * @extends UIObject
+ * @memberof UISystem
  */
 class UITile extends UIObject
 {
@@ -7799,15 +8028,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 +8052,7 @@ class UITile extends UIObject
 /** 
  * UIButton - A UI object that acts as a button
  * @extends UIObject
+ * @memberof UISystem
  */
 class UIButton extends UIObject
 {
@@ -7832,9 +8066,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()
@@ -7852,6 +8089,7 @@ class UIButton extends UIObject
 /** 
  * UICheckbox - A UI object that acts as a checkbox
  * @extends UIObject
+ * @memberof UISystem
  */
 class UICheckbox extends UIObject
 {
@@ -7865,12 +8103,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()
@@ -7902,6 +8143,7 @@ class UICheckbox extends UIObject
 /** 
  * UIScrollbar - A UI object that acts as a scrollbar
  * @extends UIObject
+ * @memberof UISystem
  */
 class UIScrollbar extends UIObject
 {
@@ -7917,14 +8159,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,29 +8179,43 @@ 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 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.interactive && this.isActiveObject() ? this.color : this.handleColor;
-        uiSystem.drawRect(handlePos, handleSize, handleColor, this.lineWidth, this.lineColor, this.cornerRadius);
+        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();
@@ -8001,6 +8262,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 +8274,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 +8288,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 +8772,7 @@ class Box2dRaycastResult
  * Box2D Joint
  * - Base class for Box2D joints 
  * - A joint is used to connect objects together
+ * @memberof Box2D
  */
 class Box2dJoint
 {
@@ -8565,6 +8828,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 +8878,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 +8942,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 +8962,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 +9015,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 +9117,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 +9166,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 +9276,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 +9372,7 @@ class Box2dWheelJoint extends Box2dJoint
  * Box2D Weld Joint
  * - Glues two objects together
  * @extends Box2dJoint
+ * @memberof Box2D
  */
 class Box2dWeldJoint extends Box2dJoint
 {
@@ -9159,6 +9431,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 +9486,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 +9554,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 +9618,7 @@ class Box2dMotorJoint extends Box2dJoint
 /** 
  * Box2D Global Object
  * - Wraps Box2d world and provides global functions
+ * @memberof Box2D
  */
 class Box2dPlugin
 {