littlejsengine 1.1.2 → 1.1.3

package/engine/engineMedals.js

@@ -1,9 +1,9 @@
 /** 
- *  LittleJS Medal System
- *  <br> - Tracks and displays medals
- *  <br> - Saves medals to local storage
- *  <br> - Newgrounds and OS13k integration
- *  @namespace Medals
+ * LittleJS Medal System
+ * <br> - Tracks and displays medals
+ * <br> - Saves medals to local storage
+ * <br> - Newgrounds and OS13k integration
+ * @namespace Medals
  */
 
 'use strict';
@@ -22,32 +22,42 @@ let medalsPreventUnlock;
 let newgrounds;
 
 // Engine internal variables not exposed to documentation
-let medalsDisplayQueue = [], medalsSaveName, medalsDisplayTimer;
+let medalsDisplayQueue = [], medalsSaveName, medalsDisplayTimeLast;
 
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Initialize medals with a save name used for storage
- *  <br> - Checks if medals are unlocked
  *  <br> - Call this after creating all medals
+ *  <br> - Checks if medals are unlocked
  *  @param {String} saveName
  *  @memberof Medals */
 function medalsInit(saveName)
 {
     // check if medals are unlocked
     medalsSaveName = saveName;
-    debugMedals || medals.forEach(medal=> medal.unlocked = localStorage[medal.storageKey()]);
+    debugMedals || medals.forEach(medal=> medal.unlocked = 1 || localStorage[medal.storageKey()]);
 }
 
-/** Medal Object - Tracks an unlockable medal */
+/** 
+ * Medal Object - Tracks an unlockable medal 
+ * @example
+ * // create a medal
+ * const medal_example = new Medal(0, 'Example Medal', 'More info about the medal goes here.', '🎖️');
+ * 
+ * // initialize medals
+ * medalsInit('Example Game');
+ * 
+ * // unlock the medal
+ * medal_example.unlock();
+ */
 class Medal
 {
-    /**
-     * Create an medal object and adds it to the list of medals
-     * @param {Number} id - The unique identifier of the medal
-     * @param {String} name - Name of the medal
-     * @param {String} [description] - Description of the medal
-     * @param {String} [icon='🏆'] - Icon for the medal
-     * @param {String} [src] - Image location for the medal
+    /** Create an medal object and adds it to the list of medals
+     *  @param {Number} id            - The unique identifier of the medal
+     *  @param {String} name          - Name of the medal
+     *  @param {String} [description] - Description of the medal
+     *  @param {String} [icon='🏆']  - Icon for the medal
+     *  @param {String} [src]         - Image location for the medal
      */
     constructor(id, name, description='', icon='🏆', src)
     {
@@ -58,13 +68,9 @@ class Medal
         this.name = name;
         this.description = description;
         this.icon = icon;
-
+        this.image = new Image();
         if (src)
-        {
-            // load image
-            this.image = new Image();
             this.image.src = src;
-        }
     }
 
     /** Unlocks a medal if not already unlocked */
@@ -74,7 +80,7 @@ class Medal
             return;
 
         // save the medal
-        ASSERT(medalsSaveName); // game name must be set
+        ASSERT(medalsSaveName); // save name must be set
         localStorage[this.storageKey()] = this.unlocked = 1;
         medalsDisplayQueue.push(this);
 
@@ -89,27 +95,28 @@ class Medal
     render(hidePercent=0)
     {
         const context = overlayContext;
-        const x = overlayCanvas.width - medalDisplayWidth;
+        const width = min(medalDisplayWidth, mainCanvas.width);
+        const x = overlayCanvas.width - width;
         const y = -medalDisplayHeight*hidePercent;
 
         // draw containing rect and clip to that region
         context.save();
         context.beginPath();
         context.fillStyle = '#ddd'
-        context.fill(context.rect(x, y, medalDisplayWidth, medalDisplayHeight));
-        context.strokeStyle = context.fillStyle = '#000';
-        context.lineWidth = 2; 
+        context.fill(context.rect(x, y, width, medalDisplayHeight));
+        context.strokeStyle = '#000';
+        context.lineWidth = 3;
         context.stroke();
         context.clip();
 
+        // draw the icon and text
         this.renderIcon(x+15+medalDisplayIconSize/2, y+medalDisplayHeight/2);
-
-        // draw the text
         context.textAlign = 'left';
-        context.font = '3em '+ defaultFont;
-        context.fillText(this.name, x+medalDisplayIconSize+25, y+35);
-        context.font = '1.5em '+ defaultFont;
-        context.restore(context.fillText(this.description, x+medalDisplayIconSize+25, y+70));
+        context.font = '38px '+ fontDefault;
+        context.fillText(this.name, x+medalDisplayIconSize+30, y+28);
+        context.font = '24px '+ fontDefault;
+        context.fillText(this.description, x+medalDisplayIconSize+30, y+60);
+        context.restore();
     }
 
     /** Render the icon for a medal
@@ -121,21 +128,18 @@ class Medal
     {
         // draw the image or icon
         const context = overlayContext;
+        context.fillStyle = '#000';
         context.textAlign = 'center';
         context.textBaseline = 'middle';
-        context.font = size*.6 + 'px '+ defaultFont;
-        context.fillStyle = '#000';
-        if (this.image)
+        context.font = size*.7 + 'px '+ fontDefault;
+        if (this.image.src)
             context.drawImage(this.image, x-size/2, y-size/2, size, size);
         else
             context.fillText(this.icon, x, y); // show icon if there is no image
     }
  
     // Get local storage key used by the medal
-    storageKey()
-    {
-        return medalsSaveName + '_medal_' + this.id;
-    }
+    storageKey() { return medalsSaveName + '_' + this.id; }
 }
 
 // engine automatically renders medals
@@ -146,11 +150,11 @@ function medalsRender()
     
     // update first medal in queue
     const medal = medalsDisplayQueue[0];
-    const time = timeReal - medalsDisplayTimer;
-    if (!medalsDisplayTimer)
-        medalsDisplayTimer = timeReal;
+    const time = timeReal - medalsDisplayTimeLast;
+    if (!medalsDisplayTimeLast)
+        medalsDisplayTimeLast = timeReal;
     else if (time > medalDisplayTime)
-        medalsDisplayQueue.shift(medalsDisplayTimer = 0);
+        medalsDisplayQueue.shift(medalsDisplayTimeLast = 0);
     else
     {
         // slide on/off medals
@@ -164,14 +168,19 @@ function medalsRender()
 
 ///////////////////////////////////////////////////////////////////////////////
 
-/** Newgrounds API wrapper object */
+/** 
+ * Newgrounds API wrapper object
+ * @example
+ * // create a newgrounds object, replace the app id and cipher with your own
+ * const app_id = '53123:1ZuSTQ9l';
+ * const cipher = 'enF0vGH@Mj/FRASKL23Q==';
+ * newgrounds = new Newgrounds(app_id, cipher);
+ */
 class Newgrounds
 {
-    /**
-     * Create a newgrounds object
-     * @param {Number} app_id - The newgrounds App ID
-     * @param {String} [cipher] - The encryption Key (AES-128/Base64)
-     */
+    /** Create a newgrounds object
+     *  @param {Number} app_id   - The newgrounds App ID
+     *  @param {String} [cipher] - The encryption Key (AES-128/Base64) */
     constructor(app_id, cipher)
     {
         ASSERT(!newgrounds && app_id);
@@ -199,7 +208,6 @@ class Newgrounds
             if (medal)
             {
                 // copy newgrounds medal data
-                medal.image =       new Image();
                 medal.image.src =   newgroundsMedal['icon'];
                 medal.name =        newgroundsMedal['name'];
                 medal.description = newgroundsMedal['description'];
@@ -223,7 +231,7 @@ class Newgrounds
     unlockMedal(id) { return this.call('Medal.unlock', {'id':id}, 1); }
 
     /** Send message to post score
-     * @param {Number} id - The scoreboard id
+     * @param {Number} id    - The scoreboard id
      * @param {Number} value - The score value */
     postScore(id, value) { return this.call('ScoreBoard.postScore', {'id':id, 'value':value}, 1); }
 
@@ -231,21 +239,21 @@ class Newgrounds
     logView() { return this.call('App.logView', {'host':this.host}, 1); }
 
     /** Get scores from a scoreboard
-     * @param {Number} id - The scoreboard id
-     * @param {String} [user=0] - A user's id or name
+     * @param {Number} id         - The scoreboard id
+     * @param {String} [user=0]   - A user's id or name
      * @param {Number} [social=0] - If true, only social scores will be loaded
-     * @param {Number} [skip=0] - Number of scores to skip before start
+     * @param {Number} [skip=0]   - Number of scores to skip before start
      * @param {Number} [limit=10] - Number of scores to include in the list
-     * @return {Object} - The response JSON object
+     * @return {Object}           - The response JSON object
      */
     getScores(id, user=0, social=0, skip=0, limit=10)
     { return this.call('ScoreBoard.getScores', {'id':id, 'user':user, 'social':social, 'skip':skip, 'limit':limit}); }
 
     /** Send a message to call a component of the Newgrounds API
-     * @param {String}  component - Name of the component
+     * @param {String}  component      - Name of the component
      * @param {Object}  [parameters=0] - Parameters to use for call
-     * @param {Boolean} [async=0] - If true, wait for response before continuing (will cause stall)
-     * @return {Object} - The response JSON object
+     * @param {Boolean} [async=0]      - If true, don't wait for response before continuing (avoid stall)
+     * @return {Object}                - The response JSON object
      */
     call(component, parameters=0, async=0)
     {

package/engine/engineObject.js

@@ -5,51 +5,83 @@
 'use strict';
 
 /** 
- *  LittleJS Object Base Object Class
- *  <br> - Base object class used by the engine
- *  <br> - Automatically adds self to object list
- *  <br> - Will be updated and rendered each frame
- *  <br> - Renders as a sprite from a tilesheet by default
- *  <br> - Can have color and addtive color applied
- *  <br> - 2d Physics and collision system
- *  <br> - Sorted by renderOrder
- *  <br> - Objects can have children attached
- *  <br> - Parents are updated before children, and set child transform
- *  <br> - Call destroy() to get rid of objects
+ * LittleJS Object Base Object Class
+ * <br> - Base object class used by the engine
+ * <br> - Automatically adds self to object list
+ * <br> - Will be updated and rendered each frame
+ * <br> - Renders as a sprite from a tilesheet by default
+ * <br> - Can have color and addtive color applied
+ * <br> - 2d Physics and collision system
+ * <br> - Sorted by renderOrder
+ * <br> - Objects can have children attached
+ * <br> - Parents are updated before children, and set child transform
+ * <br> - Call destroy() to get rid of objects
+ * <br>
+ * <br>The physics system used by objects is simple and fast with some caveats...
+ * <br> - Collision uses the axis aligned size, the object's rotation angle is only for rendering
+ * <br> - Objects are guaranteed to not intersect tile collision from physics
+ * <br> - If an object starts or is moved inside tile collision, it will not collide with that tile
+ * <br> - Collision for objects can be set to be solid to block other objects
+ * <br> - Objects may get pushed into overlapping other solid objects, if so they will push away
+ * <br> - Solid objects are more performance intensive and should be used sparingly
+ * @example
+ * // create an engine object, normally you would first extend the class with your own
+ * const pos = vec2(2,3);
+ * const object = new EngineObject(pos); 
  */
 class EngineObject
 {
-    /**
-     * Create an engine object and adds it to the list of objects
-     * @param {Vector2} [position=new Vector2(0,0)] - World space position of the object
-     * @param {Vector2} [size=defaultObjectSize] - World space size of the object
-     * @param {Number}  [tileIndex=-1] - Tile to use to render object, untextured if -1
-     * @param {Vector2} [tileSize=defaultTileSize] - Size of tile in source pixels
-     * @param {Number}  [angle=0] - Angle to rotate the object
-     * @param {Color}   [color] - Color to apply to tile when rendered
+    /** Create an engine object and adds it to the list of objects
+     *  @param {Vector2} [position=new Vector2(0,0)] - World space position of the object
+     *  @param {Vector2} [size=objectDefaultSize]    - World space size of the object
+     *  @param {Number}  [tileIndex=-1]              - Tile to use to render object, untextured if -1
+     *  @param {Vector2} [tileSize=tileSizeDefault]  - Size of tile in source pixels
+     *  @param {Number}  [angle=0]                   - Angle to rotate the object
+     *  @param {Color}   [color]                     - Color to apply to tile when rendered
+     *  @param {Number}  [renderOrder=0]             - Objects sorted by renderOrder before being rendered
      */
-    constructor(pos=vec2(), size=defaultObjectSize, tileIndex=-1, tileSize=defaultTileSize, angle=0, color)
+    constructor(pos=vec2(), size=objectDefaultSize, tileIndex=-1, tileSize=tileSizeDefault, angle=0, color, renderOrder=0)
     {
         // set passed in params
         ASSERT(pos && pos.x != undefined && size.x != undefined); // ensure pos and size are vec2s
+
+        /** @property {Vector2} - World space position of the object */
         this.pos = pos.copy();
+        /** @property {Vector2} - World space width and height of the object */
         this.size = size;
+        /** @property {Vector2} - Size of object used for drawing, uses size if not set */
+        this.drawSize;
+        /** @property {Number}  - Tile to use to render object, untextured if -1 */
         this.tileIndex = tileIndex;
+        /** @property {Vector2} - Size of tile in source pixels */
         this.tileSize = tileSize;
+        /** @property {Number}  - Angle to rotate the object */
         this.angle = angle;
+        /** @property {Color}   - Color to apply when rendered */
         this.color = color;
-
-        // set physics defaults
-        this.mass         = defaultObjectMass;
-        this.damping      = defaultObjectDamping;
-        this.angleDamping = defaultObjectAngleDamping;
-        this.elasticity   = defaultObjectElasticity;
-        this.friction     = defaultObjectFriction;
-
-        // init other object stuff
+        /** @property {Color}   - Additive color to apply when rendered */
+        this.additiveColor;
+
+        // set object defaults
+        /** @property {Number} [mass=objectDefaultMass]                 - How heavy the object is */
+        this.mass         = objectDefaultMass;
+        /** @property {Number} [damping=objectDefaultDamping]           - How much to slow down velocity each frame (0-1) */
+        this.damping      = objectDefaultDamping;
+        /** @property {Number} [angleDamping=objectDefaultAngleDamping] - How much to slow down rotation each frame (0-1) */
+        this.angleDamping = objectDefaultAngleDamping;
+        /** @property {Number} [elasticity=objectDefaultElasticity]     - How bouncy the object is when colliding (0-1) */
+        this.elasticity   = objectDefaultElasticity;
+        /** @property {Number} [friction=objectDefaultFriction]         - How much friction to apply when sliding (0-1) */
+        this.friction     = objectDefaultFriction;
+        /** @property {Number} [gravityScale=1]                         - How much to scale gravity by for this object */
+        this.gravityScale = 1;
+        /** @property {Number} [renderOrder=0]                          - Objects are sorted by render order */
+        this.renderOrder = renderOrder;
+
+        // init other internal object stuff
         this.spawnTime = time;
-        this.velocity = vec2(this.collideSolidObjects = this.renderOrder = this.angleVelocity = 0);
-        this.collideTiles = this.gravityScale = 1;
+        this.velocity = vec2(this.collideSolidObjects = this.angleVelocity = 0);
+        this.collideTiles = 1;
         this.children = [];
 
         // add to list of objects
@@ -69,8 +101,8 @@ class EngineObject
         }
 
         // limit max speed to prevent missing collisions
-        this.velocity.x = clamp(this.velocity.x, maxObjectSpeed, -maxObjectSpeed);
-        this.velocity.y = clamp(this.velocity.y, maxObjectSpeed, -maxObjectSpeed);
+        this.velocity.x = clamp(this.velocity.x, -objectMaxSpeed, objectMaxSpeed);
+        this.velocity.y = clamp(this.velocity.y, -objectMaxSpeed, objectMaxSpeed);
 
         // apply physics
         const oldPos = this.pos.copy();
@@ -99,14 +131,14 @@ class EngineObject
         {
             // check collisions against solid objects
             const epsilon = 1e-3; // necessary to push slightly outside of the collision
-            for (const o of engineCollideObjects)
+            for (const o of engineObjectsCollide)
             {
                 // non solid objects don't collide with eachother
-                if (!this.isSolid & !o.isSolid || o.destroyed || o.parent)
+                if (!this.isSolid & !o.isSolid || o.destroyed || o.parent || o == this)
                     continue;
 
                 // check collision
-                if (!isOverlapping(this.pos, this.size, o.pos, o.size) || o == this)
+                if (!isOverlapping(this.pos, this.size, o.pos, o.size))
                     continue;
 
                 // pass collision to objects
@@ -118,7 +150,7 @@ class EngineObject
                     // if already was touching, try to push away
                     const deltaPos = oldPos.subtract(o.pos);
                     const length = deltaPos.length();
-                    const pushAwayAccel = .001; // push away if alread overlapping
+                    const pushAwayAccel = .001; // push away if already overlapping
                     const velocity = length < .01 ? randVector(pushAwayAccel) : deltaPos.scale(pushAwayAccel/length);
                     this.velocity = this.velocity.add(velocity);
                     if (o.mass) // push away if not fixed
@@ -129,16 +161,15 @@ class EngineObject
                 }
 
                 // check for collision
-                const sx = this.size.x + o.size.x;
-                const sy = this.size.y + o.size.y;
-                const smallStepUp = (oldPos.y - o.pos.y)*2 > sy + gravity; // prefer to push up if small delta
-                const isBlockedX = abs(oldPos.y - o.pos.y)*2 < sy;
-                const isBlockedY = abs(oldPos.x - o.pos.x)*2 < sx;
+                const sizeBoth = this.size.add(o.size);
+                const smallStepUp = (oldPos.y - o.pos.y)*2 > sizeBoth.y + gravity; // prefer to push up if small delta
+                const isBlockedX = abs(oldPos.y - o.pos.y)*2 < sizeBoth.y;
+                const isBlockedY = abs(oldPos.x - o.pos.x)*2 < sizeBoth.x;
                 
                 if (smallStepUp || isBlockedY || !isBlockedX) // resolve y collision
                 {
                     // push outside object collision
-                    this.pos.y = o.pos.y + (sy/2 + epsilon) * sign(oldPos.y - o.pos.y);
+                    this.pos.y = o.pos.y + (sizeBoth.y/2 + epsilon) * sign(oldPos.y - o.pos.y);
                     if (o.groundObject && wasMovingDown || !o.mass)
                     {
                         // set ground object if landed on something
@@ -161,15 +192,14 @@ class EngineObject
 
                         // lerp betwen elastic or inelastic based on elasticity
                         const elasticity = max(this.elasticity, o.elasticity);
-                        this.velocity.y = lerp(elasticity, elastic0, inelastic);
-                        o.velocity.y = lerp(elasticity, elastic1, inelastic);
+                        this.velocity.y = lerp(elasticity, inelastic, elastic0);
+                        o.velocity.y = lerp(elasticity, inelastic, elastic1);
                     }
-                    debugPhysics && smallStepUp && (abs(oldPos.x - o.pos.x)*2 > sx) && console.log('stepUp', oldPos.y - o.pos.y);
                 }
                 if (!smallStepUp && (isBlockedX || !isBlockedY)) // resolve x collision
                 {
                     // push outside collision
-                    this.pos.x = o.pos.x + (sx/2 + epsilon) * sign(oldPos.x - o.pos.x);
+                    this.pos.x = o.pos.x + (sizeBoth.x/2 + epsilon) * sign(oldPos.x - o.pos.x);
                     if (o.mass)
                     {
                         // inelastic collision
@@ -183,13 +213,12 @@ class EngineObject
 
                         // lerp betwen elastic or inelastic based on elasticity
                         const elasticity = max(this.elasticity, o.elasticity);
-                        this.velocity.x = lerp(elasticity, elastic0, inelastic);
-                        o.velocity.x = lerp(elasticity, elastic1, inelastic);
+                        this.velocity.x = lerp(elasticity, inelastic, elastic0);
+                        o.velocity.x = lerp(elasticity, inelastic, elastic1);
                     }
                     else // bounce if other object is fixed
                         this.velocity.x *= -this.elasticity;
                 }
-
                 debugPhysics && debugAABB(this.pos, this.size, o.pos, o.size, '#f0f');
             }
         }
@@ -198,8 +227,6 @@ class EngineObject
             // check collision against tiles
             if (tileCollisionTest(this.pos, this.size, this))
             {
-                //debugPhysics && debugRect(this.pos, this.size, '#ff0');
-
                 // if already was stuck in collision, don't do anything
                 // this should not happen unless something starts in collision
                 if (!tileCollisionTest(oldPos, this.size, this))
@@ -256,19 +283,19 @@ class EngineObject
     
     /** Called to check if a tile collision should be resolved
      *  @param {Number}  tileData - the value of the tile at the position
-     *  @param {Vector2} pos - tile where the collision occured
-     *  @return {Boolean} true if the collision should be resolved */
+     *  @param {Vector2} pos      - tile where the collision occured
+     *  @return {Boolean}         - true if the collision should be resolved */
     collideWithTile(tileData, pos)        { return tileData > 0; }
     
     /** Called to check if a tile raycast hit
      *  @param {Number}  tileData - the value of the tile at the position
-     *  @param {Vector2} pos - tile where the raycast is
-     *  @return {Boolean} true if the raycast should hit */
+     *  @param {Vector2} pos      - tile where the raycast is
+     *  @return {Boolean}         - true if the raycast should hit */
     collideWithTileRaycast(tileData, pos) { return tileData > 0; }
 
     /** Called to check if a tile raycast hit
      *  @param {EngineObject} object - the object to test against
-     *  @return {Boolean} true if the collision should be resolved
+     *  @return {Boolean}            - true if the collision should be resolved
      */
     collideWithObject(o)              { return 1; }
 
@@ -312,24 +339,12 @@ class EngineObject
 
     /** Set how this object collides
      *  @param {boolean} [collideSolidObjects=0] - Does it collide with solid objects
-     *  @param {boolean} [isSolid=0] - Does it collide with and block other objects (expensive in large numbers)
-     *  @param {boolean} [collideTiles=1] - Does it collide with the tile collision */
+     *  @param {boolean} [isSolid=0]             - Does it collide with and block other objects (expensive in large numbers)
+     *  @param {boolean} [collideTiles=1]        - Does it collide with the tile collision */
     setCollision(collideSolidObjects=0, isSolid=0, collideTiles=1)
     {
         ASSERT(collideSolidObjects || !isSolid); // solid objects must be set to collide
 
-        // track collidable objects in separate list
-        if (collideSolidObjects && !this.collideSolidObjects)
-        {
-            ASSERT(!engineCollideObjects.includes(this));
-            engineCollideObjects.push(this);
-        }
-        else if (!collideSolidObjects && this.collideSolidObjects)
-        {
-            ASSERT(engineCollideObjects.includes(this))
-            engineCollideObjects.splice(engineCollideObjects.indexOf(this), 1);
-        }
-
         this.collideSolidObjects = collideSolidObjects;
         this.isSolid = isSolid;
         this.collideTiles = collideTiles;