littlejsengine 1.14.11 → 1.14.19

package/src/engineSettings.js

@@ -306,7 +306,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
@@ -329,17 +329,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
@@ -404,7 +404,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
@@ -449,7 +449,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
@@ -539,7 +539,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

package/src/engineTileLayer.js

@@ -4,7 +4,7 @@
  * - 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
  */
 
 'use strict';
@@ -14,13 +14,13 @@
 
 /** 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
@@ -36,7 +36,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)
@@ -54,7 +54,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)
@@ -77,8 +77,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)
     {
@@ -109,9 +109,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--;)
@@ -138,6 +138,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;
@@ -175,6 +176,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));
  */
@@ -189,15 +191,19 @@ class CanvasLayer extends EngineObject
     */
     constructor(position, size, angle=0, renderOrder=0, canvasSize=vec2(512))
     {
+        ASSERT(isVector2(canvasSize), 'canvasSize must be a Vector2');
         super(position, size, undefined, angle, WHITE, renderOrder);
 
         /** @property {HTMLCanvasElement} - The canvas used by this layer */
         this.canvas = headlessMode ? undefined : new OffscreenCanvas(canvasSize.x, canvasSize.y);
         /** @property {OffscreenCanvasRenderingContext2D} - The 2D canvas context used by this layer */
-        this.context = headlessMode ? undefined : this.canvas.getContext('2d');
-        /** @property {WebGLTexture} - Texture if using WebGL for this layer, call useWebGL to enable */
-        this.glTexture = undefined;
-        this.gravityScale = 0; // disable gravity by default for canvas layers
+        this.context = this.canvas?.getContext('2d');
+        /** @property {TextureInfo} - Texture info to use for this object rendering */
+        const useWebGL = false; // do not use webgl by default
+        this.textureInfo = new TextureInfo(this.canvas, useWebGL);
+
+        // disable physics by default
+        this.mass = this.gravityScale = this.friction = this.restitution = 0;
     }
 
     /** Destroy this canvas layer */
@@ -206,9 +212,7 @@ class CanvasLayer extends EngineObject
         if (this.destroyed)
             return;
 
-        // free up the WebGL texture
-        if (this.glTexture)
-            glDeleteTexture(this.glTexture);
+        this.textureInfo.destroyWebGLTexture();
         super.destroy();
     }
 
@@ -231,19 +235,27 @@ class CanvasLayer extends EngineObject
     draw(pos, size, angle=0, color=WHITE, mirror=false, additiveColor, screenSpace=false, context)
     {
         // draw the canvas layer as a single tile that uses the whole texture
-        const useWebGL = glEnable && this.glTexture !== undefined;
-        const tileInfo = new TileInfo().setFullImage(this.canvas, this.glTexture);
+        const useWebGL = glEnable && this.textureInfo.hasWebGL();
+        const tileInfo = new TileInfo().setFullImage(this.textureInfo);
         drawTile(pos, size, tileInfo, color, angle, mirror, additiveColor, useWebGL, screenSpace, context);
     }
 
+    /**
+     * @callback Canvas2DDrawCallback - Function that draws to a canvas 2D context
+     * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+     * @memberof TileLayers
+     */
+
     /** Draw onto the layer canvas in world space (bypass WebGL)
      *  @param {Vector2}  pos
      *  @param {Vector2}  size
      *  @param {number}   angle
      *  @param {boolean}  mirror
-     *  @param {Function} drawFunction */
+     *  @param {Canvas2DDrawCallback} drawFunction */
     drawCanvas2D(pos, size, angle, mirror, drawFunction)
     {
+        if (!this.context) return;
+
         const context = this.context;
         context.save();
         pos = pos.subtract(this.pos).multiply(this.tileInfo.size);
@@ -278,7 +290,7 @@ class CanvasLayer extends EngineObject
             else
             {
                 // untextured
-                context.fillStyle = color;
+                context.fillStyle = color.toString();
                 context.fillRect(-.5, -.5, 1, 1);
             }
         });
@@ -296,15 +308,10 @@ class CanvasLayer extends EngineObject
      *  @param {boolean} [enable] - enable WebGL rendering and update the texture */
     useWebGL(enable=true)
     {
-        if (glEnable && enable)
-        {
-            if (this.glTexture)
-                glSetTextureData(this.glTexture, this.canvas);
-            else
-                this.glTexture = glCreateTexture(this.canvas);
-        }
+        if (enable)
+            this.textureInfo.createWebGLTexture();
         else
-            this.glTexture = undefined;
+            this.textureInfo.destroyWebGLTexture();
     }
 }
 
@@ -315,7 +322,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));
  */
@@ -325,26 +334,15 @@ class TileLayer extends CanvasLayer
     *  @param {Vector2}  position      - World space position
     *  @param {Vector2}  size          - World space size
     *  @param {TileInfo} [tileInfo]    - Default tile info for layer (used for size and texture)
-    *  @param {Vector2}  [scale=(1,1)] - How much to scale this layer when rendered
     *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
-    *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering
     */
-    constructor(position, size, tileInfo=tile(), scale=vec2(1), renderOrder=0, useWebGL=glEnable)
+    constructor(position, size, tileInfo=tile(), renderOrder=0)
     {
-        super(position, size, 0, renderOrder, size);
-        this.tileInfo = tileInfo;
-
         const canvasSize = size.multiply(tileInfo.size);
-        /** @property {HTMLCanvasElement} - The canvas used by this tile layer */
-        this.canvas = new OffscreenCanvas(canvasSize.x, canvasSize.y);
-        /** @property {OffscreenCanvasRenderingContext2D} - The 2D canvas context used by this tile layer */
-        this.context = this.canvas.getContext('2d');
-        /** @property {WebGLTexture} - Texture if using WebGL for this layer */
-        this.glTexture = useWebGL ? glCreateTexture(this.canvas) : undefined;
-        // set no friction by default, applied friction is max of both objects
-        this.friction = 0;
-        // set no restitution by default, applied restitution is max of both objects
-        this.restitution = 0;
+        super(position, size, 0, renderOrder, canvasSize);
+
+        // set tile info
+        this.tileInfo = tileInfo;
 
         // init tile data
         this.data = [];
@@ -370,6 +368,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;
@@ -381,7 +381,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()
@@ -389,10 +392,11 @@ class TileLayer extends CanvasLayer
         ASSERT(drawContext !== this.context, 'must call redrawEnd() after drawing tiles!');
 
         // draw the tile layer as a single tile
-        const tileInfo = new TileInfo().setFullImage(this.canvas, this.glTexture);
-        const pos = this.pos.add(this.size.scale(.5));
-        const useWebGL = glEnable && this.glTexture !== undefined;
-        drawTile(pos, this.size, tileInfo, WHITE, 0, false, CLEAR_BLACK, useWebGL);
+        const tileInfo = new TileInfo().setFullImage(this.textureInfo);
+        const size = this.drawSize || this.size;
+        const pos = this.pos.add(size.scale(.5));
+        const useWebGL = glEnable && this.textureInfo.hasWebGL();
+        drawTile(pos, size, tileInfo, WHITE, 0, false, CLEAR_BLACK, useWebGL);
     }
 
     /** Draw all the tile data to an offscreen canvas
@@ -404,8 +408,7 @@ class TileLayer extends CanvasLayer
         for (let y = this.size.y; y--;)
             this.drawTileData(vec2(x,y), false);
         this.redrawEnd();
-        if (this.glTexture)
-            this.useWebGL(); // update WebGL texture
+        this.useWebGL();
     }
 
     /** Call to start the redraw process
@@ -413,6 +416,8 @@ class TileLayer extends CanvasLayer
      *  @param {boolean} [clear] - Should it clear the canvas before drawing */
     redrawStart(clear=false)
     {
+        if (!this.context) return;
+
         // save current render settings
         /** @type {[HTMLCanvasElement|OffscreenCanvas, CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D, Vector2, Vector2, number]} */
         this.savedRenderSettings = [drawCanvas, drawContext, mainCanvasSize, cameraPos, cameraScale];
@@ -441,6 +446,8 @@ class TileLayer extends CanvasLayer
     /** Call to end the redraw process */
     redrawEnd()
     {
+        if (!this.context) return;
+
         ASSERT(drawContext === this.context, 'must call redrawStart() before drawing tiles');
         glCopyToContext(drawContext);
         //debugSaveCanvas(this.canvas);
@@ -457,6 +464,8 @@ class TileLayer extends CanvasLayer
      */
     drawTileData(layerPos, clear=true)
     {
+        if (!this.context) return;
+        
         // clear out where the tile was, for full opaque tiles this can be skipped
         const s = this.tileInfo.size;
         if (clear)
@@ -484,6 +493,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
 {
@@ -492,12 +502,10 @@ class TileCollisionLayer extends TileLayer
     *  @param {Vector2}  size          - World space size
     *  @param {TileInfo} [tileInfo]    - Tile info for layer
     *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
-    *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering
     */
-    constructor(position, size, tileInfo=tile(), renderOrder=0, useWebGL=glEnable)
+    constructor(position, size, tileInfo=tile(), renderOrder=0)
     {
-        const scale = vec2(1); // collision layers are not scaled
-        super(position, size.floor(), tileInfo, scale, renderOrder, useWebGL);
+        super(position, size.floor(), tileInfo, renderOrder);
 
         /** @property {Array<number>} - The tile collision grid */
         this.collisionData = [];
@@ -527,6 +535,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();
@@ -538,6 +547,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);
     }
@@ -547,6 +557,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;
     }
@@ -558,6 +569,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;
@@ -588,6 +602,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;

package/src/engineUtilities.js

@@ -231,6 +231,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();
 }
 
@@ -241,6 +243,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
@@ -303,6 +312,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
@@ -399,6 +409,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)
@@ -539,9 +550,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);
@@ -549,8 +561,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)
@@ -646,6 +660,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
@@ -823,7 +838,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)
@@ -865,77 +881,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
@@ -997,4 +1014,34 @@ 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);
 }