StageXL StageXL for Dart

StageXL is a package for the Dart programming language. It offers an easy to use and complete API for impressive 2D content like games and other rich applications. The library started as an easy migration path for Adobe Flash developers to HTML5. Therefore the StageXL API is for the most part identical to the Flash API. Today many developers who have no prior experience with Flash are using StageXL for their applications.

To simplify the migration from Flash to HTML5, the StageXL library uses the same class hierarchy as Flash does. You can extend your UI-objects from DisplayObject(Container) or just work with the Sprite class. The methods and properties of the classes are the ones you already know from the Flash API.

The BitmapData class represents the pixels of an image or the content you draw at runtime. Add an instance of the Bitmap class to the Display List to make the BitmapData visible. Of course all DisplayObjects are scalable, rotatable, movable and blendable with the familiar properties like x, y, rotation, scaleX, scaleY and alpha.

In some cases the classes even extend the capabilities of Flash. One example are the handy pivotX and pivotY properties of every DisplayObject which allow you to set the pivot or anchor point of your DisplayObject.

The Stage class represents the main drawing area and is a wrapper over the HTML5 Canvas element. Use the addChild or removeChild methods to add or remove other DisplayObjects to or from the Stage.

  • BitmapData
  • EventDispatcher
    • DisplayObject
      • Bitmap
      • Shape
      • InteractiveObject
        • SimpleButton
        • TextField
        • MovieClip
        • DisplayObjectContainer
          • Stage
          • Sprite

Events work the same way as they do in Flash. All the major Event classes are available with the same names and properties. The event flow uses the familiar three-phase approach: Capture Phase, Target Phase and Bubbling Phase.

mySprite.addEventListener(Event.ENTER_FRAME, enterFrameListener);
mySprite.addEventListener(MouseEvent.CLICK, mouseClickListener, useCapture:true);

The Dart language uses a more modern stream based event API. We recommend to use this new pattern to utilize new possibilities and to be a good citizen in the Dart community. The API is a little bit different compared to Flash, but the functionality is pretty much the same.

var subscription1 = mySprite.onEnterFrame.listen(enterFrameListener);
var subscription2 = mySprite.onMouseClick.listen(mouseClickListener);
var subscription3 = mySprite.on("customEvent").listen(customEventListener);

subscription1.cancel();    // equals removeEventListener(...)
subscription2.pause();     // pause receiving events
subscription2.resume();    // resume receiving events
  • EventDispatcher
  • EventPhase
  • Event
    • MouseEvent
    • TouchEvent
    • KeyboardEvent
    • TextEvent
    • EnterFrameEvent

  • Stream<Event>
  • StreamSubscription<Event>

To display and format text the TextField and TextFormat classes are available. The TextField class is the Display Object you can add to the Display List. Change the content of the TextField at any time by modifying the text property. The TextFormat class supports all the properties to set the font, color, alignment and style of the text.

The fonts in the TextFormat class are not limited to the typical HTML fonts. Use Google's open web fonts to bring quality typography to your application. Just add the font's css-style to your page and use the font in TextFormat like you do with any other font.

var textField = new TextField();
textField.defaultTextFormat = new TextFormat('Spicy Rice', 30, Color.Black);
textField.text = 'The quick brown fox jumps over the lazy dog.'
textField.x = 20;
textField.y = 20;
textField.width = 100;
textField.height = 50;
textField.wordWrap = true;
  • TextFormat
  • TextFormatAlign
  • TextFieldType
  • TextLineMetrics
  • EventDispatcher
    • DisplayObject
      • InteractiveObject
        • TextField

Playing audio in HTML5 can be difficult. All modern browsers use slightly different implementations of the standard. Google Chrome supports the Web Audio API which is not a HTML5 standard yet, but offers the best audio playback capabilities for games. Another problem is the support of all the audio codecs (mp3/ogg/wav) used in different browsers.

To hide all the problems and differences the StageXL library wraps those APIs and provides the familiar Sound APIs of Flash. The library also selects the codec which is supported by the browser. You just have to provide the audio file in mp3 and ogg format, this way your application will work in all major browsers.

// The ResourceManager substitutes embedded resources of Flash.
var resourceManager = new ResourceManager();
resourceManager.addSound("plop", "sounds/plop.mp3");   // loads ogg-file in Firefox!

var sound = resourceManager.getSound("plop");
var soundTransform = new SoundTransform(0.5);
var soundChannel =, soundTransform);
  • SoundTransform
  • SoundMixer
  • Sound
    • AudioElementSound
    • WebAudioApiSound
    • MockSound
  • SoundChannel
    • AudioElementSoundChannel
    • WebAudioApiSoundChannel
    • MockSoundChannel

Filters are used for visual effects like drop shadow, glow, blur and others. The StageXL library supports five different filters out of the box. You can also create your own filters by extending the BitmapFilter base class.

Calculating visual effects is an expensive computational operation. To optimize the performance at runtime you can apply filters to static BitmapDatas or add them to an arbitrary DisplayObject and subsequently call the applyCache method to achieve good render performance.

var spaceShip = new SpaceShip();
spaceShip.x = 100;
spaceShip.y = 50;
spaceShip.filters = [
    new ColorMatrixFilter.grayscale(),
    new GlowFilter(Color.Yellow, 1.0, 20, 20)];
spaceShip.applyCache(0, 0, 200, 80);
  • BitmapFilter
    • ColorMatrixFilter
    • BlurFilter
    • DropShadowFilter
    • GlowFilter
    • AlphaMaskFilter
    • BevelFilter(todo)

The StageXL library provides an easy to use animation framework. You can animate your objects by implementing the Animatable interface or simply use the Tween class to animate your Display Objects properties like x, y, scaleX, scaleY, rotation and alpha. In addition you can control the flow of your application by using the DelayedCall class.

All classes which implements the Animatable interface can be added to the Juggler. The Juggler controls the timeline of your application and advances all Animatable objects by the time that has passed since the last frame. You should use the Juggler instance provided by the render loop to drive your animations. For more information please read the Wiki article about the Juggler animation framework.

var tween = new Tween(sprite, 2.0, TransitionFunction.easeOutBounce);;;
tween.delay = 1.0;
tween.onComplete = () => sprite.removeFromParent();

  • TransitionFunction
  • Animatable
    • Juggler
    • Tween
    • Transition
    • DelayedCall

In Flash developers often embed resources in their SWF files. This is not possible on the web, but the ResourceManager provides an easy way to load images, sounds and other resources from the server. You only have to add the URLs and the ResourceManager will download all files. Once the files are loaded you will be notified by a Future.

If your application uses a large number of small images, it is best practice to merge those small images into one big image. This big image is called texture atlas (or sprite sheet) and accelerates the download and improves the render performance. The StageXL library supports the file format of Texture Packer, which is the most popular tool on the web.

var resourceManager = new ResourceManager()
  ..addBitmapData('dog', 'images/dog.png')
  ..addSound('plop', 'sounds/plop.mp3')
  ..addTextureAtlas('fl', 'images/flowers.json', TextureAtlasFormat.JSONARRAY);

resourceManager.load().then((result) {
  var dog = resourceManager.getBitmapData('dog');
  var plop = resourceManager.getSound('plop');
  var flowers = resourceManager.getTextureAtlas('fl');
  var daisy = flowers.getBitmapData('daisy');
  • Resource
  • TextureAtlas