@makefully/platypus 4.1.5 → 4.1.8

package/src/Gamepad.js

@@ -0,0 +1,175 @@
+import Data from './Data.js';
+import Vector from './Vector.js';
+import {arrayCache} from './utils/array.js';
+import recycle from 'recycle';
+
+const
+    /**
+     * This class defines an axis-aligned bounding box (AABB) which is used during the collision process to determine if two objects are colliding. This is used in a few places including [CollisionBasic](platypus.components.CollisionBasic.html) and [[Collision-Shape]].
+     *
+     * @memberof platypus
+     * @class Gamepad
+     * @param gamepad {number} The browser's gamepad object.
+     * @param id {number} Id of gamepad.
+     * @param deadzone {number} distance from axis `0` position to ignore.
+     * @param height {number} The height of the AABB.
+     * @return {platypus.Gamepad} Returns the new aabb object.
+     */
+    Gamepad = function (gamepad, onDown, onUp, onChange, id = '', deadzone = 0.1) {
+        this.source = gamepad;
+        this.deadzone = deadzone;
+        this.axes = this.axes || arrayCache.setUp();
+        for (let i = 0; i < (gamepad.axes.length >> 1); i++) {
+            this.axes.push(clampVector(Vector.setUp(gamepad.axes[i * 2], gamepad.axes[i * 2 + 1]), deadzone));
+        }
+        this.buttons = this.buttons || arrayCache.setUp();
+        for (let i = 0; i < gamepad.buttons.length; i++) {
+            this.buttons.push(gamepad.buttons[i].value);
+        }
+        this.id = id || `${gamepad.id} - ${gamepad.index}`; // Adding index to make it unique.
+
+        this.onDown = onDown;
+        this.onUp = onUp;
+        this.onChange = onChange;
+    },
+    playEffectOptions = {
+        duration: 500,
+        startDelay: 0,
+        strongMagnitude: 1.0,
+        weakMagnitude: 1.0
+    },
+    controllers = {
+        a0: 'LeftStick',
+        a1: 'RightStick',
+        b0: 'AButton',
+        b1: 'BButton',
+        b2: 'XButton',
+        b3: 'YButton',
+        b4: 'LeftBumper',
+        b5: 'RightBumper',
+        b6: 'LeftTrigger',
+        b7: 'RightTrigger',
+        b8: 'BackButton',
+        b9: 'StartButton',
+        b10: 'LeftStickButton',
+        b11: 'RightStickButton',
+        b12: 'UpDPad',
+        b13: 'DownDPad',
+        b14: 'LeftDPad',
+        b15: 'RightDPad'
+    },
+    clampVector = function (v, deadzone) {
+        const m = v.magnitude();
+
+        if (m > 1) {
+            v.x *= 1 / m;
+            v.y *= 1 / m;
+        } else if (m < deadzone) {
+            v.x = 0;
+            v.y = 0;
+        } else {
+            const span = 1 - deadzone;
+            v.x = (v.x - deadzone) / span;
+            v.y = (v.y - deadzone) / span;
+        }
+
+        return v;
+    },
+    proto = Gamepad.prototype;
+
+proto.dualRumble = function (duration = 500, delay = 0, strong = 1.0, weak = 1.0) {
+    playEffectOptions.duration = duration;
+    playEffectOptions.startDelay = delay;
+    playEffectOptions.strongMagnitude = strong;
+    playEffectOptions.weakMagnitude = weak;
+    this.source.vibrationActuator.playEffect('dual-rumble', playEffectOptions);
+};
+
+proto.update = function (gamepad) {
+    const
+        axes = this.axes,
+        buttons = this.buttons,
+        onDown = this.onDown,
+        onUp = this.onUp,
+        onChange = this.onChange;
+
+    for (let i = 0; i < axes.length; i++) {
+        const
+            oldVector = axes[i],
+            newVector = clampVector(Vector.setUp(gamepad.axes[i * 2], gamepad.axes[i * 2 + 1]), this.deadzone);
+
+        if (!newVector.equals(oldVector, 2)) {
+            const event = Data.setUp(
+                    'code', controllers[`a${i}`],
+                    'direction', oldVector,
+                    'gamepad', this,
+                    'id', this.id
+                );
+
+            oldVector.set(newVector);
+            onChange(event);
+            event.recycle();
+        }
+
+        newVector.recycle();
+    }
+    for (let i = 0; i < gamepad.buttons.length; i++) {
+        const
+            newButton = gamepad.buttons[i],
+            newValue = newButton.value,
+            oldButton = buttons[i];
+        
+        if (newValue !== oldButton) {
+            const event = Data.setUp(
+                    'code', controllers[`b${i}`],
+                    'button', newButton,
+                    'gamepad', this,
+                    'id', this.id
+                );
+
+            buttons[i] = newValue;
+
+            if (oldButton === 0) {
+                onDown(event);
+                onChange(event);
+            } else if (newValue === 0) {
+                onChange(event);
+                onUp(event);
+            } else {
+                onChange(event);
+            }
+
+            event.recycle();
+        }
+    }
+};
+    
+/**
+ * Returns an Gamepad from cache or creates a new one if none are available.
+ *
+ * @method platypus.Gamepad.setUp
+ * @return {platypus.Gamepad} The instantiated Gamepad.
+ */
+/**
+ * Returns a Gamepad back to the cache.
+ *
+ * @method platypus.Gamepad.recycle
+ * @param {platypus.Gamepad} gamepad The Gamepad to be recycled.
+ */
+/**
+ * Relinquishes properties of the Gamepad and recycles it.
+ *
+ * @method platypus.Gamepad#recycle
+ */
+recycle.add(Gamepad, 'Gamepad', Gamepad, function () {
+    for (let i = 0; i < this.axes.length; i++) {
+        this.axes[i].recycle();
+    }
+    this.axes.length = 0;
+    this.buttons.length = 0;
+    this.onDown = null;
+    this.onUp = null;
+    this.onChange = null;
+}, true);
+
+export default Gamepad;

package/src/ID3CaptionPlayer.js

@@ -0,0 +1,61 @@
+import {CaptionFactory, CaptionPlayer, HtmlRenderer} from 'springroll';
+
+const
+    nullCaption = [{
+        content: "Prevent empty captions error.",
+        start: 0,
+        end: 1
+    }],
+    findAndFormatCaptionsFromTags = ({tags}, length) => {
+        const
+            {SYLT} = tags;
+
+        if (SYLT) {
+            const
+                list = Array.isArray(SYLT) ? SYLT : [SYLT],
+                captionsSYLT = list.filter(({data}) => data.descriptor === 'captions')[0] ?? list.filter(({data}) => data.contentType === 'transcription')[0] ?? list.filter(({data}) => data.contentType === 'lyrics')[0] ?? null;
+
+            if (captionsSYLT) {
+                return CaptionFactory.createCaption(captionsSYLT.data.synchronisedText.map(({text: content, timeStamp: start}, index, arr) => {
+                    const
+                        next = arr[index + 1];
+
+                    return {
+                        content,
+                        start: Math.max(start, 0.001), // Prevents CaptionPlayer from playing caption before the audio is loaded/playing.
+                        end: next ? next.timeStamp : length
+                    };
+                }));
+            }
+        }
+
+        return null;
+    },
+    ID3CaptionPlayer = class extends CaptionPlayer {
+        constructor (captions = {nullCaption}, captionsElement, tagReader = null) {
+            super(captions, new HtmlRenderer(captionsElement));
+
+            if (tagReader) {
+                this.getCaption = (audio) => new Promise((resolve, reject) => {
+                    tagReader.read(audio.media?.file ?? audio.url, {
+                        onSuccess: (tags) => resolve(findAndFormatCaptionsFromTags(tags, (audio.duration * 1000) >> 0)),
+                        onError: reject
+                    });
+                });
+            }
+        }
+
+        async start (audio, audioId, ...args) {
+            if (this.getCaption && typeof this.captions[audioId] === 'undefined') {
+                try {
+                    this.captions[audioId] = await this.getCaption(audio);
+                } catch (e) {
+                    this.captions[audioId] = null;
+                    platypus.debug.warn(e.type, e.info);
+                }
+            }
+            super.start(this.captions[audioId] ? audioId : audio.url, ...args);
+        }
+    };
+
+export default ID3CaptionPlayer;

package/src/Messenger.js

@@ -0,0 +1,365 @@
+/* global platypus, window */
+import EventHandlerList from './EventHandlerList.js';
+import {arrayCache, greenSlice} from './utils/array.js';
+
+const
+    getPerfTools = () => typeof performance !== 'undefined' && performance.mark && performance.measure ? performance : null,
+    runBoth = function (f1, f2) {
+        return function () {
+            f1.apply(this, arguments);
+            f2.apply(this, arguments);
+        };
+    };
+
+/**
+ * Messenger provides prioritized event-based communication between
+ * components, entities, and systems.
+ *
+ * Features include:
+ * - prioritized listeners
+ * - one-time listeners
+ * - deterministic execution ordering
+ * - safe listener mutation during dispatch
+ * - pooled listener structures
+ * - array/object event dispatch formats
+ * - optional debug instrumentation
+ *
+ * Messenger is commonly mixed into entities and components to
+ * provide lightweight pub/sub behavior without repeated allocations.
+ *
+ * @memberof platypus
+ * @class Messenger
+ */
+class Messenger {
+    /**
+     * Creates a Messenger instance.
+     *
+     * @param {Object} [options]
+     * Configuration options.
+     *
+     * @param {Boolean} [options.debug=false]
+     * Enables nested-event debugging and performance instrumentation.
+     */
+    constructor ({debug} = {}) {
+        this._listeners = {};
+        this._destroyed = false;
+        this.loopCheck = arrayCache.setUp();
+
+        if (debug) {
+            const
+                triggerEvent = this.triggerEvent;
+
+            this.triggerEvent = function (event, value) {
+                const
+                    debugLimit = 5,
+                    debugLogging = value && value.debug;
+                let debugCount = 0;
+                
+                // Debug logging.
+                if (debugLogging || this.debug) {
+                    const perfTools = getPerfTools();
+
+                    for (let i = 0; i < this.loopCheck.length; i++) {
+                        if (this.loopCheck[i] === event) {
+                            debugCount += 1;
+                            if (debugCount > debugLimit) {
+                                throw "Endless loop detected for '" + event + "'.";
+                            } else {
+                                platypus.debug.warn("Event '" + event + "' is nested inside another '" + event + "' event.");
+                            }
+                        }
+                    }
+    
+                    this.loopCheck.push(event);
+
+                    if (perfTools) {
+                        perfTools.mark("a");
+                    }
+
+                    const
+                        count = triggerEvent.apply(this, arguments);
+
+                    if (perfTools) {
+                        perfTools.mark("b");
+                        perfTools.measure(this.type + ":" + event, 'a', 'b');
+                    }
+                    this.loopCheck.length = this.loopCheck.length - 1;
+                    if (debugLogging) {
+                        if (count) {
+                            platypus.debug.log('Entity "' + this.type + '": Event "' + event + '" has ' + count + ' subscriber' + ((count > 1) ? 's' : '') + '.', value);
+                        } else {
+                            platypus.debug.warn('Entity "' + this.type + '": Event "' + event + '" has no subscribers.', value);
+                        }
+                    }
+                    return count;
+                } else {
+                    return triggerEvent.apply(this, arguments);
+                }
+            };
+        }
+    }
+
+    /**
+     * Registers an event listener.
+     *
+     * Listeners are executed in ascending priority order.
+     * Lower priority values execute first.
+     *
+     * When priorities match, listeners execute in
+     * registration order.
+     *
+     * If no context is supplied, the Messenger instance
+     * becomes the callback context.
+     *
+     * @method on
+     *
+     * @param {String} name
+     * Event name.
+     *
+     * @param {Function} callback
+     * Function invoked when the event fires.
+     *
+     * @param {Object} [context=this]
+     * Callback execution context.
+     *
+     * @param {Boolean} [once=false]
+     * Whether the listener should automatically remove
+     * itself after its first execution.
+     *
+     * @param {Number} [priority=MAX_SAFE_INTEGER]
+     * Listener execution priority.
+     *
+     * Lower numbers execute first.
+     */
+    on (name, callback, context = null, once = false, priority = -1) {
+        if (!this._destroyed) {
+            const
+                listenerList = this._listeners[name] = this._listeners[name] ?? EventHandlerList.setUp();
+
+            return listenerList.add(callback, context ?? this, once, priority === -1 ? Number.MAX_SAFE_INTEGER : priority);
+        }
+
+        return null;
+    }
+
+    /**
+     * Removes listeners.
+     *
+     * Calling without arguments removes all listeners.
+     *
+     * Calling with only an event name removes all listeners
+     * for that event.
+     *
+     * Calling with both name and callback removes matching
+     * listeners for that callback.
+     *
+     * @method off
+     *
+     * @param {String} [name]
+     * Event name.
+     *
+     * @param {Function} [callback]
+     * Listener callback.
+     */
+    off (name, callback, context) {
+        if (!this._destroyed) {
+            // remove all
+            if (typeof name === 'undefined') {
+                this.getMessageIds().forEach((id) => this._listeners[id].recycle());
+                this._listeners = {};
+            } else {
+                const
+                    listenerList = this._listeners[name];
+
+                if (listenerList) {
+                    // remove all listeners for that event
+                    if (typeof callback === 'undefined') {
+                        listenerList.recycle();
+                        delete this._listeners[name];
+                    } else {
+                        //remove single listener
+                        listenerList.remove(callback, context);
+                        if (!listenerList.handlers.length) {
+                            listenerList.recycle();
+                            delete this._listeners[name];
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Returns a string describing the Messenger as "[Messenger object]".
+     *
+     * @return String
+     */
+    toString () {
+        return "[Messenger Object]";
+    }
+
+    /**
+     * Dispatches one or more events.
+     *
+     * Supported formats:
+     *
+     * String:
+     * trigger('jump', value)
+     *
+     * Array:
+     * trigger(['jump', 'land'], value)
+     *
+     * Object:
+     * trigger({
+     *     event: 'jump',
+     *     message: value,
+     *     debug: true
+     * })
+     *
+     * @method trigger
+     *
+     * @param {String|Array|Object} events
+     * Event descriptor.
+     *
+     * @param {*} [message]
+     * Event payload.
+     *
+     * @param {Boolean} [debug]
+     * Enables debug logging for this dispatch.
+     *
+     * @return {Number}
+     * Total number of listeners triggered.
+     */
+    trigger (events, message, debug) {
+        if (typeof events === 'string') {
+            return this.triggerEvent.apply(this, arguments);
+        } else if (Array.isArray(events)) {
+            const
+                args = greenSlice(arguments);
+            let count = 0;
+
+            for (let i = 0; i < events.length; i++) {
+                args[0] = events[i];
+                count += this.trigger.apply(this, args);
+            }
+            arrayCache.recycle(args);
+
+            return count;
+        } else if (events.event) {
+            if (typeof events.debug !== 'undefined') {
+                return this.triggerEvent(
+                    events.event,
+                    events.message ?? message,
+                    events.debug
+                );
+            }
+
+            return this.triggerEvent(
+                events.event,
+                events.message ?? message
+            );
+        } else {
+            platypus.debug.warn('Event incorrectly formatted: must be string, array, or object containing an "event" property.', events);
+            return 0;
+        }
+    }
+    
+    /**
+     * Dispatches a single event directly.
+     *
+     * This bypasses trigger-format normalization and is
+     * the fastest dispatch path.
+     *
+     * @method triggerEvent
+     *
+     * @param {String} type
+     * Event name.
+     *
+     * @param {...*} args
+     * Arguments forwarded to listeners.
+     *
+     * @return {Number}
+     * Number of listeners triggered.
+     */
+    triggerEvent (type, ...args) {
+        const
+            {_listeners} = this;
+
+        if (!this._destroyed && _listeners.hasOwnProperty(type) && (_listeners[type])) {
+            return _listeners[type].trigger(args);
+        }
+        
+        return 0;
+    }
+    
+    /**
+     * This method returns all the messages that this entity is concerned about.
+     *
+     * @return {Array} An array of strings listing all the messages for which this Messenger has handlers.
+     */
+    getMessageIds () {
+        return Object.keys(this._listeners);
+    }
+    
+    /**
+     * This method relinguishes Messenger properties
+     *
+     */
+    destroy () {
+        arrayCache.recycle(this.loopCheck);
+        this.loopCheck = null;
+        this._destroyed = true;
+        this.getMessageIds().forEach((id) => this._listeners[id].recycle());
+        this._listeners = null;
+    }
+
+    /**
+     * This read-only property shows whether this Messenger is destroyed.
+     *
+     * @property destroyed
+     * @type Boolean
+     * @default false
+     */
+    get destroyed () {
+        return this._destroyed;
+    }
+
+    /**
+     * Adds Messenger functionality to a Class.
+     *
+     * @param {Class|Function} ClassObject The class to add Messenger behavior to.
+     */
+    static mixin (ClassObject) {
+        const
+            fromProto = Messenger.prototype,
+            toProto = ClassObject.prototype,
+            methods = Object.getOwnPropertyNames(fromProto);
+        let i = methods.length;
+
+        while (i--) {
+            const
+                key = methods[i];
+
+            if (key !== 'constructor') {
+                if (toProto[key]) {
+                    toProto[key] = runBoth(toProto[key], fromProto[key]);
+                } else {
+                    toProto[key] = fromProto[key];
+                }
+            }
+        }
+    }
+
+    /**
+     * Call this method in an Object's instantiation if `Messenger.mixin` has been called on its Class.
+     *
+     * @param {Object} object The object for which Messenger should be instantiated.
+     */
+    static initialize (object) {
+        object._listeners = {};
+        object._destroyed = false;
+        object.loopCheck = arrayCache.setUp();
+    }
+}
+
+export default Messenger;