Animatron/player — pull request #57 by shamansir (2012-11-02 21:55:51+00:00)
Title: v0.246b: Time is relative in all of the modifiers. Tweens are now totally identical to band-restricted modifiers

**Major** change is that ALL types of the modifiers now receive _relative time_.

The another **major** change is that _tweens_ are TOTALLY identical to _band-restricted modifiers_ now, they just have predefined functions.

This Pull Request will **BREAK** most of the code used with previous versions. The version just before these changes has `v0.245` tag, so it is safe to switch to it and your code will work properly, but will be outdated.

So, developers who use the engine should change their code accordingly, and I recommend to do it in a separate branch, use `v0.245` and `v0.246b` tags to checkout and switch versions of player.

Some new aggressive errors may appear while using new code, please report it to me, by e-mail or through issues, I'll try to fix them asap.

Final `v0.246` version will fix `AnimatronImporter`, new-found bugs and include docs. If you feel unsafe, you may wait to the final `v0.246` version which should fix bugs unrelated to animations and those were found during deep investigation into changes. But please participate in the switch to help to find new errors.

#### _Changes that may break the code:_

* tweens now act as a band-restricted modifiers, so they get value of `0` before their band wasn't started and value of `1` after their band; please keep that in mind when you use overlapping modifiers or apply sequenced changes.
* simple modifiers now take time `t` in range of `0..1`, second argument is `duration`, so to get the actual value you should use `t * duration`; `data` is the _third_ argument now.
* default band for any empty element is back to `0..10`, before it was `0..MAX_INT` — it was changed back since all modifiers now get `0..1` of `t` and in previous version empty elements got the very small `t`.
* state is now totally clean in modifiers when it comes inside on new frame, so code like `this.x += 5` will not work (and failed to work before, but it is another story), please use previous state that is accessible through `this._`: `this.x = this._.x + 5`; but if you have a code with overlapping modifiers, `this.x += 5` will add `5` to the value left in state from the modifier performed before (in the same frame).

#### All changes:

Modifiers types:

* `b().modify(function(t, [duration[, data]]) { ... })` — now modifier takes `t` in range `0..1`, and takes `duration`, which is duration of the element band (same to `this.$.duration()`).
* `b().modify([x, y], function(t, [duration[, data]]) { ... })`, will call a modifier through the inner band, getting _value from `0..1`_ in the duration of the band `[x, y]`, like tweens. It is important to note that it will get `0` all the time before `x` and `1` all the time after `y`, please consider that when using this type of modifiers and tweens; since `duration` value is the duration of the given `[x, y]` band, to get duration of the elements' band, you may use `this.$.duration()`.
* `b().modify(my_t, function(t, [duration[, data]]) { ... })` will call a modifier at `my_t` time or a bit later, if framerate is low, and will get actual time when it was called. `my_t` is like a band-time, defined in seconds after element was started and `t` is in range of `0..1`, relative to a band of the element. It is now used instead of `b().at()` method which in its order calls this method.

See example from [Previous PR#53](https://github.com/Animatron/player/pull/56) to get vision of new types of modifiers.

Other changes:

* Tweens are equal to band-modifiers, their functions are also changed accordingly
* Default band for empty element is now `0..10`
* It is now possible to pass easing for any modifier (I should also mention it in docs)
* Element state is now cleared on every frame (previously it was cloned and passed to new-frame modifiers)
* `scene.duration` and elements' bands calculation fixes, default band for the element is now [0, 10]
* More bands, scene & element duration tests, so they should work more polished
* Partly refactored errors to be collected in a single object

`v0.247` is planned to include relative-modifiers, so:

b().band([0, 5]).modify([2.5, 4], function(t) { ... })
b().band([0, 5]).rmodify([1/2, 4/5], function(t) { ... })

will be equal, and the same with triggers:

b().band([0, 5]).modify(2.5, function(t) { ... })
b().band([0, 5]).rmodify(1/2, function(t) { ... })