GSAP time unit to ms?

[tomByrer]

To me, having a truly 'unified API' would require they take the same input, thus all conform to ms, don't you think? A bit of extra maths, but less programming & worry when switching. Or am I missing something here?

[SkidX]

yes, you are missing 'Tweene.defaultTimeUnit' and the fact that the maths is already there :)
If you are using only tweene-gsap, Tweene.defaultTimeUnit is initialized with 's' because we assume that you are used to the convention of that specific lib, so we let you start with the behavior that you probably expect.
In all other cases Tweene.defaultTimeUnit is equal to 'ms' for the same reason, because it is most likely what you expect, coming from one of the other supported libraries (velocity, transit or jquery).
However you could change that setting at the top of your script or any time you want, and you can change the used unit also on a single call basis, for example like this:

Tweene.get($target).duration('1.5s').delay('100ms')

Any value passed as pure number, is interpreted accordingly to Tweene.defaultTimeUnit, that you can change, so you have total control on it and the api is unified, because once you have set that value to your preferred unit, then the animation code is exactly the same whatever library you choice to use.

You can refer to this for a complete explanation, let me know if something is not clear:
http://tweene.com/docs/#duration

[SkidX]

to be clearer with an example:

require('tweene'); // all drivers loaded, defaultTimeUnit is 'ms'
Tweene.get($target1, 'gsap').to({opacity: 0}, 500);
Tweene.get($target2, 'transit').to({opacity: 0}, 500);
Tweene.get($target3, 'velocity').to({opacity: 0}, 500);
// same behavior for all these calls

[tomByrer]

Thanks for your detailed explanation!
This is where I find concern, sorry if I wasn't clear:

// use Tweene with GSAP: default time unit is 's'
...
// use Tweene with jQuery: default time unit is 'ms'

So if I have code written in Tweene, I'd hope I would not have to re-write the times.
The way I would read "default time unit is 's'", I would think Tweene's time is 's', not Tweene translating from 's' into 'ms'. Also, this is confusing:

// set your default time unit and driver
Tweene.defaultTimeUnit = 's';
Tweene.defaultDriver = 'gsap';

If there was automatic translation, then I would assume Tweene's GSAP driver would do this, not needing a specific translation.

Perhaps my PR makes things more clear?

[SkidX]

you don'thave to rewrite the times in your animation code and you don't have to concern about any time translation.
Tweene.defaultTimeUnit is just the unit you want to use in your code whatever is the library of your choice, so you don't have to worry about any translation or rewrite. Do you want to use milliseconds in your script? Then set

Tweene.defaultTimeUnit = 'ms';
Tweene.to($target, {opacity: 0}, 500); // duration = half second
Tweene.to($target, {opacity: 0}, '0.5s'); // duration = half second

Do you want to use seconds? It's up to you. Then set

Tweene.defaultTimeUnit = 's';
Tweene.to($target, {opacity: 0}, 0.5); // duration = half second
Tweene.to($target, {opacity: 0}, '500ms'); // duration = half second

I don't think that talking of internal conversions that may or not may happen can help the user to understand better how to use it. It has to know only that it can choose the unit it likes more, and use it without any trouble. I'm explaining the external API there, not how I handle it internally.

Do you think that changing that comment with something like " the predefined value of Tweene.defaultTimeUnit is 's' " could explain better ?

[tomByrer]

Do you think that changing that comment with something like " the predefined value of Tweene.defaultTimeUnit is 's' " could explain better?

Some.
I learn by example. So seeing GSAP consistently being set to 's' & the other set to 'ms' throws me off.

[SkidX]

I understand your point, but the intention is to limit as much as possible the friction in the transition from using native libraries "as is" to using them with Tweene.

So, how does it work in GSAP? You have to set times in seconds. So if you want to give a try to Tweene and you port your examples from GSAP to Tweene + GSAP, you will have to basically change only the namespace, from TweenMax.to(...) to Tweene.to(...), leaving almost all other params unchanged. This is the reason to have it predefined in "seconds". But you can change it, if you want.

What if you come from one of the other supported libraries? You probably expect to write your code in 'ms' unit, so you will find it predefined. But, again, you can change it, if you want.

Your legit question is "what is the time unit used in Tweene"? But the answer is not 's' and is not 'ms', it is "whatever you like". It can be seconds or milliseconds or both at the same time. It tries to let the user write code as it is in its current habit, not to force it to change it to adapt to the way other libraries expect.

However I agree with the fact that the comment about Tweene.defaultTimeUnit there in the "getting started" section is not clear and can bring to misunderstanding because it's talking of something it is not yet explained at that point of documentation, so I'll try to rewrite that part better this evening after work.
Thanks for pointing it out.

[SkidX]

I tried to explain it better in the readme and I removed those ambigous sentences.

[tomByrer]

limit as much as possible the friction in the transition from using native library "as is" to using them with Tweene

Yes, I didn't understand this until later. You're trying to make it easier for people to port code from the original animation lib into tweene.

Your updated README is much better; cheers!