Returns : Timeline

A new timeline instance containing the root tweens and timelines

Details

Seamlessly transfers all tweens, timelines, and (optionally) delayed calls from the root timeline into a new timeline so that you can perform advanced tasks on a seemingly global basis without affecting tweens/timelines that you create after the export.

For example, imagine a game that uses the GSAP for all of its animations and at some point during the game, you want to slow everything down to a stop (tweening the timeScale) while at the same time animating a new popup window into place:

var tl = gsap.exportRoot();
gsap.to(tl, {duration: 0.5, timeScale: 0});
//this tween isn't affected because it's created after the export.
gsap.fromTo(myWindow, {scaleX: 0, scaleY: 0}, {duration: 1, scaleX: 1, scaleY: 1});

You could then re-animate things when you’re ready by tweening the timeScale back to 1. Or you could use exportRoot() to collect all the animations and pause() them and then animate the popup screen (or whatever). Then resume() that instance or even reverse().

You can exportRoot() as many times as you want; all it does is wrap all the loose tweens, timelines, and delayedCalls into a timeline which itself gets placed onto the root, so if you exportRoot() again, that timeline would get wrapped into another one, etc. Things can be nested as deeply as you want.

However, if you plan to call exportRoot() a lot (hundreds or thousands of times), it’d be wise to de-nest things from the previous export first to avoid a situation where the browser thinks there’s a recursion error (maximum callstack). You could do so like this (assumes we previously declared a variable named “allAnimations” to store the exported root):

//De-nest things from the "allAnimations" exported root if one exists...
if (allAnimations) {
    var animations = allAnimations.getChildren(),
        startTime = allAnimations.startTime(),
        root = allAnimations.timeline,
        l = animations.length,
        i;
    for (i = 0; i < l; i++) {
        root.add(animations[i], animations[i].startTime() - animations[i].delay() + startTime);
    }
    allAnimations.kill();
}
//now do the export
allAnimations = gsap.exportRoot();

Note: completed tweens and timelines are removed from the root (for automatic garbage collection), so if you exportRoot() after a particular tween completes, it won’t be included in the export. The only way around that is to set autoRemoveChildren property of the Animation._rootTimeline to false, but that is NOT recommended because you’d need to manually kill() your tweens and timelines manually to make them eligible for garbage collection.