do not default to global TWEEN group for new Tweens, do not auto-add/remove tweens from groups, and update docs accordingly

[trusktr]

feat: do not automatically add/remove a tween to/from its associated group

feat: the tween.group(group) method now has a reciprocal tween.remove() method that will remove a tween from its associated group, and unassociate the group. tween.group() without an arg is no longer valid, see breaking changes and migration below.

fix: when a tween is stopped before its end time, do not allow its update method to continue, therefore preventing logic (f.e. repeat logic) from being triggered

docs: improved the docs, adding some missing information, removing all examples of the global TWEEN group which has been deprecated, and adding docs on how to manage groups of tweens. Also updated samples to use import syntax for importing Tween, avoiding the use of the TWEEN UMD global variable which has been deprecated.

feat: A new Group.allStopped() method returns true if all tweens in a group are not playing (i.e. stopped, and not paused), otherwise false. Useful for stopping an animation loop once all tweens in a group have finished their animation.

BREAKING:

• Tweens are no longer automatically added or removed from groups by default when you call any Tween methods such as start(), stop(), or pause(), and the preserve parameter to Group.update() now defaults to true and is deprecated to be removed in a future major version.
  • MIGRATION: To keep old behavior for a while, explicitly call group.update() with false for the second parameter. To migrate forward, do not rely on automatic add/remove of tweens, and instead add/remove tweens to/from groups manually.
• Group.update() no longer returns a boolean indicating if all tweens have been removed.
  • MIGRATION: Don't rely on auto-add/remove to/from groups. This boolean return was previously useful for stopping an animation loop once all tweens were finished animating. Instead, use the new Group.allStopped() method to check if all tweens in a group are stopped in order to determine whether or not to continue an animation loop.
• The second group parameter to Tween.constructor now defaults to undefined instead of the global TWEEN group. Additionally it accepts a value of true to restore the old default behavior. The true value is deprecated and will be removed in a future major version.
  • MIGRATION: For the time being the parameter can be set to true to restore the old behavior. To migrate forward, use tween.group(group) or group.add(tween) instead.
• The argless tween.group() signature has been removed.
  • MIGRATION: Use group.add(tween) or group.remove(tween) instead. tween.group(TWEEN), TWEEN.add(tween), and TWEEN.remove(tween) will also work for now, but they are deprecated and will be removed in a future major version.
• Group.update's second parameter preserve defaults to true now, and is deprecated to be removed in a future major version, at which point tweens of a group will no longer be automatically added/remove to/from a group when calling any Tween methods such as start(), pause(), or stop().
  • MIGRATION: For now, explicitly set the parameter to false to restore old default behavior when calling group.update(). To migrate forward, do not rely on the automatic add/remove behavior, and instead manually add or remove tweens to or from groups.
• To make the fix for tween.update() to be a no-op for stopped tweens, we had to break an undocumented feature that allowed tweens to move backward in time (added preservation flag in TWEEN.update to be able to go backward in time #271).
  • MIGRATION: To move tweens backward in time after they have already completed, first call tween.start(startTime) then proceed to call tween.update(time) in reverse order as before (see the unit test with "go backward in time" in its name). Without calling tween.start() nothing will happen because stopped/completed tweens will now always return early from update(), as they are considered to be no longer running.