@makefully/platypus 4.1.5 → 4.1.8

package/src/CollisionShape.js

@@ -0,0 +1,315 @@
+import AABB from './AABB.js';
+import Vector from './Vector.js';
+import recycle from 'recycle';
+
+const
+    circleRectCollision = function (circle, rect) {
+        const
+            rectAabb = rect.aABB,
+            hh = rectAabb.halfHeight,
+            hw = rectAabb.halfWidth,
+            shapeDistanceX = Math.abs(circle.x - rect.x),
+            shapeDistanceY = Math.abs(circle.y - rect.y),
+            radius = circle.radius;
+        
+        /* This checks the following in order:
+            - Is the x or y distance between shapes less than half the width or height respectively of the rectangle? If so, we know they're colliding.
+            - Is the x or y distance between the shapes greater than the half width/height plus the radius of the circle? Then we know they're not colliding.
+            - Otherwise, we check the distance between a corner of the rectangle and the center of the circle. If that distance is less than the radius of the circle, we know that there is a collision; otherwise there is not.
+        */
+        return (shapeDistanceX < hw) || (shapeDistanceY < hh) || ((shapeDistanceX < (hw + radius)) && (shapeDistanceY < (hh + radius)) && ((((shapeDistanceX - hw) ** 2) + ((shapeDistanceY - hh) ** 2)) < radius ** 2));
+    },
+    collidesCircle = function (shape) {
+        return this.aABB.collides(shape.aABB) && (
+            ((shape.type === 'rectangle') && circleRectCollision(this, shape)) ||
+            ((shape.type === 'circle')    && ((((this.x - shape.x) ** 2) + ((this.y - shape.y) ** 2)) <= ((this.radius + shape.radius) ** 2)))
+        );
+    },
+    collidesDefault = function () {
+        return false;
+    },
+    collidesRectangle = function (shape) {
+        return this.aABB.collides(shape.aABB) && (
+            (shape.type === 'rectangle') ||
+            ((shape.type === 'circle') && circleRectCollision(shape, this))
+        );
+    },
+    /**
+     * This class defines a collision shape, which defines the 'space' an entity occupies in the collision system. Currently only rectangle and circle shapes can be created. Collision shapes include an axis-aligned bounding box (AABB) that tightly wraps the shape. The AABB is used for initial collision checks.
+     *
+     * @memberof platypus
+     * @class CollisionShape
+     * @param owner {platypus.Entity} The entity that uses this shape.
+     * @param definition {Object} This is an object of key/value pairs describing the shape.
+     * @param definition.x {number} The x position of the shape. The x is always located in the center of the object.
+     * @param definition.y {number} The y position of the shape. The y is always located in the center of the object.
+     * @param [definition.type="rectangle"] {String} The type of shape this is. Currently this can be either "rectangle" or "circle".
+     * @param [definition.jumpThrough] {Object} x/y unit determining jump-through face.
+     * @param [definition.width] {number} The width of the shape if it's a rectangle.
+     * @param [definition.height] {number} The height of the shape if it's a rectangle.
+     * @param [definition.radius] {number} The radius of the shape if it's a circle.
+     * @param [definition.offsetX] {number} The x offset of the collision shape from the owner entity's location.
+     * @param [definition.offsetY] {number} The y offset of the collision shape from the owner entity's location.
+     * @param [definition.regX] {number} The registration x of the collision shape with the owner entity's location if offsetX is not provided.
+     * @param [definition.regY] {number} The registration y of the collision shape with the owner entity's location if offsetX is not provided.
+     * @param collisionType {String} A string describing the collision type of this shape.
+     */
+    CollisionShape = function (owner, definition, collisionType) {
+        const
+            {x, y} = owner ?? definition,
+            {offsetX, offsetY, radius = 0, type = 'rectangle'} = definition,
+            diameter = radius * 2,
+            width = type === 'circle' ? diameter : definition.width ?? diameter,
+            height = type === 'circle' ? diameter : definition.height ?? diameter,
+            regX = definition.regX ?? (width / 2),
+            regY = definition.regY ?? (height / 2);
+
+        // If this shape is recycled, the vectors will already be in place.
+        if (!this.initialized) {
+            this.initialized = true;
+            Vector.assign(this, 'offset', 'offsetX', 'offsetY');
+            Vector.assign(this, 'position', 'x', 'y');
+            Vector.assign(this, 'size', 'width', 'height');
+            this.aABB = AABB.setUp();
+        }
+
+        this.owner = owner;
+        this.collisionType = collisionType;
+        this.jumpThrough = definition.jumpThrough ? Vector.setUp(definition.jumpThrough.x, definition.jumpThrough.y) : null;
+        this.type = type;
+        this.subType = '';
+        
+        /**
+         * Determines whether shapes collide.
+         *
+         * @method platypus.CollisionShape#collides
+         * @param shape {platypus.CollisionShape} The shape to check against for collision.
+         * @return {Boolean} Whether the shapes collide.
+         */
+        if (type === 'circle') {
+            this.collides = collidesCircle;
+        } else if (type === 'rectangle') {
+            this.collides = collidesRectangle;
+        } else {
+            this.collides = collidesDefault;
+        }
+        this.size.setXYZ(width, height);
+        this.radius = radius;
+
+        this.offset.setXYZ(offsetX ?? ((width  / 2) - regX), offsetY ?? ((height / 2) - regY));
+        this.position.setXYZ(x, y).add(this.offset);
+        this.aABB.setAll(this.x, this.y, width, height);
+    },
+    proto = CollisionShape.prototype;
+
+/**
+ * Updates the shape to match another shape.
+ *
+ * @method platypus.CollisionShape#updateAll
+ * @param updateAll {platypus.CollisionShape} The shape to copy into this one.
+ */
+proto.updateAll = function (shape) {
+    this.owner = shape.owner;
+    this.collisionType = shape.collisionType;
+    this.type = shape.type;
+    this.subType = shape.subType;
+    this.offset.x = shape.offset.x;
+    this.offset.y = shape.offset.y;
+    this.position.x = shape.position.x;
+    this.position.y = shape.position.y;
+    this.size.x = shape.size.x;
+    this.size.y = shape.size.y;
+    this.radius = shape.radius;
+    this.aABB.setAll(this.x, this.y, this.width, this.height);
+    if (this.type === 'circle') {
+        this.collides = collidesCircle;
+    } else if (this.type === 'rectangle') {
+        this.collides = collidesRectangle;
+    } else {
+        this.collides = collidesDefault;
+    }
+};
+
+/**
+ * Updates the location of the shape and AABB. The position you send should be that of the owner, the offset of the shape is added inside the function.
+ *
+ * @method platypus.CollisionShape#update
+ * @param ownerX {number} The x position of the owner.
+ * @param ownerY {number} The y position of the owner.
+ */
+proto.update = function (ownerX, ownerY) {
+    const
+        x = ownerX + this.offsetX,
+        y = ownerY + this.offsetY;
+
+    this.position.setXYZ(x, y);
+    this.aABB.move(x, y);
+};
+
+/**
+ * Move the shape's x position.
+ *
+ * @method platypus.CollisionShape#moveX
+ * @param x {number} The x position to which the shape should be moved.
+ */
+proto.moveX = function (x) {
+    this.x = x;
+    this.aABB.moveX(x);
+};
+
+/**
+ * Move the shape's y position.
+ *
+ * @method platypus.CollisionShape#moveY
+ * @param y {number} The y position to which the shape should be moved.
+ */
+proto.moveY = function (y) {
+    this.y = y;
+    this.aABB.moveY(y);
+};
+
+/**
+ * Move the shape's x and y position.
+ *
+ * @method platypus.CollisionShape#moveXY
+ * @param x {number} The x position to which the shape should be moved.
+ * @param y {number} The y position to which the shape should be moved.
+ */
+proto.moveXY = function (x, y) {
+    this.x = x;
+    this.y = y;
+    this.aABB.move(x, y);
+};
+
+/**
+ * Returns the axis-aligned bounding box of the shape.
+ *
+ * @method platypus.CollisionShape#getAABB
+ * @return {platypus.AABB} The AABB of the shape.
+ */
+proto.getAABB = function () {
+    return this.aABB;
+};
+
+/**
+ * Set the shape's position as if the entity's x position is in a certain location.
+ *
+ * @method platypus.CollisionShape#setXWithEntityX
+ * @param entityX {number} The x position of the entity.
+ */
+proto.setXWithEntityX = function (entityX) {
+    this.x = entityX + this.offsetX;
+    this.aABB.moveX(this.x);
+};
+
+/**
+ * Set the shape's position as if the entity's y position is in a certain location.
+ *
+ * @method platypus.CollisionShape#setYWithEntityY
+ * @param entityY {number} The y position of the entity.
+ */
+proto.setYWithEntityY = function (entityY) {
+    this.y = entityY + this.offsetY;
+    this.aABB.moveY(this.y);
+};
+
+/**
+ * Transform the shape using a matrix transformation.
+ *
+ * @method platypus.CollisionShape#multiply
+ * @param matrix {Array} A matrix used to transform the shape.
+ */
+proto.multiply = function (m) {
+    const
+        pos = this.position,
+        own = this.owner.position;
+    
+    pos.subtractVector(own);
+    
+    pos.multiply(m);
+    this.offset.multiply(m);
+    this.size.multiply(m);
+    
+    pos.addVector(own);
+    this.width  = Math.abs(this.width);
+    this.height = Math.abs(this.height);
+    
+    this.aABB.setAll(this.x, this.y, this.width, this.height);
+};
+
+/**
+ * Expresses whether this shape contains the given point.
+ *
+ * @method platypus.CollisionShape#containsPoint
+ * @param x {number} The x-axis value.
+ * @param y {number} The y-axis value.
+ * @return {boolean} Returns `true` if this shape contains the point.
+ */
+proto.containsPoint = function (x, y) {
+    return this.aABB.containsPoint(x, y) && (
+        (this.type === 'rectangle') ||
+        ((this.type === 'circle') && ((((this.x - x) ** 2) + ((this.y - y) ** 2)) <= this.radius ** 2))
+    );
+};
+
+/**
+* Returns a JSON object describing the collision shape.
+*
+* @method platypus.CollisionShape#toJSON
+* @return {Object} Returns a JSON definition that can be used to recreate the collision shape.
+**/
+proto.toJSON = function () {
+    const
+        json = {
+            type: this.type
+        },
+        width = this.size.width,
+        height = this.size.height;
+
+    if (width / 2 !== this.regX) {
+        json.regX = this.regX;
+    }
+    if (height / 2 !== this.regY) {
+        json.regY = this.regY;
+    }
+    if (this.offset.x !== ((width / 2) - this.regX)) {
+        json.offsetX = this.offset.x;
+    }
+    if (this.offset.y !== ((height / 2) - this.regY)) {
+        json.offsetY = this.offset.y;
+    }
+    if (this.type === 'circle') {
+        json.radius = this.radius;
+    } else {
+        json.width = width;
+        json.height = height;
+    }
+
+    return json;
+};
+
+/**
+ * Returns an CollisionShape from cache or creates a new one if none are available.
+ *
+ * @method platypus.CollisionShape.setUp
+ * @return {platypus.CollisionShape} The instantiated CollisionShape.
+ */
+/**
+ * Returns a CollisionShape back to the cache.
+ *
+ * @method platypus.CollisionShape.recycle
+ * @param {platypus.CollisionShape} The CollisionShape to be recycled.
+ */
+/**
+ * Relinquishes properties of the CollisionShape and recycles it.
+ *
+ * @method platypus.CollisionShape#recycle
+ */
+recycle.add(CollisionShape, 'CollisionShape', CollisionShape, function () {
+    if (this.jumpThrough) {
+        this.jumpThrough.recycle();
+    }
+    this.jumpThrough = null;
+}, true);
+
+export default CollisionShape;

package/src/Component.js

@@ -0,0 +1,231 @@
+/*global platypus */
+import {arrayCache, greenSplice} from './utils/array.js';
+import Data from './Data.js';
+
+/**
+ * This is the extendable Component class. Typically specific component classes should be created using `createComponentClass()`. This method accepts component definitions and creates component classes that can be used to create components by entities.  It adds properties and methods that are common to all components so that component definitions can focus on unique properties and methods.
+ *
+ * To create an extended component class, use the following syntax:
+ *
+ *      createComponentClass(componentDefinition, prototype);
+ *
+ *  * `componentDefinition` is list of key/value pairs that describe the component's behavior.
+ *  * `prototype` is an optional prototype that this component extends.
+ * See [component-template.js]("component-template"%20Component.html) for an example componentDefinition that can be sent into this component class factory.
+ *
+ * @memberof platypus
+ * @class Component
+ * @static
+ */
+export default class Component {
+    constructor (type, owner, id) {
+        this.type = type;
+        this.owner = owner;
+        this.id = id;
+        this.publicMethods = Data.setUp();
+        this.listener = Data.setUp(
+            "events", arrayCache.setUp(),
+            "messages", arrayCache.setUp()
+        );
+    }
+
+    /**
+     * Called by constructor once the component is ready.
+     * 
+     * @method platypus.Component#initialize
+     */
+    initialize () {}
+
+    /**
+     * Returns a JSON object describing the component.
+     *
+     * @method platypus.Component#toJSON
+     * @return {Object} Returns a JSON definition that can be used to recreate the component.
+     **/
+    /* toJSON () {} */ // defined in factory.js
+
+    /**
+     * Returns a string describing the component.
+     *
+     * @method platypus.Component#toString
+     * @return {String} Returns the component type as a string of the form "[Component ComponentType]".
+     **/
+    toString () {
+        return "[Component " + this.type + "]";
+    }
+
+    /**
+     * This method cleans up listeners and methods that this component added to the entity. It should never be called by the component itself. Call this.owner.removeComponent(this) instead.
+     *
+     * @method platypus.Component#destroy
+     * @private
+     */
+    destroy () {
+        if (this.listener) {
+            const
+                publicMethods = this.publicMethods,
+                keys = Object.keys(publicMethods);
+            let i = keys.length;
+
+            // Handle component's destroy method before removing messaging and methods.
+            if (this._destroy) {
+                this._destroy();
+            }
+            
+            // Now remove event listeners and methods.
+            while (i--) {
+                this.removeMethod(keys[i]);
+            }
+            this.publicMethods.recycle();
+            
+            this.removeEventListeners();
+            arrayCache.recycle(this.listener.events);
+            arrayCache.recycle(this.listener.messages);
+            this.listener.recycle();
+            this.listener = null;
+        }
+    }
+
+    /**
+     * This method removes multiple event listeners from the entity.
+     *
+     * @method platypus.Component#removeEventListeners
+     * @param [listeners] {Array} The list of listeners to remove. If not supplied, all event listeners are removed.
+     * @private
+     */
+    removeEventListeners (listeners) {
+        if (!listeners) {
+            const
+                {listener, owner} = this,
+                {events, messages} = listener,
+                {length} = events;
+
+            for (let i = 0; i < length; i++) {
+                owner.off(events[i], messages[i]);
+            }
+            events.length = 0;
+            messages.length = 0;
+        } else {
+            for (let i = 0; i < listeners.length; i++) {
+                this.removeEventListener(listeners[i]);
+            }
+        }
+    }
+
+    /**
+     * This method adds an event listener to the entity.
+     *
+     * @method platypus.Component#addEventListener
+     * @param event {String} The event that this component should listen for.
+     * @param callback {Function} The handler for the event.
+     * @return handler {Function} A reference to the bound handler.
+     * @private
+     */
+    addEventListener (event, callback, priority) {
+        const
+            handler = callback.bind(this); // <-- I think we need to stop doing this
+        
+        this.listener.events.push(event);
+        this.listener.messages.push(handler);
+        this.owner.on(event, handler, priority);
+
+        return handler;
+    }
+
+    /**
+     * This method adds one or more event listeners to the entity and returns a teardown function.
+     *
+     * @method platypus.Component#addEventListener
+     * @param eventsObject {Object} Key/value pairs with event names for keys and handlers as values.
+     * @return {Function} Handler teardown function.
+     * @private
+     */
+    addEventListeners (eventsObject) {
+        const
+            {owner} = this,
+            {parent} = owner,
+            tds = Object.keys(eventsObject).map((key) => {
+                const
+                    handler = this.addEventListener(key, eventsObject[key]);
+
+                return () => this.removeEventListener(key, handler);
+            });
+
+        if (owner.state.get('loaded')) {
+            parent.triggerEvent?.('child-entity-updated', owner);
+        }
+
+        return () => {
+            tds.forEach((td) => td());
+            parent.triggerEvent?.('child-entity-updated', owner);
+        };
+    }
+
+    /**
+     * This method adds a method to the entity.
+     *
+     * @method platypus.Component#addMethod
+     * @param name {String} The name of the method. For example, if name is "turnYellow", the method is accessible on the entity as `entity.turnYellow()`.
+     * @param func {Function} The function describing the method.
+     * @private
+     */
+    addMethod (name, func) {
+        if (this.owner[name]) {
+            platypus.debug.warn(this.owner.type + ': Entity already has a method called "' + name + '". Method not added.');
+        } else {
+            this.owner[name] = func.bind(this);
+            this.publicMethods[name] = func;
+        }
+    }
+
+    /**
+     * This method removes an event listener from the entity.
+     *
+     * @method platypus.Component#removeEventListener
+     * @param event {String} The event for which to remove a listener.
+     * @param callback {Function} The listener to remove. If not supplied, all event listeners for the provided event are removed.
+     * @private
+     */
+    removeEventListener (event, callback) {
+        const
+            {listener, owner} = this,
+            {events, messages} = listener;
+        
+        for (let i = events.length - 1; i >= 0; i--) {
+            if ((events[i] === event) && (!callback || (messages[i] === callback))) {
+                owner.off(event, messages[i]);
+                greenSplice(events, i);
+                greenSplice(messages, i);
+            }
+        }
+    }
+
+    /**
+     * This method removes a method from the entity.
+     *
+     * @method platypus.Component#removeMethod
+     * @param name {String} The name of the method to be removed.
+     * @private
+     */
+    removeMethod (name) {
+        if (!this.owner[name]) {
+            platypus.debug.warn(this.owner.type + ': Entity does not have a method called "' + name + '".');
+        } else {
+            delete this.owner[name];
+        }
+        delete this.publicMethods[name];
+    };
+
+    /**
+     * This method can be overwritten to provide the list of assets this component requires. This method is invoked when the list of game scenes is created to determine assets for each scene.
+     *
+     * @method platypus.Component#getAssetList
+     * @param definition {Object} The definition for the component.
+     * @param properties {Object} The properties of the Entity.
+     * @param defaultProperties {Object} The default properties of the Entity.
+     * @return {Array} A list of the necessary assets to load.
+     */
+    static getAssetList () {
+        return arrayCache.setUp();
+    }
+}

package/src/Data.js

@@ -0,0 +1,64 @@
+import recycle from 'recycle';
+
+/**
+ * This class defines a generic data object to use for messaging. It includes recycle methods to encourage reuse.
+ *
+ * @memberof platypus
+ * @class Data
+ * @param {String|Object} first Can be an object of key/value pairs or the parameters can be an alternating list of keys and values.
+ * @return {Data} Returns the new Data object.
+ */
+const
+    Data = function (first) {
+        let i = arguments.length;
+        
+        if (first) {
+            if (typeof first === 'string') {
+                if (i % 2) {
+                    this[i] = null;
+                    i -= 1;
+                }
+                while (i) {
+                    this[arguments[i - 2]] = arguments[i - 1];
+                    i -= 2;
+                }
+            } else {
+                const
+                    keys = Object.keys(first);
+                let j = keys.length;
+
+                while (j--) {
+                    this[keys[j]] = first[keys[j]];
+                }
+            }
+        }
+    };
+
+/**
+ * Returns Data from cache or creates a new one if none are available.
+ *
+ * @method platypus.Data.setUp
+ * @return {platypus.Data} The instantiated Data.
+ */
+/**
+ * Returns Data back to the cache. Prefer the Data's recycle method since it recycles property objects as well.
+ *
+ * @method platypus.Data.recycle
+ * @param {platypus.Data} The Data to be recycled.
+ */
+/**
+ * Relinquishes Data properties and recycles it.
+ *
+ * @method platypus.Data#recycle
+ */
+recycle.add(Data, 'Data', Data, function () {
+    const
+        keys = Object.keys(this);
+    let i = keys.length;
+
+    while (i--) {
+        delete this[keys[i]];
+    }
+}, true);
+
+export default Data;