Next Gen Tween Library - Fatina v4

[kefniark]

Description

Fatina as a library has done a decent job for the past few years.
But they are still way for improvements, so for the v4 I would like to rebuild the project and make it more future proof and just better.

This document is just to define the feature scope of this new version.
Feel free to contribute if you would like to see changes.

---

1. Performance

Even if Fatina is quite fast compare to lot of other libraries, there are room for massive improvements under the hood.

• Web Workers
  Using Parallelization is definitely a way to leverage lot of the math involved and the quantity of object to updates

• ArrayBuffer
  A linear memory allocation can drastically speed up iteration, allow for reusing memory more efficiently while lowering the amount of GC involved

On mobile where every ms count, it could be really a massive improvement for Webgl games.

---

2. Better Typescript Support

One things which could really help the dev experience is to make types more strict.
Let's use the tools we have to avoid typo and stupid mistakes 😄

const sprite = { x: 0, y: 0 }
tween(sprite, { z: 5 }, 200) <= // this should throw a compilation error, `z` is not a property of sprite

---

3. Fatina Tween API

As started recently with the Transition Syntax, the API can be improved and made more user friendly.
So the first target would be to make API less verbose and less error prone

• Import
  Get rid of the Fatina parent object and expose everything directly. That parent object was mostly there for browser compatibility, and now we moved to ESM we don't really need it anymore.
  This would also allow for Tree Shaking and reduce the size of fatina for the host project.

import { tween } from Fatina

And .init() should also be removed as it confused people starting to use the lib

• Autostart
  Bad usage for .start() is one of the most common mistake, let's try to make that automatic and remove the friction

tween(obj, { x: 5 }, 200) // <= no need for .start()

await sequence([
  tween(obj, { x: 5 }, 200), // <= those will be auto stop and controlled by the sequence
  tween(obj, { y: 5 }, 200)
]).async() // <= this will autostart and return a promise

• Automatic Conflict Resolution
  One of the most confusing things in tweening libraries is the need to keep reference to old tweens to be able to kill them and start new animations on the same objects. This is often verbose, hard to get around and can lead to visual glitch.

The idea is to make real tweens atomic per object and property, and if another animation touch the same property, automatically cancel any previous one. Basically any animation on a property overwrite the previous one.

const obj = { x: 0, y: 0 }
tween(obj, { x: 10, y: 10 }, 500)
// ...
tween(obj, { x: 2, y: 2 }, 150) // the previous tween is instantly cancelled
tween(obj, { y: 0 }, 200) // the previous tween is only partially cancelled

// the object will end up with `{ x: 2, y: 0 }`, no need for .kill()

• Nested Properties
  As part of the previous point with auto conflict resolution, if we track per object and per property active tweens.
  It would allow us to have more complex tween and allow for nesting properties.

// currently you have to do 2 tweens
Fatina.tween(sprite).to({ alpha: 1 }, 350).start()
Fatina.tween(sprite.position).to({ x: 50, y: 50 }, 350).start()

// nesting could allow to make that way shorter
tween(sprite, { alpha: 1, "position.x": 50 }, 350)

// and related to conflict, the following tween should overwrite the previous tween `x` modification
tween(sprite.position, { x: 100 }, 200)

• Inline Tween Instantiation
  Chaining syntax can quickly become verbose and hard to follow, a bit of callback hell feeling. Provide better helper to create tweens

// current chaining syntax
tween(obj).to({ x: 2 }, 200).setEasing('linear').start()

// shorter syntax with 3 arguments for most common usage
tween(obj, { x: 2 }, 200)

// and a more compact 2 arguments
tween(obj, {
  to: { x: 2 },
  duration: 200,
  easing: 'linear'
})

• Tween Delay
  A long asked feature, not having to rely on sequence just to delay tweens.
  Make it a first citizen and basic feature of tween

tween(obj, {
  to: { x: 2 },
  duration: 200,
  delay: 500
})

• Tween more than int
  Add the ability to tween things like rgb color, or array of string (list of sprite) by default.
  It's already possible, but require to hack around the .onUpdate() which has a penality cost and not really readable.
  Make it a first citizen documented would make it more user friendly

// tween color
tween(obj, { color: "#FF0000" }, 500)

// tween in a list of values (better steps)
tween(obj, {
  to: { sprite: "run4.jpg" },
  steps: ["run1.jpg", "run2.jpg", "run3.jpg", "run4.jpg"]
  duration: 500
})

---

4. Better Composition

For the moment everything is build around Sequence, they are powerful but a bit hard to get around.
And some API like .join() a bit under used.
It would make more sense to design it in a similar fashion to Promise that people are used to

sequence([ tween1, tween2 ]) // will play tween1 then tween2
any([ tween1, tween2 ]) // this will play tween 1 and tween 2 in parallel and wait for at least one to complete
all([ tween1, tween2 ]) // this will play tween 1 and tween 2 in parallel and wait for both to complete

Sequence would be only used for linear sequence (what they were designed for originally) and new methods any and all to parallelize things.

await sequence([
  tween1, // <= tween
  any([ tween4, tween5 ]), <= parallel
  all([ tween2, tween3 ]) <= parallel
]).async()

---

5. Simplify Ticker Usage

Ticker are clearly under used and their cascading model make it hard to work with webworker.
The idea would be to make it a top level concept and directly bind them to tween.

clock({ id: 'game', framerate: 30, timescale: 1 }) // create a new clock

tween(obj1, { x: 5 }) // a UI tween
tween(obj2, { to: { x: 10 }, clock: 'game' }) // a Game tween

clock().setTimescale(0.5) // <= all the tweens are now playing half speed
clock('game').pause() // <= the first tween continue but the second one is paused

And related to the previous point, setTimescale should only be available on Tween or Clock.
On sequence it feel like a duplicated feature, which add some complexity without being really used that much.
The parent doesn't have to control the play speed of their childrens.

And like current ticker, let those clock them have their own update loop, this is useful for more advanced usage

await clock('game').update(dt)

// <= can check for collision here, without having to wait for the UI tweens to run

await Promise.all([
  clock('environment').update(dt),
  clock('ui').update(dt)
])

---

6. Documentation

The current hugo documentation has made his time, a more modern refresh could help the onboarding of new users