~~NOTOC~~

====== Adobe Animate ======

---- dataentry extension ----
author_mail   : daniel@gamua.com Daniel Sperl
description   : Load and play Adobe Animate CC's 'Texture Atlas' animations
compatible    : v2.4       # the Starling version you tested the extension with
tags          : animate, movieclip, animation
homepage_url  : https://github.com/Gamua/Starling-Extension-Adobe-Animate
----

===== Overview =====

<note important>Be sure to use at least Animate CC version 2019.2 for this extension! Adobe made some crucial enhancements in that release, leading to smaller JSON files and easier export to different scale factors.</note>

For a long time, //Animate CC// has been offering a "Sprite Sheet" export option. In Starling terminology, it created a //TextureAtlas//: one big texture that includes SubTextures for each frame of the timeline -- ready to be loaded into Starling's //MovieClip// instance.

In 2017, //Adobe// added a new export format called [[https://blogs.adobe.com/contentcorner/2017/07/03/create-a-texture-atlas-with-animate-cc-for-your-favorite-game-engines/|Texture Atlas]]. That name is misleading for Starling developers — it's actually a new format that efficiently describes an //Animate CC// animation.

Such an export creates 3 files:

  * **spritemap.png** -- a texture atlas containing all elements of the animation (not the frames, but the actual building blocks).
  * **spritemap.json** -- a JSON file that describes the positions of each SubTexture inside the PNG file (similar to Starling's native XML format for texture atlases).
  * **Animation.json** -- a description of the animation in JSON format. It describes which object is visible at which frame; the complete timeline, layers, symbols, etc.

**This extension can load and display this new format.**

Here is an example of the extension in action! Have a look at several different animation phases of the Ninja Girl™ and its fearless assistant, Bunny.

{{ :extensions:ninja-girl.mp4?495x470 |}}

[This animation was created by the brilliant [[http://www.keyframer.com|Chris Georgenes]], the designer who also brought the Starling logo to life! You'll find the complete FLA file in the project download.]

===== Usage =====

==== Exporting from Animate CC ====

Adobe describes the process of exporting an animation from Animate CC in [[https://helpx.adobe.com/animate/using/create-sprite-sheet.html|this tutorial]].

In a nutshell:

  * Create the animation inside a new Symbol, i.e. it must show up in the "Library" panel.
  * Right-click on the Symbol and choose "Generate Texture Atlas". In the dialog box that pops up, choose a folder in which to store the 3 output files.

==== Playback inside Starling ====

=== Adding Code & Assets ===

First, you need to add the extension code to your game. I recommend you simply copy the "starling.extensions.animate" package (found inside the "src" folder) to your game.

Now you need to add the actual animation files to your project. Add them just like any other assets -- but keep the folders intact. You should have one folder per animation.

Like here:

<file>
/assets/joker/Animation.json
/assets/joker/spritemap.json
/assets/joker/spritemap.png

/assets/mole/Animation.json
/assets/mole/spritemap.json
/assets/mole/spritemap.png

// etc.
</file>

<note tip>You can also add those //png// files to one of your texture atlases, of course. Just be sure that they are accessible via the name of the //folder// ("joker", "mole"), not "spritemap".</note>

**Alternative: Embedding the files**

If you want to embed the files into your game (useful for pure Flash projects), you need to follow some simple naming conventions.

  * file name: ''[name]/Animation.json'' → member name: ''[name]_animation''
  * file name: ''[name]/spritemap.json'' → member name: ''[name]_spritemap''
  * file name: ''[name]/spritemap.png''  → member name: ''[name]''

The [[https://github.com/Gamua/Starling-Extension-Adobe-Animate/blob/58fab587f76101c6aa38a386355f33e3de2a16e8/src/StartupWeb.as#L40|Demo project]] shows an example of how it's done.

=== Loading the Assets ===

The extension contains an extended version of Starling's //AssetManager//, called //AnimAssetManager//. Use this version of the class in your game -- it can do everything the standard AssetManager can, but adds some new features.

Enqueue the animation assets as shown below.

<code as3>
var appDir:File = File.applicationDirectory;
var assets:AnimAssetManager = new AnimAssetManager();
assets.enqueue(appDir.resolvePath("assets/joker/"));
assets.enqueue(appDir.resolvePath("assets/mole/"));
assets.loadQueue(/* ... */);
</code>

That's all there is to do!

=== Basic Playback ===

To actually display those animations, we are going to create instances of the new //Animation// class. It works very similar to a classic Flash //MovieClip//, with the exception that you need to add it to a //Juggler// to see any movement -- hey, this is still Starling, right?

Instantiating those //Animations// couldn't be easier. The //AnimAssetManager// does that for us. Like this:

<code as3>
var mole:Animation = assets.createAnimation("mole");
addChild(mole);
Starling.juggler.add(mole);
</code>

That's it! This will display the looping mole animation.

Of course, the //Animation// class is very flexible when it comes to playback.

<code as3>
// if you named two frames of the animation "walk" and "end-walk",
// this will make the clip loop between the two.
mole.addFrameAction("end-walk", 
  function():void { mole.gotoFrame("walk"); }
);

// change the frames per second
mole.frameRate = 24;

// disable looping (all animations loop per default)
mole.loop = false;

// get notified when the animation is finished
mole.addEventListener(Event.COMPLETE, onMoleComplete);
</code>

=== Labels ===

By adding labels to your animations, you gain a lot of flexibility for playback. For example, here's a potential timeline of a clip with several animation cycles:

{{ :extensions:mole-timeline.png?nolink |}}

The index of a certain label can be queried with the ''getFrame'' method:

<code as3>
mole.getFrame("walk"); // → 20
</code>

You can also jump to that frame directly:

<code as3>
mole.gotoFrame("walk");
</code>

Of course, this means that the animation will eventually move to (and beyond) the "crouch" label. To display only the walk cycle, let it loop between "walk" and "crouch" instead:

<code as3>
mole.addFrameAction("crouch", 
    function():void { mole.gotoFrame("walk"); }
);
</code>

The problem with this approach is that you never know if "crouch" will always stay the animation coming after "walk". After all, the source clip could change in the future.

Thus, it's better to make use of the ''getNextLabel'' method:

<code as3>
var labelAfterWalk:String = ninja.getNextLabel("walk"); // → 'crouch'
mole.addFrameAction(labelAfterWalk, 
    function():void { mole.gotoFrame("walk"); }
);
</code>

Better safe than sorry!

=== The AnimationAtlas ===

Actually, I took a small shortcut above. We let the //AnimAssetManager// create the animation for us directly; but the animation is actually stored inside an //AnimationAtlas//. You can get that from the //AnimAssetManager//, too.

<code as3>
var atlas:AnimationAtlas = assets.getAnimationAtlas("mole");
</code>

Just like a //TextureAtlas// stores lots of different textures, an //AnimationAtlas// stores lots of different animations (or, to be exact: the raw data to create lots of animations).

With that atlas, you can create the mole animation like this:

<code as3>
var mole:Animation = atlas.createAnimation();
</code>

This will instantiate the default animation stored inside the movie clip; i.e. the main time line of the //Animate CC// symbol.

The atlas might contain other symbols, too. E.g. you could simply add lots of instances of other symbols inside its timeline and access them like this:

<code as3>
var background:Animation = atlas.createAnimation("background");
</code>

To find out at runtime which animations are available, trace them out like here:

<code as3>
trace(atlas.getAnimationNames().join(", ")); // mole, background, hands, feet, ...
</code>

[Note that these are only made-up names. The download repository does contain a 'mole' animation, but it does not contain those sub-symbols.]

===== Reducing the file size =====

On export from Animate CC, be sure to enable the option "Optimize Animation.json file". Otherwise, the JSON file becomes incredibly big quickly.

Also, beware that you can actually zip-compress that file and have Starling uncompress it at runtime! 

To do that, check out the [[Zipped-Assets]] extension. Copy the class //ZipLoader// to your project and assign an instance of it to your //AnimAssetManager//:

<code as3>assets.dataLoader = new ZipLoader();</code>

That's it! Now you can zip the json files individually (always one JSON per zip file).

**Deprecated: Script that optimizes 'Animation.json'**

If you've created your animation before Animate CC added the 'optimize Animation.json file' option, you can also use a small tool that's coming with this extension. I wrote that when Animate CC didn't yet have that option.

You can find it inside the repository's ''tools/optimize_json'' folder. Look at the [[https://github.com/Gamua/Starling-Extension-Adobe-Animate/tree/master/tools/optimize_json|README.md]] file for installation and usage instructions.

In a nutshell, here's what the tool does.

<code bash>
# Optimize an ''Animation.json'' file like this:
optimize_json.rb path/to/Animation.json

# Optionally, zip the file along the way:
optimize_json.rb --zip path/to/Animation.json
</code>

That way, the "ninja-girl" animation, for example, shrinks down from over 4MB to just 476 kB, or 32 kB when zipped! 

===== Limitations =====

The current version of this extension does not support all features that are stored in the Animate CC format. Most notably, **masks** and **filters** are missing, as well as **color tinting**. 

Note that even when those features will be implemented, they will come with a noticeable performance penalty -- so they should be avoided, anyway. Nevertheless, feel free to open an issue inside the [[https://github.com/Gamua/Starling-Extension-Adobe-Animate/issues|Issue Tracker]] if you need them.

===== Changelog =====

  * //2018/03/06//: First public version
  * //2018/06/04//: Renamed //AssetManagerEx// to //AnimAssetManager//
  * //2018/09/10//: Added Ruby script that optimizes ''Animation.JSON'' files
  * //2019/05/15//: Added support for new 'minified' JSON files
  * //2022/10/29//: Added support for slightly changed Adobe Animate output


===== User Comments =====

//Feel free to edit this part of the page if you want to add information that's lacking in the above description.\\
Questions are better asked in the [[http://forum.starling-framework.org|forum]], though.//