CreateJS - Documentation

What is CreateJS?

CreateJS is a suite of modular libraries and tools that simplify HTML5 canvas development. It provides a consistent, easy-to-use API for working with shapes, text, images, video, and more, abstracting away many of the complexities of the underlying Canvas API. The libraries are designed to be lightweight, performant, and cross-browser compatible, making them suitable for a wide range of projects, from simple animations to complex interactive applications. CreateJS includes several key libraries: EaselJS (for display and animation), TweenJS (for animation), SoundJS (for audio playback), and PreloadJS (for asset loading).

Why Use CreateJS?

CreateJS offers several compelling reasons for choosing it as your HTML5 canvas framework:

Setting up your Development Environment

Setting up your development environment for CreateJS is straightforward. You primarily need:

  1. A Text Editor or IDE: Choose your preferred code editor (e.g., VS Code, Sublime Text, Atom) or an Integrated Development Environment (IDE) like WebStorm.

  2. A Web Browser: Modern browsers (Chrome, Firefox, Safari, Edge) all support the HTML5 Canvas API and will work with CreateJS.

  3. The CreateJS Libraries: Download the CreateJS libraries from the official CreateJS website or use a CDN (Content Delivery Network) to include them in your project. CDNs provide quick access and avoid the need for local downloads. An example using a CDN is shown below:

<script src="https://code.createjs.com/1.0.0/createjs.min.js"></script>

Remember to replace 1.0.0 with the desired CreateJS version.

  1. An HTML File: Create an HTML file to structure your project. This file will include the CreateJS libraries and your JavaScript code.

  2. A JavaScript File (Optional): For larger projects, it’s recommended to keep your CreateJS code in a separate JavaScript file for better organization and maintainability.

CreateJS Libraries and Modules

CreateJS consists of several core libraries, each focusing on a specific aspect of canvas development:

Each library is self-contained and can be used independently, or in combination with the others to create complex and interactive applications. Understanding the functionality of each library is crucial for effective CreateJS development.

EaselJS: Displaying Graphics

Stage, Shapes, and Containers

EaselJS uses a Stage object as the root of the display list. The stage represents the canvas element where everything is drawn. All display objects, including shapes, bitmaps, text, and containers, are added to the stage. Containers are crucial for organizing and managing complex scenes; they act as invisible holders for other display objects, allowing you to group and manipulate them together.

Shapes are created using classes like Shape, Circle, Rectangle, and Ellipse. You define their properties (like color, fill, stroke) and add them to the stage or a container. For complex shapes, you can use the graphics API to draw paths.

Example of creating a simple circle and adding it to the stage:

let stage = new createjs.Stage("myCanvas"); // "myCanvas" is the ID of your canvas element
let circle = new createjs.Shape();
circle.graphics.beginFill("red").drawCircle(50, 50, 30);
stage.addChild(circle);
stage.update();

Working with Bitmaps

EaselJS allows you to easily display images using the Bitmap class. You create a Bitmap object by providing an image URL or an existing HTMLImageElement. Once added to the stage, bitmaps can be scaled, rotated, and repositioned like other display objects. For optimal performance, preload images using PreloadJS before adding them to the stage.

Example of loading and displaying a bitmap:

let image = new Image();
image.onload = function() {
  let bitmap = new createjs.Bitmap(image);
  stage.addChild(bitmap);
  stage.update();
};
image.src = "myImage.png";

Text and Typography

EaselJS provides the Text class for rendering text on the canvas. You can control font size, family, color, and alignment. You can also use rich text with HTML-like formatting, though this may affect rendering performance for large amounts of text. For improved performance with multiple lines of text, consider using a TextField instead.

Example of creating and adding text:

let text = new createjs.Text("Hello, world!", "20px Arial", "#000000");
text.x = 100;
text.y = 100;
stage.addChild(text);
stage.update();

Event Handling

EaselJS makes event handling straightforward. You can add event listeners to display objects to respond to mouse events (click, mouseover, mouseout, etc.) and stage events. The addEventListener method is used to attach listeners.

Example of adding a click event listener to a shape:

circle.addEventListener("click", function(event) {
  console.log("Circle clicked!");
});

Animation Fundamentals

Animation in EaselJS is typically achieved by repeatedly updating the properties (position, rotation, scale) of display objects within a tick event handler. The Ticker class provides a consistent update loop. You modify the object’s properties in each tick, creating the illusion of movement.

Example of basic animation using the Ticker:

createjs.Ticker.addEventListener("tick", handleTick);
function handleTick(event) {
  circle.x += 2; // Move the circle 2 pixels to the right each frame.
  stage.update(event);
}

Tweens and Timers

TweenJS offers a powerful and efficient way to create smooth animations. It handles transitions between property values over a specified duration, using various easing functions. Timers provide a simple way to execute functions at specified intervals.

Example of a simple tween:

createjs.Tween.get(circle).to({x: 300, y: 200}, 1000, createjs.Ease.linear); // Move circle over 1 second.

Display Lists and Optimization

The EaselJS display list is a hierarchical structure of display objects. Efficient organization is crucial for performance, especially in complex scenes. Minimize the number of objects on the stage, group related objects into containers, and use caching strategically to improve rendering speeds. Avoid excessive use of rich text and unnecessary updates to improve performance further. Understanding the display list structure and using optimization techniques is essential for creating high-performance applications.

TweenJS: Animation and Transitions

Basic Tweening

TweenJS simplifies the creation of animations by providing methods to smoothly transition the properties of objects over time. The core function is createjs.Tween.get(), which takes a target object and allows you to define the properties to animate, their target values, and the duration of the animation.

A basic example of tweening an object’s x and y properties:

let circle = new createjs.Shape();
// ... (add circle to stage) ...

createjs.Tween.get(circle)
  .to({ x: 200, y: 100 }, 1000); // Move to (200, 100) over 1000 milliseconds (1 second)

This code will smoothly animate the circle’s position from its current location to (200, 100) over one second. You can specify multiple properties within the to() method.

Easing Functions

Easing functions control the speed and timing of the animation. TweenJS provides a range of built-in easing functions (e.g., createjs.Ease.linear, createjs.Ease.quadIn, createjs.Ease.cubicOut, etc.), each creating a different animation curve. These control the rate of change of the animated property over time, affecting the perceived smoothness and character of the animation.

Example using a different easing function:

createjs.Tween.get(circle)
  .to({ x: 200, y: 100 }, 1000, createjs.Ease.backOut); // Uses a bounce-back effect.

Chaining Tweens

Tweens can be chained together to create complex animations with multiple stages. Each .to() call adds a new tween segment to the animation sequence. You can define different properties and durations for each segment.

Example of chaining tweens:

createjs.Tween.get(circle)
  .to({ x: 200, y: 100 }, 1000, createjs.Ease.quadOut)
  .to({ x: 400, y: 200, alpha: 0 }, 500, createjs.Ease.sineIn); // Fade out while moving

This code moves the circle to (200, 100) using a quadratic easing, then to (400, 200) while fading it out using a sine easing.

Complex Animations

TweenJS is capable of animating various properties beyond simple position. You can animate alpha (opacity), scale, rotation, color, and even custom properties. For more complex animations involving multiple objects or coordinated movements, you may need to use callbacks or event listeners to synchronize actions. Consider structuring your code efficiently, perhaps by grouping animations using containers, for better organization.

Example animating multiple properties:

createjs.Tween.get(circle)
  .to({ x: 200, y: 100, scaleX: 2, scaleY: 2, alpha: 0.5 }, 1000);

TweenJS Events

TweenJS provides events that allow you to execute functions at specific points in an animation’s lifecycle (e.g., change, complete). This allows for precise control and the triggering of other actions based on animation progress. Event listeners are added using addEventListener().

Example of using a complete event:

createjs.Tween.get(circle)
  .to({ x: 200, y: 100 }, 1000)
  .addEventListener("change", function(event) {
    console.log("Tween is changing");
  })
  .addEventListener("complete", function(event) {
    console.log("Tween is complete");
    // Perform additional actions here
  });

The change event fires during the animation, and the complete event fires when the animation concludes. Other useful events include paused and resume.

SoundJS: Audio Integration

Playing Sounds

SoundJS simplifies the process of playing audio files in your CreateJS applications. The core class is createjs.Sound. Before playing sounds, you must register them using createjs.Sound.registerSound(), which takes a path to the sound file. Once registered, sounds can be played using createjs.Sound.play().

Example of playing a sound:

// Preload the sound (recommended for better performance)
createjs.Sound.registerSound("./mySound.mp3", "mySound");

// Play the sound
createjs.Sound.play("mySound");

Ensure that the sound file exists at the specified path and that it’s in a supported format (MP3, Ogg, WAV are commonly supported).

Sound Effects and Music

SoundJS can handle both short sound effects and longer music tracks. The distinction is primarily in how you manage their playback and potential looping. Short sound effects are typically played once, while music tracks may loop continuously or play for a specific duration.

Example of playing a looping music track:

createjs.Sound.registerSound("./myMusic.mp3", "myMusic");
let instance = createjs.Sound.play("myMusic", {loop: -1}); // -1 loops indefinitely

You can stop the music using instance.stop(); where instance is the reference to the sound instance obtained from createjs.Sound.play().

Sound Playback Control

SoundJS provides various methods to control sound playback:

These methods operate on the sound instance returned by createjs.Sound.play().

Audio Sprites

Audio sprites are a technique for storing multiple sounds within a single audio file. SoundJS supports audio sprites by specifying the start and end times of each sound within the file. This is useful for optimizing loading times and reducing the number of individual audio files.

Example using an audio sprite:

// Preload the sprite sheet.
createjs.Sound.registerSound("./soundSprite.mp3", "soundSprite");
let soundManifest = [
    {id: "sound1", src: "soundSprite.mp3", data:{offset:0, duration: 1000}}, // 1-second sound
    {id: "sound2", src: "soundSprite.mp3", data:{offset:1000, duration: 500}}   // 0.5-second sound
];
createjs.Sound.registerManifest(soundManifest);
//Play the audio sprites
createjs.Sound.play("sound1");
createjs.Sound.play("sound2");

Note: offset is in milliseconds.

Handling Errors and Events

SoundJS provides mechanisms for handling errors and events during audio playback:

Example of adding an event listener:

let instance = createjs.Sound.play("mySound");
instance.addEventListener("complete", handleSoundComplete);

function handleSoundComplete(event) {
  console.log("Sound finished playing!");
}

Proper error and event handling ensures robust audio management in your application. Remember to handle potential issues gracefully to improve the user experience.

PreloadJS: Asset Management

Loading Images, Sounds, and Other Assets

PreloadJS is a powerful library for managing the loading of assets in your CreateJS applications. It handles the asynchronous loading of various asset types (images, sounds, text files, JSON data, etc.), providing a structured and efficient way to manage the loading process. The core class is createjs.LoadQueue. You create a LoadQueue instance and add files to it using the loadManifest() method, which takes an array of file specifications.

Example of loading images:

let queue = new createjs.LoadQueue(true); // true enables file progress events
queue.loadManifest([
    {id: "image1", src: "image1.jpg"},
    {id: "image2", src: "image2.png"}
]);

queue.on("complete", handleComplete, this);

function handleComplete() {
    let image1 = queue.getResult("image1");
    let bitmap1 = new createjs.Bitmap(image1);
    // ... add bitmap to stage ...
}

This code creates a LoadQueue, loads two images, and uses an event listener to execute handleComplete() after the loading is finished, where queue.getResult("image1") retrieves the loaded image.

Progress Monitoring

PreloadJS provides progress events that allow you to monitor the loading status of your assets. The progress event fires periodically, giving you the percentage of completed loading. The complete event indicates that all assets have been loaded successfully.

Example of monitoring progress:

queue.on("progress", handleProgress, this);
queue.on("complete", handleComplete, this);

function handleProgress(event) {
    console.log("Loading progress: " + Math.round(event.progress * 100) + "%");
}

function handleComplete() {
    console.log("All assets loaded!");
}

This code adds event listeners to track both progress and completion.

Error Handling

PreloadJS provides mechanisms for handling errors during asset loading. The error event fires when an asset fails to load. The event object provides information about the failed asset.

Example of handling errors:

queue.on("error", handleError, this);

function handleError(event) {
    console.error("Error loading asset:", event.item);
}

This code adds an error handler to gracefully manage asset loading failures.

Manifest Files and Configuration

For larger projects, it’s often beneficial to use manifest files (typically JSON files) to define the assets to be loaded. Manifest files provide a centralized and organized way to specify asset paths, IDs, and other metadata. PreloadJS can load assets directly from a manifest file.

Example manifest file (manifest.json):

[
    {id: "image1", src: "image1.jpg"},
    {id: "sound1", src: "sound1.mp3"},
    {id: "data1", src: "data1.json"}
]

Example loading from a manifest:

let queue = new createjs.LoadQueue(true);
queue.loadManifest("./manifest.json");
// ... add event listeners ...

Advanced Loading Techniques

PreloadJS offers advanced features for optimizing asset loading:

By understanding these advanced techniques, you can optimize your asset loading strategy to enhance the performance of your CreateJS applications. Remember to always test and profile your asset loading procedures to ensure optimal efficiency for your target audience and devices.

Utility Libraries

Ticker and Tick Events

The CreateJS Ticker is a core utility class providing a consistent and high-performance mechanism for executing code at regular intervals, forming the basis for animation and other time-based events. The Ticker dispatches “tick” events, which are crucial for updating the display and performing animations in EaselJS and other CreateJS libraries. It’s designed to be highly efficient and cross-browser compatible, handling inconsistencies in browser timing mechanisms.

The Ticker can be used in different modes:

Example using the Ticker for animation:

createjs.Ticker.addEventListener("tick", handleTick);

function handleTick(event) {
  // Update game state based on the time elapsed since the last tick (event.delta)
  myObject.x += 5; // Example: move an object 5 pixels
  stage.update(event); // Update the display
}

The stage.update(event) call is crucial to refresh the canvas display after each update.

EventDispatcher

The createjs.EventDispatcher class is a fundamental utility for managing events throughout CreateJS. Many CreateJS objects (including the Stage, DisplayObject, LoadQueue, and SoundInstance classes) inherit from EventDispatcher, providing a consistent event handling mechanism. This promotes modularity and provides a clean pattern for managing interactions.

Key functionalities include:

Example using EventDispatcher:

let myObject = new createjs.EventDispatcher();

myObject.addEventListener("myCustomEvent", handleMyEvent);

function handleMyEvent(event) {
  console.log("My custom event triggered!", event);
}

myObject.dispatchEvent({type: "myCustomEvent", data: "some data"});

This example shows creating a custom event and attaching a listener to handle it. The EventDispatcher provides a structured and powerful way to manage events within and between different CreateJS components. Understanding its use is crucial for building more complex and interactive applications.

Advanced Topics

Performance Optimization

Optimizing performance is crucial for creating smooth and responsive CreateJS applications, especially when dealing with complex scenes or animations. Key strategies include:

Debugging and Troubleshooting

Debugging CreateJS applications often involves standard JavaScript debugging techniques, but specific CreateJS considerations include:

Integrating with Other Libraries

CreateJS is designed to work well with other JavaScript libraries. Common integration points include:

Remember to consider potential conflicts between libraries and ensure proper initialization and compatibility.

Creating Interactive Applications

CreateJS provides a strong foundation for building interactive applications. Effective strategies include:

Working with External Data Sources

Fetching and using external data (from JSON APIs, databases, etc.) involves:

Accessibility Considerations

Accessibility is crucial for inclusive application design. Consider these points:

Best Practices

Examples and Tutorials

This section provides a starting point for exploring the capabilities of CreateJS through various examples and tutorials. More extensive examples and tutorials can be found on the official CreateJS website and community resources.

Simple Animations

Simple animations are a great way to start learning CreateJS. These examples focus on basic animation principles using EaselJS and TweenJS. They often involve animating the position, scale, rotation, or alpha (opacity) of simple shapes or bitmaps.

Example: A bouncing ball animation can be created by using TweenJS to repeatedly change the ball’s vertical position, applying an easing function to simulate the bounce. This would involve setting up a Ticker event listener to update the ball’s position in each tick and using createjs.Tween.get() to control the animation’s timing and easing.

Interactive Games

Interactive games showcase the capabilities of CreateJS for creating engaging user experiences. These examples usually demonstrate the use of event handling, collision detection, and game logic.

Example: A simple “Breakout” clone could be developed using EaselJS to render the bricks, paddle, and ball. TweenJS would handle the ball’s movement, and event listeners would respond to mouse or touch input for paddle control. Collision detection would be implemented to handle ball-brick and ball-paddle interactions, managing score and game state.

Complex Visualizations

Complex visualizations demonstrate how CreateJS can handle large datasets and sophisticated graphics. These examples highlight the importance of performance optimization techniques.

Example: A data visualization displaying stock prices over time could use EaselJS to create a line graph. The graph would dynamically update based on data fetched from an external source. Efficient techniques would be employed to handle large datasets smoothly. This might involve techniques like data chunking or using containers to manage the visual elements efficiently. Consider the use of efficient data structures and algorithms to optimize the update process.

Case Studies

Case studies offer in-depth looks at real-world applications built with CreateJS. These provide insight into architectural decisions, problem-solving approaches, and best practices.

Example: A case study could analyze the implementation of a web-based interactive map using CreateJS. The study would discuss how assets were managed (e.g., using PreloadJS), how map interactions were handled, and strategies employed for optimizing performance when displaying large maps. It might highlight challenges encountered and the solutions implemented. It could also include performance benchmarks and user feedback.

These examples and tutorials are intended as starting points. Experimenting with different techniques and expanding on these basic concepts will help you master CreateJS and build sophisticated applications. Remember to refer to the official CreateJS documentation and community resources for more detailed information and inspiration.

Appendix

Glossary of Terms

This glossary defines key terms used throughout the CreateJS documentation.

API Reference

A comprehensive API reference provides detailed information about all classes, methods, and properties within the CreateJS libraries. This reference typically includes:

The location of the complete API reference will vary depending on the version of CreateJS and the preferred method of access (e.g., online documentation, locally downloaded files).

Troubleshooting Common Issues

This section addresses frequently encountered problems and provides solutions. Common issues may include:

Community Resources and Support

The CreateJS community offers various resources for support and collaboration:

Engaging with the community is a valuable way to resolve issues, learn best practices, and stay informed about updates and developments in CreateJS.