Collie is a JavaScript library for making optimized animations and games for mobile platforms. Collie is available under the LGPL v2.1 open source license. To download the latest version, visit http://jindo.dev.naver.com/collie/.

Collie runs on both the desktop and mobile devices, but is designed to be highly optimized for mobile applications. It has been performance tested on more than 18 different devices across a range of platforms. You can view the results of these tests on the Collie site (see Figure 1).

Figure 1. The Collie performance test page shows results by mobile device and OS

Collie selects the best rendering method, either HTML5 Canvas or CSS3, for the device on which it is running as determined by the test results. The result looks identical across the two rendering methods. Thus, Collie enables you to design your interface without having to worry about the best rendering method to use on various devices.

In this tutorial, you’ll use Collie to create an animation of a walking rabbit that jumps when clicked or touched.

Getting started with a simple example

Before getting to the rabbit animation, you can learn the basics of using Collie by creating an animation that simply rotates the Collie logo in the middle of the page.

Creating the markup

First, you need to load the Collie script file into an HTML file.

Create a project folder.
Download the JavaScript file from the Collie site and place it in a subfolder named js in your project folder. You can download collie.js or the minified version, collie.min.js.
Create an HTML file in your project folder and paste the following code into it:

        <!doctype html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no" />
</head>
<body>
<div id="container"></div>
<script src="js/collie.min.js"></script>
<script type="text/javascript">
    // Create code here.
</script>
</body>
</html>
    

Note: The code samples in this article use the minified version of the library, collie.min.js. If you want to use collie.js instead, you’ll need to update the scripts accordingly.

Collie does not have any dependencies, so you do not need to import any additional libraries. It is also designed to be lightweight; it is only about 20kb when compressed.

As you may notice, the code above includes a viewport meta tag, which is necessary to optimize viewing pages on mobile:

        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no" />
    

To learn more about how the viewport meta tag works, refer to the Apple developer documentation.

Creating a layer

Prior to creating the logo object, you need to create a layer for holding display objects. The Collie Layer component is capable of holding various display objects and it is equivalent to a single canvas.

To create the new layer, add the following code inside the script block of your HTML page:

        var layer = new collie.Layer({
    width: 320,
    height: 480
});
    

You can specify options when creating a layer. The options used above create a layer corresponding to a mobile display with a 320 pixel width and a 480 pixel height. For more details, see the API documentation for Layer.

Loading an image using ImageManager

Images used in animations or games are usually loaded asynchronously because the number of images can be considerable. Collie asynchronously manages its image resources using ImageManager. You can load images using the add method in ImageManager. Insert the following code inside the script block of your HTML page:

        collie.ImageManager.add({
    logo: "http://jindo.dev.naver.com/collie/img/small/logo.png"
});

// Create display object. Although image has yet to be loaded, you may use the logo.
    

Although ImageManager loads images asynchronously, you can create display objects using the images without needing to check the loading result. Once the display object is created and the image has completely loaded, ImageManager allocates the loaded image to the display object. However, if you don’t want an empty display object to be in the display, you can wait until all images are loaded before creating the objects; for example:

        collie.ImageManager.add({
  logo: "http://jindo.dev.naver.com/collie/img/small/logo.png"
}, function () {
  // Create display object after all images are loaded
});

    

For more details, see the API documentation for ImageManager.

Creating a display object

To display the loaded image on the screen, you must create a display object. There are various kinds of display objects within Collie, including Circle for marking circles and Text for creating a text DisplayObject. To create a logo that rotates, you will create a display object using MovableObject, which is capable of using the velocity attribute.

Add the following code immediately following the comment within the prior ImageManager code:

        var logo = new collie.MovableObject({
    x: "center",
    y: "center",
    backgroundImage: "logo",
    velocityRotate: 50
}).addTo(layer);
    

When creating a display object, you can add the corresponding object to a layer using the addTo method. A display object will only be displayed on the screen when it is added to a layer or a parent display object.

A display object also can accept a set of options as its first argument. As shown above, you can use character strings as the value for x and y instead of specifying the pixel coordinate position. For the backgroundImage setting, the code above specifies the "logo" ImageManager instance created earlier. The display object will be automatically sized to fit the background image size unless width and height values are specified.

The velocityRotate property is a special property for MovableObject. It specifies the rotation angle in degrees per second. For instance, when this property is set to 50, the object will rotate 50 degrees in every second. Horizontal and vertical velocity can also be specified using velocityX and velocityY. Refer to the API documentation for MovableObject for more information.

Preparing a Renderer

At this point, you’ve created a display object and added it to a layer. To show the object on the screen, you need to add the prepared layer to a Renderer and execute the Renderer.

Insert the following code immediately after the MovableObject code you just added:

        collie.Renderer.addLayer(layer);
collie.Renderer.load(document.getElementById("container"));
collie.Renderer.start();
    

First, the code above adds the prepared layer onto the Renderer using the addLayer method. Next, it uses the load method to initialize Collie on a DOM object with the id of "container":

<div id="container"></div>

Lastly, it runs Renderer by invoking the start method. The optional first argument to the start method is time frame in milliseconds that determines the frames per second (FPS) for the animation. You may also simply add "fps" at the end of your string and Collie will determine the proper numeric value for the frames per second for you. The default value is "60fps", however in a typical mobile environment it is most effective to run with "30fps"; for example:

collie.Renderer.start("30fps");

Full code for the rotating logo

Here is the complete code for the rotating logo:

        <!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no" />
</head>
<body>
<div id="container"></div>
<script type="text/javascript" src="js/collie.min.js"></script>
<script type="text/javascript">
var layer = new collie.Layer({
    width: 320,
    height: 480
});
 
collie.ImageManager.add({
    logo: "http://jindo.dev.naver.com/collie/img/small/logo.png"
});
 
var logo = new collie.MovableObject({
    x: "center",
    y: "center",
    velocityRotate: 50,
    backgroundImage: "logo"
}).addTo(layer);
 
collie.Renderer.addLayer(layer);
collie.Renderer.load(document.getElementById("container"));
collie.Renderer.start();
</script>
</body>
</html>

    

When you run this code you should see a rotating image on the screen (see Figure 2).

Figure 2. The rotating logo image

Creating motion using a sprite sheet

Now that you have seen how to use Collie for making a simple animation, you’re ready to create a more complex animation of a moving rabbit using a sprite sheet.

Preparing an image and an object

A sprite sheet expresses a continuous scene into a single image (see Figure 3).

Figure 3. A sprite sheet for a walking rabbit

When creating a display object using a sprite, the size of a single screen will be based on the width and height arguments you supply.

Create a copy of your logo rotation page, and replace the ImageManager and DisplayObject calls with the following code:

        collie.ImageManager.add({
    rabbit: "http://jindo.dev.naver.com/collie/img/small/yame_walk.png"
});
var rabbit = new collie.DisplayObject({
    x: "center",
    y: "center",
    width: 129.4,
    height: 165,
    backgroundImage: "rabbit"
}).addTo(layer);
    

The above code, when used with a Renderer, displays a motionless rabbit on the screen (see Figure 4).

Figure 4. A display object showing only the first frame of a sprite sheet

Adding animation

To infuse a little life into this rabbit, you’ll need to create an animation. Collie supports various types of animations, including delay, repeat, and transition.

The following code uses a cycle animation with the sprite (add this code below the rabbit DisplayObject):

        collie.Timer.cycle(rabbit, "18fps", {
    from: 0,
    to: 8,
    loop: 0
});
    

Animations can be created using collie.Timer. The cycle function’s first argument is either the display object you wish to animate or a callback function. The second argument specifies the animation’s frames per second. The third argument is an object with animation options. Refer to the API documentation for AnimationCycle for further information.

Here is the complete code for the animated rabbit.

        <!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no" />
</head>
<body>
<div id="container"></div>
<script type="text/javascript" src="http://jindo.dev.naver.com/collie/deploy/collie.min.js"></script>
<script type="text/javascript">
var layer = new collie.Layer({
    width: 320,
    height: 480
});
 
collie.ImageManager.add ({
    rabbit: "http://jindo.dev.naver.com/collie/img/small/yame_walk.png"
});
 
var rabbit = new collie.DisplayObject({
    x: "center",
    y: "center",
    width: 129.4,
    height: 165,
    backgroundImage: "rabbit"
}).addTo(layer);
 
collie.Timer.cycle(rabbit, "18fps", {
    from: 0,
    to: 8,
    loop: 0
});
 
collie.Renderer.addLayer(layer);
collie.Renderer.load(document.getElementById("container"));
collie.Renderer.start();
</script>
</body>
</html>
    

Creating a continuously moving background

A single rabbit moving on the screen is not terribly exciting. You can make it more engaging with a background that moves along with the rabbit’s walk.

Preparing the image and object

To make a moving background, you need to prepare an image that is more than double the size of what is displayed on the screen. Start by creating a MovableObject instance using the backgroundRepeat property as shown below:

        collie.ImageManager.add({
    ground: "http://jindo.dev.naver.com/collie/img/large/ground.png"
});
var ground = new collie.MovableObject({
    x: 0,
    width: 320 * 2,
    height: 88,
    velocityX: -50,
    backgroundImage: "ground",
    backgroundRepeat: "repeat-x"
}).bottom(0).addTo(layer);
    

Since the ground needs to move in the opposite direction of the rabbit, you need to use MovableObject with a negative input velocity value.

The code above moves the background across the screen once. To make the object seem as if it is moving continuously, the ground needs to return to the original position every time the screen passes by. This is done using the rangeX and positionRepeat options of the display object:

        var ground = new collie.MovableObject({
    x: 0,
    width: 320 * 2,
    height: 88,
    velocityX: -50,
    backgroundImage: "ground",
    backgroundRepeat: "repeat-x",
    rangeX: [-320, 0],
    positionRepeat: true
}).bottom(0).addTo(layer);

    

The rangeX value refers to the allowable scope of the object’s x coordinate, and positionRepeat, when set to true, moves the object to the start when the end is reached.

Using events to add interactivity

Collie supports user interaction via object events. You can use this feature to make the rabbit jump up when the mouse is clicked or the screen is tapped.

Adding an event to the object

You can add an event by invoking the attach method on an object.

        rabbit.attach({
    click: function (e) {
        // Perform specific motion
    }
});
    

When using the click event, the object will respond to taps on mobile devices and clicks on desktops.

Defining the jump animation

To make the rabbit look like it is jumping, you need to define a parabolic motion. You can use the transition animation and animation queue as shown below for a parabolic motion:

        var currentY = rabbit.get("y");
rabbit.attach({
    click: function (e) {
        collie.Timer.queue().
            transition(rabbit, 400, {
                to: currentY - 100,
                effect: collie.Effect.easeOut,
                set: "y"
            }).
            transition(rabbit, 400, {
                to: currentY,
                effect: collie.Effect.easeIn,
                set: "y"
            });
    }
});
    

A transition animation defines a continuous motion by using various animation effects. The animation queue is used to combine multiple animations into one. Refer to the API documentation for Effect for complete details on the animation effects that Collie supports.

Supporting high-resolution displays

Collie enables you to support high-resolution displays, such as those on the iPhone 4 and iPhone 5, with ease.

If you have high-resolution images (see Figure 5), add the following line prior to using the ImageManager:

collie.Renderer.RETINA_DISPLAY = "auto";

The default value for collie.Renderer.RETINA_DISPLAY is "false". If you set this value as true or false, you will be able to create a high-resolution environment regardless of the type of device. Setting this value to true or false allows you to manually configure the Retina support, which can be useful for testing purposes.

Figure 5. A high-resolution image (left) specially made for Retina display and an ordinary image (right) when viewed on a Retina display.

Checking the display before image loading

When you set collie.Renderer.RETINA_DISPLAY to "auto", Collie will automatically choose the standard resolution image for typical displays but will load a high resolution image when it detects a high-resolution display. To add Retina support to each object with Collie, use the isRetinaDisplay method of Renderer and load images for that object suitable for each resolution; for example:

        var folder = collie.Renderer.isRetinaDisplay() ? "large" : "small";
collie.ImageManager.add({
    rabbit: "http://jindo.dev.naver.com/collie/img/" + folder + "/yame_walk.png",
    ground: "http://jindo.dev.naver.com/collie/img/" + folder + "/ground.png"
});

    

Debugging

The desktop is clearly a more convenient development environment than a mobile device. You can explicitly direct Collie to use a specific rendering mode (HTML5 canvas and DOM) to test locally for each environment; for example:

collie.Renderer.DEBUG_RENDERING_MODE = "dom";

The above code should be defined before using Collie. The default value for collie.Renderer.DEBUG_RENDERING_MODE is "auto" but you can manually configure the mode by setting it to "canvas" or "dom".

Collie also provides performance debugging information via FPSConsole (see Figure 6).

To see this information, add the following code to your script:

        var fpsConsole = new collie.FPSConsole();
fpsConsole.load();
    

You also need to include the following required script:

        <script src="http://jindo.dev.naver.com/collie/deploy/collie.tool.min.js"></script>
    

Figure 6. The completed animation with FPSConsole output.

Putting in all together

Below is the finished code for all the steps in this tutorial. It creates an animated walking rabbit that jumps when clicked or tapped.

        <!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no" />
</head>
<body>
<div id="container"></div>
<script src="http://jindo.dev.naver.com/collie/deploy/collie.min.js"></script>
<script>
collie.Renderer.RETINA_DISPLAY = "auto";
var folder = collie.Renderer.isRetinaDisplay() ? "large" : "small";
collie.ImageManager.add({
    rabbit: "http://jindo.dev.naver.com/collie/img/" + folder + "/yame_walk.png",
    ground: "http://jindo.dev.naver.com/collie/img/" + folder + "/ground.png"
});
 
var layer = new collie.Layer({
    width: 320,
    height: 480
});

var rabbit = new collie.DisplayObject({
    x: "center",
    width: 129.4,
    height: 165,
    zIndex: 2,
    backgroundImage: "rabbit"
}).bottom(50).addTo(layer);

var currentY = rabbit.get("y");

rabbit.attach({
    click: function (e) {
        collie.Timer.queue().
            transition(rabbit, 400, {
                to: currentY - 100,
                effect: collie.Effect.easeOut,
                set: "y"
            }).
            transition(rabbit, 400, {
                to: currentY,
                effect: collie.Effect.easeIn,
                set: "y"
            });
    }
});

collie.Timer.cycle(rabbit, "18fps", {
    from: 0,
    to: 8,
    loop: 0
});

var ground = new collie.MovableObject({
    x: 0,
    width: 320 * 2,
    height: 88,
    velocityX: -200,
    backgroundImage: "ground",
    backgroundRepeat: "repeat-x",
    rangeX: [-320, 0],
    positionRepeat: true
}).bottom(0).addTo(layer);

collie.Renderer.addLayer(layer);
collie.Renderer.load(document.getElementById("container"));
collie.Renderer.start();
</script>
</body>
</html>
    

You can also try the above code at http://jsbin.com/oyopeq/2/

Where to go from here

Collie is optimized for mobile platforms while also providing development convenience and productivity on the desktop. Using Collie, you will be able to create optimal animations that automatically rely on either the DOM or Canvas depending on the best fit for the circumstances, while also supporting Retina displays.

The ultimate goal of Collie is to enable developers to focus on the creative aspects of animation rather than the technical aspects of creating the animation in the browser.

For more examples on using Collie and full API documentation, visit the Collie site.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.

Introducing Collie: A high-performance animation library for JavaScript

by Sangmin Shim

Content

Created

Page tools

Requirements

Prerequisite knowledge

Additional required products

User level