Adobe Animate

author:
Daniel Sperl
description:
Load and play Adobe Animate CC's 'Texture Atlas' animations
compatible:
v2.4
tag:
animate, movieclip, animation
homepage:
https://github.com/Gamua/Starling-Extension-Adobe-Animate

Overview

The main problem with this extension is that the “texture atlas” export functionality of Animate CC is lacking a few crucial features. Please help us get this to Adobe's attention by following the steps outlined here!

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 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! Use the directional keys on your keyboard (up, down, left, right) to change the animation phases of the Ninja Girl™.

The Adobe Flash Plugin is needed to display this content.

[This animation was created by the brilliant 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 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:

/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.
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”.

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 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.

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

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:

var mole:Animation = assets.createAnimation("mole");
addChild(mole);
Starling.juggler.add(mole);

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

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

// 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);

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:

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

mole.getFrame("walk"); // → 20

You can also jump to that frame directly:

mole.gotoFrame("walk");

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:

mole.addFrameAction("crouch", 
    function():void { mole.gotoFrame("walk"); }
);

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:

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

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.

var atlas:AnimationAtlas = assets.getAnimationAtlas("mole");

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:

var mole:Animation = atlas.createAnimation();

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:

var background:Animation = atlas.createAnimation("background");

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

trace(atlas.getAnimationNames().join(", ")); // mole, background, hands, feet, ...

[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

The “Animation.json” file that is exported by Adobe Animate becomes really big quickly. However, the file is mostly made up of whitespace – Animate CC doesn't “minify” it. Furthermore, it contains redundant data (e.g. DecomposedMatrix) and misses the opportunity of combining empty frames via the duration property.

Until Adobe fixes that, I figured a small tool would do the job nicely. You can find it inside the repository's tools/optimize_json folder. Look at the README.md file for installation and usage instructions.

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

# 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

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

Zip support

If you zip the files as shown above (or by simply using a standard zip compressor), you'll want to teach the AnimAssetManager class how to unzip those files, of course!

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:

assets.dataLoader = new ZipLoader();

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

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 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

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 forum, though.

  extensions/adobe-animate.txt · Last modified: 2018/09/11 09:24 by daniel
 
Powered by DokuWiki