littlejsengine 1.0.14 → 1.1.8

package/engine/{engineMedal.js → engineMedals.js}

@@ -1,24 +1,61 @@
-/*
-    LittleJS Medal System
-    - Tracks and displays medals
-    - Saves medals to local storage
-    - Newgrounds and OS13k integration
-*/
+/** 
+ *  LittleJS Medal System
+ *  <br> - Tracks and displays medals
+ *  <br> - Saves medals to local storage
+ *  <br> - Newgrounds and OS13k integration
+ *  @namespace Medals
+ */
 
 'use strict';
 
-const medals = [], medalsDisplayQueue = [];
-let medalsGameName, medalsPreventUnlock, medalsDisplayTimer, newgrounds;
+/** List of all medals
+ *  @memberof Medals */
+const medals = [];
 
-function medalsInit(gameName)
+/** Set to stop medals from being unlockable (like if cheats are enabled)
+ *  @memberof Medals */
+let medalsPreventUnlock;
+
+/** This can used to enable Newgrounds functionality
+ *  @type {Newgrounds}
+ *  @memberof Medals */
+let newgrounds;
+
+// Engine internal variables not exposed to documentation
+let medalsDisplayQueue = [], medalsSaveName, medalsDisplayTimer;
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Initialize medals with a save name used for storage
+ *  <br> - Checks if medals are unlocked
+ *  <br> - Call this after creating all medals
+ *  @param {String} saveName
+ *  @memberof Medals */
+function medalsInit(saveName)
 {
     // check if medals are unlocked
-    medalsGameName = gameName;
+    medalsSaveName = saveName;
     debugMedals || medals.forEach(medal=> medal.unlocked = localStorage[medal.storageKey()]);
 }
 
+/** 
+ * 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.', '🎖️');
+ * 
+ * // 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
+     */
     constructor(id, name, description='', icon='🏆', src)
     {
         ASSERT(id >= 0 && !medals[id]);
@@ -37,26 +74,25 @@ class Medal
         }
     }
 
+    /** Unlocks a medal if not already unlocked */
     unlock()
     {
         if (medalsPreventUnlock || this.unlocked)
             return;
 
         // save the medal
-        ASSERT(medalsGameName); // game name must be set
+        ASSERT(medalsSaveName); // game name must be set
         localStorage[this.storageKey()] = this.unlocked = 1;
         medalsDisplayQueue.push(this);
 
         // save for newgrounds and OS13K
         newgrounds && newgrounds.unlockMedal(this.id);
-        localStorage['OS13kTrophy,' + this.icon + ',' + medalsGameName + ',' + this.name] = this.description;
-    }
- 
-    storageKey()
-    {
-        return medalsGameName + '_medal_' + this.id;
+        localStorage['OS13kTrophy,' + this.icon + ',' + medalsSaveName + ',' + this.name] = this.description;
     }
 
+    /** Render a medal
+     *  @param {Number} [hidePercent=0] - How much to slide the medal off screen
+     */
     render(hidePercent=0)
     {
         const context = overlayContext;
@@ -77,25 +113,36 @@ class Medal
 
         // draw the text
         context.textAlign = 'left';
-        context.font = '3em '+ defaultFont;
+        context.font = '3em '+ fontDefault;
         context.fillText(this.name, x+medalDisplayIconSize+25, y+35);
-        context.font = '1.5em '+ defaultFont;
+        context.font = '1.5em '+ fontDefault;
         context.restore(context.fillText(this.description, x+medalDisplayIconSize+25, y+70));
     }
 
+    /** Render the icon for a medal
+     *  @param {Number} x - Screen space X position
+     *  @param {Number} y - Screen space Y position
+     *  @param {Number} [size=medalDisplayIconSize] - Screen space size
+     */
     renderIcon(x, y, size=medalDisplayIconSize)
     {
         // draw the image or icon
         const context = overlayContext;
         context.textAlign = 'center';
         context.textBaseline = 'middle';
-        context.font = size*.6 + 'px '+ defaultFont;
+        context.font = size*.6 + 'px '+ fontDefault;
         context.fillStyle = '#000';
         if (this.image)
             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;
+    }
 }
 
 // engine automatically renders medals
@@ -106,9 +153,9 @@ function medalsRender()
     
     // update first medal in queue
     const medal = medalsDisplayQueue[0];
-    const time = realTime - medalsDisplayTimer;
+    const time = timeReal - medalsDisplayTimer;
     if (!medalsDisplayTimer)
-        medalsDisplayTimer = realTime;
+        medalsDisplayTimer = timeReal;
     else if (time > medalDisplayTime)
         medalsDisplayQueue.shift(medalsDisplayTimer = 0);
     else
@@ -123,15 +170,26 @@ function medalsRender()
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-// Newgrounds API wrapper
 
+/** 
+ * 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) */
     constructor(app_id, cipher)
     {
         ASSERT(!newgrounds && app_id);
         this.app_id = app_id;
         this.cipher = cipher;
+        this.host = location ? location.hostname : '';
 
         // create an instance of CryptoJS for encrypted calls
         cipher && (this.cryptoJS = CryptoJS());
@@ -153,11 +211,16 @@ class Newgrounds
             if (medal)
             {
                 // copy newgrounds medal data
-                medal.name = newgroundsMedal['name'];
+                medal.image =       new Image();
+                medal.image.src =   newgroundsMedal['icon'];
+                medal.name =        newgroundsMedal['name'];
                 medal.description = newgroundsMedal['description'];
-                medal.unlocked = newgroundsMedal['unlocked'];
-                medal.image = new Image();
-                medal.image.src = newgroundsMedal['icon'];
+                medal.unlocked =    newgroundsMedal['unlocked'];
+                medal.difficulty =  newgroundsMedal['difficulty'];
+                medal.value =       newgroundsMedal['value'];
+
+                if (medal.value)
+                    medal.description = medal.description + ' (' + medal.value + ')';
             }
         }
     
@@ -167,30 +230,55 @@ class Newgrounds
         debugMedals && console.log(this.scoreboards);
     }
 
-    unlockMedal(id)
-    {
-        return this.call('Medal.unlock', {'id':id}, 1);
-    }
+    /** Send message to unlock a medal by id
+     * @param {Number} id - The medal id */
+    unlockMedal(id) { return this.call('Medal.unlock', {'id':id}, 1); }
 
-    postScore(id, value)
-    {
-        return this.call('ScoreBoard.postScore', {'id':id, 'value':value}, 1);
-    }
+    /** Send message to post score
+     * @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); }
+
+    /** Send message to log a view */
+    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} [social=0] - If true, only social scores will be loaded
+     * @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
+     */
     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});
-    }
-    
+    { 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 {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
+     */
     call(component, parameters=0, async=0)
     {
+        const call = {'component':component, 'parameters':parameters};
+        if (this.cipher)
+        {
+            // encrypt using AES-128 Base64 with cryptoJS
+            const cryptoJS = this.cryptoJS;
+            const aesKey = cryptoJS['enc']['Base64']['parse'](this.cipher);
+            const iv = cryptoJS['lib']['WordArray']['random'](16);
+            const encrypted = cryptoJS['AES']['encrypt'](JSON.stringify(call), aesKey, {'iv':iv});
+            call['secure'] = cryptoJS['enc']['Base64']['stringify'](iv.concat(encrypted['ciphertext']));
+            call['parameters'] = 0;
+        }
+
         // build the input object
         const input = 
         {
             'app_id':     this.app_id,
             'session_id': this.session_id,
-            'call':       this.encryptCall({'component':component, 'parameters':parameters})
+            'call':       call
         };
 
         // build post data
@@ -205,21 +293,6 @@ class Newgrounds
         debugMedals && console.log(xmlHttp.responseText);
         return xmlHttp.responseText && JSON.parse(xmlHttp.responseText);
     }
-    
-    encryptCall(call)
-    {
-        if (!this.cipher)
-            return call;
-        
-        // encrypt using AES-128 Base64 with cryptoJS
-        const cryptoJS = this.cryptoJS;
-        const aesKey = cryptoJS['enc']['Base64']['parse'](this.cipher);
-        const iv = cryptoJS['lib']['WordArray']['random'](16);
-        const encrypted = cryptoJS['AES']['encrypt'](JSON.stringify(call), aesKey, {'iv':iv});
-        call['secure'] = cryptoJS['enc']['Base64']['stringify'](iv.concat(encrypted['ciphertext']));
-        call['parameters'] = 0;
-        return call;
-    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////

package/engine/engineObject.js

@@ -1,49 +1,86 @@
 /*
-    LittleJS Object Base Class
-    - Base object class used by the engine
-    - Automatically adds self to object list
-    - Will be updated and rendered each frame
-    - Renders as a sprite from a tilesheet by default
-    - Can have color and addtive color applied
-    - 2d Physics and collision system
-    - Sorted by renderOrder
-    - Objects can have children attached
-    - Parents are updated before children, and set child transform
-    - Call destroy() to get rid of objects
+    LittleJS Object System
 */
 
 '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
+ * @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
 {
-    constructor(pos, size=defaultObjectSize, tileIndex=-1, tileSize=defaultTileSize, angle=0, color)
+    /** 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=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;
+        /** @property {Color}  - Additive color to apply when rendered */
+        this.additiveColor;
 
-        // set physics defaults
-        this.mass         = defaultObjectMass;
-        this.damping      = defaultObjectDamping;
-        this.angleDamping = defaultObjectAngleDamping;
-        this.elasticity   = defaultObjectElasticity;
-        this.friction     = defaultObjectFriction;
+        // 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 object stuff
+        // 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
         engineObjects.push(this);
     }
     
+    /** Update the object transform and physics, called automatically by engine once each frame */
     update()
     {
         const parent = this.parent;
@@ -56,8 +93,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();
@@ -111,7 +148,7 @@ class EngineObject
                     if (o.mass) // push away if not fixed
                         o.velocity = o.velocity.subtract(velocity);
                         
-                    debugPhysics && debugAABB(this.pos, o.pos, this.size, o.size, '#f00');
+                    debugPhysics && debugAABB(this.pos, this.size, o.pos, o.size, '#f00');
                     continue;
                 }
 
@@ -177,7 +214,7 @@ class EngineObject
                         this.velocity.x *= -this.elasticity;
                 }
 
-                debugPhysics && debugAABB(this.pos, o.pos, this.size, o.size, '#f0f');
+                debugPhysics && debugAABB(this.pos, this.size, o.pos, o.size, '#f0f');
             }
         }
         if (this.collideTiles)
@@ -185,8 +222,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))
@@ -199,13 +234,20 @@ class EngineObject
                         // set if landed on ground
                         this.groundObject = wasMovingDown;
 
-                        // push out of collision and bounce
-                        this.pos.y = oldPos.y;
+                        // bounce velocity
                         this.velocity.y *= -this.elasticity;
+
+                        // adjust next velocity to settle on ground
+                        const o = (oldPos.y - this.size.y/2|0) - (oldPos.y - this.size.y/2);
+                        if (o < 0 && o > -1 && o > this.damping * this.velocity.y + gravity * this.gravityScale) 
+                            this.velocity.y = this.damping ? (o - gravity * this.gravityScale) / this.damping : 0;
+
+                        // move to previous position
+                        this.pos.y = oldPos.y;
                     }
                     if (isBlockedX)
                     {
-                        // push out of collision and bounce
+                        // move to previous position and bounce
                         this.pos.x = oldPos.x;
                         this.velocity.x *= -this.elasticity;
                     }
@@ -214,12 +256,14 @@ class EngineObject
         }
     }
        
+    /** Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder */
     render()
     {
         // default object render
         drawTile(this.pos, this.drawSize || this.size, this.tileIndex, this.tileSize, this.color, this.angle, this.mirror, this.additiveColor);
     }
     
+    /** Destroy this object, destroy it's children, detach it's parent, and mark it for removal */
     destroy()             
     { 
         if (this.destroyed)
@@ -231,15 +275,45 @@ class EngineObject
         for (const child of this.children)
             child.destroy(child.parent = 0);
     }
-    collideWithTile(data, pos)        { return data > 0; }
-    collideWithTileRaycast(data, pos) { return data > 0; }
+    
+    /** 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 */
+    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 */
+    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
+     */
     collideWithObject(o)              { return 1; }
+
+    /** How long since the object was created
+     *  @return {Number} */
     getAliveTime()                    { return time - this.spawnTime; }
-    applyAcceleration(a)              { ASSERT(!this.isFixed()); this.velocity = this.velocity.add(a); }
+
+    /** Apply acceleration to this object (adjust velocity, not affected by mass)
+     *  @param {Vector2} acceleration */
+    applyAcceleration(a)              { if (this.mass) this.velocity = this.velocity.add(a); }
+
+    /** Apply force to this object (adjust velocity, affected by mass)
+     *  @param {Vector2} force */
     applyForce(force)	              { this.applyAcceleration(force.scale(1/this.mass)); }
-    isFixed()                         { return !this.mass; }
-    getMirrorSign(s=1)                { return this.mirror ? -s : s; }
+    
+    /** Get the direction of the mirror
+     *  @return {Number} -1 if this.mirror is true, or 1 if not mirrored */
+    getMirrorSign() { return this.mirror ? -1 : 1; }
 
+    /** Attaches a child to this with a given local transform
+     *  @param {EngineObject} child
+     *  @param {Vector2}      [localPos=new Vector2]
+     *  @param {Number}       [localAngle=0] */
     addChild(child, localPos=vec2(), localAngle=0)
     {
         ASSERT(!child.parent && !this.children.includes(child));
@@ -248,6 +322,9 @@ class EngineObject
         child.localPos = localPos.copy();
         child.localAngle = localAngle;
     }
+
+    /** Removes a child from this one
+     *  @param {EngineObject} child */
     removeChild(child)
     {
         ASSERT(child.parent == this && this.children.includes(child));
@@ -255,7 +332,11 @@ class EngineObject
         child.parent = 0;
     }
 
-    setCollision(collideSolidObjects, isSolid, collideTiles=1)
+    /** 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 */
+    setCollision(collideSolidObjects=0, isSolid=0, collideTiles=1)
     {
         ASSERT(collideSolidObjects || !isSolid); // solid objects must be set to collide
 
@@ -275,35 +356,4 @@ class EngineObject
         this.isSolid = isSolid;
         this.collideTiles = collideTiles;
     }
-}
-
-function destroyAllObjects()
-{
-    // remove all objects that are not persistent or are descendants of something persistent
-    for (const o of engineObjects)
-        o.persistent || o.parent || o.destroy();
-    engineObjects = engineObjects.filter(o=>!o.destroyed);
-}
-
-function forEachObject(pos, size, callbackFunction, objects=engineObjects)
-{
-    if (!pos)
-    {
-        // all objects
-        for (const o of objects)
-            callbackFunction(o);
-    }
-    else if (size.x != undefined)
-    {
-        // aabb test
-        for (const o of objects)
-            isOverlapping(pos, size, o.pos, o.size) && callbackFunction(o);
-    }
-    else
-    {
-        // circle test
-        const sizeSquared = size*size;
-        for (const o of objects)
-            pos.distanceSquared(o.pos) < sizeSquared && callbackFunction(o);
-    }
 }