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 > Other Panels > 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, classic 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/ ) if they do not already exist. 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 library is published to a JavaScript file as reusable classes within a 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.

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

The extension does not currently support advanced features such as custom easing curves, new-style motion tweens (only classic motion tweens), inverse kinematics, masks, motion guides, or shape tweens.

Further, any layer with a 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 you can have empty frames).

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

The Toolkit supports classic tweens, simple easing (ease in and out), graphic instances, tweening most properties, labels, and JavaScript scripting (see below).

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

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 without any interactivity as pure movie clips. Interactivity (for example, button states) currently must be added separately via code.

MovieClip instances behave as Graphic instances based on the instance properties (.mode, .loop, and .startPosition). There is no separate Graphic type.

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.

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.

If you do experience issues with vector output, try selecting the shape, and choosing Break Apart from the Modify menu.

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.

Note: Flash Pro has limitations on which sounds can be exported. See the "Sound Export Problems" section below for more details.

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. For example, sound on iOS is extremely limited. 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.

Flash Pro imposes some limitations on what sounds properly export from the FLA. We hope to address these limitations in a future version of Toolkit.

If you are seeing error messages when exporting sounds, try the following:

1. Make sure the sounds you import into your FLA are MP3s and are encoded at 160kbps or less.
2. Try removing the MP3 metadata. You can do this using the Adobe Media Encoder application that is installed with Flash Professional.

• To set the remove metadata option:
  • launch Adobe Media Encoder
  • open the Preferences dialog
  • click on the metadata item on the left side of the dialog
  • set the Export Options menu to "None"
  • set the Preservation Rules menu to "Exclude All"
  • click OK to close the preferences dialog
• To process individual WAV and MP3 files:
  • click the Add Source button in the main AME window
  • select an MP3 or WAV file from the open file dialog
  • now the sound file is in the queue
  • change the drop-down that says F4V to MP3 - this is your output format
  • choose the output bit rate (160kbps or less)
  • click the green "run" button

Import the new sound into your FLA and replace or delete the original sound.

3. If you are still encountering problems, simply rename your source files according to the names in the error messages, and move them into the sounds directory manually. Then, uncheck the sounds option in the panel to prevent it from generating errors.

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.

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. This defaults to the same directory as the FLA, but can be changed with the browse button "..."
• Images, Sounds, JavaScript libraries - the relative URLs to export images, sounds, and supporting JavaScript libraries to. If the checkbox to the right is not checked, images are not be exported from the FLA, but the specified path is still used to assemble image URLS. This can be used speed up publishing from an FLA with lots of media, or to avoid overwriting modified JavaScript libraries.
• 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.
• Include hidden layers - if unchecked hidden layers are not be 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).
• Hosted libraries - if checked, the output uses copies of the libraries hosted on the CreateJS CDN at code.createjs.com. Hosting allows the libraries to be cached and shared between various sites.

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.