Using the Flash Professional Toolkit for CreateJS

To install Toolkit for CreateJS for Flash Professional CS6, simply open Toolkit for CreateJS.zxp with Adobe Extension Manager CS6 and restart Flash Professional.

Select Window > Toolkit for CreateJS to open the panel. You may also want to set up a keyboard shortcut for publishing to CreateJS by editing your keyboard shortcuts (Flash > Keyboard Shortcuts...) and adding a shortcut for the menu item Commands > Publish for CreateJS.

The Toolkit for CreateJS extension allows designers and animators to use Flash Professional CS6 to create assets for HTML5 projects using the CreateJS JavaScript libraries. It is not intended for building full games or experiences within Flash Pro.

It supports most of the core animation and illustration capabilities of Flash, including vectors, bitmaps, tweens, sounds, and JavaScript timeline scripting. This document contains more information on exactly what is supported.

When run on an FLA named TestFile.fla , it generates two files in the specified output directory:

• TestFile.js contains reusable classes representing the stage and all symbols in the library.
• TestFile.html is a simple HTML page that preloads assets, links libraries, instantiates the stage, and sets up the Ticker to run at the appropriate framerate.

This provides a quick way to preview the assets, while making it easy to link all of the assets into your own HTML files without having to edit the output.

The Toolkit also copies all necessary JavaScript libraries into the specified library directory (defaults to ./libs/ ). The Toolkit exports all images and sounds in the FLA into the appropriate directories (./images/ and ./sounds/).

If preview is checked, the panel launches the html file in the system's default browser.

Warnings are generated in the output panel for any unsupported features in your content when you publish.

CreateJS is a suite of open-source (MIT licensed) JavaScript libraries that make it easier to develop rich, interactive content for HTML5. The primary libraries that are used by the Toolkit are:

• EaselJS - provides a display list (similar to the Flash player), mouse interaction, and filter effects for the HTML5 canvas element. Used by the toolkit for displaying all graphics.
• TweenJS - a simple to use, but very powerful JavaScript tweening and animation library. All timeline animations published by the Toolkit use TweenJS.
• SoundJS - provides a plugin architecture for playing audio on the web. SoundJS allows you to play sound via a simple API using HTML5 Audio tags, WebAudio, or Flash Player. SoundJS is the default library for playing sound from the Toolkit, but is easy to override by modifying the window.playSound method in the published HTML.
• PreloadJS - instantiable load queues that use XHR2 (when available) or standard HTML tags. Provides smooth progress, and a robust event model. Used by default for loading assets in the HTML published by toolkit, but can be easily changed.

To learn more about CreateJS, including demos and in-depth API documentation, visit the CreateJS website.

Your FLA's library is published to a JavaScript file as reusable classes within a configurable lib namespace. Toolkit supports bitmap symbols and timeline symbols. The latter are any type of symbol that has a timeline. In other words, the Toolkit attempts to publish MovieClip, Graphic, and Button symbols. Your FLA stage is also published as an instantiable class.

Similar to publishing to SWF, only symbols in use (referenced from the stage) or set to Export for ActionScript are included in the generated JavaScript library.

JavaScript class names are based on the AS3 class name set on the library item, or on the library name if a class name is not set.

Within your JavaScript, you can instantiate and work with these symbols in a manner similar to ActionScript:

Bitmaps and sounds are automatically copied to your output directory.

Symbols also have a nominalBounds property appended with a rectangle specifying the pixel bounds of the untransformed symbol. If you enable the multiframe bounds setting, then timeline symbols also have a frameBounds property containing an array of bounds corresponding to each frame in the timeline.

Note: Including multiframe bounds significantly increases publish time.

There are a number of restrictions to the type of timeline animations that can be published.

The extension does not currently support certain advanced features such as custom easing curves, or inverse kinematics. New (non-classic) motion tweens and shape tweens are supported, but are collapsed into frame by frame animations.

In comparison, classic tweens are maintained as runtime tweens, which makes them have a very small file size, and allows them to be manipulated through code. Note however, that any layer with a classic tween can only have a single symbol instance on it. It cannot have mixed content, and it must be an instance of the same library item for the full duration of the layer (though it can have empty frames).

Layers without classic tweens can contain any content supported by the extension (text, bitmaps, groups, vector graphics, symbols). Elements in these layers are reused between keyframes if their names match.

Toolkit supports classic tweens of most properties with simple eases (ease in/out), shape tweens (collapsed), motion tweens (collapsed), graphic instances, labels, and js scripting (see below).

It also supports mask layers with some restrictions. The mask layer cannot contain symbol instances, bitmaps or text; only vector shapes are supported. Shape tweens and keyframes are supported to allow animated masks.

Some shape-based IK animations will publish correctly, but this is an unsupported feature.

JavaScript code can be added to your timeline on a keyframe using the ActionScript panel, with the following comment format:

Published MovieClip symbols expose methods to control the timeline, similar to ActionScript.

JavaScript does not use this as an implicit scope like ActionScript 3, so you must specify your scope in any timeline scripts. For example:

Note: Unlike Flash, which starts frame indexes at 1, EaselJS timelines begin at 0. This difference in indexing requires you to subtract 1 from the frame indexes displayed in Flash Professional. For example, gotoAndPlay(0) moves the playhead to the first frame of the movie clip in EaselJS, which is labeled as frame 1 in Flash Pro.

Toolkit for CreateJS supports the following instance properties for all instances:

• Alpha
• X
• Y
• Rotation
• scaleX
• scaleY
• skewX
• skewY
• visible

Both Text and MovieClip instances support:

• shadow
• glow filters (not recommended due to performance concerns in canvas)

For symbol instances, the Toolkit also supports:

• cacheAsBitmap (translated into a cache() call)
• the "add" blend mode
• graphic mode properties (loop, play once, single frame, and first frame).

Note: Unlike Flash, EaselJS does not automatically update the cache on animated content. If you cache a MovieClip instance, the animation does not update properly without additional scripting.

Toolkit does not currently support color transforms, 3D transformations, or additional filters.

MovieClip, Graphic, and Button symbols with more than one frame are all published as EaselJS MovieClips with timelines. Symbols with only one frame are published as EaselJS Containers.

Buttons are published with full interactivity. Note that in some browsers content with both buttons and bitmaps may throw security errors due to restrictions in accessing local content. Test with another browser, or using a web server.
MovieClip instances behave as Graphic or Button instances based on the instance properties. There is no separate symbol types for Button or Graphic in the exported content.

For Text, the following properties are supported:

• text
• line height
• font
• font size
• color
• justification (left, right, center)
• bold
• italic

Note: multiline text may display unexpectedly. It's generally recommended to display text via HTML and CSS layered over the canvas content where possible. The DOMElement class in EaselJS can assist with this.

TLF text fields are published, but none of the advanced features of TLF are supported.

Most vector art publishes correctly. Currently, oval (non-circular) radial gradients are not supported. Likewise, bitmap (also know as pattern) fills do not support transforms on the fill. You may also see differences in stroke widths on shapes that have been scaled, or that use sub-pixel stroke sizes.

It is generally recommended that you optimize your shapes (Modify > Shape > Optimize), especially on content imported from other tools (for example, Illustrator). Optimizing significantly decreases publish time and file size.

For vector based animations, it is recommended that you tween symbols containing vector art (for example, tweening a leg symbol) rather than redrawing vectors every frame. Tweening symbols with vector art achieves smaller file sizes and faster publish times. See the sample FLA for an example of this technique.

Sounds are exported from the library, and timeline sounds are supported, including looping or repeating sounds. Sounds are exported as MP3s.

MP3 sound files are not supported in all browsers. You can manually add ogg sound files for broader support.

Sounds are limited by the restrictions on audio in the browser. See the SoundJS documentation for more details.

Toolkit makes no distinction between stream, start, and event sounds. It does not support the Stop sync action or sound effects. It does support the loop and repeat count settings.

Images are also exported from your library in either JPG or PNG32 format. Toolkit for CreateJS uses JPG unless the image has transparency, or you have set its compression type to lossless (and the original source was not a JPG). The toolkit uses the quality setting specified in the properties dialog for each image for JPGs.

This is a brief overview of each control on the Panel (top-to-bottom).

Toolkit settings

• Publish - publishes the frontmost FLA for CreateJS.
• Preview - if checked, attempts to open the HTML in your default browser when publishing is complete.
• Help (?) - launches online help for the panel in your default browser.

Timeline Settings

• Loop - if checked the timeline loops, if not it stops when it plays to the end.

Publish Settings

• Output - the directory where the FLA is published. Click the arrow button to the right to open the directory in your OS's file browser.

Edit Settings

• Opens the Settings dialog

The settings dialog allows you to edit preferences for how the current FLA will be published. Here is an overview of the available settings:

• Output - the directory the FLA will be published to. This defaults to the same directory as the FLA, but can be changed with the browse button "..."
  
• Publish HTML - if unchecked, the HTML file is not generated. If preview is checked, it still attempts to open the HTML file if it exists. This can be useful to prevent a modified HTML file from being overwritten.
• Asset Paths - the relative URLs to export images, sounds, and supporting CreateJS JavaScript libraries to. If the check box to the right is not checked, those assets are not exported from the FLA, but the specified path is still used to assemble their URLS. This can speed up publishing from an FLA with a lot of media assets, or avoid overwriting modified JavaScript libraries.
• JS Namespaces - the namespace in which symbols, images, and the CreateJS libraries will be placed into and referenced from.
• Hosted libs - if checked, this uses copies of the libraries hosted on the CreateJS CDN at code.createjs.com. This allows the libraries to be cached and shared between various sites.
• Include hidden layers - if unchecked, hidden layers are not included in the output.
• Compact shapes - if checked, vector instructions are outputted in a compact form. Uncheck to export readable, verbose instructions (useful for learning purposes).
• Multiframe bounds - if checked, timeline symbols include a frameBounds property containing an array of Rectangles corresponding to the bounds of each frame in the timeline. Note that including multiframe bounds significantly increases publish time.

To get started with an example, read Getting Started with the Flash Professional Toolkit for CreateJS.

For more information and documentation on Toolkit for CreateJS, visit the Adobe Developer Connection.

For more information and documentation on the CreateJS libraries, visit the CreateJS website.