littlejsengine 1.16.2 → 1.17.1

package/src/engineTileLayer.js

@@ -32,7 +32,7 @@ function tileCollisionGetData(pos)
 
 /** Check if a tile layer collides with another object
  *  @param {Vector2}      pos
- *  @param {Vector2}      [size=(0,0)]
+ *  @param {Vector2}      [size=vec2()]
  *  @param {EngineObject} [object] - An object or undefined for generic test
  *  @param {boolean}      [solidOnly] - Only check solid layers if true
  *  @return {TileCollisionLayer}
@@ -150,20 +150,20 @@ function tileLayersLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisionLa
 class TileLayerData
 {
     /** Create a tile layer data object, one for each tile in a TileLayer
-     *  @param {number}  [tile]      - The tile to use, untextured if undefined
+     *  @param {number}  [tile] - The tile to use, untextured if undefined
      *  @param {number}  [direction] - Integer direction of tile, in 90 degree increments
-     *  @param {boolean} [mirror]    - If the tile should be mirrored along the x axis
-     *  @param {Color}   [color]     - Color of the tile */
+     *  @param {boolean} [mirror] - If the tile should be mirrored along the x axis
+     *  @param {Color}   [color] - Color of the tile */
     constructor(tile, direction=0, mirror=false, color=new Color)
     {
-        /** @property {number}  - The tile to use, untextured if undefined */
-        this.tile      = tile;
-        /** @property {number}  - Integer direction of tile, in 90 degree increments */
+        /** @property {number} - The tile to use, untextured if undefined */
+        this.tile = tile;
+        /** @property {number} - Integer direction of tile, in 90 degree increments */
         this.direction = direction;
         /** @property {boolean} - If the tile should be mirrored along the x axis */
-        this.mirror    = mirror;
-        /** @property {Color}   - Color of the tile */
-        this.color     = color.copy();
+        this.mirror = mirror;
+        /** @property {Color} - Color of the tile */
+        this.color = color.copy();
     }
 
     /** Set this tile to clear, it will not be rendered */
@@ -174,7 +174,7 @@ class TileLayerData
 /**
  * Canvas Layer - cached off screen rendering system
  * - Contains an offscreen canvas that can be rendered to
- * - WebGL rendering is optional, call useWebGL to enable
+ * - WebGL rendering is optional, call updateWebGL to enable/update
  * @extends EngineObject
  * @memberof TileLayers
  * @example
@@ -188,8 +188,9 @@ class CanvasLayer extends EngineObject
      *  @param {number}   [angle] - Angle the layer is rotated by
      *  @param {number}   [renderOrder] - Objects sorted by renderOrder
      *  @param {Vector2}  [canvasSize] - Default size of canvas, can be changed later
+     *  @param {boolean}  [useWebGL] - Should this layer use WebGL for rendering
     */
-    constructor(position, size, angle=0, renderOrder=0, canvasSize=vec2(512))
+    constructor(position, size, angle=0, renderOrder=0, canvasSize=vec2(512), useWebGL=glEnable)
     {
         ASSERT(isVector2(canvasSize), 'canvasSize must be a Vector2');
         super(position, size, undefined, angle, WHITE, renderOrder);
@@ -199,13 +200,10 @@ class CanvasLayer extends EngineObject
         /** @property {OffscreenCanvasRenderingContext2D} - The 2D canvas context used by this layer */
         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);
-        /** @property {boolean} - True if WebGL texture needs to be refreshed */
-        this.refreshWebGL = false;
 
         // disable physics by default
-        this.mass = this.gravityScale = this.friction = this.restitution = 0;
+        this.mass = 0;
     }
 
     /** Destroy this canvas layer */
@@ -220,7 +218,7 @@ class CanvasLayer extends EngineObject
     // Render the layer, called automatically by the engine
     render()
     {
-        this.draw(this.pos, this.size, this.angle, this.color, this.mirror, this.additiveColor);
+        this.draw(this.pos, this.size, this.color, this.angle, this.mirror, this.additiveColor);
     }
 
     /** Draw this canvas layer centered in world space, with color applied if using WebGL
@@ -233,103 +231,54 @@ class CanvasLayer extends EngineObject
     *  @param {boolean} [screenSpace] - If true the pos and size are in screen space
     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
     *  @memberof Draw */
-    draw(pos, size, angle=0, color=WHITE, mirror=false, additiveColor, screenSpace=false, context)
+    draw(pos, size, color=WHITE, angle=0, mirror=false, additiveColor, screenSpace=false, context)
     {
-        const useWebGL = glEnable && this.textureInfo.hasWebGL();
-        if (useWebGL && this.refreshWebGL)
-        {
-            // update the WebGL texture
-            this.textureInfo.createWebGLTexture();
-            this.refreshWebGL = false;
-        }
-
         // draw the canvas layer as a single tile that uses the whole texture
         const tileInfo = new TileInfo().setFullImage(this.textureInfo);
+        const useWebGL = this.hasWebGL();
         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 {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);
-        size = size.multiply(this.tileInfo.size);
-        context.translate(pos.x, this.canvas.height - pos.y);
-        context.rotate(angle);
-        context.scale(mirror ? -size.x : size.x, size.y);
-        drawFunction(context);
-        context.restore();
-    }
-
     /** Draw a tile onto the layer canvas in world space
      *  @param {Vector2}  pos
-     *  @param {Vector2}  [size=(1,1)]
+     *  @param {Vector2}  [size=vec2(1)]
      *  @param {TileInfo} [tileInfo]
-     *  @param {Color}    [color=(1,1,1,1)]
-     *  @param {number}   [angle=0]
-     *  @param {boolean}  [mirror=false] */
-    drawTile(pos, size=vec2(1), tileInfo, color=new Color, angle, mirror)
+     *  @param {Color}    [color=WHITE]
+     *  @param {number}   [angle]
+     *  @param {boolean}  [mirror] */
+    drawTile(pos, size=vec2(1), tileInfo, color=new Color, angle=0, mirror=false)
     {
-        this.drawCanvas2D(pos, size, angle, mirror, (context)=>
-        {
-            const textureInfo = tileInfo && tileInfo.textureInfo;
-            if (textureInfo)
-            {
-                context.globalAlpha = color.a; // only alpha is supported
-                context.drawImage(textureInfo.image,
-                    tileInfo.pos.x,  tileInfo.pos.y,
-                    tileInfo.size.x, tileInfo.size.y, -.5, -.5, 1, 1);
-                context.globalAlpha = 1;
-            }
-            else
-            {
-                // untextured
-                context.fillStyle = color.toString();
-                context.fillRect(-.5, -.5, 1, 1);
-            }
-        });
+        pos = pos.subtract(this.pos).multiply(this.tileInfo.size);
+        size = size.multiply(this.tileInfo.size);
+        pos.y = this.canvas.height - pos.y;
+
+        // draw the tile onto the layer canvas
+        const oldMainCanvasSize = mainCanvasSize;
+        mainCanvasSize = vec2(this.canvas.width, this.canvas.height);
+        const useWebGL = this.hasWebGL();
+        useWebGL && glSetRenderTarget(this.textureInfo.glTexture);
+        const drawContext = useWebGL ? undefined : this.context;
+        drawTile(pos, size, tileInfo, color, angle, mirror, undefined, useWebGL, true, drawContext);
+        useWebGL && glSetRenderTarget();
+        mainCanvasSize = oldMainCanvasSize;
     }
 
     /** Draw a rectangle onto the layer canvas in world space
      *  @param {Vector2} pos
-     *  @param {Vector2} [size=(1,1)]
-     *  @param {Color}   [color=(1,1,1,1)]
-     *  @param {number}  [angle=0] */
+     *  @param {Vector2} [size=vec2(1)]
+     *  @param {Color}   [color=WHITE]
+     *  @param {number}  [angle] */
     drawRect(pos, size, color, angle)
     { this.drawTile(pos, size, undefined, color, angle); }
 
-    /** Create or update the WebGL texture for this layer
-     *  @param {boolean} [enable] - enable WebGL rendering and update the texture 
-     *  @param {boolean} [immediate] - shoulkd the texture be updated immediately
-     */
-    useWebGL(enable=true, immediate=false)
-    {
-        if (!immediate && enable && this.textureInfo.hasWebGL())
-        {
-            // refresh the texture when needed
-            this.refreshWebGL = true;
-            return;
-        }
+    /** Create WebGL texture if necessary and copy layer canvas to it */
+    updateWebGL()
+    { this.textureInfo.createWebGLTexture(); }
 
-        if (enable)
-            this.textureInfo.createWebGLTexture();
-        else
-            this.textureInfo.destroyWebGLTexture();
-    }
+    /** Check if this layer is using WebGL
+     *  @return {boolean} */
+    hasWebGL()
+    { return glEnable && this.textureInfo.hasWebGL(); }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -348,50 +297,67 @@ class CanvasLayer extends EngineObject
 class TileLayer extends CanvasLayer
 {
     /** Create a tile layer object
-    *  @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}  position - World space position
+    *  @param {Vector2}  size - World space size
+    *  @param {TileInfo} [tileInfo] - Default tile info for layer (used for size and texture)
     *  @param {number}   [renderOrder] - Objects are sorted by renderOrder
     */
     constructor(position, size, tileInfo=tile(), renderOrder=0)
     {
         const canvasSize = tileInfo ? size.multiply(tileInfo.size) : size;
-        super(position, size, 0, renderOrder, canvasSize);
-
-        // set tile info
-        this.tileInfo = tileInfo;
-
-        // init tile data
+        const useWebGL = true;
+        super(position, size, 0, renderOrder, canvasSize, useWebGL);
+        
+        /** @property {TileInfo} - Default tile info for layer */
+        this.tileInfo = undefined;
+        /** @property {Array<TileLayerData>} - Default tile info for layer */
         this.data = [];
-        for (let j = this.size.area(); j--;)
-            this.data.push(new TileLayerData);
+        /** @property {boolean} - Is this layer using a webgl texture? */
+        this.isUsingWebGL = false;
 
         if (headlessMode)
         {
-            // disable rendering
-            this.redraw       = () => {};
-            this.render       = () => {};
-            this.redrawStart  = () => {};
-            this.redrawEnd    = () => {};
-            this.drawTileData = () => {};
-            this.drawCanvas2D = () => {};
-            this.useWebGL     = () => {};
+            // disable rendering in headless mode
+            this.render         = () => {};
+            this.redraw         = () => {};
+            this.redrawStart    = () => {};
+            this.redrawEnd      = () => {};
+            this.drawTileData   = () => {};
+            this.redrawTileData = () => {};
+            this.drawLayerTile  = () => {};
+            this.drawLayerRect  = () => {};
+            this.clearLayerRect = () => {};
+            return;
+        }
+        
+        if (tileInfo)
+        {
+            // set tile info
+            this.tileInfo = tileInfo.frame(0);
+            this.tileInfo.bleed = 0; // disable bleed for tile layers
         }
+
+        // init tile data
+        for (let j = this.size.area(); j--;)
+            this.data.push(new TileLayerData);
     }
 
     /** Set data at a given position in the array
      *  @param {Vector2}       layerPos - Local position in array
-     *  @param {TileLayerData} data     - Data to set
+     *  @param {TileLayerData} data - Data to set
      *  @param {boolean}       [redraw] - Force the tile to redraw if true */
     setData(layerPos, data, redraw=false)
     {
+        layerPos = layerPos.floor();
         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;
-            redraw && this.drawTileData(layerPos);
-        }
+
+        if (!layerPos.arrayCheck(this.size)) return;
+        this.data[(layerPos.y|0)*this.size.x+layerPos.x|0] = data;
+
+        if (!redraw) return;
+        const isRedraw = drawContext === this.context;
+        isRedraw ? this.drawTileData(layerPos) : this.redrawTileData(layerPos);
     }
 
     /** Get data at a given position in the array
@@ -400,7 +366,18 @@ class TileLayer extends CanvasLayer
     getData(layerPos)
     { 
         ASSERT(isVector2(layerPos), 'layerPos must be a Vector2');
-        return layerPos.arrayCheck(this.size) && this.data[(layerPos.y|0)*this.size.x+layerPos.x|0]; 
+        return layerPos.arrayCheck(this.size) && this.data[(layerPos.y|0)*this.size.x+layerPos.x|0];
+    }
+
+    // Update the tile layer, refresh texture if needed
+    update()
+    {
+        if (!glEnable && this.isUsingWebGL)
+        {
+            // redraw the layer if webgl was disabled or context lost
+            this.isUsingWebGL = false;
+            this.redraw();
+        }
     }
 
     // Render the tile layer, called automatically by the engine
@@ -408,40 +385,35 @@ class TileLayer extends CanvasLayer
     {
         ASSERT(drawContext !== this.context, 'must call redrawEnd() after drawing tiles!');
 
-        if (this.refreshWebGL)
-        {
-            // update the WebGL texture
-            this.textureInfo.createWebGLTexture();
-            this.refreshWebGL = false;
-        }
-
-        // draw the tile layer as a single tile
-        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);
+        this.draw(pos, this.size, this.color, this.angle, this.mirror, this.additiveColor);
     }
 
+    /** Called after this layer is redrawn, does nothing by default */
+    onRedraw() {}
+
     /** Draw all the tile data to an offscreen canvas
-     *  - This may be slow in some browsers but only needs to be done once */
+     *  - This may be slow if not using webgl but only needs to be done once */
     redraw()
     {
         this.redrawStart(true);
         for (let x = this.size.x; x--;)
         for (let y = this.size.y; y--;)
             this.drawTileData(vec2(x,y), false);
+        this.hasWebGL() && glFlush();
+        this.onRedraw();
         this.redrawEnd();
-        this.useWebGL();
     }
 
     /** Call to start the redraw process
-     *  - This can be used to manually update small parts of the level
+     *  - This can be used to manually update parts of the level
      *  @param {boolean} [clear] - Should it clear the canvas before drawing */
     redrawStart(clear=false)
     {
         if (!this.context) return;
-
+        ASSERT(drawContext !== this.context);
+        
         // save current render settings
         /** @type {[CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D, Vector2, Vector2, number, Color]} */
         this.savedRenderSettings = [drawContext, mainCanvasSize, cameraPos, cameraScale, canvasClearColor];
@@ -449,33 +421,37 @@ class TileLayer extends CanvasLayer
         // set the draw canvas and context to this layer
         // use camera settings to match this layer's canvas
         drawContext = this.context;
-        cameraPos = this.size.scale(.5);
-        const tileSize = this.tileInfo ? this.tileInfo.size : vec2(1);
-        cameraScale = tileSize.x;
-        canvasClearColor = CLEAR_BLACK;
+        const tileSize = this.tileInfo?.size ?? vec2(1);
         mainCanvasSize = this.size.multiply(tileSize);
-        if (clear)
+        canvasClearColor = CLEAR_BLACK;
+        cameraPos = this.size.multiply(tileSize).scale(.5);
+        cameraScale = 1;
+
+        // set render target to this layer
+        this.isUsingWebGL = this.hasWebGL();
+        if (this.isUsingWebGL)
+            glSetRenderTarget(this.textureInfo.glTexture, clear);
+        else
         {
-            // clear and set size
-            this.canvas.width  = mainCanvasSize.x;
-            this.canvas.height = mainCanvasSize.y;
+            // disable smoothing for pixel art
+            this.context.imageSmoothingEnabled = !tilesPixelated;
+            if (clear)
+            {
+                // clear and set size
+                this.canvas.width  = mainCanvasSize.x;
+                this.canvas.height = mainCanvasSize.y;
+            }
         }
-
-        // disable smoothing for pixel art
-        drawContext.imageSmoothingEnabled = !tilesPixelated;
-
-        // setup gl rendering if enabled
-        glPreRender();
     }
 
     /** Call to end the redraw process */
     redrawEnd()
     {
         if (!this.context) return;
+        ASSERT(drawContext === this.context);
 
-        ASSERT(drawContext === this.context, 'must call redrawStart() before drawing tiles');
-        glCopyToContext(drawContext);
-        //saveCanvas(this.canvas);
+        if (glEnable && this.textureInfo.glTexture)
+            glSetRenderTarget();
 
         // set stuff back to normal
         [drawContext, mainCanvasSize, cameraPos, cameraScale, canvasClearColor] = this.savedRenderSettings;
@@ -490,24 +466,75 @@ class TileLayer extends CanvasLayer
     drawTileData(layerPos, clear=true)
     {
         if (!this.context) return;
+        ASSERT(drawContext === this.context, 'must call redrawStart() before drawing tiles');
         
-        // clear out where the tile was, for full opaque tiles this can be skipped
-        const s = this.tileInfo.size;
-        if (clear)
-        {
-            const pos = layerPos.multiply(s);
-            this.context.clearRect(pos.x, this.canvas.height-pos.y, s.x, -s.y);
-        }
+        // clear out where the tile was, can be skipped for fully opaque tiles
+        const drawSize = this.tileInfo?.size ?? vec2(1);
+        const drawPos = layerPos.multiply(drawSize);
+        clear && this.clearLayerRect(drawPos, drawSize);
 
         // draw the tile if it has layer data
         const d = this.getData(layerPos);
-        if (d.tile !== undefined)
-        {
-            ASSERT(drawContext === this.context, 'must call redrawStart() before drawing tiles');
-            const pos = layerPos.add(vec2(.5));
-            const tileInfo = tile(d.tile, s, this.tileInfo.textureIndex, this.tileInfo.padding);
-            drawTile(pos, vec2(1), tileInfo, d.color, d.direction*PI/2, d.mirror);
-        }
+        if (!d.tile) return;
+
+        const tileInfo = this.tileInfo && this.tileInfo.tile(d.tile);
+        this.drawLayerTile(drawPos, drawSize, tileInfo, d.color, d.direction*PI/2, d.mirror);
+    }
+
+    /** Draw the tile at a given position in the tile grid
+     *  This can be used to clear tiles when they are destroyed
+     *  For better performance use drawTileData inside a redrawStart/End block
+     *  @param {Vector2} layerPos
+     *  @param {boolean} [clear] - should the old tile be cleared
+     */
+    redrawTileData(layerPos, clear=true)
+    {
+        if (!this.context) return;
+        ASSERT(drawContext !== this.context, 'redrawStart() should not be active when calling redrawTileData(), instead use drawTileData()');
+
+        this.redrawStart();
+        this.drawTileData(layerPos, clear);
+        this.redrawEnd();
+    }
+
+    /** Draw textured tile in layer space
+     *  @param {Vector2}  pos - Position in pixel coordinates
+     *  @param {Vector2}  [size=vec2(1)] - Size of the tile
+     *  @param {TileInfo} [tileInfo] - Tile info to use, untextured if undefined
+     *  @param {Color}    [color=WHITE] - Color to modulate with
+     *  @param {number}   [angle] - Angle to rotate by
+     *  @param {boolean}  [mirror] - Is image flipped along the Y axis?
+     *  @param {Color}    [additiveColor] - Additive color to be applied if any */
+    drawLayerTile(pos, size=vec2(1), tileInfo, color=WHITE,
+    angle=0, mirror, additiveColor)
+    {
+        const drawPos = pos.add(size.scale(.5));
+        drawTile(drawPos, size, tileInfo, color, angle, mirror, additiveColor);
+    }
+
+    /** Clear a rectangle in layer space
+     *  @param {Vector2} pos
+     *  @param {Vector2} size
+     *  @param {Color} [color=WHITE] - Color to modulate with
+     *  @param {number} [angle] - Angle to rotate by
+     */
+    drawLayerRect(pos, size, color, angle=0)
+    { this.drawLayerTile(pos, size, undefined, color, angle); }
+
+    /** Clear a rectangle in layer space
+     *  @param {Vector2} pos - position in pixel coordinates
+     *  @param {Vector2} size
+     */
+    clearLayerRect(pos, size)
+    {
+        ASSERT(drawContext === this.context, 'must call redrawStart() before clearing tiles');
+
+        const x = pos.x, y = this.canvas.height - pos.y - size.y;
+        const useWebGL = this.hasWebGL();
+        if (useWebGL)
+            glClearRect(x, y, size.x, size.y);
+        else
+            this.context.clearRect(x, y, size.x, size.y);
     }
 }
 
@@ -516,7 +543,6 @@ class TileLayer extends CanvasLayer
  * Tile Collision Layer - a tile layer with collision
  * - adds collision data and functions to TileLayer
  * - there can be multiple tile collision layers
- * - tile collision layers should not overlap each other
  * @extends TileLayer
  * @memberof TileLayers
  */
@@ -588,7 +614,7 @@ class TileCollisionLayer extends TileLayer
 
     /** Check if collision with another object should occur
     *  @param {Vector2}      pos
-    *  @param {Vector2}      [size=(0,0)]
+    *  @param {Vector2}      [size=vec2()]
     *  @param {EngineObject} [object]
     *  @return {boolean} */
     collisionTest(pos, size=new Vector2, object)

package/src/engineUtilities.js

@@ -1,10 +1,7 @@
 /**
  * LittleJS Utility Classes and Functions
- * - General purpose math library
- * - Vector2 - fast, simple, easy 2D vector class
- * - Color - holds a rgba color with some math functions
+ * - General purpose utilities
  * - Timer - tracks time automatically
- * - RandomGenerator - seeded random number generator
  * @namespace Utilities
  */
 
@@ -70,6 +67,9 @@ function saveCanvas(canvas, filename='screenshot', type='image/png')
  *  @memberof Utilities */
 function saveDataURL(url, filename='download', revokeTime)
 {
+    ASSERT(isString(url), 'saveDataURL requires url string');
+    ASSERT(isString(filename), 'saveDataURL requires filename string');
+
     // create link for saving screenshots
     const link = document.createElement('a');
     link.download = filename;
@@ -77,4 +77,100 @@ function saveDataURL(url, filename='download', revokeTime)
     link.click();
     if (revokeTime !== undefined)
         setTimeout(()=> URL.revokeObjectURL(url), revokeTime);
+}
+
+/** Share content using the native share dialog if available
+ *  @param {string} title - title of the share
+ *  @param {string} url - url to share
+ *  @param {Function} [callback] - Called when share is complete
+ *  @memberof Utilities */
+function shareURL(title, url, callback)
+{
+    ASSERT(isString(title), 'shareURL requires title string');
+    ASSERT(isString(url), 'shareURL requires url string');
+    navigator.share?.({title, url}).then(()=>callback?.());
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * 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
+ *
+ * let b = new Timer(1); // creates a timer with 1 second left
+ * b.unset();            // unset the timer
+ */
+class Timer
+{
+    /** Create a timer object set time passed in
+     *  @param {number} [timeLeft] - How much time left before the timer 
+     *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
+    constructor(timeLeft, useRealTime=false)
+    {
+        ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Constructed Timer is invalid.', timeLeft);
+        this.useRealTime = useRealTime;
+        const globalTime = this.getGlobalTime();
+        this.time = timeLeft === undefined ? undefined : globalTime + 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)
+    {
+        ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
+        const globalTime = this.getGlobalTime();
+        this.time = globalTime + timeLeft;
+        this.setTime = timeLeft;
+    }
+
+    /** Set if the timer should keep running even when the game is paused
+     *  @param {boolean} [useRealTime] */
+    setUseRealTime(useRealTime=true)
+    {
+        ASSERT(!this.isSet(), 'Cannot change global time setting while timer is set.');
+        this.useRealTime = useRealTime;
+    }
+
+    /** Unset the timer */
+    unset() { this.time = undefined; }
+
+    /** Returns true if set
+     * @return {boolean} */
+    isSet() { return this.time !== undefined; }
+
+    /** Returns true if set and has not elapsed
+     * @return {boolean} */
+    active() { return this.getGlobalTime() < this.time; }
+
+    /** Returns true if set and elapsed
+     * @return {boolean} */
+    elapsed() { return this.getGlobalTime() >= this.time; }
+
+    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
+     * @return {number} */
+    get() { return this.isSet()? this.getGlobalTime() - this.time : 0; }
+
+    /** Get percentage elapsed based on time it was set to, returns 0 if not set
+     * @return {number} */
+    getPercent() { return this.isSet()? 1-percent(this.time - this.getGlobalTime(), 0, this.setTime) : 0; }
+
+    /** Get the time this timer was set to, returns 0 if not set
+     * @return {number} */
+    getSetTime() { return this.isSet() ? this.setTime : 0; }
+
+    /** Get the current global time this timer is based on
+     * @return {number} */
+    getGlobalTime() { return this.useRealTime ? timeReal : time; }
+
+    /** Returns this timer expressed as a string
+     * @return {string} */
+    toString() { return this.isSet() ? abs(this.get()) + ' seconds ' + (this.get()<0 ? 'before' : 'after' ) : 'unset'; }
+
+    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
+     * @return {number} */
+    valueOf() { return this.get(); }
 }