@makefully/platypus 4.1.4 → 4.1.6

package/src/ActionState.js

@@ -0,0 +1,121 @@
+import Data from './Data.js';
+import StateMap from './StateMap.js';
+import {arrayCache} from './utils/array.js';
+import recycle from 'recycle';
+
+const
+    /**
+     * This class defines an action state based on one or more inputs. This is used by [EntityController](platypus.components.EntityController.html) to produce event messages listing whether a particular action is "triggered", "pressed", and/or "released".
+     *
+     * @memberof platypus
+     * @class ActionState
+     * @param event {string} The name of the event to trigger on the Entity.
+     * @param states {Object} A list of key/value pairs describing what states should be `true` or `false` on the Entity for this action to be triggered.
+     * @param trigger {Function} The function to be called if one or more inputs are active and the current state of the Entity is valid.
+     * @property {string} [event] The name of the event to trigger on the Entity.
+     * @property {Function} [trigger] The function to call if the ActionState is active.
+     * @property {boolean} [active] Whether any of the ActionState's inputs are active.
+     * @property {boolean} [wasActive] Whether any of the ActionState's inputs were active last update.
+     * @property {boolean} [valid] Whether the Entity's state is valid for this ActionState.
+     * @property {boolean} [wasValid] Whether the Entity's state was valid for this ActionState last update.
+     * @property {platypus.StateMap} [states] The state of the Entity that is valid for this ActionState.
+     * @property {Array} [inputs] The list of input toggles to track control input.
+     * @property {platypus.Data} [stateSummary] The message that is passed to the Entity if the ActionState is active.
+     * @return {ActionState} Returns the new ActionState object.
+     */
+    ActionState = function (event, states, trigger) {
+        this.event     = event;
+        this.trigger   = trigger;
+        this.active    = false;
+        this.wasActive = false;
+        this.valid     = true;
+        this.wasValid  = true;
+        this.states = StateMap.setUp(states);
+        this.inputs = arrayCache.setUp();
+
+        this.stateSummary = Data.setUp(
+            "pressed",   false,
+            "released",  false,
+            "triggered", false
+        );
+    },
+    orArray = function (element) {
+        return element;
+    },
+    proto = ActionState.prototype;
+
+/**
+ * Updates the state of the action by checking the state of the Entity and whether any inputs are active.
+ *
+ * @method platypus.ActionState#update
+ * @param state {Object} The Entity's `state` property to compare against the ActionState's valid state.
+ * @return {Boolean} Whether the ActionState is triggered, pressed, or released.
+ */
+proto.update = function (state) {
+    const
+        ss = this.stateSummary;
+    
+    this.valid     = state.includes(this.states);
+    this.active    = this.inputs.some(orArray);
+    
+    ss.pressed     = this.valid && this.active;
+    ss.released    = this.wasActive && ((!this.valid && this.wasValid) || (this.valid && !this.active));
+    ss.triggered   = this.valid && this.active && !this.wasActive;
+    
+    this.wasValid  = this.valid;
+    this.wasActive = this.active;
+    
+    return ss.pressed || ss.released || ss.triggered;
+};
+
+/**
+ * Triggers events on the Entity related to the ActionState's state. This is necessarily separate from the `update` method since triggered events could affect entity state. The messages have the following form and are only triggered if one of the values is `true`:
+ *
+ *     {
+ *         "triggered": true,
+ *         "pressed": true,
+ *         "released": false
+ *     }
+ *
+ * Here is a mapping of the various event messages depending on the ActionState's state.
+ *
+ *     ActionState State:
+ *          wasValid:  0 0 0 0  0 0 0 0  1 1 1 1  1 1 1 1
+ *             valid:  0 0 0 0  1 1 1 1  0 0 0 0  1 1 1 1
+ *         wasActive:  0 0 1 1  0 0 1 1  0 0 1 1  0 0 1 1
+ *            active:  0 1 0 1  0 1 0 1  0 1 0 1  0 1 0 1
+ *     Events:
+ *         triggered:  0 0 0 0  0 1 0 0  0 0 0 0  0 1 0 0
+ *           pressed:  0 0 0 0  0 1 0 1  0 0 0 0  0 1 0 1
+ *          released:  0 0 0 0  0 0 1 0  0 0 1 1  0 0 1 0
+ *
+ * @method platypus.ActionState#resolve
+ */
+proto.resolve = function () {
+    this.trigger(this.event, this.stateSummary);
+};
+
+/**
+ * Returns an ActionState from cache or creates a new one if none are available.
+ *
+ * @method platypus.ActionState.setUp
+ * @return {platypus.ActionState} The instantiated ActionState.
+ */
+/**
+ * Returns an ActionState back to the cache. Prefer the ActionState's recycle method since it recycles property objects as well.
+ *
+ * @method platypus.ActionState.recycle
+ * @param {platypus.ActionState} actionState The ActionState to be recycled.
+ */
+/**
+ * Relinquishes properties of the ActionState and recycles it.
+ *
+ * @method platypus.ActionState#recycle
+ */
+recycle.add(ActionState, 'ActionState', ActionState, function () {
+    this.states.recycle();
+    this.stateSummary.recycle();
+    arrayCache.recycle(this.inputs);
+}, true);
+
+export default ActionState;

package/src/AssetManager.js

@@ -0,0 +1,206 @@
+/**
+ * This class is instantiated by Platypus at `platypus.assetCache` to track assets: loading assets needed for particular layers and unloading assets once they're no longer needed.
+ *
+ * @memberof platypus
+ * @class AssetManager
+**/
+/* global platypus, setTimeout */
+import Data from './Data.js';
+import DataMap from './DataMap.js';
+import {Assets} from 'pixi.js';
+import {arrayCache} from './utils/array.js';
+
+const
+    fn = /^(?:\w+:\/{2}\w+(?:\.\w+)*\/?)?(?:[\/.]*?(?:[^?]+)?\/)?(?:([^\/?]+?)(?:\.(\w+|{\w+(?:,\w+)*}))?)(?:\?\S*)?$/,
+    formatAsset = function (asset) { //TODO: Make this behavior less opaque.
+        const
+            path = asset.src ?? asset,
+            match = path.match(fn);
+            
+        if (asset.id) {
+            platypus.debug.warn(`AssetManager: Use "alias" instead of "id" for asset identification. (${asset.id})`);
+        }
+
+        return Data.setUp(
+            'alias', asset.alias ?? [asset.id ?? (match ? match[1] : path)],
+            'src', path,
+            'data', asset.data ?? null
+        );
+    };
+
+export default class AssetManager {
+    constructor () {
+        this.assets = DataMap.setUp();
+        this.counts = Data.setUp();
+    }
+
+    /**
+     * This method removes an asset from memory if it's the last needed instance of the asset.
+     *
+     * @method platypus.AssetManager#delete
+     * @param {*} alias
+     * @return {Boolean} Returns `true` if asset was removed from asset cache.
+     */
+    delete (alias) {
+        const assets = this.assets;
+
+        if (assets.has(alias)) {
+            const counts = this.counts;
+
+            counts[alias] -= 1;
+            if (counts[alias] === 0) {
+                const asset = assets.get(alias);
+                
+                if (asset && asset.src) {
+                    asset.src = '';
+                }
+                assets.delete(alias);
+            }
+
+            return !counts[alias];
+        } else {
+            return false;
+        }
+    }
+
+    /**
+     * Returns a loaded instance of a given asset.
+     *
+     * @method platypus.AssetManager#get
+     * @param {*} alias
+     * @return {Object} Returns the asset if defined.
+     */
+    get (alias) {
+        return this.assets.get(alias);
+    }
+
+    /**
+     * Returns alias for given path.
+     *
+     * @method platypus.AssetManager#getFileId
+     * @param {*} path
+     * @return {String} Returns alias generated from path.
+     */
+    getFileId (path) {
+        const match = path.match(fn);
+
+        return match ? match[1] : path;
+    }
+
+    /**
+     * Returns whether a given asset is currently loaded by the AssetManager.
+     *
+     * @method platypus.AssetManager#has
+     * @param {*} alias
+     * @return {Object} Returns `true` if the asset is loaded and `false` if not.
+     */
+    has (alias) {
+        return this.assets.has(alias);
+    }
+
+    /**
+     * Sets a mapping between an alias and a loaded asset. If the mapping already exists, simply increment the count for a given alias.
+     *
+     * @method platypus.AssetManager#set
+     * @param {*} alias
+     * @param {*} value The loaded asset.
+     * @param {Number} count The number of assets needed.
+     */
+    set (alias, value, count = 1) {
+        const
+            assets = this.assets,
+            counts = this.counts;
+
+        if (assets.has(alias)) {
+            counts[alias] += count;
+        } else {
+            assets.set(alias, value);
+            counts[alias] = count;
+        }
+    }
+
+    /**
+     * Loads a list of assets.
+     *
+     * @method platypus.AssetManager#load
+     * @param {Array} list A list of assets to load.
+     * @param {Function} one This function is called as each asset is loaded.
+     * @param {Function} all This function is called once all assets in the list are loaded.
+     */
+    async load (list, one, all) {
+        const
+            counts = this.counts,
+            needsLoading = arrayCache.setUp(),
+            adds = Data.setUp();
+
+        if (platypus.game?.options?.images ?? platypus.game?.options?.audio) {
+            platypus.debug.warn('AssetManager: Default asset folders are no longer specified via game options. Include pathing in asset imports.');
+        }
+
+        // work-around for Pixi v7 Spine PMA issue https://github.com/pixijs/pixijs/issues/9141
+        Assets.setPreferences({
+            preferCreateImageBitmap: false,
+            preferWorker: false
+        });
+
+        for (let i = 0; i < list.length; i++) {
+            const
+                item = formatAsset(list[i]),
+                alias = item.alias?.[0] ?? item.id ?? item.src ?? item;
+
+            if (this.has(alias)) {
+                counts[alias] += 1;
+            } else if (adds.hasOwnProperty(alias)) {
+                adds[alias] += 1;
+            } else {
+                adds[alias] = 1;
+                needsLoading.push(item);
+            }
+        }
+
+        if (needsLoading.length) {
+            // Do this first to pass `data` property if needed
+            needsLoading.forEach((asset) => Assets.add(asset));
+
+            const
+                aliases = needsLoading.map((asset) => asset.alias[0]),
+                loadedList = await Assets.load(aliases, one);
+
+            aliases.forEach((alias) => {
+                const
+                    response = loadedList[alias];
+
+                this.set(alias, response, adds[alias]);
+            });
+
+            if (all) {
+                all();
+            }
+        } else {
+            setTimeout(() => { // To run in same async sequence as above.
+                if (one) {
+                    one(1);
+                }
+                if (all) {
+                    all();
+                }
+            }, 1);
+        }
+
+        arrayCache.recycle(needsLoading);
+    }
+
+    /**
+     * Unloads a list of assets. This is identical to passing each item in the list to `.delete()`.
+     *
+     * @method platypus.AssetManager#unload
+     * @param {Array} list A list of assets to unload.
+     */
+    unload (list) {
+        let i = list.length;
+
+        while (i--) {
+            this.delete(list[i].alias?.[0] ?? list[i].id ?? list[i]);
+        }
+    }
+}

package/src/CollisionData.js

@@ -0,0 +1,96 @@
+import Vector from './Vector.js';
+import recycle from 'recycle';
+
+/**
+ * CollisionData holds collision data passed to entities during collisions with other entities. This class is primarily used by the ["HandlerCollision"]("HandlerCollision"%20Component.html) Component to trigger messages on child entities as collision occur.
+ *
+ * @memberof platypus
+ * @class CollisionData
+ * @param occurredOrData {Boolean|CollisionData} Whether this represents an actual collision between two shapes. If a CollisionData instance is provided, the instance's full set of values are copied.
+ * @param direction {Number} 1 or -1 to define the direction of the collision.
+ * @param position {Number} A positive number describing position along the line of collision direction.
+ * @param deltaMovement {Number} A positive number describing the magnitude of overlap.
+ * @param aABB {platypus.AABB} An AABB of the colliding shape.
+ * @param thisShape {platypus.Shape} The moving shape.
+ * @param thatShape {platypus.Shape} The stationary shape being collided with.
+ * @param vector {platypus.Vector} The vector describing the contact point.
+ * @param stuck {Number} The amount of unwarranted overlap if shapes start in a collided position before moving.
+ * @return {platypus.CollisionData} Returns the new CollisionData object.
+ */
+const
+    CollisionData = function (occurredOrData) {
+        if (!this.vector) {
+            this.vector = Vector.setUp();
+        }
+        if (occurredOrData instanceof CollisionData) {
+            this.copy(occurredOrData);
+        } else {
+            this.set.apply(this, arguments);
+        }
+    },
+    proto = CollisionData.prototype;
+
+/**
+ * Sets all of the properties of the CollisionData.
+ *
+ * @method platypus.CollisionData#set
+ * @param occurred {Boolean} Whether this represents an actual collision between two shapes.
+ * @param direction {Number} 1 or -1 to define the direction of the collision.
+ * @param position {Number} A positive number describing position along the line of collision direction.
+ * @param deltaMovement {Number} A positive number describing the magnitude of overlap.
+ * @param aABB {platypus.AABB} An AABB of the colliding shape.
+ * @param thisShape {platypus.Shape} The moving shape.
+ * @param thatShape {platypus.Shape} The stationary shape being collided with.
+ * @param vector {platypus.Vector} The vector describing the contact point.
+ * @param stuck {Number} The amount of unwarranted overlap if shapes start in a collided position before moving.
+ */
+proto.set = function (occurred, direction, position, deltaMovement, aABB, thisShape, thatShape, vector, stuck) {
+    this.occurred = occurred || false;
+    this.direction = direction || null;
+    this.position = position || null;
+    this.deltaMovement = deltaMovement || null;
+    this.aABB = aABB || null;
+    this.thisShape = thisShape || null;
+    this.thatShape = thatShape || null;
+    this.vector.set(vector);
+    this.stuck  = stuck || 0;
+};
+
+/**
+ * Sets all of the properties of the CollisionData to match those of the provided CollisionData object.
+ *
+ * @method platypus.CollisionData#copy
+ * @param dataToCopy {CollisionData} The object values to copy.
+ */
+proto.copy = function (dataToCopy) {
+    this.occurred         = dataToCopy.occurred;
+    this.direction         = dataToCopy.direction;
+    this.position         = dataToCopy.position;
+    this.deltaMovement     = dataToCopy.deltaMovement;
+    this.aABB             = dataToCopy.aABB;
+    this.thisShape      = dataToCopy.thisShape;
+    this.thatShape      = dataToCopy.thatShape;
+    this.vector.setVector(dataToCopy.vector);
+    this.stuck          = dataToCopy.stuck;
+};
+
+/**
+ * Returns an collisionData from cache or creates a new one if none are available.
+ *
+ * @method platypus.CollisionData.setUp
+ * @return {platypus.CollisionData} The instantiated CollisionData.
+ */
+/**
+ * Returns a collisionData back to the cache.
+ *
+ * @method platypus.CollisionData.recycle
+ * @param collisionData {platypus.CollisionData} The collisionData to be recycled.
+ */
+/**
+ * Relinquishes properties of the collisionData and recycles it.
+ *
+ * @method platypus.CollisionData#recycle
+ */
+recycle.add(CollisionData, 'CollisionData', CollisionData, null, true);
+
+export default CollisionData;

package/src/CollisionDataContainer.js

@@ -0,0 +1,127 @@
+import {arrayCache} from './utils/array.js';
+import recycle from 'recycle';
+
+/**
+ * CollisionDataContainer holds lists of CollisionData passed to entities during collisions with other entities. This class is primarily used by the ["HandlerCollision"]("HandlerCollision"%20Component.html) Component to trigger messages on child entities as collisions occur.
+ *
+ * @memberof platypus
+ * @class CollisionDataContainer
+ * @return {platypus.CollisionDataContainer} Returns the new aabb object.
+ */
+const
+    CollisionDataContainer = function () {
+        if (!this.xData && !this.yData) {
+            this.xData = arrayCache.setUp();
+            this.yData = arrayCache.setUp();
+            this.xDeltaMovement = Infinity;
+            this.yDeltaMovement = Infinity;
+        } else {
+            this.reset();
+        }
+    },
+    proto = CollisionDataContainer.prototype;
+
+/**
+ * Adds a CollisionData object to the container's X-axis if the movement distance is less than or equal to collision data collected so far.
+ *
+ * @method platypus.CollisionDataContainer#tryToAddX
+ * @param collisionData {platypus.CollisionData} The collision data to add.
+ * @return {Boolean} Whether the collision data was added.
+ */
+proto.tryToAddX = function (collisionData) {
+    if (collisionData.deltaMovement > this.xDeltaMovement) {
+        return false;
+    } else if (collisionData.deltaMovement < this.xDeltaMovement) {
+        this.resetX(collisionData.deltaMovement);
+    }
+
+    this.xData.push(collisionData);
+
+    return true;
+};
+
+/**
+ * Adds a CollisionData object to the container's Y-axis if the movement distance is less than or equal to collision data collected so far.
+ *
+ * @method platypus.CollisionDataContainer#tryToAddY
+ * @param collisionData {platypus.CollisionData} The collision data to add.
+ * @return {Boolean} Whether the collision data was added.
+ */
+proto.tryToAddY = function (collisionData) {
+    if (collisionData.deltaMovement > this.yDeltaMovement) {
+        return false;
+    } else if (collisionData.deltaMovement < this.yDeltaMovement) {
+        this.resetY(collisionData.deltaMovement);
+    }
+    
+    this.yData.push(collisionData);
+    
+    return true;
+};
+
+/**
+ * Resets the X and Y axes.
+ *
+ * @method platypus.CollisionDataContainer#reset
+ */
+proto.reset = function () {
+    this.resetX(Infinity);
+    this.resetY(Infinity);
+};
+
+/**
+ * Resets the X axis.
+ *
+ * @param delta {Number} The delta value of the X-axis.
+ * @method platypus.CollisionDataContainer#resetX
+ */
+proto.resetX = function (delta) {
+    const
+        {xData} = this;
+    let i = xData.length;
+    
+    while (i--) {
+        xData[i].recycle();
+    }
+    xData.length = 0;
+    this.xDeltaMovement = delta;
+};
+
+/**
+ * Resets the Y axis.
+ *
+ * @param delta {Number} The delta value of the Y-axis.
+ * @method platypus.CollisionDataContainer#resetY
+ */
+proto.resetY = function (delta) {
+    const
+        {yData} = this;
+    let i = yData.length;
+    
+    while (i--) {
+        yData[i].recycle();
+    }
+    yData.length = 0;
+    this.yDeltaMovement = delta;
+};
+
+/**
+ * Returns an CollisionDataContainer from cache or creates a new one if none are available.
+ *
+ * @method platypus.CollisionDataContainer.setUp
+ * @return {platypus.CollisionDataContainer} The instantiated CollisionDataContainer.
+ */
+/**
+ * Returns a CollisionDataContainer back to the cache.
+ *
+ * @method platypus.CollisionDataContainer.recycle
+ * @param CollisionDataContainer {platypus.CollisionDataContainer} The CollisionDataContainer to be recycled.
+ */
+/**
+ * Relinquishes properties of the CollisionDataContainer and recycles it.
+ *
+ * @method platypus.CollisionDataContainer#recycle
+ */
+recycle.add(CollisionDataContainer, 'CollisionDataContainer', CollisionDataContainer, null, true);
+
+export default CollisionDataContainer;