createjs / easeljs

The Easel Javascript library provides a full, hierarchical display list, a core interaction model, and helper classes to make working with the HTML5 Canvas element much easier.

EaselJS

EaselJS is a library for building high-performance interactive 2D content in HTML5. It provides a feature-rich display list to allow you to manipulate and animate graphics. It also provides a robust interactive model for mouse and touch interactions.

It is excellent for building games, generative art, ads, data visualization, and other highly graphical experiences. It works well alone, or with the rest of the CreateJS suite: SoundJS, PreloadJS, and TweenJS.

It has no external dependencies, and should be compatible with virtually any framework you enjoy using.

Simple Example

//Draw a square on screen.
var stage = new createjs.Stage('myCanvas');
var shape = new createjs.Shape();
shape.graphics.beginFill('red').drawRect(0, 0, 120, 120);
stage.addChild(shape);
stage.update();

Sprite Animation Example

var ss = new createjs.SpriteSheet({
	frames: {
		width: 32,
		height: 64,
		numFrames: 19
	},
	animations: {run: [0, 25], jump: [26, 63, "run"]},
	images: ["./assets/runningGrant.png"]
});
	
var sprite = new createjs.Sprite(ss, "run");
sprite.scaleY = sprite.scaleX = 0.4;
stage.addChild(sprite);
	
sprite.on("click", function() { sprite.gotoAndPlay("jump"); });
	
createjs.Ticker.on("tick", stage);

Support and Resources

• Find examples and more information at the EaselJS web site.
• Read the documentation.
• Discuss, share projects, and interact with other users on reddit.
• Ask technical questions on Stack Overflow.
• File verified bugs or formal feature requests using Issues on GitHub.
• There is a Google Group for discussions and support.
• Have a look at the included examples and API documentation for more in-depth information.

It was built by gskinner.com, and is released for free under the MIT license, which means you can use it for almost any purpose (including commercial projects). We appreciate credit where possible, but it is not a requirement.

Classes

The API is inspired in part by Flash's display list, and should be easy to pick up for both JS and AS3 developers. Check out the docs for more information.

DisplayObject Abstract base class for all display elements in EaselJS. Exposes all of the display properties (ex. x, y, rotation, scaleX, scaleY, skewX, skewY, alpha, shadow, etc) that are common to all display objects.

Stage The root level display container for display elements. Each time tick() is called on Stage, it will update and render the display list to its associated canvas.

Container A nestable display container, which lets you aggregate display objects and manipulate them as a group.

Bitmap Draws an image, video or canvas to the canvas according to its display properties.

Sprite Displays single frames or animations from sprite sheets, and provides APIs for managing playback and sequencing.

Shape Renders a Graphics object within the context of the display list.

Graphics Provides an easy to use API for drawing vector data. Can be used with Shape, or completely stand alone.

Text Renders a single line of text to the stage.

BitmapText Renders text using a SpriteSheet of letter.

DOMElement An experimental display object that allows you to manage an HTML element as a part of the display list.

Filter The base filter class that other filters (ex. BlurFilter, ColorMatrixFilter, etc) extend.

There are also a few helper classes included:

Shadow Defines all of the properties needed to display a shadow on a display object.

Ticker Provides a pausable centralized tick manager for ticking Stage instances or other time based code.

UID Very simple class that provides global, incremental unique numeric IDs.

SpriteSheet Encapsulates all the data associated with a sprite sheet to be used with Sprite.

SpriteSheetUtils Contains utility methods for extending existing sprite sheets with flipped frames and extracting individual frames.

SpriteSheetBuilder Build a bitmap SpriteSheet from vector graphics at run time. Get the filesize savings of vector, with the performance of a SpriteSheet.

Matrix2D Represents a 3x3 affine transformation matrix. Used internally for calculating concatenated transformations.

Rectangle Represents a rectangle as defined by the points (x, y) and (x+width, y+height).

Point Represents a point on a 2 dimensional x / y coordinate system.

A WebGL implementation currently exists, but is limited.

StageGL A drop-in replacement for the EaselJS Stage class that fully supports a WebGL pipeline. StageGL will draw most Bitmap- based content, including any cached DisplayObjects.

WebGLInspector A utility and helper class designed to work with StageGL to help investigate and test performance or display problems.

easeljs's Issues

Create Performance Test Suite

We need to create a performance test suite, and tests for EaselJS. This will allow us to bench mark performance (code and rendering), and help provide us a performance baseline when making future changes.

SpriteSheetUtils.js error in Firefox 3.6.13

on line 131...
Security error code: 1000
img.src = canvas.toDataURL("image/png");

Add stage.toImage API to Stage

Add a stage.toImage API to Stage:

stage.toImage(imageType, backgroundColor);

imageType defaults to" image/png"
backgroundColor will default to transparent. It can take any valid HTML color, including HEX and rgb and rgba.

Thought about going to Google Closure?

I've used it a bunch for the box2d work we've done at Pixel Lab.

Not only do you get amazing compression, but it's wonderful at finding bugs and tightening up documentation.

https://github.com/thinkpixellab/box2dWeb

I didn't see a discussion forum for Easel, so my apologies for opening an issue.

Z-index

There is no way to control z-index now (beside removing and adding everything in the right order). It would be nice to have control over the z-index conceptual property in a concrete and easy way.

Add Support for DisplayObject filters

We should look at adding support for display object filters such as Blur, ColorMatrix, Convolution, etc...

Graphics.rect not pixel precise

When I draw a rectangle using Graphics.rect(0, 0, 100, 100); the resulting rectangle on screen is not 100 x 100 but 99 x 100 pixel in size.

I tried this with EaselJS 0.3.2 in Firefox 4, IE9 and Opera 11 on Windows Vista 64 Bit.

A minimalistic test case is here: https://gist.github.com/1008837

BitmapSequence behind Bitmap flickers

Hi, everone.

First of all i'd like to say excelent job to gSkiner for this great library.

I'm having a problem doing the following:
I have a bitmapSequence object and a Bitmap on scene.
The bitmapSequence has a callback function that keeps the walking animation loooping.
When i add the Bitmap first and the sequence later there is no problem (like a background).
When i add the sequence first and the bitmap later, every time the animation ends there is a flicker and the bitmap and sequence get drawn again side by side (the sequence next to the bitmap) then at the next frame is all normal.

Any help would be apreciated.

Using a global Easel object (module pattern)

Use the module pattern (http://www.yuiblog.com/blog/2007/06/12/module-pattern/) to have a single global object (EASEL).

computeSpectrum support

I know this might not be part of easeljs, but i think if we could have a flash wrapped computeSpectrum.

I have just used your VolumeData.js, really useful. Not sure if you can open source the AIR file and extend it with more sound audio methods.

Stage.getBounds

We should think about adding a Stage.getBounds API, that returns a Rectangle.

I thought we had this, but I cannot find it the docs.

BitmapSequence does not animate if there is no frameData

I have a SpriteSheet (created with Zoe), which contains an empty frameData object. I am trying to animate it in a BitmapSequence, by calling:

bmpSeq.gotoAndPlay(0);

This will display the first frame, but does not animate the sequence.

Here is the non-working example:

https://gist.github.com/844152

If if dont pass the empty frameData to the SpriteSheet constructor, then the animation animates as expected.

Here is the working example:

https://gist.github.com/844158

I think that regardless of the frameData, if I call gotoAndPlay and specify a frame, the animation should work.

Problem with Graphics.bezierCurveTo

Hello,

For a project using it, I found there is a typo in the Graphics.bezierCurveTo method ine the Version 0.3.2, at line 414 :
this._boundsQueue.push(new Command(this._bezierCurveToBounds, [_x, _y, cp1x, cp1y, cp2x, cp2y, x, y]));

should be :
this._boundsQueue.push(new Command(this._bezierCurveToBounds, [.this_x, .this_y, cp1x, cp1y, cp2x, cp2y, x, y]));

otherwise the browser throws an error. :)

Recursive Clone for containers

I solved the lack of recursive clone on container. I've uploaded on github's gist the patch:

• Coffeescritp version: https://gist.github.com/809538
• Its compiled (in JS) version: https://gist.github.com/809539

mousemove event is processed regardless of whether anything is listening for it

Stage.js

p._handleMouseMove = function(e) {
...
}

Place a console.log("_handleMouseMove") just inside the handler.

and then run any example and move the mouse over the canvas. _handleMouseMove repeatedly is called, even though nothing is listening for it. This can be very CPU intensive, and is a hit that every example takes regardless of whether it uses mouse events or mouse move events.

At a minimum, we should check whether mouseEventsEnabled is set to true, and if not, either short circuit, and exit out of the event handler, or (better) dont subscribe to the event at all.

Ideally, we will do a combination of:

• Only listen for event if mouseEventsEnabled is set to true
• Only listen for event if the callback has been set

Since the callback is a property, this might be difficult, and would probably require using a method to set the callback, as opposed to having external code set it directly.

We might be able to use Object.watch, but would probably have to implement some of it ourselves for cross browser compatibility:

https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/watch
http://stackoverflow.com/questions/1269633/javascript-watch-for-object-properties-changes
http://stackoverflow.com/questions/1269633/javascript-watch-for-object-properties-changes

Container::_testHit throwing

Container::_testHit throws an error on a "domain error" (when a pic loaded from other domain) making objectsUnderPoint fail completely.

But of course the Container can also have "good" children.

Maybe better to "fail silently" instead of throwing? Not sure cause the throw in itself is quite useful.

Rename MouseEvent

We may need to consider renaming the MouseEvent class to avoid collisions with the browser's native MouseEvent.

kevmoo did some work on this in a submitted patch:

https://github.com/kevmoo/EaselJS/commit/484e3037b398571bdece0980a7ff8bfa98ad76c3

Rename Tick to Ticker

Rename the Tick class, to Ticker. Ticker is more descriptive of what the class does.

Recommend making Text.textBaseline default to "top"

To behave more like a display object, I think textBaseline property of Text should be top. Currently, it uses "alphabetic", which is the standard for Canvas.

Scale and Registration Point

Hi,

When using scale on simple geometric figures, like rectangles, with the registration point on a non-zero position, the actual image is off by a factor equal to (scale - 1) * (dimension / 2). Weirdly enough, when using shapes and graphics, the scale actually changes the position, making it "move away" from the screen.

Edit: the graphics can only be seen when you use the drawRect at , instead of using the x,y position of the shape. As expected.

Edit2: The showcase on the comment below.

Text not displayed - Opera 11.01

Hello,

Try this page on Opera 11.01:

http://easeljs.com/examples/game/game.html

The texts are not displayed.

Document Timer / tick event timing

We should document when and the order that the tick event is called, both by Ticker, as well as by the Stage.

BitmapSequence starts on the wrong frame.

Because tick() happens before draw, the first frame displayed by BitmapSequence will always be one higher than expected. For example:
mySeq.gotoAndPlay(3);

The first frame to be drawn will actually be frame 4 because it will increment prior to the subsequent draw. We should revisit this for v0.4 - it's a complex issue if we want to maintain support for calling draw independent of the display list. It may require the addition of an exitTick event or similar.

Inline docs for Matrix2D indicate that skew isn't supported, but it does seem to be

The properties for Matrix2D have the following lines:

/** Position 0,1 in an affine transformation Matrix. Used in rotation (also skewing, but not supported in Easel). **/
p.b = 0;

But, further down there is an explicit skew method. I'm thinking this is just a documentation issues, but what, exactly, the property comments are saying isn't 100% clear. Personally I would drop the detailed comments and instead just reference what position in the matrix the letters correspond to. After all, if you're using those properties you probably know what you're doing with matrix math and thus those explanations just serve to confuse.

onMouseOver

One of the missing features is the implementation of onMouseOver and friends. What are your ideas of how to address it?

I understand that it is a big performance bottleneck to create mouse hit area test because canvas provides no built-in method for that.

I am aware that this issue can by addressed by creating multiple canvases and looking at pixel transparency or by using isPointInPath maybe. Both slow and not very versatile.

Ui.ajax.org seems to do something really clever layers functionality that enables onMouseOver: http://ui.ajax.org/#demos/elements.chart.2dpie Looking at the sources I do not understand how it works, though...

Rotating Container make adds blank space

I've uploaded an example here. It's worse on Google Chrome, as its canvas implementation has trouble with rotations.

Look at changing cache implementation to use get / putImageData

We should look at changing our internal caching implementation from using a separate canvas and drawImage, to using get / putImageData.

This is based on some of the performance research posted at:

http://dt.deviantart.com/blog/38471599/

I have pushed a new branched call "cache_test", in which I have changed the cache and draw apis for DisplayObject to use getImageData and pushImageData. Using the cache.html example included in the examples, I am seeing about 10 - 15% increase in performance, from 40 FPS using the current caching, to 45 - 47 FPS using putImageData.

You should be able to pull the new branch with:

git pull origin cache_test

The current branch is not production ready, as there is an issue where transparent pixels are being drawn as black, but I wanted to post it here to get some thoughts on whether this path is worth pursuing further.

Update:

I have been doing some more research on this, and Im not sure that get / putImageData is going to be flexible enough for us (at least for caching).

It appears that using putImageData will completely overwrite any pixels it replaces, as opposed to blending them as drawImage does:

http://dropshado.ws/post/1244700472/putimagedata-is-a-complete-jerk
https://processing-js.lighthouseapp.com/projects/41284/tickets/381-drawing-transparent-pixels-to-the-canvas-doesnt-preserve-underlying-canvas-color

Also, note that putImageData performance will probably change depending on the area of the graphic being cached. Im not sure if the same is true for drawImage.

Document that when extending Easel display classes you should explicitly call initialize()

If initialize is not explicitly called then all sorts of things go wonky due to the fact that initialize() is where the display classes setup their children array and get assigned their UID.

Rotating Bitmap on Chrome

I'm not sure why, but when I try to rotate a large bitmap on Chrome, the graphic appears to "jump" around. This does not happen in IE9RC or Firefox.

My repro is here:

http://www.wiredprairie.us/examples/easeljs/canvasdemo/

Is this just a Chrome issue with rotation?

Rotation and Registration Point

Hi,

I want to rotate a particular shape like rectangle, ellipse etc. around its center. To achieve this, I had set regX and regY to center of that shape. But it is shifting the shape. In detail, I did following things.

Suppose I am drawing ellipse as below :

newShape.graphics.drawEllipse(start.x, start.y, width, height);

newShape.regX = start.x + width / 2;
newShape.regY = start.y + height / 2;

then I am rotating this shape with button. Button Click event has following code

newShape = rotateCnt;
rotateCnt += 10;

This is actually shifting the shape and rotating it about (0, 0).
If I would not set regX & regY then shape will not be shifted but rotated about (0, 0)

DisplayObject.compositeOperation should default to "source-over"

Currently, DisplayObject.compositeOperation defaults to null, it should default to "source-over", which is the default value specified by the canvas specification:

http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#compositing

attribute DOMString globalCompositeOperation; // (default source-over)

There are a couple of reasons for this:

1. It ensures that the same globalCompositeOperation value is used across browsers, even if a specific browser uses a non-standard default
2. It ensures that outside code can access the correct value even if it has not been explicitly set.

I was going to make this change myself by setting:

p.compositeOperation = "source-over";

However, I noticed that updateCache is relying on the compositeOperation value being set to null to determine whether it should clear the current cache.

/**
* Redraws the display object to its cache. Calling updateCache without an active cache will throw an error.
* If compositeOperation is null the current cache will be cleared prior to drawing. Otherwise the display object
* will be drawn over the existing cache using the specified compositeOperation.
* @param compositeOperation The compositeOperation to use, or null to clear the cache and redraw it. <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#compositing">whatwg spec on compositing</a>.
*/
p.updateCache = function(compositeOperation) {
    if (this.cacheCanvas == null) { throw "cache() must be called before updateCache()"; }
    var ctx = this.cacheCanvas.getContext("2d");
    ctx.setTransform(1, 0, 0, 1, -this._cacheOffsetX, -this._cacheOffsetY);
    if (!compositeOperation) { ctx.clearRect(0, 0, this.cacheCanvas.width+1, this.cacheCanvas.height+1); }
    else { ctx.globalCompositeOperation = compositeOperation; }
    this.draw(ctx, true);
    if (compositeOperation) { ctx.globalCompositeOperation = "source-over"; }
}

One potential solution would be to add a static property:

DisplayObject.DEFAULT_COMPOSITE_OPERATION = "source-over";

and then set:

p.compositeOperation = DisplayObject.DEFAULT_COMPOSITE_OPERATION;

And then in updateCache change:

if (!compositeOperation) { ctx.clearRect(0, 0, this.cacheCanvas.width+1, this.cacheCanvas.height+1); }

to

if (compositeOperation == DisplayObject.DEFAULT_COMPOSITE_OPERATION) { ctx.clearRect(0, 0, this.cacheCanvas.width+1, this.cacheCanvas.height+1); }

However, this would make it difficult to differentiate between when the compositeOperation has been explicitly set (and thus when to clear the cache).

_testHit fails on IE9/FF4

The line

var hit = ctx.getImageData(0, 0, 1, 1).data[3] > 1;

in DisplayObject.js returns 255 in Chrome 12, but returns 0 in IE 9 and Firefox 4.

get value of an element

i can use scaleX to set value of a shape, but how can I get value of a shape?

Stage.update does not pass elapsed ms

Although the Stage.update method handily ticks everything on the stage it does not pass the elapsed ms in the same way that ticks directly from the Ticker do...

A little confusing when you are expecting ever tick method to receive this param.

Extend MouseEvent object

MouseEvent should contain more information from the original mouse event, like the button pressed and the modifier keys.

SpriteSheetUtils working canvas cache

There is an issue with some sort of browser caching happening on the working canvas in SpriteSheetUtils, this has manifested itself as graphics from a SpriteSheet attached to one Bitmap Sequence appearing in another Bitmap Sequence.

I have fixed this in my particular instance by recreating the workingCanvas every time. I am not sure why this is fixing it - but it is! I am hoping to put together a reproducible testcase for this so that a better solution can be found as it has many hours of frustration here.

Change documentation format from JSDoc to Yui Doc

Yui Doc provides much more flexibility for us.

This is currently in progress. More info here:

https://github.com/gskinner/EaselJS/wiki/Documentation

Simple AS3 Ported Gallery

K guys this isn't issue... yet! We are going to mock a simple as3 photo gallery. We won't worry about the model instead lets get the view and controller down first. So flash and math just put out a cool little photo gallery tut in which we are going to mock ( http://www.flashandmath.com/advanced/tweengal/ ) So now that we have idea of what we are going to build let get started. We will address each issue as it arises. The project can be found here git://github.com/Ba5ik7/EaselJS_AS3_Port.git

Links to source on the page

The links to source are incorrect. For example, on http://easeljs.com/docs/symbols/DisplayObject.html, the Defined in links to http://easeljs.com/docs/symbols/src/C__gskin_Projects_gitEasel_src_easeljs_display_DisplayObject.js.html

Follow JS best-practices for Graphics constructor

With regards to https://github.com/gskinner/EaselJS/blob/master/src/easeljs/display/Graphics.js#L136

Right now Graphics takes a string of Javascript and evaluates it later using
with (this) { eval(instructions); }

This is just gross -- with and eval are both constructs filed in the Use Extremely Sparingly folder. It seems like if instead of accepting a string for instructions, the constructor should accept a function instead, and then in p.initialize call instructions.call(this). It will have the same end result, but be faster, safer, and with more syntax highlighting in client code :)

Rename stage.tick to stage.update

We need to rename stage.tick to stage.update.

This will make it clear about what the API is doing (updating and rendering the stage), and help avoid confusion about the Ticker.tick event.

Container Interaction

From the documentation: "If an onClick handler is set on a container, it will receive the event if any of its children are clicked." However I tried this:
var startButton = new Container();
buttonBg = new Shape();
buttonBg.graphics.f("#A6A6A6").ss(1).s("#0F0").rr(55,55,55,25,5);
var label = new Text("Start", "16px Arial", "#000");
label.textAlign = "center";
label.x = 82;
label.y = 73;
label.maxWidth = 25;
label.alpha = 0.7;
startButton.addChild(buttonBg,label);
stage.addChild(startButton);
startButton.onClick = function(evt) { console.log("Start Pressed"); }

Nothing happened. But this worked:
buttonBg.onClick = function(evt) { console.log("Start Pressed"); }

Update build.bash file to generate jsdocs.

Ideally it would:

• build docs
• fix paths on "files.html" in docs (ie. delete "../../EaselJS/src/" or what have you)
• rewrite class files to use var p = Class.prototype; (this saves > 4kb in easel.js)
• run closure compiler to build easel.js
• revert class files to use Class.prototype (or alternately, do the reverse rewrite for jsdocs)

Graceful degradation for browsers that don't support canvas

I just started playing with EaselJS and I'm loving it. However, I was a bit surprised that when I opened up my test page in IE8 that EaselJS throws errors just including the library. I had expected that as long as I had a check like if(!document.createElement('canvas').getContext) and didn't try to use anything that the page wouldn't break, and I'd just show a friendly "Get a real browser" message ;-)

Is there an expected way to handle this fairly common use case? Internet Explorer 6, 7 and 8 still make up about 57% of the browser market. Conditional comments aren't a good idea, since feature testing is far more robust using scripts like Modernizr. It wouldn't be too hard to fix statements like these:

DisplayObject._hitTestContext = DisplayObject._hitTestCanvas.getContext("2d");
Text._workingContext = document.createElement("canvas").getContext("2d");
Ticker._listeners.indexOf

I'm willing to help out if this is something you'd like to address.

[Request] Support for textures

It seems possible to be doable using context clipping. Would be really nice to have.

Suggestion: move towards 'call'-based ctor/baseclass access model

Here's enough of a sample to get game.js working

https://github.com/kevmoo/EaselJS/commit/b7116839c2f6b194ccbce6ef2b3494f71b43396a

Upside: removes a lot of boiler plate while keeping functionality. Instead of creating aliases for baseclass methods, simple use the 'call' method.

I'm happy to own migrating existing code towards this model.

getObjectUnderPoint doesn't work on container

On version 0.2 worked great. A simple way to show this is to put the bitmap on the drag and drop example on a container. No configuration of mouseenabled/mouseChildren made this work.

error regarding 'getContext' in Graphics.js of EaselJS 0.3.2 using Internet Explorer 9

I'm currently tinkering with EaselJS (awesome library btw!) but when I am using the new Internet Explorer 9 I get an JavaScript error. I'll try to give a minimalistic example of the error in this issue (my first day on github btw):

Host the following two files "test.html" and "Graphics.js" (which is from EaselJS 0.3.2)...

https://gist.github.com/929286

...on a local webserver and open them with (the 32 bit version of) Internet Explorer 9 (version 9.0.8112.16421 in my case). Do not open them locally (file:) but really over a web server (http: or https:). I am using nginx 0.8.50 on a (U.S. version of) Windows Vista 64 bit for this. Afterwards I get the following error dialogs:

error 1
Line: 162
Error: Object doesn't support property or method 'getContext'"

error 2
SCRIPT438: Object doesn't support property or method 'getContext'
Graphics.js, line 162 character 2

Build.sh's jar file

What is the path-to-compiler.jar on build.sh? I could not find it on the repository...

Ticker addListener error in IE7

I noticed that Ticker throws an error in IE7 when adding a listener. Placing a try catch block around the removeListener() call inside the function fixes the issue:

try { this.removeListener(o); } catch( e ){ }