Update BUGS for 1.1 and upcoming 1.2.

[pwl6.git] / src / yuu / ce.js

/* Copyright 2014 Yukkuri Games
   Licensed under the terms of the GNU GPL v2 or later
   @license http://www.gnu.org/licenses/gpl-2.0.html
   @source: http://yukkurigames.com/yuu/
*/

(function (yuu) {
    "use strict";

    /** yuu-ce - entity/component system for the Yuu engine

        Game logic in Yuu is implemented via entities and components.
        Entities (yuu.E) represent "things" in the world, and
        components (yuu.C) individual properties or abilities of those
        things. By attaching and detaching components, entities gain
        and lose those abilities.

        This system prioritizes for convenience and simplicity over
        performance. Many common optimizations in E/C systems, like
        component pooling and array-of-structures, are not
        implemented. (And are of questionable value in a language like
        JavaScript.)
    */

    var yT = this.yT || require("./yT");
    var yf = this.yf || require("./yf");

    yuu.E = yT({
        constructor: function () {
            /** Entity, a shell to customize with components

                Entities exist as an aggregate of components (yuu.C).
                They are used for components to talk to each other, or
                other systems to handle systems in aggregate without
                caring about the underlying details.

                Entities expose components in two ways.
                
                First, components may have one or more slots; when a
                component is attached to an entity it slots itself
                into those properties on that entity. For example, if
                you attach a Transform component to an entity, you can
                retrieve it via e.transform.

                Second, components may have one or more message
                taps. This allows them to listen for, and respond to,
                messages sent to the entity. Unlike slots many
                attached components may have the same tap.
            */
            this.parent = null;
            this.children = [];
            this.taps = {};
            this.attach.apply(this, arguments);
        },

        addChild: function (child) { this.addChildren(child); },
        removeChild: function (child) { this.removeChildren(child); },

        addChildren: function () {
            yf.stash("parent", this, arguments);
            this.children = this.children.concat(yf.slice(arguments));
        },

        removeChildren: function () {
            this.children = yf.filter(
                yf.lacks.bind(null, arguments), this.children);
            yf.stash("parent", null, arguments);
        },

        attach: function () {
            /** Attach a component to this entity.

                If the entity already has a component in the same slots,
                an error will be thrown.
            */
            for (var j = 0; j < arguments.length; ++j) {
                var c = arguments[j];
                var i;
                for (i = 0; i < c.SLOTS.length; ++i)
                    if (this[c.SLOTS[i].slot])
                        throw new Error("Entity already has a " + c.SLOTS[i]);
                for (i = 0; i < c.SLOTS.length; ++i)
                    this[c.SLOTS[i]] = c;
                for (i = 0; i < c.TAPS.length; ++i)
                    this.taps[c.TAPS[i]] = (this.taps[c.TAPS[i]] || [])
                        .concat(c);
                c.entity = this;
                c.attached(this);
            }
        },

        detach: function () {
            /** Detach a component from this entity */
            for (var j = 0; j < arguments.length; ++j) {
                var c = arguments[j];
                var i;
                for (i = 0; i < c.SLOTS.length; ++i)
                    if (this[c.SLOTS[i].slot] !== c)
                        throw new Error("Entity has a wrong " + c.SLOTS[i]);
                for (i = 0; i < c.SLOTS.length; ++i)
                    delete this[c.SLOTS[i]];
                for (i = 0; i < c.TAPS.length; ++i)
                    this.taps[c.TAPS[i]] = yf.without(this.taps[c.TAPS[i]], c);
                c.entity = null;
                c.detached(this);
            }
        },

        _message: function (name, params) {
            var taps = this.taps[name];
            var children = this.children;
            var i;
            if (taps)
                for (i = 0; i < taps.length; ++i)
                    taps[i][name].apply(taps[i], params);
            for (i = 0; i < children.length; ++i)
                children[i]._message(name, params);
        },
        message: function (name) {
            /** Message components listening on the named tap */
            this._message(name, yf.tail(arguments));
        },
    });

    yuu.C = yT({
        entity: { value: null, writable: true },
        SLOTS: { value: [], configurable: true },
        TAPS: { value: [], configurable: true },

        attached: function (entity) { },
        detached: function (entity) { },
    });

    yuu.DataC = yT(yuu.C, {
        /** A component for random scratch data

            Storing this in a separate component rather than on the
            entity directly reduces the chance of naming conflicts and
            also the number of hidden classes.
        */

        constructor: function (data) {
            Object.assign(this, data || {});
        },

        SLOTS: ["data"]
    });


    yuu.Animation = yT(yuu.C, {
        constructor: function (timeline, params, completionHandler, delay) {
            this.timeline = yf.mapValues(yf.arrayify, timeline);
            this.params = params;
            this.completionHandler = completionHandler;
            this.keys = Object.keys(timeline)
                .sort(function (a, b) {
                    return +this._lookup(a) - +this._lookup(b);
                }.bind(this));
            this._t1 = +this._lookup(yf.last(this.keys)) + 1;
            this._t = -(delay || 0);
            this._pc = 0;
            this._tweens = [];
        },

        attached: function () {
            this.tick();
        },

        _lookup: function (k) {
            return (k in this.params) ? this.params[k] : k;
        },

        set1: function (setter) {
            var $ = this.params.$;
            yf.ipairs.call(this, function (k, v) {
                $[k] = this._lookup(v);
            }, setter);
        },

        set: function (setters) {
            yf.ipairs.call(this, function (name, setter) {
                var $ = this._lookup(name);
                yf.ipairs.call(this, function (k, v) {
                    $[k] = this._lookup(v);
                }, setter);
            }, setters);
        },

        _addTween: function (tweens, instr) {
            var repeat = instr.repeat || 0;
            var cycles = Math.abs(repeat) + 1;
            var easing = yf.isFunction(instr.easing)
                ? instr.easing
                : yuu.Tween[(instr.easing || "ease").toUpperCase()];
            var duration, complete;

            if ("complete" in instr) {
                complete = this._lookup(instr.complete);
                duration = (complete - this._t) / cycles;
            } else if ("duration" in instr) {
                duration = this._lookup(instr.duration);
                complete = this._t + duration * cycles;
            }

            if (isFinite(cycles)) {
                this._tweens.push(
                    new yuu.Tween(tweens, duration, repeat, easing));
                this._t1 = Math.max(complete + 1, this._t1);
            } else {
                this.entity.attach(new yuu.TweenC(
                    tweens, duration, repeat, easing));
            }
        },

        tween1: function (tween, instr) {
            var nt = { $: this._lookup(instr.$) || this.params.$ };
            yf.ipairs.call(this, function (k, v) {
                nt[k] = [nt.$[k], this._lookup(v)];
            }, tween);
            this._addTween([nt], instr);
        },

        tween: function (targets, instr) {
            var tweens = [];
            yf.ipairs.call(this, function (name, tween) {
                var nt = { $: this._lookup(name) || this.params.$ };
                yf.ipairs.call(this, function (k, v) {
                    nt[k] = [nt.$[k], this._lookup(v)];
                }, tween);
                tweens.push(nt);
            }, targets);
            this._addTween(tweens, instr);
        },

        tweenAll: function (tween, instr) {
            var tweens = [];
            var $s = this._lookup(instr.$s) || this.params.$s;
            yf.irange.call(this, function (i) {
                var nt = { $: $s[i] };
                yf.ipairs.call(this, function (k, v) {
                    nt[k] = [nt.$[k], this._lookup(v)[i]];
                }, tween);
                tweens.push(nt);
            }, $s.length);
            this._addTween(tweens, instr);
        },

        event: function (name) {
            this.params[name](this, this.params);
        },

        _dispatch: function (instr) {
            if (instr.set1)
                this.set1(instr.set1);
            if (instr.set)
                this.set(instr.set);
            if (instr.tween1)
                this.tween1(instr.tween1, instr);
            if (instr.tween)
                this.tween(instr.tween, instr);
            if (instr.tweenAll)
                this.tweenAll(instr.tweenAll, instr);
            if (instr.event)
                this.event(instr.event);
        },

        tick: function () {
            var t = this._t;
            var i;
            for (var key = this.keys[this._pc];
                 this._lookup(key) <= t;
                 key = this.keys[++this._pc]) {
                yf.each.call(this, this._dispatch, this.timeline[key]);
            }

            for (i = this._tweens.length - 1; i >= 0; --i ) {
                if (this._tweens[i].tick())
                    this._tweens.splice(i, 1);
            }

            if (++this._t > this._t1) {
                if (this.completionHandler)
                    this.completionHandler(this);
                this.entity.detach(this);
            }
        },

        tock: function (p) {
            for (var i = this._tweens.length - 1; i >= 0; --i)
                this._tweens[i].tock(p);
        },

        TAPS: ["tick", "tock"]
    });

    yuu.Tween = yT({
        /** Tween object properties over time

            This component changes properties over time, and can
            handle synchronizing multiple objects and multiple
            properties.

            The `property` is either a single object with the special
            `$` property set to the object to tween and every other
            property set to the properties to tween with values [min,
            max], or a list of such objects. For example, to tween a.x
            from 0 to 1, a.y from 2 to 3, and b.z from 1 to 2, you
            would pass

                [{ $: a, x: [0, 1], y: [2, 3] },
                 { $: b, z: [1, 2] }]

            The `duration` is specified in ticks (e.g. calls to
            director.tick).

            `repeat` may be a positive number to repeat the tween that
            many times, or a negative number to cycle back to the
            minimum (and then back to the maximum, etc.) that many
            times. `Infinity` will repeat the tween forever and
            `-Infinity` will cycle the tween back and forth forever.

            A custom easing equation may be provided. This is a
            function which takes a p = [0, 1] and returns the eased p.
        */

        constructor: function (props, duration, repeat, easing) {
            this._object = [];
            this._property = [];
            this._a = [];
            this._b = [];
            this._count = 0;
            this.duration = duration || 60;
            this.repeat = repeat || 0;
            this.easing = easing || yuu.Tween.LINEAR;
            yf.each.call(this, function (oab) {
                yf.ipairs.call(this, function (name, ab) {
                    if (name !== "$") {
                        this._object.push(oab.$);
                        this._property.push(name);
                        this._a.push(ab[0]);
                        this._b.push(ab[1]);
                    }
                }, oab);
            }, yf.arrayify(props));
            this._updateAt(0);
        },

        tick: function () {
            var t = this._count / this.duration;
            ++this._count;
            if (t > 1 && !this.repeat)
                return true;
            else if (t >= 1 && this.repeat) {
                if (this.repeat < 0) {
                    var n = this._a;
                    this._a = this._b;
                    this._b = n;
                }
                this._count = 1;
                t = 0;

                if (this.repeat < 0) {
                    this.repeat++;
                } else if (this.repeat > 0) {
                    this.repeat--;
                }
            }
            this._updateAt(t);
        },

        tock: function (p) {
            var t = (this._count + p - 1) / this.duration;
            if (t <= 1)
                this._updateAt(t);
        },

        _updateAt: function (t) {
            var p = this.easing ? this.easing(t) : t;
            for (var i = 0; i < this._object.length; ++i) {
                // a was the existing property, b was the one provided
                // by the user.  By lerping from b to a, the user can
                // control the lerp type in some awkward cases -
                // e.g. CSS DOM values are all exposed as strings so a
                // will be a string/String, but if b is provided as a
                // number/Number, this will lerp numerically.
                //
                // FIXME: This still doesn't work right if the lerp is
                // later reversed due to negative repeats.
                var object = this._object[i];
                var property = this._property[i];
                var a = this._a[i];
                var b = this._b[i];
                object[property] = yuu.lerp(b, a, 1 - p);
            }
        },

        count: {
            get: function () { return this._count; },
            set: function (v) { this._count = Math.round(v); },
        },

        duration: { value: 60, chainable: true },
        repeat: { value: 0, chainable: true },
        easing: { value: null, chainable: true },
    });

    yuu.TweenC = yT(yuu.C, {
        constructor: function () {
            this._tween = yf.construct(yuu.Tween, arguments);
        },

        tick: function () {
            if (this._tween.tick())
                this.entity.detach();
        },

        tock: { proxy: "_tween.tock" },
        count: { alias: "_tween.count" },
        duration: { alias: "_tween.duration", chainable: true },
        repeat: { alias: "_tween.repeat", chainable: true },
        easing: { alias: "_tween.easing", chainable: true },

        TAPS: ["tick", "tock"]
    });

    yuu.Tween.LINEAR = null;
        /** No easing */

    yuu.Tween.EASE = function (p) {
        /** Ease in and out

            This equation is from _Improving Noise_ (Perlin, 2002). It
            is symmetrical around p=0.5 and has zero first and second
            derivatives at p=0 and p=1.
        */
        return p * p * p * (p * (p * 6.0 - 15.0) + 10.0);
    };

    yuu.Tween.EASE_IN = function (p) {
        return p * p * p;
    };

    yuu.Tween.METASPRING = function (amplitude, pulsation) {
        /** A generator for springy tweens

            The amplitude controls how far from the final position the
            spring will bounce, as a multiple of the distance between the
            start and end. A "normal" amplitude is around 0.5 to 1.5.

            The pulsation constant controls the rigidity of the spring;
            higher pulsation results in a spring that bounces more quickly
            and more often during a fixed interval. A "normal" pulsation
            constant is around 15 to 30.
        */
        return function (p) {
            return 1 + Math.cos(pulsation * p + Math.PI) * (1 - p) * amplitude;
        };
    };

    yuu.Tween.STEPPED = function (segments, alpha) {
        return function (p) {
            p = p * segments;
            var lower = Math.floor(p);
            var upper = Math.floor((p + alpha));
            if (upper > lower) {
                var p1 = 1 - (upper - p) / alpha;
                return (lower + p1) / segments;
            } else {
                return lower / segments;
            }
        };
    };

    yuu.Transform = yT(yuu.C, {
        /** A 3D position, rotation (as quaternion), and scale

            This also serves as an object lesson for a simple slotted
            component.
        */
        constructor: function (position, rotation, scale) {
            this._position = vec3.clone(position || [0, 0, 0]);
            this._rotation = quat.clone(rotation || [0, 0, 0, 1]);
            this._scale = vec3.clone(scale || [1, 1, 1]);
            this._matrix = mat4.create();
            this._dirty = true;
            this._version = 0;
            this._parentVersion = null;
        },

        SLOTS: ["transform"],

        position: {
            chainable: true,
            get: function () { return this._position.slice(); },
            set: function (v) { this._dirty = true;
                                vec3.copy(this._position, v); }
        },
        rotation: {
            chainable: true,
            get: function () { return this._rotation.slice(); },
            set: function (v) { this._dirty = true;
                                quat.normalize(this._rotation, v); }
        },
        scale: {
            chainable: true,
            get: function () { return this._scale.slice(); },
            set: function (v) { this._dirty = true;
                                vec3.copy(this._scale, v); }
        },
        x: {
            chainable: true,
            get: function () { return this._position[0]; },
            set: function (x) { this._dirty = true; this._position[0] = x; }
        },
        y: {
            chainable: true,
            get: function () { return this._position[1]; },
            set: function (x) { this._dirty = true; this._position[1] = x; }
        },
        z: {
            chainable: true,
            get: function () { return this._position[2]; },
            set: function (x) { this._dirty = true; this._position[2] = x; }
        },
        xy: { swizzle: "xy", chainable: true },

        scaleX: {
            chainable: true,
            get: function () { return this._scale[0]; },
            set: function (x) { this._dirty = true; this._scale[0] = x; }
        },
        scaleY: {
            chainable: true,
            get: function () { return this._scale[1]; },
            set: function (x) { this._dirty = true; this._scale[1] = x; }
        },
        scaleZ: {
            chainable: true,
            get: function () { return this._scale[2]; },
            set: function (x) { this._dirty = true; this._scale[2] = x; }
        },

        worldToLocal: function (p) {
            var x = (p.x || p[0] || 0);
            var y = (p.y || p[1] || 0);
            var z = (p.z || p[2] || 0);
            var local = [x, y, z];
            var matrix = mat4.clone(this.matrix);
            return vec3.transformMat4(local, local, mat4.invert(matrix, matrix));
        },

        contains: function (p) {
            p = this.worldToLocal(p);
            return p[0] >= -0.5 && p[0] < 0.5
                && p[1] >= -0.5 && p[1] < 0.5
                && p[2] >= -0.5 && p[2] < 0.5;
        },

        ypr: {
            chainable: true,
            get: function () {
                var q = this._rotation;
                var x = q[0]; var sqx = x * x;
                var y = q[1]; var sqy = y * y;
                var z = q[2]; var sqz = z * z;
                var w = q[3];
                var abcd = w * x + y * z;
                if (abcd > 0.499)
                    return [2 * Math.atan2(x, w), Math.PI / 2, 0];
                else if (abcd < -0.499)
                    return [-2 * Math.atan2(x, w), -Math.PI / 2, 0];
                else {
                    var adbc = w * z - x * y;
                    var acbd = w * y - x * z;
                    return [Math.atan2(2 * adbc, 1 - 2 * (sqz + sqx)),
                            Math.asin(2 * abcd),
                            Math.atan2(2 * acbd, 1 - 2 * (sqy + sqx))];
                }
                
            },
            set: function (ypr) {
                var q = this._rotation;
                quat.identity(q);
                quat.rotateZ(q, q, ypr[0]);
                quat.rotateY(q, q, ypr[2]);
                quat.rotateX(q, q, ypr[1]);
                this._dirty = true;
            }
        },

        yaw: { aliasSynthetic: "ypr[0]", chainable: true },
        pitch: { aliasSynthetic: "ypr[1]", chainable: true },
        roll: { aliasSynthetic: "ypr[2]", chainable: true },

        matrix: {
            get: function () {
                var pt = this.entity.parent && this.entity.parent.transform;
                var pm = pt && pt.matrix;
                var ptVersion = pt && pt._version;
                if (this._dirty || (ptVersion !== this._parentVersion)) {
                    var m = this._matrix;
                    mat4.identity(m);
                    mat4.fromRotationTranslation(
                        m, this._rotation, this._position);
                    mat4.scale(m, m, this._scale);
                    if (pm)
                        mat4.multiply(m, pm, m);
                    this._dirty = false;
                    this._matrix = m;
                    this._parentVersion = ptVersion;
                    this._version = (this._version + 1) | 0;
                }
                return this._matrix;
            }
        }
    });

    yuu.Ticker = yT(yuu.C, {
        /** Set a callback to run every n ticks

            If the callback returns true, it is rescheduled for
            execution (like setInterval). If it returns false, this
            component is removed from the entity.
        */
        constructor: function (callback, interval, delay) {
            this.callback = callback;
            this.interval = interval;
            this._accum = 0;
            this._count = -(delay || 0);
        },

        tick: function () {
            this._accum += 1;
            if (this._accum === this.interval) {
                this._accum = 0;
                if (!this.callback(this._count++))
                    this.entity.detach(this);
            }
        },

        TAPS: ["tick"]
    });

}).call(typeof exports === "undefined" ? this : exports,
        typeof exports === "undefined"
        ? this.yuu : (module.exports = require('./core')));