Type annotations for the CreateJS Toolkit

imageDo you really know CreateJS?

Many people have heard about it, but I often find out that they don’t really know what CreateJS is, what it can do, and why it can really help developing expressive websites in HTML5 today.

Believe me, it’s a topic worth digging!


What is CreateJS?

CreateJS, not to be confused with CreateJS Toolkit, is a solid set of JavaScript libraries developed by Grant Skinner. His great Flash experience led him to design the libraries so that they will be immediately familiar to Flash developers.

It features:

  • EaselJS: provides a Flash-like display list for the HTML5 Canvas,
  • TweenJS: animation engine obviously,
  • PreloadJS: assets loading made simple,
  • SoundJS: any idea?

What is the CreateJS Toolkit?

The CreateJS Toolkit for Adobe Flash Professional (that’s its actual full name) is an extension for Flash Professional (surprise) which can be installed in Flash Pro CS6 and which will be included in Flash Pro CC by default.

This extension is able to generate an HTML5 version from your FLA thanks to the CreateJS libraries.

Really, it’s able to convert most Flash features into code; there are a few important limitations that make it look broken if not used with care. So read carefully Grant’s presentation linked above!

Technically it generates:

  • one HTML page, to setup the animation and the preloader,
  • one JavaScript file, to define all your FLA library symbols as JavaScript code leveraging the CreateJS libraries,
  • and all your images and sound medias which will be loaded at run time.

What about Edge Animate, Reflow,…?

One may wonder if Adobe Edge tools and this Flash Pro toolkit compete for the same job. Think of them as complementary tools:

  • Edge Animate and Reflow are tools designed to work with the DOM,

  • The Toolkits for CreateJS helps you work with one DOM element: the Canvas.

A modern website will combine the best of the possibilities offered by the DOM and the Canvas. You don’t want to make complex layouts or text-heavy contents using the Canvas when the DOM will do a much better job.

Understanding the HTML5 Canvas

In an HTML page, a Canvas behaves exactly like a (transparent) image. It can be positioned and animated like any HTML image. You can create as many Canvases as you want.

The Canvas can have different rendering modes – the most widely supported with about 90% penetration (IE9+ and all other desktop and mobile browsers) is the “2D context” which is actually now hardware accelerated in most cases and offer great performances in general (IE9+ Canvas in particular is very good). The “webGl context” is also quite popular, but its penetration is considerably more limited.

The 2D context is quite capable with vectors and bitmaps, but it’s a bit complex and it has some limitations:

  • it exposes a low level API, inspired by openGl; in practice it feels a bit like drawing in a BitmapData with a fancy way to build matrix transformations,
  • complex vectors can be very heavy on the CPU as they are entirely declared in code,
  • text support is very basic,
  • filters are limited to a “shadow” which can be used for drop-shadows and glows; also they are not consistently accelerated (filters are relatively slow on IE9/10),
  • composition (“blend mode”) is limited; in practice you can only use normal or additive blending.

The Canvas API being relatively low-level it can become quite complex to create elaborated scenes as you are likely to have to re-invent a display list, animation system and caching for good performance – this is why numerous libraries, like CreateJS, have appeared to simplify and optimize the way you work with the Canvas.

“I don’t want to code in JavaScript”

I actually like coding in JavaScript – but I don’t like to code complex applications in JavaScript.

If you think about ActionScript3 in comparison, with its handy class system and type annotations, you quickly regret the great tooling you had access to, with almighty code completion and refactoring.

Thankfully, there are a few solutions, all free and open source, that compile to JavaScript if you want classes and explicit types. I can recommend any of these three wholeheartedly.

Typescript

Typescript is a typed superset of JavaScript that compiles to plain and nice JavaScript.

If you appreciate JavaScript you will probably find it the most elegant and less alienating solution: it adds modules, classes, type annotations, generics,.. on top of vanilla JavaScript.

It doesn’t however solve any of the famous JavaScript quirks, except you don’t have to deal with the prototype.

Typescript is already quite popular, but still very young: it was published in 2012 by Microsoft, and is more precisely led by Anders Hejlsberg of Turbo Pascal, Delphi and C# fame (my hero). It has a growsing toolking support, starting with the official Visual Studio extension (even the free Express edition), IntelliJ Ultimate, and you can get something usable with Sublime Text 2.

Haxe

The Haxe language is similar to ActionScript3 but a lot richer (enums, generics) and with a lightning fast and very powerful compiler (strict type inference, functions inlining, dead code elimination).

Haxe language has many “targets”: JavaScript, Flash, PHP, C++, Neko, C#, Java,… Haxe provides a core API and a target-specific API.

Haxe was created in 2006 as a successor of MTASC, the free open source ActionScript2 compiler that revolutionized Flash development. There are a few IDEs and editors that very nicely support Haxe JS: FlashDevelop, IntelliJ Ultimate, Sublime Text 2,…

Dart

Dart is a class-based language for the web, designed to be easy to learn. Like Typescript it adds classes and type annotations, and like Haxe it very strictly enforces classes. See my Adventures in Dart Land.

It was actually designed by Google’s V8 JavaScript engine creators to solve scripting performance in the browser. One key solution is to make object structures immutable so the browser JavaScript engines can optimally optimize the code execution.

Dart was announced about 2 years ago and is near v1.0. The Dart Editor (Eclipse based) is quite good (and free), featuring a very good type inference to identify errors, code completion, and a growing number of refactoring actions; but you can try IntelliJ’s Dart support too.

How to use CreateJS with these languages?

For Dart it’s a bit complicated – forget it for CreateJS, but Adobe will soon release the Toolkit for Dart which will do a similar job, but generating Dart code leveraging the StageXL Dart library. Stay tuned, I’m proud of it!

For Typescript and Haxe: both languages have “definitions” which offer a fully typed way to work with the CreateJS libraries. In both cases it is very easy to use the libraries and you can easily find samples and demos to quickly get started.

Typescript hint: use the Typescript Definitions Manager to add (easeljs, tweenjs, preloadjs, soundjs) definitions to your projects.

Haxe hint: CreateJS externs are on haxelib (haxelib install createjs).

But…

Remember, the CreateJS Toolkit generates a JavaScript file with your FLA library symbols declared as code: you don’t have definitions for these elements… until now!

Introducing the CreateJS Definitions Generator

I’ve written a tool, createjs-def, which can generate the appropriate definition file from what the CreateJS Toolkit outputs.

It supports Haxe and Typescript, but it could easily be extended to other languages (like Jangaroo’s or Randori’s AS3 but they don’t have CreateJS libraries definitions yet).

The tool is available:

  • as simple JSFL scripts that work automatically,
  • as a node.js command line tool.

Sources and instructions:

Get createjs-def on github!

Demo 🙂

(an animation by Chris Georgenes)

Get this Haxe-based demo sources here.

13 thoughts on “Type annotations for the CreateJS Toolkit

  1. thanks for the compressed information on the subject, but the demo doesn’t work on firefox 21.0 in OSX. bit of a show stopper.. 😉

  2. @karl
    This is strange as it works here in Firefox 19 and 21 on OSX.

  3. Does this work with Flash CC and a HTML5 project?
    I don’t know what to do with the Generate Typescript Definitions.jsfl or Generate Haxe Definitions.jsfl.

    I put them on the folder C:\Users\username\AppData\Local\Adobe\Flash CC\language\Configuration\

    and exported from Fash. If I run the file I only see on Flash CC on the output console “No CreateJS export data”.

    Need some help on this… =/

  4. @croxover you must first use the CreateJS Toolkit to export the JS files, then the JSFLs can take that to generate definitions for Haxe/Typescript.

    However, I didn’t test with the new Flash CC release where CreateJS Toolkit is fully integrated as the HTML5 document format… I’m not sure it generates the same metadata that these JSFLs support.
    In the meantime, if it doesn’t work, you should give a try to the downloadable extention which possibly should work with either AS3 and JS Flash documents:
    http://www.adobe.com/devnet/createjs/articles/getting-started.html

  5. Thank you Philippe for your fast reply…

    I managed to get this working using a trail version of Flash CS6. I created a new CS6 project and then exported using createjs toolkit 1.2 and run your script using: commands -> run command… -> *select Generate Typescript Definitions.jsfl.

    This generated the definitions. =)

    But this doesn’t work on Flash CC at least I can’t put it to work.
    Now you can not use the toolkit on CC. CC had an update where you create a HTML5 project (createjs on the background I think). The final js outputs are different…

    I will try to use the definitions… I’m afraid something may be broken (I’m using typescript 1.0, createjs 0.7.1). I will just let you now.

    Thank you for or support.

  6. @croxover sounds like the script has to be updated – it definitely worked with Flash CC until they pushed the new HTML5 documents…

  7. yeps… I’m getting problems =(

    don’t know exactly what, but I get errors when trying to create an instance of the export.

    this.myFlashStage = new Flash.FlashStage();

    Unhandled exception at line 12, column 21703 in http://localhost:2479/js/easeljs-0.7.1.min.js

    0x800a139e – JavaScript runtime error: TypeMismatchError

  8. @croxover well an old toolkit won’t generate something compatible with the latest version of CreateJS.

    I looked at the new HTML5 FLAs and the problem is that the metadata that the toolkit is using doesn’t exist anymore – the needed info now should be extracted from the publish settings. That’s probably all that is needed to change here.

  9. I created a simple definition just to see things on the screen:

    Something like:

    declare module Flash
    {
    export class FlashStage extends createjs.MovieClip
    {
    constructor();
    }

    var Properties: { manifest: string[] };
    }

    But can’t access the symbols inside. I think I need to create a reference to all of then right?
    In this project I have more than 250 symbols. It’s a real bummer to map all the references.
    Is it difficult to fix the script? I hope you can find a solution. Thank you for your effort.

  10. @croxover
    – I fixed the JSFLs to support the new HTML5 file format
    – the definitions only serve for compilation/completion purpose; you must reference the JS that Flash outputs. I suggest you look at my sample in bin/index.html.

  11. hahahaha thank you so much!
    it works!! =D

    Just exported the project on CC and executed your script, et voila…

    “Definitions file for typescript was generated successfuly” =D

    ///
    class FlashStageScreen extends Flash.FlashStage
    {
    private canvas: HTMLCanvasElement;

    constructor(canvas: HTMLCanvasElement)
    {
    super();

    this.canvas = canvas;
    this.mySymbol.on(“click”, this.onMouseClick);
    this.mySymbol.name = “router wifi”;
    }

    private onMouseClick(evt: createjs.MouseEvent): void
    {
    alert(“click = ” + evt.target);
    }
    }

  12. Pingback: The Big List of HTML5 Game Tutorials | Game Venture

Leave a Reply

Your email address will not be published. Required fields are marked *