@makefully/platypus 4.1.5 → 4.1.6

package/src/components/Timeline.js

@@ -0,0 +1,314 @@
+/* global platypus */
+import {arrayCache, greenSplice} from '../utils/array.js';
+import Data from '../Data.js';
+import createComponentClass from '../factory.js';
+import TimeEventList from '../TimeEventList.js';
+
+const
+    pause = function () {
+        this.active--;
+    },
+    play = function () {
+        this.active++;
+    },
+    updateLogic = function (tick) {
+        const
+            {executionFlow, owner, timelineInstances} = this,
+            delta = tick.delta;
+        let i = timelineInstances.length,
+            removalOccurred = false;
+        
+        while (i--) {
+            const
+                instance = timelineInstances[i];
+
+            if (instance.remove) {
+                greenSplice(timelineInstances, i);
+                instance.timeline.recycle();
+                instance.recycle();
+                removalOccurred = true;
+            } else if (instance.active) {
+                if (instance.timeline.list.length === 0) {
+                    greenSplice(timelineInstances, i);
+                    instance.timeline.recycle();
+                    instance.recycle();
+                    removalOccurred = true;
+                } else {
+                    this.progressTimeline(instance, delta);
+                }
+            }
+        }
+        
+        if (timelineInstances.length) {
+            if (removalOccurred && executionFlow === 'serial') {
+                const
+                    timeline = timelineInstances[0];
+                    
+                if (!timeline.active) {
+                    timeline.play();
+                }
+            }
+            owner.triggerEvent('timeline-progress', timelineInstances);
+        }
+    };
+
+export default createComponentClass(/** @lends platypus.components.Timeline.prototype */{
+    
+    id: 'Timeline',
+    
+    properties: {
+        /**
+         * Sets the execution flow if multiple timelines are triggered.
+         *     * "parallel" - Each timeline begins immediately when triggered and does not directly affect other timelines.
+         *     * "serial" - A timeline doesn't start if another timeline is currently active: it will append itself to a queue of timelines and run eventually.
+         *     * "exclusive" - Timeline begins immediately and will stop any other active timeline.
+         *     * "tentative" - Timeline begins if no other timelines are active, otherwise it is ignored.
+         */
+        executionFlow: 'parallel',
+
+        /**
+         * Defines the set of timelines. Triggering the key for one of the events will run the timeline. A timeline can contain three different types integers >= 0, strings, and objects. Integers are interpreted as waits and define
+         * pauses between events. Strings are intepreted as event calls. Objects can contain several parameters: entity, event, message. The entity is the id of the entity that
+         * the event will be fired on. The event can be a string or array. If a string, it will call that event on the entity or owner. If an array, the value will be passed
+         * to the event handling system.
+         *
+         *  "timelines": {
+         *      "sample-timeline-1": [
+         *          500,
+         *          "sample-event",
+         *          {"event": "sample-event", "message": "sample-message"},
+         *          {"entity": "entity-id-to-trigger-event-on", "event": "sample-event"},
+         *          {"event": ["sample-event", "sample-event-2", {"event": "sample-event-3", "message": "sample-message"}]},
+         *      ],
+         *      "sample-timeline-2": [
+         *          200,
+         *          "sample-event"
+         *      ]
+         * }
+         *
+         * @property timelines
+         * @type Object
+         * @default {}
+         */
+        timelines: {}
+    },
+    
+    /**
+     * Timeline enables the scheduling of events based on a linear timeline
+     *
+     * @memberof platypus.components
+     * @uses platypus.Component
+     * @constructs
+     * @listens platypus.Entity#handle-logic
+     * @listens platypus.Entity#stop-active-timelines
+     */
+    initialize: function () {
+        const
+            keys = Object.keys(this.timelines),
+            {length} = keys;
+
+        this.timelineInstances = arrayCache.setUp();
+
+        for (let i = 0; i < length; i++) {
+            const
+                timelineId = keys[i];
+
+            this.addTimeline(timelineId, this.timelines[timelineId]);
+        }
+    },
+
+    events: {
+        "handle-logic": updateLogic,
+
+        "pause-timelines": function () {
+            this.timelineInstances.forEach((timeline) => {
+                if (timeline.active) {
+                    timeline.pause();
+                }
+            });
+        },
+
+        "play-timelines": function () {
+            const
+                {executionFlow, timelineInstances} = this;
+
+            if (executionFlow === 'serial') {
+                if (timelineInstances.length) { 
+                    const
+                        timeline = timelineInstances[0];
+                        
+                    if (!timeline.active) {
+                        timeline.play();
+                    }
+                }
+            } else {
+                timelineInstances.forEach((timeline) => {
+                    if (!timeline.active) {
+                        timeline.play();
+                    }
+                });
+            }
+        },
+
+        /**
+         * Stops active timelines.
+         *
+         * @event platypus.Entity#stop-active-timelines
+         */
+        "stop-active-timelines": function () {
+            const
+                instances = this.timelineInstances;
+            let i = instances.length;
+
+            while (i--) {
+                if (instances[i].active) {
+                    instances[i].remove = true;
+                }
+            }
+        },
+
+        /**
+         * Stops all timelines.
+         *
+         * @event platypus.Entity#stop-all-timelines
+         */
+        "stop-all-timelines": function () {
+            const
+                instances = this.timelineInstances;
+            let i = instances.length;
+
+            while (i--) {
+                instances[i].remove = true;
+            }
+        },
+
+        /**
+         * Add a timeline dynamically.
+         *
+         * @event platypus.Entity#add-timeline
+         * @param eventId {String} The event to listen for to trigger the timeline.
+         * @param timeline {Array} The array of timeline data.
+         */
+        "add-timeline": function (eventId, timeline) {
+            this.addTimeline(eventId, timeline);
+        },
+
+        /**
+         * Play a timeline dynamically.
+         *
+         * @event platypus.Entity#start-timeline
+         * @param timeline {Array} The array of timeline data.
+         */
+        "start-timeline": function (timeline) {
+            this.startTimeline(timeline);
+        }
+    },
+    
+    methods: {
+        addTimeline: function (eventId, timeline) {
+            this.addEventListener(eventId, () => this.startTimeline(timeline));
+        },
+        createTimeStampedTimeline: function (timeline, active = 1) {
+            const
+                timeStampedTimeline = TimeEventList.setUp(timeline);
+
+            return Data.setUp(
+                "timeline", timeStampedTimeline,
+                "time", 0,
+                "total", timeStampedTimeline.getDuration(),
+                "active", 1,
+                "pause", pause,
+                "play", play,
+                "remove", false
+            );
+        },
+        startTimeline (timeline) {
+            const
+                {executionFlow, timelineInstances} = this;
+
+            switch (executionFlow) {
+            case 'serial':
+                timelineInstances.push(this.createTimeStampedTimeline(timeline), timelineInstances.some(({active}) => active) ? 0 : 1);
+                return true;
+            case 'exclusive':
+                timelineInstances.forEach((instance) => instance.remove = true);
+                timelineInstances.push(this.createTimeStampedTimeline(timeline));
+                return true;
+            case 'tentative':
+                if (!timelineInstances.some(({active}) => active)) {
+                    timelineInstances.push(this.createTimeStampedTimeline(timeline));
+                    return true;
+                }
+                return false;
+            default:
+                timelineInstances.push(this.createTimeStampedTimeline(timeline));
+                return true;
+            }
+        },
+        progressTimeline (instance, delta) {
+            const
+                timeline = instance.timeline;
+            
+            instance.time += delta;
+            
+            //Go through the timeline playing events if the time has progressed far enough to trigger them.
+            timeline.getEvents(instance.time).forEach((entry) => {
+                const
+                    {event, entity} = entry;
+
+                if (typeof event === 'function') {
+                    event(this.owner, instance);
+                } else {
+                    let triggerOn = this.owner;
+
+                    if (entity) {
+                        if (typeof entity === 'string') {
+                            if (this.owner.getEntityById) {
+                                triggerOn = this.owner.getEntityById(entity);
+                            } else {
+                                triggerOn = this.owner.parent.getEntityById(entity);
+                            }
+                        } else {
+                            triggerOn = entity; // Maybe it's an Entity.
+                        }
+                        
+                        if (!triggerOn) {
+                            platypus.debug.warn('No entity of that id');
+                            triggerOn = this.owner;
+                        }
+                    }
+                    
+                    triggerOn.trigger(entry);
+                }
+                
+                entry.recycle();
+            });
+        },
+        destroy: function () {
+            const
+                instances = this.timelineInstances;
+            let i = instances.length;
+            
+            while (i--) {
+                const
+                    instance = instances[i];
+
+                instance.timeline.recycle();
+                instance.recycle();
+            }
+            arrayCache.recycle(instances);
+            this.timelineInstances = null;
+        }
+    },
+
+    publicMethods: {
+        // asynchronous wait that incorporates ticker pauses.
+        wait (time) {
+            return new Promise ((resolve, reject) => {
+                if (!this.startTimeline([time, resolve])) {
+                    reject();
+                }
+            });
+        }
+    }
+});

package/src/components/Tutorial.js

@@ -0,0 +1,267 @@
+/* global platypus */
+import createComponentClass from '../factory.js';
+import {greenSlice} from '../utils/array.js';
+
+const
+    entityAdded = function (entity) {
+        if (entity.type in this.watchedEntities) {
+            this.watchedEntities[entity.type].push(entity);
+        }
+    },
+    entityRemoved = function (entity) {
+        const
+            watchedEntities = this.watchedEntities[entity.type];
+
+        for (let x = watchedEntities.length - 1; x >= 0; x--) {
+            if (watchedEntities[x] === entity) {
+                watchedEntities.splice(x, 1);
+                break;
+            }
+        }
+    },
+    updateLogic = function (tick) {
+        const
+            delta = tick.delta;
+        let toPlay = null,
+            toPlayIndex = -1;
+        
+        for (let x = 0; x < this.tutorials.length; x++) {
+            const
+                tut = this.tutorials[x];
+            let keepChecking = false;
+
+            if (!this.playing && this.theQueue.length === 0) {
+                keepChecking = true;
+            } else if ((!this.playing && this.theQueue.length > 0) && (tut.priority > this.theQueue[0].priority)) {
+                keepChecking = true;
+            } else if (this.playing && (this.playing.priority < tut.priority)) {
+                keepChecking = true;
+            } else if (tut.queue) {
+                keepChecking = true;
+            }
+
+            if (!keepChecking) {
+                continue;
+            }
+
+            if (this.checkRequirements(tut.requirements)) {
+                if (tut.replayDelay && tut.replayDelayTimer > 0) {
+                    tut.replayDelayTimer -= delta;
+                    if (tut.replayDelayTimer > 0) {
+                        continue;
+                    }
+                }
+                
+                if (!toPlay || toPlay.priority < tut.priority) {
+                    //TML - If we only have one item we try to play, then we may prevent certain audio from playing if it's only valid for a single tick.
+                    toPlay = tut;
+                    toPlayIndex = x;
+                }
+            }
+        }
+
+        if (toPlay) {
+            const
+                tutorial = this.tutorials.splice(toPlayIndex, 1)[0];
+
+            if (this.playing) {
+                if (tutorial.priority > this.playing.priority) {
+                    /**
+                     * On receiving this message, audio will stop playing.
+                     *
+                     * @event platypus.Entity#stop-audio
+                     * @param audioId {String} If an audioId is provided, that particular sound instance is stopped. Otherwise all audio is stopped.
+                     */
+                    this.owner.triggerEvent('stop-audio');
+                    this.play(tutorial);
+                } else {
+                    this.queue(tutorial);
+                }
+            } else if (this.theQueue.length > 0) {
+                if (tutorial.priority > this.theQueue[0].priority) {
+                    this.play(tutorial);
+                } else {
+                    this.play(this.theQueue.splice(0, 1)[0]);
+                    this.queue(tutorial);
+                }
+            } else {
+                this.play(tutorial);
+            }
+        } else if (!this.playing && this.theQueue.length > 0) {
+            this.play(this.theQueue.splice(0, 1)[0]);
+        }
+    };
+
+export default createComponentClass(/** @lends platypus.components.Tutorial.prototype */{
+    
+    id: 'Tutorial',
+    
+    properties: {
+        
+        /* An array of tutorial definition objects. These objects define what events will be called by the tutorial, the priority of the tutorial, how often and how many times it will fire, the required conditions for it to fire, and more.
+            *
+            * "tutorialDefs": [
+            *      {
+            *          "events": ["example-vo-event"],         //An Array of Strings. Defines the events to fire when all the conditions for this tutorial are met. If there are multiple events, one is chosen at random. All events in the array will play before any repeat.
+            *          "priority": 5,                          //The priorioty of the tutorial. Higher numbered tutorials interrupt lower numbered. Default: 0.
+            *          "queue": true,                          //Will the tutorial queue up if played while another tutorial is playing? Default: false.
+            *          "timesToReplay": 3,                     //The number of times a tutorial will replay. Set to 0 to make a tutorial play only once. Default: Infinity.
+            *          "replayDelay": 10000,                   //While the conditions are met, the tutorial will replay at this interval in milliseconds. If set to null, it will not repeat. Default: null.
+            *          "level": "example-level",               //Tutorial will only play when this level is the currently loaded level.
+            *          "requirements": {                       //The requirements is a collection of entities types that are watched by the tutorial to determine if the conditions to play this tutorial are true.
+            *              "example-entity-type": ["example-entity-state"]     //The requirements is a set of key-value pairs. The keys are entity types that the tutorial will watch. The values are arrays of states of that entity type which must be true for the tutorial to play.
+            *          }
+            *      }
+            * ]
+            *
+            * @property tutorialDefs
+            * @type Array [Object]
+            * @default []
+            */
+        "tutorialDefs": []
+    },
+        
+    /**
+     * Tutorial provides a framework for playing tutorials. It allows the user to define things such as under what conditions tutorials will play, how often they play, and which tutorials have priority.
+     *
+     * @memberof platypus.components
+     * @uses platypus.Component
+     * @constructs
+     * @listens platypus.Entity#child-entity-added
+     * @listens platypus.Entity#child-entity-removed
+     * @listens platypus.Entity#handle-logic
+     * @listens platypus.Entity#peer-entity-added
+     * @listens platypus.Entity#peer-entity-removed
+     * @listens platypus.Entity#sequence-complete
+     * @fires platypus.Entity#stop-audio
+     */
+    initialize: function () {
+        this.playing = null;
+        this.theQueue = [];
+        this.watchedEntities = {};
+        this.tutorials = [];
+
+            
+        for (let x = 0; x < this.tutorialDefs.length; x++) {
+            const
+                tutDef = this.tutorialDefs[x];
+
+            if (!tutDef.events) {
+                platypus.debug.warn("Tutorial definition lacks events.");
+            } else {
+                const
+                    tutorial = {
+                        events: greenSlice(tutDef.events),
+                        originalEvents: greenSlice(tutDef.events),
+                        priority: tutDef.priority || 0,
+                        queue: tutDef.queue || false,
+                        timesToReplay: (typeof tutDef.timesToReplay === 'number') ? tutDef.timesToReplay : Infinity,
+                        replayDelay: tutDef.replayDelay || null,
+                        replayDelayTimer: tutDef.replayDelay || null,
+                        level: tutDef.level,
+                        requirements: {}
+                    },
+                    keys = Object.keys(tutDef.requirements),
+                    {length} = keys;
+    
+                for (let i = 0; i < length; i++) {
+                    const
+                        entityType = keys[i];
+    
+                    tutorial.requirements[entityType] = greenSlice(tutDef.requirements[entityType]);
+                    if (!this.watchedEntities[entityType]) {
+                        this.watchedEntities[entityType] = [];
+                    }
+                }
+                this.tutorials.push(tutorial);
+            }
+        }
+    },
+
+    events: {// These are messages that this component listens for
+        "child-entity-added": entityAdded,
+
+        "peer-entity-added": entityAdded,
+
+        "child-entity-removed": entityRemoved,
+
+        "peer-entity-removed": entityRemoved,
+        
+        "handle-logic": updateLogic,
+
+        "sequence-complete": function () {
+            if (this.playing.timesToReplay >= 0) {
+                this.tutorials.push(this.playing);
+            }
+            this.playing = null;
+        }
+    },
+    
+    methods: {// These are internal methods that are invoked by this component.
+        play: function (tutorial) {
+            this.playing = tutorial;
+            if (this.playing.events.length === 0) {
+                this.playing.events = greenSlice(this.playing.originalEvents);
+            }
+
+            this.owner.triggerEvent(this.playing.events.splice(Math.floor(Math.random() * this.playing.events.length), 1)[0]);
+
+            tutorial.timesToReplay -= 1;
+            tutorial.replayDelayTimer = tutorial.replayDelay;
+        },
+        queue: function (tutorial) {
+            let added = false;
+
+            for (let x = 0; x < this.theQueue.length; x++) {
+                if (this.theQueue[x].priority < tutorial.priority) {
+                    this.theQueue.splice(x, 0, tutorial);
+                    added = true;
+                    break;
+                }
+            }
+            
+            if (!added) {
+                this.theQueue.push(tutorial);
+            }
+        },
+        checkRequirements: function (requirements) {
+            const
+                keys = Object.keys(requirements),
+                {length} = keys;
+    
+            //Going through the types of entities
+            for (let i = 0; i < length; i++) {
+                const
+                    entityType = keys[i],
+                    states = requirements[entityType];
+                let metRequirement = true;
+
+                for (let y = this.watchedEntities[entityType].length - 1; y >= 0; y--) {  //Going through the instances of those entities
+                    const
+                        anEntity = this.watchedEntities[entityType][y];
+
+                    metRequirement = true;
+                    for (let x = 0; x < states.length; x++) {   //Going through the required states of an entity instance
+                        if (!anEntity.state.get(states[x])) {
+                            metRequirement = false;
+                            break;
+                        }
+                    }
+                    if (metRequirement) {
+                        break;
+                    }
+                }
+                if (!metRequirement) {
+                    return false;
+                }
+            }
+            return true;
+        },
+        destroy: function () {
+            this.watchedEntities = null;
+            this.theQueue = null;
+            this.playing = null;
+            this.tutorials = null;
+        }
+    }
+});