littlejsengine 1.12.6 → 1.13.1

package/src/engineUtilities.js

@@ -22,19 +22,17 @@ const PI = Math.PI;
  *  @memberof Utilities */
 function abs(value) { return Math.abs(value); }
 
-/** Returns lowest of two values passed in
- *  @param {number} valueA
- *  @param {number} valueB
+/** Returns lowest value passed in
+ *  @param {...number} values
  *  @return {number}
  *  @memberof Utilities */
-function min(valueA, valueB) { return Math.min(valueA, valueB); }
+function min(...values) { return Math.min(...values); }
 
-/** Returns highest of two values passed in
- *  @param {number} valueA
- *  @param {number} valueB
+/** Returns highest value passed in
+ *  @param {...number} values
  *  @return {number}
  *  @memberof Utilities */
-function max(valueA, valueB) { return Math.max(valueA, valueB); }
+function max(...values) { return Math.max(...values); }
 
 /** Returns the sign of value passed in
  *  @param {number} value
@@ -67,12 +65,17 @@ function percent(value, valueA, valueB)
 { return (valueB-=valueA) ? clamp((value-valueA)/valueB) : 0; }
 
 /** Linearly interpolates between values passed in using percent
- *  @param {number} percent
  *  @param {number} valueA
  *  @param {number} valueB
+ *  @param {number} percent
  *  @return {number}
  *  @memberof Utilities */
-function lerp(percent, valueA, valueB) { return valueA + clamp(percent) * (valueB-valueA); }
+function lerp(valueA, valueB, percent)
+{
+    if (valueA >= 0 && valueA <= 1 && ((valueB < 0 || valueB > 1) && (percent < 0 || percent > 1)))
+        console.warn('lerp() parameter order changed! use lerp(start, end, p)');
+    return valueA + clamp(percent) * (valueB-valueA);
+ }
 
 /** Returns signed wrapped distance between the two values passed in
  *  @param {number} valueA
@@ -84,14 +87,18 @@ function distanceWrap(valueA, valueB, wrapSize=1)
 { const d = (valueA - valueB) % wrapSize; return d*2 % wrapSize - d; }
 
 /** Linearly interpolates between values passed in with wrapping
- *  @param {number} percent
  *  @param {number} valueA
  *  @param {number} valueB
+ *  @param {number} percent
  *  @param {number} [wrapSize]
  *  @returns {number}
  *  @memberof Utilities */
-function lerpWrap(percent, valueA, valueB, wrapSize=1)
-{ return valueA + clamp(percent) * distanceWrap(valueB, valueA, wrapSize); }
+function lerpWrap(valueA, valueB, percent, wrapSize=1)
+{
+    if (valueA >= 0 && valueA <= 1 && ((valueB < 0 || valueB > 1) && (percent < 0 || percent > 1)))
+        console.warn('lerpWrap() parameter order changed! use lerpWrap(start, end, p)');
+    return valueA + clamp(percent) * distanceWrap(valueB, valueA, wrapSize);
+}
 
 /** Returns signed wrapped distance between the two angles passed in
  *  @param {number} angleA
@@ -101,12 +108,12 @@ function lerpWrap(percent, valueA, valueB, wrapSize=1)
 function distanceAngle(angleA, angleB) { return distanceWrap(angleA, angleB, 2*PI); }
 
 /** Linearly interpolates between the angles passed in with wrapping
- *  @param {number} percent
  *  @param {number} angleA
  *  @param {number} angleB
+ *  @param {number} percent
  *  @returns {number}
  *  @memberof Utilities */
-function lerpAngle(percent, angleA, angleB) { return lerpWrap(percent, angleA, angleB, 2*PI); }
+function lerpAngle(angleA, angleB, percent) { return lerpWrap(angleA, angleB, percent, 2*PI); }
 
 /** Applies smoothstep function to the percentage value
  *  @param {number} percent
@@ -114,6 +121,12 @@ function lerpAngle(percent, angleA, angleB) { return lerpWrap(percent, angleA, a
  *  @memberof Utilities */
 function smoothStep(percent) { return percent * percent * (3 - 2 * percent); }
 
+/** Checks if the value passed in is a power of two
+ *  @param {number} value
+ *  @return {boolean}
+ *  @memberof Utilities */
+function isPowerOfTwo(value) { return !(value & (value - 1)); }
+
 /** Returns the nearest power of two not less then the value
  *  @param {number} value
  *  @return {number}
@@ -199,6 +212,14 @@ async function fetchJSON(url)
     return response.json();
 }
 
+/** 
+ * Check if object is a valid number, not NaN or undefined, but it may be infinite
+ * @param {any} n
+ * @return {boolean}
+ * @memberof Utilities
+ */
+function isNumber(n) { return typeof n == 'number' && !isNaN(n); }
+
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Random global functions
@@ -219,6 +240,12 @@ function rand(valueA=1, valueB=0) { return valueB + Math.random() * (valueA-valu
  *  @memberof Random */
 function randInt(valueA, valueB=0) { return Math.floor(rand(valueA,valueB)); }
 
+/** Randomly returns true or false given the chance of true passed in
+ *  @param {number} [chance]
+ *  @return {boolean}
+ *  @memberof Random */
+function randBool(chance=.5) { return rand() < chance; }
+
 /** Randomly returns either -1 or 1
  *  @return {number}
  *  @memberof Random */
@@ -228,7 +255,7 @@ function randSign() { return randInt(2) * 2 - 1; }
  *  @param {number} [length]
  *  @return {Vector2}
  *  @memberof Random */
-function randVector(length=1) { return new Vector2().setAngle(rand(2*PI), length); }
+function randVec2(length=1) { return new Vector2().setAngle(rand(2*PI), length); }
 
 /** Returns a random Vector2 within a circular shape
  *  @param {number} [radius]
@@ -236,7 +263,7 @@ function randVector(length=1) { return new Vector2().setAngle(rand(2*PI), length
  *  @return {Vector2}
  *  @memberof Random */
 function randInCircle(radius=1, minRadius=0)
-{ return radius > 0 ? randVector(radius * rand(minRadius / radius, 1)**.5) : new Vector2; }
+{ return radius > 0 ? randVec2(radius * rand(minRadius / radius, 1)**.5) : new Vector2; }
 
 /** Returns a random color between the two passed in colors, combine components if linear
  *  @param {Color}   [colorA=(1,1,1,1)]
@@ -265,8 +292,8 @@ function randColor(colorA=new Color, colorB=new Color(0,0,0,1), linear=false)
 class RandomGenerator
 {
     /** Create a random number generator with the seed passed in
-     *  @param {number} seed - Starting seed */
-    constructor(seed)
+     *  @param {number} [seed] - Starting seed or engine default seed */
+    constructor(seed = 123456789)
     {
         /** @property {number} - random seed */
         this.seed = seed;
@@ -291,6 +318,11 @@ class RandomGenerator
     *  @return {number} */
     int(valueA, valueB=0) { return Math.floor(this.float(valueA, valueB)); }
 
+    /** Randomly returns true or false given the chance of true passed in
+    *  @param {number} [chance]
+    *  @return {boolean} */
+    bool(chance=.5) { return this.float() < chance; }
+
     /** Randomly returns either -1 or 1 deterministically
     *  @return {number} */
     sign() { return this.float() > .5 ? 1 : -1; }
@@ -300,11 +332,22 @@ class RandomGenerator
     *  @param {number} [valueB]
     *  @return {number} */
     floatSign(valueA=1, valueB=0) { return this.float(valueA, valueB) * this.sign(); }
+
+    /** Returns a random angle between -PI and PI
+    *  @return {number} */
+    angle() { return this.float(-PI, PI); }
+
+    /** Returns a seeded vec2 with size between the two values passed in
+    *  @param {number} valueA
+    *  @param {number} [valueB]
+    *  @return {Vector2} */
+    vec2(valueA=1, valueB=0)
+    { return vec2(this.float(valueA, valueB), this.float(valueA, valueB)); }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 
-/** 
+/**
  * Create a 2d vector, can take 1 or 2 scalar values
  * @param {number} [x]
  * @param {number} [y] - if y is undefined, x is used for both
@@ -315,7 +358,7 @@ class RandomGenerator
  * b = vec2();         // set b to (0, 0)
  * @memberof Utilities
  */
-function vec2(x=0, y) { return new Vector2(x, y == undefined? x : y); }
+function vec2(x=0, y) { return new Vector2(x, y === undefined ? x : y); }
 
 /** 
  * Check if object is a valid Vector2
@@ -325,6 +368,15 @@ function vec2(x=0, y) { return new Vector2(x, y == undefined? x : y); }
  */
 function isVector2(v) { return v instanceof Vector2; }
 
+// vector2 asserts
+function ASSERT_VECTOR2_VALID(v) { ASSERT(isVector2(v) && v.isValid(), 'Vector2 is invalid.', v); }
+function ASSERT_NUMBER_VALID(n) { ASSERT(isNumber(n), 'Number is invalid.', n); }
+function ASSERT_VECTOR2_NORMAL(v)
+{
+    ASSERT_VECTOR2_VALID(v);
+    ASSERT(abs(v.lengthSquared()-1) < .01, 'Vector2 is not normal.', v); 
+}
+
 /** 
  * 2D Vector object with vector math library
  * - Functions do not change this so they can be chained together
@@ -345,7 +397,7 @@ class Vector2
         this.x = x;
         /** @property {number} - Y axis location */
         this.y = y;
-        ASSERT(this.isValid());
+        ASSERT(this.isValid(), 'Constructed Vector2 is invalid.', this);
     }
 
     /** Sets values of this vector and returns self
@@ -356,7 +408,6 @@ class Vector2
     {
         this.x = x;
         this.y = y;
-        ASSERT(this.isValid());
         return this;
     }
 
@@ -367,47 +418,27 @@ class Vector2
     /** Returns a copy of this vector plus the vector passed in
      *  @param {Vector2} v - other vector
      *  @return {Vector2} */
-    add(v)
-    {
-        ASSERT(isVector2(v));
-        return new Vector2(this.x + v.x, this.y + v.y);
-    }
+    add(v) { return new Vector2(this.x + v.x, this.y + v.y);}
 
     /** Returns a copy of this vector minus the vector passed in
      *  @param {Vector2} v - other vector
      *  @return {Vector2} */
-    subtract(v)
-    {
-        ASSERT(isVector2(v));
-        return new Vector2(this.x - v.x, this.y - v.y);
-    }
+    subtract(v) { return new Vector2(this.x - v.x, this.y - v.y); }
 
     /** Returns a copy of this vector times the vector passed in
      *  @param {Vector2} v - other vector
      *  @return {Vector2} */
-    multiply(v)
-    {
-        ASSERT(isVector2(v));
-        return new Vector2(this.x * v.x, this.y * v.y);
-    }
+    multiply(v) { return new Vector2(this.x * v.x, this.y * v.y); }
 
     /** Returns a copy of this vector divided by the vector passed in
      *  @param {Vector2} v - other vector
      *  @return {Vector2} */
-    divide(v)
-    {
-        ASSERT(isVector2(v));
-        return new Vector2(this.x / v.x, this.y / v.y);
-    }
+    divide(v) { return new Vector2(this.x / v.x, this.y / v.y); }
 
     /** Returns a copy of this vector scaled by the vector passed in
      *  @param {number} s - scale
      *  @return {Vector2} */
-    scale(s)
-    {
-        ASSERT(!isVector2(s));
-        return new Vector2(this.x * s, this.y * s);
-    }
+    scale(s) { return new Vector2(this.x * s, this.y * s); }
 
     /** Returns the length of this vector
      * @return {number} */
@@ -420,20 +451,12 @@ class Vector2
     /** Returns the distance from this vector to vector passed in
      * @param {Vector2} v - other vector
      * @return {number} */
-    distance(v)
-    {
-        ASSERT(isVector2(v));
-        return this.distanceSquared(v)**.5;
-    }
+    distance(v) { return this.distanceSquared(v)**.5; }
 
     /** Returns the distance squared from this vector to vector passed in
      * @param {Vector2} v - other vector
      * @return {number} */
-    distanceSquared(v)
-    {
-        ASSERT(isVector2(v));
-        return (this.x - v.x)**2 + (this.y - v.y)**2;
-    }
+    distanceSquared(v) { return (this.x - v.x)**2 + (this.y - v.y)**2; }
 
     /** Returns a new vector in same direction as this one with the length passed in
      * @param {number} [length]
@@ -456,20 +479,19 @@ class Vector2
     /** Returns the dot product of this and the vector passed in
      * @param {Vector2} v - other vector
      * @return {number} */
-    dot(v)
-    {
-        ASSERT(isVector2(v));
-        return this.x*v.x + this.y*v.y;
-    }
+    dot(v) { return this.x*v.x + this.y*v.y; }
 
     /** Returns the cross product of this and the vector passed in
      * @param {Vector2} v - other vector
      * @return {number} */
-    cross(v)
-    {
-        ASSERT(isVector2(v));
-        return this.x*v.y - this.y*v.x;
-    }
+    cross(v) { return this.x*v.y - this.y*v.x; }
+
+    /** Returns a copy this vector reflected by the surface normal
+     * @param {Vector2} normal - surface normal (should be normalized)
+     * @param {number} restitution - how much to bounce, 1 is perfect bounce, 0 is no bounce
+     * @return {Vector2} */
+    reflect(normal, restitution=1)
+    { return this.subtract(normal.scale((1+restitution)*this.dot(normal))); }
 
     /** Returns the clockwise angle of this vector, up is angle 0
      * @return {number} */
@@ -481,6 +503,8 @@ class Vector2
      * @return {Vector2} */
     setAngle(angle=0, length=1) 
     {
+        ASSERT_NUMBER_VALID(angle);
+        ASSERT_NUMBER_VALID(length);
         this.x = length*Math.sin(angle);
         this.y = length*Math.cos(angle);
         return this;
@@ -490,7 +514,8 @@ class Vector2
      * @param {number} angle
      * @return {Vector2} */
     rotate(angle)
-    { 
+    {
+        ASSERT_NUMBER_VALID(angle);
         const c = Math.cos(-angle), s = Math.sin(-angle); 
         return new Vector2(this.x*c - this.y*s, this.x*s + this.y*c);
     }
@@ -500,8 +525,11 @@ class Vector2
      * @param {number} [length] */
     setDirection(direction, length=1)
     {
+        ASSERT_NUMBER_VALID(direction);
+        ASSERT_NUMBER_VALID(length);
         direction = mod(direction, 4);
-        ASSERT(direction==0 || direction==1 || direction==2 || direction==3);
+        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);
     }
@@ -515,10 +543,20 @@ class Vector2
      * @return {Vector2} */
     invert() { return new Vector2(this.y, -this.x); }
 
+    /** Returns a copy of this vector absolute values
+     * @return {Vector2} */
+    abs() { return new Vector2(abs(this.x), abs(this.y)); }
+
     /** Returns a copy of this vector with each axis floored
      * @return {Vector2} */
     floor() { return new Vector2(Math.floor(this.x), Math.floor(this.y)); }
 
+    /** Returns new vec2 with modded values
+    *  @param {number} [divisor]
+    *  @return {Vector2} */
+    mod(divisor=1)
+    { return new Vector2(mod(this.x, divisor), mod(this.y, divisor)); }
+
     /** Returns the area this vector covers as a rectangle
      * @return {number} */
     area() { return abs(this.x * this.y); }
@@ -529,35 +567,36 @@ class Vector2
      * @return {Vector2} */
     lerp(v, percent)
     {
-        ASSERT(isVector2(v));
-        return this.add(v.subtract(this).scale(clamp(percent)));
+        ASSERT_VECTOR2_VALID(v);
+        ASSERT_NUMBER_VALID(percent);
+        const p = clamp(percent);
+        return new Vector2(v.x*p + this.x*(1-p), v.y*p + this.y*(1-p));
     }
 
     /** Returns true if this vector is within the bounds of an array size passed in
      * @param {Vector2} arraySize
      * @return {boolean} */
     arrayCheck(arraySize)
-    {
-        ASSERT(isVector2(arraySize));
-        return this.x >= 0 && this.y >= 0 && this.x < arraySize.x && this.y < arraySize.y;
-    }
+    { return this.x >= 0 && this.y >= 0 && this.x < arraySize.x && this.y < arraySize.y; }
 
     /** Returns this vector expressed as a string
      * @param {number} digits - precision to display
      * @return {string} */
     toString(digits=3) 
     {
+        ASSERT_NUMBER_VALID(digits);
         if (debug)
-            return `(${(this.x<0?'':' ') + this.x.toFixed(digits)},${(this.y<0?'':' ') + this.y.toFixed(digits)} )`;
+        {
+            if (this.isValid())
+                return `(${(this.x<0?'':' ') + this.x.toFixed(digits)},${(this.y<0?'':' ') + this.y.toFixed(digits)} )`;
+            else
+                return `(${this.x}, ${this.y})`;
+        }
     }
 
     /** Checks if this is a valid vector
      * @return {boolean} */
-    isValid()
-    {
-        return typeof this.x == 'number' && !isNaN(this.x)
-            && typeof this.y == 'number' && !isNaN(this.y);
-    }
+    isValid() { return isNumber(this.x) && isNumber(this.y); }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -592,13 +631,16 @@ function hsl(h, s, l, a) { return new Color().setHSLA(h, s, l, a); }
  */
 function isColor(c) { return c instanceof Color; }
 
+// color asserts
+function ASSERT_COLOR_VALID(c) { ASSERT(isColor(c) && c.isValid(), 'Color is invalid.', c); }
+
 /** 
  * Color object (red, green, blue, alpha) with some helpful functions
  * @example
  * let a = new Color;              // white
  * let b = new Color(1, 0, 0);     // red
  * let c = new Color(0, 0, 0, 0);  // transparent black
- * let d = rgb(0, 0, 1);           // blue using rgb color
+ * let d = rgb(0, 0, 1);         // blue using rgb color
  * let e = hsl(.3, 1, .5);         // green using hsl color
  */
 class Color
@@ -618,7 +660,7 @@ class Color
         this.b = b;
         /** @property {number} - Alpha */
         this.a = a;
-        ASSERT(this.isValid());
+        ASSERT(this.isValid(), 'Constructed Color is invalid.', this);
     }
 
     /** Sets values of this color and returns self
@@ -633,7 +675,6 @@ class Color
         this.g = g;
         this.b = b;
         this.a = a;
-        ASSERT(this.isValid());
         return this;
     }
 
@@ -644,38 +685,22 @@ class Color
     /** Returns a copy of this color plus the color passed in
      * @param {Color} c - other color
      * @return {Color} */
-    add(c)
-    {
-        ASSERT(isColor(c));
-        return new Color(this.r+c.r, this.g+c.g, this.b+c.b, this.a+c.a);
-    }
+    add(c) { return new Color(this.r+c.r, this.g+c.g, this.b+c.b, this.a+c.a); }
 
     /** Returns a copy of this color minus the color passed in
      * @param {Color} c - other color
      * @return {Color} */
-    subtract(c)
-    {
-        ASSERT(isColor(c));
-        return new Color(this.r-c.r, this.g-c.g, this.b-c.b, this.a-c.a);
-    }
+    subtract(c) { return new Color(this.r-c.r, this.g-c.g, this.b-c.b, this.a-c.a); }
 
     /** Returns a copy of this color times the color passed in
      * @param {Color} c - other color
      * @return {Color} */
-    multiply(c)
-    {
-        ASSERT(isColor(c));
-        return new Color(this.r*c.r, this.g*c.g, this.b*c.b, this.a*c.a);
-    }
+    multiply(c) { return new Color(this.r*c.r, this.g*c.g, this.b*c.b, this.a*c.a); }
 
     /** Returns a copy of this color divided by the color passed in
      * @param {Color} c - other color
      * @return {Color} */
-    divide(c)
-    {
-        ASSERT(isColor(c));
-        return new Color(this.r/c.r, this.g/c.g, this.b/c.b, this.a/c.a);
-    }
+    divide(c) { return new Color(this.r/c.r, this.g/c.g, this.b/c.b, this.a/c.a); }
 
     /** Returns a copy of this color scaled by the value passed in, alpha can be scaled separately
      * @param {number} scale
@@ -694,8 +719,14 @@ class Color
      * @return {Color} */
     lerp(c, percent)
     {
-        ASSERT(isColor(c));
-        return this.add(c.subtract(this).scale(clamp(percent)));
+        ASSERT_COLOR_VALID(c);
+        ASSERT_NUMBER_VALID(percent);
+        const p = clamp(percent);
+        return new Color(
+            c.r*p + this.r*(1-p), 
+            c.g*p + this.g*(1-p), 
+            c.b*p + this.b*(1-p), 
+            c.a*p + this.a*(1-p));
     }
 
     /** Sets this color given a hue, saturation, lightness, and alpha
@@ -718,7 +749,7 @@ class Color
         this.g = f(p, q, h);
         this.b = f(p, q, h - 1/3);
         this.a = a;
-        ASSERT(this.isValid());
+        ASSERT_COLOR_VALID(this);
         return this;
     }
 
@@ -730,20 +761,19 @@ class Color
         const g = clamp(this.g);
         const b = clamp(this.b);
         const a = clamp(this.a);
-        const max = Math.max(r, g, b);
-        const min = Math.min(r, g, b);
-        const l = (max + min) / 2;
-        
+        const maxC = max(r, g, b);
+        const minC = min(r, g, b);
+        const l = (maxC + minC) / 2;
         let h = 0, s = 0;
-        if (max != min)
+        if (maxC != minC)
         {
-            let d = max - min;
-            s = l > .5 ? d / (2 - max - min) : d / (max + min);
-            if (r == max)
+            let d = maxC - minC;
+            s = l > .5 ? d / (2 - maxC - minC) : d / (maxC + minC);
+            if (r == maxC)
                 h = (g - b) / d + (g < b ? 6 : 0);
-            else if (g == max)
+            else if (g == maxC)
                 h = (b - r) / d + 2;
-            else if (b == max)
+            else if (b == maxC)
                 h =  (r - g) / d + 4;
         }
         return [h / 6, s, l, a];
@@ -755,6 +785,8 @@ class Color
      * @return {Color} */
     mutate(amount=.05, alphaAmount=0) 
     {
+        ASSERT_NUMBER_VALID(amount);
+        ASSERT_NUMBER_VALID(alphaAmount);
         return new Color
         (
             this.r + rand(amount, -amount),
@@ -768,7 +800,10 @@ class Color
      * @param {boolean} [useAlpha] - if alpha should be included in result
      * @return {string} */
     toString(useAlpha = true)      
-    { 
+    {
+        ASSERT(typeof useAlpha == 'boolean', 'Use alpha boolean is invalid.', useAlpha);
+        if (debug && !this.isValid())
+            return `#000`;
         const toHex = (c)=> ((c=clamp(c)*255|0)<16 ? '0' : '') + c.toString(16);
         return '#' + toHex(this.r) + toHex(this.g) + toHex(this.b) + (useAlpha ? toHex(this.a) : '');
     }
@@ -778,7 +813,7 @@ class Color
      * @return {Color} */
     setHex(hex)
     {
-        ASSERT(typeof hex == 'string' && hex[0] == '#');
+        ASSERT(typeof hex == 'string' && hex[0] == '#', 'Color hex code must be a string starting with #');
         ASSERT([4,5,7,9].includes(hex.length), 'Invalid hex');
 
         if (hex.length < 6)
@@ -798,7 +833,7 @@ class Color
             this.a = hex.length == 9 ? fromHex(7) : 1;
         }
 
-        ASSERT(this.isValid());
+        ASSERT_COLOR_VALID(this);
         return this;
     }
     
@@ -816,11 +851,8 @@ class Color
     /** Checks if this is a valid color
      * @return {boolean} */
     isValid()
-    {
-        return typeof this.r == 'number' && !isNaN(this.r)
-            && typeof this.g == 'number' && !isNaN(this.g)
-            && typeof this.b == 'number' && !isNaN(this.b)
-            && typeof this.a == 'number' && !isNaN(this.a);
+    { 
+        return isNumber(this.r) && isNumber(this.g) && isNumber(this.b) && isNumber(this.a);
     }
 }
 
@@ -832,11 +864,21 @@ class Color
  *  @memberof Utilities */
 const WHITE = rgb(); 
 
+/** Color - Clear White #ffffff with 0 alpha
+ *  @type {Color}
+ *  @memberof Utilities */
+const CLEAR_WHITE = rgb(1,1,1,0);
+
 /** Color - Black #000000
  *  @type {Color}
  *  @memberof Utilities */
 const BLACK = rgb(0,0,0);
 
+/** Color - Clear Black #000000 with 0 alpha
+ *  @type {Color}
+ *  @memberof Utilities */
+const CLEAR_BLACK = rgb(0,0,0,0);
+
 /** Color - Gray #808080
  *  @type {Color}
  *  @memberof Utilities */
@@ -897,18 +939,28 @@ class Timer
 {
     /** Create a timer object set time passed in
      *  @param {number} [timeLeft] - How much time left before the timer elapses in seconds */
-    constructor(timeLeft) { this.time = timeLeft == undefined ? undefined : time + timeLeft; this.setTime = timeLeft; }
+    constructor(timeLeft)
+    {
+        ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Constructed Timer is invalid.', timeLeft);
+        this.time = timeLeft === undefined ? undefined : time + timeLeft;
+        this.setTime = timeLeft;
+    }
 
     /** Set the timer with seconds passed in
      *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds */
-    set(timeLeft=0) { this.time = time + timeLeft; this.setTime = timeLeft; }
+    set(timeLeft=0)
+    {
+        ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
+        this.time = time + timeLeft;
+        this.setTime = timeLeft;
+    }
 
     /** Unset the timer */
     unset() { this.time = undefined; }
 
     /** Returns true if set
      * @return {boolean} */
-    isSet() { return this.time != undefined; }
+    isSet() { return this.time !== undefined; }
 
     /** Returns true if set and has not elapsed
      * @return {boolean} */
@@ -932,5 +984,5 @@ class Timer
     
     /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
      * @return {number} */
-    valueOf()               { return this.get(); }
+    valueOf() { return this.get(); }
 }