Is there documentation of the true method arguments somewhere?

[killroy]

The documentation is extremely incomplete in that most functionality is hidden behind an anonymous "vars" argument. Is there any documentation enumerating all the arguments that are supported by the various methods?

 

For example, often it simply says "An object defining the value for each property that should be set.". But this is plainly not true as you support only a sub-set of all properties as well as magical properties that don't exist in CSS (like scale, etc).

 

It also does not document the various magical, hidden, secret, whatever options and switches that can be set. Time and time again I come across forum answers that say something like "Simply set magicalProp: true". But of course there was no way for us to even guess such a property even exists.

 

For example, I am once again hitting the wall that "set" sets values immediately, not at the correct place in the timeline. I vaguely remember seeing some magical switch ones that makes this work correctly. But of course it's not documented anywhere, and to find it in the forum, I need to know what the answer is before.

 

So, is there actual documentation of the supported properties for each "vars" object for each method, such as "to" and "set", etc?

 

 

Yours truly frustrated,

Sven

[GreenSock]

I'm so sorry to hear about the frustration, killroy. We put a ton of effort into our docs and we often get rave reviews (got one this morning in fact), but I'm sure there's room for improvement and I'll do my best to explain why things aren't organized quite the way you're asking and then maybe you can provide some suggestions...

 

It's important to understand that the GSAP system is engineered to be EXTREMELY flexible, and as such, it's not limited to some list of pre-defined properties that you're "allowed" to tween. So we can't just slap a list into the docs. Generally it can tween any numeric property of any object. So if you create an object that has a "myWeirdPropertyThatHasAReallyLongName" property, you can tween it. 

 

Plugins add value - those are the things that solve particular problems where a property isn't a number or it has to be applied or formatted in a certain way. For example, CSS properties that have suffixes or are complex (clip:"rect(0px,2px,500px,300px)") or colors. If you want to tween the scroll position, there are nuances in each browser, etc. So we build solutions to these in the form of plugins. Those plugins insert additional capabilities, so it wouldn't be feasible to add a bunch of documentation for the set() method that lists out every conceivable property that is either native to the object or that gets added with plugins. If you don't have CSSPlugin loaded, for example, you can't tween "boxShadow" on a DOM element. It seemed to make the most sense to document that stuff in the appropriate plugin itself. 

 

So if you look at the docs for the CSSPlugin, it not only tells you that you can animate virtually any CSS property (in camelCase form), but it also lists out almost all the "magical" properties that the plugin recognizes too, like scaleX, scaleY, rotation, x, y, z, clearProps, etc. And then you'll find scroll-related properties described in the ScrollToPlugin docs, etc. 

 

Does that help clear things up? 

 

Any of the non plugin-specific special properties that you can define for a particular vars parameter (like onComplete, delay, ease, immediateRender, etc.) are detailed in the docs right with that method. Let me know if you are having trouble finding those. 

 

As far as your set() inside of a timeline not working as you expected, can you show us an example of that? Here's a codepen that shows it working great: http://codepen.io/GreenSock/pen/dPaBBq

 

I wonder if maybe you're creating a TweenLite.set() and then trying to put it into a timeline. That's totally fine to do, but when you do a TweenLite.set() or TweenMax.set(), it cannot know that you're going to put that into a timeline and schedule it for later - typically people expect a set() to work IMMEDIATELY (as in, literally, by the time the next line of code executes, it's already done). When you use the timeline's set() convenience method, it knows you're scheduling it, so it can intelligently prevent the immediate rendering for you. But you can still create a TweenLite.set() or TweenMax.set() if you prefer, and just set immediateRender:false. 

 

If you're having any trouble with it, please create a simple codepen and post a link here and we'll help out. (You can fork the one from above)

 

If you have specific suggestions for the docs, I'm all ears too. 

[killroy]

Hey,

 

I get your arguments, and man that was a thorough and detail answer. RESPECT!

 

The option I was remembering was immediateRender. Where is that in the docs? It would be good to list at least all the options that are fixed, especially if you're going to mash up arbitrary property references with internal flags, etc. I know it makes for simpler, more elegant code, I do the same in my own engine, but It leaves the API user often lost and confused.

[killroy]

Follow up: Nope, that's not it.

 

Still have a case where set and to,0 do not work, but to,0.0001 works, but intermittently. Almost like it's a timing issue. By "not work" I mean the values are NOT updated at all.

[GreenSock]

I'd be happy to take a peek at an example. Can you provide a very simple codepen demo? We're not aware of any bugs at all in 1.16.1 (that is the version you're using, right?) It's just very difficult to troubleshoot blind. 

 

You can fork the codepen I provided, or create your own. See http://greensock.com/forums/topic/9002-read-this-first-how-to-create-a-codepen-demo/for help with that (it's quite easy, actually). 

 

By the way, you were absolutely right about the config object missing in the set() docs. Our mistake - it's there now. 

[killroy]

It's hard to extract as I am working on an animation framework for my game. I believe it's related to some parts of the demo just not being ready when GSAP tries to manipulate it. So, set and short to delays don't work, but a to with a 1 second duration work. Is there some way to get GSAP to report if there is a problem? Right now it just fails silently without modifying the DOM.

[killroy]

Just to let you know, there was interference from other code that manipulated the object through a different timeline with a set. There go 5 hours I'll neveer get back!

[GreenSock]

Glad you figured it out. Just to confirm, you solved everything and there's no suspicion of a bug in GSAP, right? 

[killroy]

Hey,

 

To be honest, I don't think it's a bug, I think it's a problem with the intuitiveness of the system and the lack of documentation.

What I am trying to build is a system of animations, where I can "create" animations ahead of time and then inject copies of those at will into a global timeline. The idea is that I can globally affect playback speed and even jump back and replay some of what has happened. These sub-timelines, ideally support set, to and add functionality (for events).

 

Here is a codepen: 

See the Pen KwEmLJ by killroy (@killroy) on CodePen

 

The core concept is this:

var

  root = new TimelineLite(),

 t1 = new TimelineLite({paused: true}),

 t0 = new TimelineLite({paused: true}),

 

t1.to(...).add(...);

t2.set(...);

 

setTimeout(function() { // Simulate event

  t0.add(t1.play();

}, 100);

 

setTimeout(function() { // Simulate event

  t0.add(t2.play();

}, 500);

[killroy]

Ok, it seems that the timeline automatically looses its "playing" state when it hits the end. So I always have to do this:

 

root.add(newTl.play()).play();

 

Let's see if that fixes it...

[OSUblake]

It sounds like you are trying to do something like exportRoot to control your tweens globally. But I'm having a hard time understanding what your set problems are. From what I can tell, it looks like you have sequencing problems going on. Have you watched the sequencing and position parameter videos? Also, adding some labels might help you out so you can jump back and forth between positions in your timeline.

 

Here's a fork of your example. See if this helps you out any.

See the Pen gbERXd by osublake (@osublake) on CodePen

[killroy]

I'm building an animation engine, so there are no animations in there. Just a frame work for storing and playing back animations across my ECS framework. The (.play()).play() seems to work for now. I'll see if I run into more issues.

 

I think a lot of my issues come from the fact that GSAP is designed for small, localized animation tasks, such as needed in websites, and not for bigger stuff like my game. It's not that GSAP isn't capable, more that the default operation modes are designed for that sort of use.

 

Is there any information available how GSAP handles time lines internally? I am a bit concerned about adding sub-timelines to a larger timeline for a 20-30 minute game and what sort of memory it might leak.

[OSUblake]

I'm pretty sure GSAP is up to the challenge. Check out this game made with GSAP.

https://www.kickstarter.com/projects/nevergrind/nevergrind-html5-action-rpg

 

And here's a pretty complicated animation scene. Toggle the mouse button in the top left corner to move that thing to your mouse cursor.

See the Pen byouf by gordonnl (@gordonnl) on CodePen

 

As far as the internals go, I know GSAP uses some sort of linked list, but I've never dug deep into it, so Jack would have to answer that one.

[killroy]

The more I think about it the less I feel it will work the way I want. For example how would .clear() work in the context of nested timelines, where I don't want to clear the global one, only the keyframes related to a particular object. I think the problem is that GSAP isn't organised by the elements beign animated. I already abstracted away those refs, because of course a thing always wants to move itself and should never move something else. I'll keep at it and let you know how it works out. I might have to go back to using GSAP just for the actual animations but not the long term management.

 

Oh, and that is not a complicated animation compared to what will result from 20-30 minutes of game-play in a multi-player game

[killroy]

The more I work on this, the more I am missing a major feature, which is re-playable, dynamic animations. Which is what I am currently implementing.

 

For example, in my case I can define a named animation, something like 'moveCard' and do something like this:

card.anim.play('moveCard', x, y);

 

Underneath, it currently has to create a new timeline and add the items required for the animation. I cannot replay an existing timeline, since the arguments are "baked" into it. So I had to create another layer on top.

 

I wonder if this might be better as some kind of plug in...

[OSUblake]

There's a couple discussions on this forum where people use timelines to manage a bunch of animations and scenes, but I've never taken that approach. When I need to manage a bunch of animations that aren't sequential, I usually use some sort of list, and control them using an event aggregator and/or state.

 

What type of game are you making? And why would you need keep 20-30 minutes of animation? And if its replayable, how can it be dynamic? Maybe the invalidate method can help you out here. Seems like it would be easier just to have a function that returns a new tween, but then again, I don't know what you're building.

[killroy]

It's a turn based, two player game. Each player makes multiple actions each turn which result in a variety of animations. I want a player to click on his turn history and replay everything from 3 turns back at 4x speed, for example. I had hoped by adding everything to a single, global timeline, I'd be able to do this.

 

The animations need to be dynamic. For example I might define a moveTo(x, y) animation that has multiple steps, lifting the item, sliding it over, etc. I want to reuse this animation for multiple moves.

 

Currently my syntax is a bit clunky, but something along these lines:

 

anim.register('showHoverCard', [

['clear'],

['set', {x: '$1', y: '$2', scale: 0}],

['show'],

['add', function(){self.isVisible = true;}]

]);

[OSUblake]

This might be of some use to you. I created a demo that saves every card move you make. But instead of adding the tweens to a timeline, I just save them in an array for use later on. So when you press one of the buttons, I just dump all the stored tweens into timeline, which can then be manipulated.

 

I spent about 5 minutes building up a list of animations, and it worked fine.

 

See the Pen zxbdmL by osublake (@osublake) on CodePen

[OSUblake]

Another nice thing about using an array of tweens, is that it is real easy to build custom timelines using the Array.prototype.reduce method. You can pass in a timeline as the accumulator object, and start building a timeline À la carte. I use this technique to build animation factories in Angular.

arrayOfTweens.reduce(function(timeline, tween) {
  // Some logic..
  timeline.add(tween);
  return timeline;
}, new TimelineMax());

[killroy]

I'm currently working on making them JSON compatible with variable substitution, etc. I'll let you know how it goes. Being able to store the animations as JSON will make it much easier to create, transform, transmit and replace them.

[OSUblake]

That could work too. Here's a fork of something I was working on that creates animations from JSON. Open the timeline-service.js file to check it out. The tweenSteps array would be an object extracted from JSON. It's in Angular and uses a bunch of promises, so you may not understand everything that is going on, but should provide a little guidance.

 

http://plnkr.co/edit/D3NSr4rliU1kuDbjLNHP?p=preview