littlejsengine 1.11.9 → 1.11.13

package/plugins/uiSystem.js

@@ -5,6 +5,7 @@
  * - Buttons
  * - Checkboxes
  * - Images
+ * @namespace UISystemPlugin
  */
 
 'use strict';
@@ -12,18 +13,55 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 // ui defaults
+
+/** Default fill color for UI elements
+ *  @type {Color}
+ *  @memberof UISystemPlugin */
 let uiDefaultColor       = WHITE;
+
+/** Default outline color for UI elements
+ *  @type {Color}
+ *  @memberof UISystemPlugin */
 let uiDefaultLineColor   = BLACK;
+
+/** Default text color for UI elements
+ *  @type {Color}
+ *  @memberof UISystemPlugin */
 let uiDefaultTextColor   = BLACK;
+
+/** Default button color for UI elements
+ *  @type {Color}
+ *  @memberof UISystemPlugin */
 let uiDefaultButtonColor = hsl(0,0,.5);
+
+/** Default hover color for UI elements
+ *  @type {Color}
+ *  @memberof UISystemPlugin */
 let uiDefaultHoverColor  = hsl(0,0,.7);
-let uiDefaultLineWidth   = 4;
-let uiDefaultFont        = 'arial';
 
-// ui system
+/** Default line width for UI elements
+ *  @type {number}
+ *  @memberof UISystemPlugin */
+let uiDefaultLineWidth = 4;
+
+/** Default font for UI elements
+ *  @type {string}
+ *  @memberof UISystemPlugin */
+let uiDefaultFont = 'arial';
+
+/** List of all UI elements
+ *  @type {Array<UIObject>}
+ *  @memberof UISystemPlugin */
 let uiObjects = [];
+
+/** Context to render UI elements to
+ *  @type {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D}
+ *  @memberof UISystemPlugin */
 let uiContext;
 
+/** Set up the UI system, typically called in gameInit
+ *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
+ *  @memberof UISystemPlugin */
 function initUISystem(context=overlayContext)
 {
     uiContext = context;
@@ -60,6 +98,13 @@ function initUISystem(context=overlayContext)
     }
 }
 
+/** Draw a rectangle to the UI context
+ *  @param {Vector2} pos
+ *  @param {Vector2} size
+ *  @param {Color}   [color=uiDefaultColor]
+ *  @param {number}  [lineWidth=uiDefaultLineWidth]
+ *  @param {Color}   [lineColor=uiDefaultLineColor]
+ *  @memberof UISystemPlugin */
 function drawUIRect(pos, size, color=uiDefaultColor, lineWidth=uiDefaultLineWidth, lineColor=uiDefaultLineColor)
 {
     uiContext.fillStyle = color.toString();
@@ -74,47 +119,92 @@ function drawUIRect(pos, size, color=uiDefaultColor, lineWidth=uiDefaultLineWidt
     }
 }
 
-function drawUILine(posA, posB, thickness=uiDefaultLineWidth, color=uiDefaultLineColor)
+/** Draw a line to the UI context
+ *  @param {Vector2} posA
+ *  @param {Vector2} posB
+ *  @param {number}  [lineWidth=uiDefaultLineWidth]
+ *  @param {Color}   [lineColor=uiDefaultLineColor]
+ *  @memberof UISystemPlugin */
+function drawUILine(posA, posB, lineWidth=uiDefaultLineWidth, lineColor=uiDefaultLineColor)
 {
-    uiContext.strokeStyle = color.toString();
-    uiContext.lineWidth = thickness;
+    uiContext.strokeStyle = lineColor.toString();
+    uiContext.lineWidth = lineWidth;
     uiContext.beginPath();
     uiContext.lineTo(posA.x, posA.y);
     uiContext.lineTo(posB.x, posB.y);
     uiContext.stroke();
 }
 
+/** Draw a tile to the UI context
+ *  @param {Vector2}  pos
+ *  @param {Vector2}  size
+ *  @param {TileInfo} tileInfo
+ *  @param {Color}    [color=uiDefaultColor]
+ *  @param {number}   [angle]
+ *  @param {boolean}  [mirror]
+ *  @memberof UISystemPlugin */
 function drawUITile(pos, size, tileInfo, color=uiDefaultColor, angle=0, mirror=false)
 {
     drawTile(pos, size, tileInfo, color, angle, mirror, BLACK, false, true, uiContext);
 }
 
+/** Draw text to the UI context
+ *  @param {string}  text
+ *  @param {Vector2} pos
+ *  @param {Vector2} size
+ *  @param {Color}   [color=uiDefaultColor]
+ *  @param {number}  [lineWidth=uiDefaultLineWidth]
+ *  @param {Color}   [lineColor=uiDefaultLineColor]
+ *  @param {string}  [align]
+ *  @param {string}  [font=uiDefaultFont]
+ *  @memberof UISystemPlugin */
 function drawUIText(text, pos, size, color=uiDefaultColor, lineWidth=uiDefaultLineWidth, lineColor=uiDefaultLineColor, align='center', font=uiDefaultFont)
 {
     drawTextScreen(text, pos, size.y, color, lineWidth, lineColor, align, font, size.x, uiContext);
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-
+/** 
+ * UI Object - Base level object for all UI elements
+ */
 class UIObject
 {
-    constructor(localPos=vec2(), size=vec2())
+    /** Create a UIObject
+     *  @param {Vector2}  [pos=(0,0)]
+     *  @param {Vector2}  [size=(1,1)]
+     */
+    constructor(pos=vec2(), size=vec2())
     {
-        this.localPos = localPos.copy();
-        this.pos = localPos.copy();
-        this.size = size.copy();
+        /** @property {Vector2} - Local position of the object */
+        this.localPos   = pos.copy();
+        /** @property {Vector2} - Screen space position of the object */
+        this.pos        = pos.copy();
+        /** @property {Vector2} - Screen space size of the object */
+        this.size       = size.copy();
+        /** @property {Color} */
         this.color      = uiDefaultColor;
+        /** @property {Color} */
         this.lineColor  = uiDefaultLineColor;
+        /** @property {Color} */
         this.textColor  = uiDefaultTextColor;
+        /** @property {Color} */
         this.hoverColor = uiDefaultHoverColor;
+        /** @property {number} */
         this.lineWidth  = uiDefaultLineWidth;
+        /** @property {string} */
         this.font       = uiDefaultFont;
-        this.visible = true;
-        this.children = [];
-        this.parent = null;
+        /** @property {boolean} */
+        this.visible    = true;
+        /** @property {Array<UIObject>} */
+        this.children   = [];
+        /** @property {UIObject} */
+        this.parent     = undefined;
         uiObjects.push(this);
     }
 
+    /** Add a child UIObject to this object
+     *  @param {UIObject} child
+     */
     addChild(child)
     {
         ASSERT(!child.parent && !this.children.includes(child));
@@ -122,13 +212,17 @@ class UIObject
         child.parent = this;
     }
 
+    /** Remove a child UIObject from this object
+     *  @param {UIObject} child
+     */
     removeChild(child)
     {
         ASSERT(child.parent == this && this.children.includes(child));
         this.children.splice(this.children.indexOf(child), 1);
-        child.parent = 0;
+        child.parent = undefined;
     }
 
+    /** Update the object, called automatically by plugin once each frame */
     update()
     {
         // track mouse input
@@ -157,32 +251,55 @@ class UIObject
             this.onRelease();
         }
     }
+
+    /** Render the object, called automatically by plugin once each frame */
     render()
     {
         if (this.size.x && this.size.y)
             drawUIRect(this.pos, this.size, this.color, this.lineWidth, this.lineColor);
     }
 
-    // callback functions
+    /** Called when the mouse enters the object */
     onEnter()   {}
+
+    /** Called when the mouse leaves the object */
     onLeave()   {}
+
+    /** Called when the mouse is pressed while over the object */
     onPress()   {}
+
+    /** Called when the mouse is released while over the object */
     onRelease() {}
+
+    /** Called when the state of this object changes */
     onChange()  {}
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-
+/** 
+ * UIText - A UI object that displays text
+ * @extends UIObject
+ */
 class UIText extends UIObject
 {
-    constructor(pos, size, text='', align='center', font=fontDefault)
+    /** Create a UIText object
+     *  @param {Vector2} [pos]
+     *  @param {Vector2} [size]
+     *  @param {string}  [text]
+     *  @param {string}  [align]
+     *  @param {string}  [font=uiDefaultFont]
+     */
+    constructor(pos, size, text='', align='center', font=uiDefaultFont)
     {
         super(pos, size);
 
+        /** @property {string} */
         this.text = text;
+        /** @property {string} */
         this.align = align;
-        this.font = font;
-        this.lineWidth = 0;
+
+        this.font = font; // set font
+        this.lineWidth = 0; // set text to not be outlined by default
     }
     render()
     {
@@ -191,17 +308,31 @@ class UIText extends UIObject
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-
+/** 
+ * UITile - A UI object that displays a tile image
+ * @extends UIObject
+ */
 class UITile extends UIObject
 {
+    /** Create a UITile object
+     *  @param {Vector2}  [pos]
+     *  @param {Vector2}  [size]
+     *  @param {TileInfo} [tileInfo]
+     *  @param {Color}    [color=WHITE]
+     *  @param {number}   [angle]
+     *  @param {boolean}  [mirror]
+     */
     constructor(pos, size, tileInfo, color=WHITE, angle=0, mirror=false)
     {
         super(pos, size);
 
+        /** @property {TileInfo} - Tile image to use */
         this.tileInfo = tileInfo;
-        this.color = color;
+        /** @property {number} - Angle to rotate in radians */
         this.angle = angle;
+        /** @property {boolean} - Should it be mirrored? */
         this.mirror = mirror;
+        this.color = color;
     }
     render()
     {
@@ -210,14 +341,25 @@ class UITile extends UIObject
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-
+/** 
+ * UIButton - A UI object that acts as a button
+ * @extends UIObject
+ */
 class UIButton extends UIObject
 {
-    constructor(pos, size, text)
+    /** Create a UIButton object
+     *  @param {Vector2} [pos]
+     *  @param {Vector2} [size]
+     *  @param {string}  [text]
+     *  @param {Color}   [color=uiDefaultButtonColor]
+     */
+    constructor(pos, size, text, color=uiDefaultButtonColor)
     {
         super(pos, size);
+
+        /** @property {string} */
         this.text = text;
-        this.color = uiDefaultButtonColor;
+        this.color = color;
     }
     render()
     {
@@ -231,12 +373,22 @@ class UIButton extends UIObject
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-
+/** 
+ * UICheckbox - A UI object that acts as a checkbox
+ * @extends UIObject
+ */
 class UICheckbox extends UIObject
 {
+    /** Create a UICheckbox object
+     *  @param {Vector2} [pos]
+     *  @param {Vector2} [size]
+     *  @param {boolean} [checked]
+     */
     constructor(pos, size, checked=false)
     {
         super(pos, size);
+
+        /** @property {boolean} */
         this.checked = checked;
     }
     onPress()
@@ -258,16 +410,30 @@ class UICheckbox extends UIObject
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-
+/** 
+ * UIScrollbar - A UI object that acts as a scrollbar
+ * @extends UIObject
+ */
 class UIScrollbar extends UIObject
 {
-    constructor(pos, size, value=.5, text='')
+    /** Create a UIScrollbar object
+     *  @param {Vector2} [pos]
+     *  @param {Vector2} [size]
+     *  @param {number}  [value]
+     *  @param {string}  [text]
+     *  @param {Color}   [color=uiDefaultButtonColor]
+     *  @param {Color}   [handleColor=WHITE]
+     */
+    constructor(pos, size, value=.5, text='', color=uiDefaultButtonColor, handleColor=WHITE)
     {
         super(pos, size);
+
+        /** @property {number} */
         this.value = value;
+        /** @property {string} */
         this.text = text;
-        this.color = uiDefaultButtonColor;
-        this.handleColor = WHITE;
+        this.color = color;
+        this.handleColor = handleColor;
     }
     update()
     {

package/src/engine.js

@@ -21,61 +21,62 @@
 'use strict';
 
 /** Name of engine
- *  @type {String}
+ *  @type {string}
  *  @default
  *  @memberof Engine */
 const engineName = 'LittleJS';
 
 /** Version of engine
- *  @type {String}
+ *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.11.9';
+const engineVersion = '1.11.13';
 
 /** Frames per second to update
- *  @type {Number}
+ *  @type {number}
  *  @default
  *  @memberof Engine */
 const frameRate = 60;
 
 /** How many seconds each frame lasts, engine uses a fixed time step
- *  @type {Number}
+ *  @type {number}
  *  @default 1/60
  *  @memberof Engine */
 const timeDelta = 1/frameRate;
 
 /** Array containing all engine objects
- *  @type {Array}
+ *  @type {Array<EngineObject>}
  *  @memberof Engine */
 let engineObjects = [];
 
 /** Array with only objects set to collide with other objects this frame (for optimization)
- *  @type {Array}
+ *  @type {Array<EngineObject>}
  *  @memberof Engine */
 let engineObjectsCollide = [];
 
 /** Current update frame, used to calculate time
- *  @type {Number}
+ *  @type {number}
  *  @memberof Engine */
 let frame = 0;
 
 /** Current engine time since start in seconds
- *  @type {Number}
+ *  @type {number}
  *  @memberof Engine */
 let time = 0;
 
 /** Actual clock time since start in seconds (not affected by pause or frame rate clamping)
- *  @type {Number}
+ *  @type {number}
  *  @memberof Engine */
 let timeReal = 0;
 
 /** Is the game paused? Causes time and objects to not be updated
- *  @type {Boolean}
+ *  @type {boolean}
  *  @default false
  *  @memberof Engine */
 let paused = false;
+
 /** Set if game is paused
- *  @param {Boolean} isPaused
+ *  @param {boolean} isPaused
  *  @memberof Engine */
 function setPaused(isPaused) { paused = isPaused; }
 
@@ -108,7 +109,7 @@ function engineAddPlugin(updateFunction, renderFunction)
  *  @param {Function} gameUpdatePost - Called after physics and objects are updated, even when paused
  *  @param {Function} gameRender - Called before objects are rendered, for drawing the background
  *  @param {Function} gameRenderPost - Called after objects are rendered, useful for drawing UI
- *  @param {Array} [imageSources=[]] - List of images to load
+ *  @param {Array<string>} [imageSources=[]] - List of images to load
  *  @param {HTMLElement} [rootElement] - Root element to attach to, the document body by default
  *  @memberof Engine */
 function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources=[], rootElement=document.body)
@@ -404,9 +405,9 @@ function engineObjectsDestroy()
 
 /** Collects all object within a given area
  *  @param {Vector2} [pos]                 - Center of test area, or undefined for all objects
- *  @param {Number|Vector2} [size]         - Radius of circle if float, rectangle size if Vector2
- *  @param {Array} [objects=engineObjects] - List of objects to check
- *  @return {Array}                        - List of collected objects
+ *  @param {Vector2|number} [size]         - Radius of circle if float, rectangle size if Vector2
+ *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
+ *  @return {Array<EngineObject>}                        - List of collected objects
  *  @memberof Engine */
 function engineObjectsCollect(pos, size, objects=engineObjects)
 {
@@ -432,9 +433,9 @@ function engineObjectsCollect(pos, size, objects=engineObjects)
 
 /** Triggers a callback for each object within a given area
  *  @param {Vector2} [pos]                 - Center of test area, or undefined for all objects
- *  @param {Number|Vector2} [size]         - Radius of circle if float, rectangle size if Vector2
+ *  @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 {Array} [objects=engineObjects] - List of objects to check
+ *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
  *  @memberof Engine */
 function engineObjectsCallback(pos, size, callbackFunction, objects=engineObjects)
 { engineObjectsCollect(pos, size, objects).forEach(o => callbackFunction(o)); }
@@ -442,8 +443,8 @@ function engineObjectsCallback(pos, size, callbackFunction, objects=engineObject
 /** Return a list of objects intersecting a ray
  *  @param {Vector2} start
  *  @param {Vector2} end
- *  @param {Array} [objects=engineObjects] - List of objects to check
- *  @return {Array} - List of objects hit
+ *  @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
+ *  @return {Array<EngineObject>} - List of objects hit
  *  @memberof Engine */
 function engineObjectsRaycast(start, end, objects=engineObjects)
 {