easeljs

This week we finally had the new release of CreateJS, with a lot of changes, starting with the new site and new visual identity! All libraries (EaselJS, PreloadJS, TweenJS and SoundJS) have major updates that improve performance and the architecture.

Some important updates:

New class model with performance improvements:

In the old CreateJS, attributes were defined in the classes prototypes. By moving the definition from prototype to instance, EaselJS could decreases the canvas update time (by stage.update) in more than 2 times (a 100%-150% improvement).

The tick propagation was also improved with a small change: the tick event is reused for all display objects through the propagation of the tick, i.e., the tick event is instantiated only a single time. By avoiding redundant instantiation, the tick propagation has also an improvement of ~100%.

See:

New inheritance model

The inheritance model were updated following the modification of the class model. Now, if you want to inherit some class in CreateJS, you need to use createjs.extend and createjs.promote.

The createjs.extend function set up the prototype and constructor of a new class. The code is pretty simple:

createjs.extend = function(subclass, superclass) {
    function o() { this.constructor = subclass; }
    o.prototype = superclass.prototype;
    return (subclass.prototype = new o());
}

 and this function must be called right after the creation of the new class constructor.

The createjs.promote back up the superclass methods that were overridden. For example, if you create a FlexibleBitmap inheriting from Bitmap and override the method draw, createjs.promote back up the method bitmap draw by creating an alias Bitmap_draw inside the new FlexibleBitmap.

See:

All classes now implement properties for getters and setters

Some changes are pretty straightforward, e.g., Container.getNumChildren() is now replaced by Container.numChildren; but some names have been updated too, e.g., Ticker.getFPS() is now Ticker.framerate. Using properties instead of getters and setters is a good practice, nice to see that on CreateJS.

See:

Other updates

See https://github.com/CreateJS/EaselJS/blob/master/VERSIONS.txt for a full list of changes.

Read more

This week I made some contributions to EaselJS project. These contributions were simple pull requests to the official repository, but I’ve never did such things on Github or other version control systems, so it was a bit confusing. This post just register the steps I took to do this.

1. Create a fork of the project you want to contribute. This can be made on github interface:

github_fork

2. Clone the forked repository, for example:

git clone git@github.com:<username>/EaselJS.git

3. Create a new branch to make the changes. A branch is an isolated version of the project which will contain all modifications you made.

git checkout -b <branch_name>

4. Make the changes and commit it:

git add -A

git commit -m “<description>”

5. Push the changes to your forked project:

git push origin <branch_name>

6. Pull request the branch to the official repository. In the Github interface, all branches will created will be highlighted on the page of the forked repository together with a “Pull Request” button. Just press this button and send it.

You can send multiple pull requests, just adding new branches.

Read more

EaselJS is a Javascript library that allows the programmer to work on html canvas in an easy way. It means that EaselJS abstracts the low level API of the canvas element and provides classes, structures and functions to manipulate visual elements.

Before starting the examples and the talk about the Easel modules, let’s set up the html file which will be used as basis throughout this post. Create a file called easel.html and copy the following code:

<!DOCTYPE html>
<html>
<head>

<script src="http://code.createjs.com/easeljs-0.7.1.min.js"></script>

<script>
    function init() {
        var canvas = document.getElementById('canvas')
        var stage = new createjs.Stage(canvas);
        // CODE HERE!
    }
</script>
</head>
<body onLoad="init();">

<canvas id="canvas" width="600" height="300">alternate content</canvas>

</body>
</html>

 The Basics

EaselJS provides a whole architecture to control the objects that will be used at our games. The following list explains a bit of each one of the core components of this architecture.

  • EventDispatcher: the EventDispatcher class provides the structure for managing queues of events listeners and dispatching events. All components of EaselJS inherit from this class, thus, any component can handle events such as mouse clicks, drags, etc. For example, you can register a callback function to the ‘click’ event of a Bitmap object, causing the callback to be called whenever the user clicks that Bitmap.
  • DisplayObject: is the base class for all visual element, exposing properties such as position, rotation, scale and transparency. It means that, you can manipulate the position, rotation and other display properties of any object that draws something at the screen.
  • Container: The Container inherit from DisplayObject and provides methods to group other DisplayObjects. Using Containers, you can create hierarchy of visual objects and manipulate them together. For example, if you have a container within 3 images and move the container to the left, all the three images will be moved to the left too.
  • Stage: the Stage is the root level of the DisplayObject hierarchy, thus, if you want to show an object in canvas you need to add this object to the stage.

After adding objects to stage, you need to call the stage “update” method, otherwise the canvas will be redraw and you won’t see any change. All examples below show how to use it.

Working with Shapes

A Shape object stores a group of vector graphics that are created directly by the canvas element. Each shape has a Graphics instance which is the interface to the canvas drawing system. Check the example below.

var shape = new createjs.Shape();
shape.graphics.beginFill('#99f');
shape.graphics.drawRect(0, 0, canvas.width, canvas.height);

shape.graphics.beginFill('#33f');
shape.graphics.beginStroke('black');
shape.graphics.drawCircle(canvas.width/2, canvas.height/2, 50);

stage.addChild(shape);
stage.update();

Notice how the graphics instance does the hard work. The beginFill function sets the filling color for the next drawings while beginStroke sets the stroke color. The Graphics object provides several functions for the drawing itself, take a look at the official documentation to see how drawRect, drawCircle and other directives work.

Working with Texts

With Text objects you can draw… texts! But just plain texts, not HTML-formatted ones. EaselJS allows you to change the color, alignment, size, font, wrapping and others settings of Text objects, check the official documentation to know more:

var text = new createjs.Text('Hello, World!', '32px Arial', '#53f');
text.textAlign = 'center';
text.x = canvas.width/2;
text.y = canvas.height/2;

stage.addChild(text);
stage.update();

Working with Bitmaps

With Bitmap objects you can display an image, canvas or video (the HTML elements) into the canvas. You can instantiate the Bitmap object using the HTML element explicitly or passing a string, as shown in the example. Notice that, the first lines of the code below is a bit different from the examples above, that is because I am using a external resource (the image ‘assets/html5.png’) and we can use it before the browser totally load it. This process is automated by PreloadJS.

img = new Image();
img.src = 'assets/html5.png';
img.onload = function(event) {
    var bitmap = new createjs.Bitmap('assets/html5.png');
    bitmap.x = canvas.width/2 - bitmap.image.width/2;
    bitmap.y = canvas.height/2 - bitmap.image.width/2;

   stage.addChild(bitmap);
   stage.update();
}

Consult the documentation to know more about bitmaps:

 Working with SpriteSheets

A sprite sheet is a group of several images combined into a single larger file, e.g.:Bubbles Sprite SheetYou can also define animations using sprite sheets as shown in the example.

EaselJS provides the SpriteSheet class to handle this kind of image.  The SpriteSheet object requires some configuration to work, such as the size of each frame and the sequence of animations, check the documentation for a detailed description of each property:

img = new Image();
img.src = 'http://static.guineashots.com/tutorials/easeljs/assets/bubbles.png';
img.onload = function(event) {
    var data = {
        framerate: 10,
        images: [img],
        frames: {width:64, height:64, regX:32, regY:32},
        animations: {
            'explode': [0, 10],
        }
    }

    var spritesheet = new createjs.SpriteSheet(data);
    var animation = new createjs.Sprite(spritesheet, 'explode');
    animation.x = canvas.width/2;
    animation.y = canvas.height/2;

    stage.addChild(animation);

    createjs.Ticker.addEventListener("tick", update);
    function update(event) {
        stage.update();
    }
}

The SpriteSheet only represents the sequence of images, to see them as isolated images or animations you need a Sprite.

Notice that, in the last lines of example, I register a function “update” to the “tick” event, so it will be called every frame by Easel. In this function I call the stage update so it can redraw the canvas and show each frame of our animation.

Other Tutorials

To learn more about EaselJS, follow the official tutorials:

Read more