What's Included & API Overview

Below is an overview of the functionality this project provides. To read the complete documentation for every function and class, view the full API documentation.

Classes

The objects provided below are useful representations of a variety of entities often found in interactive environments. Box, Actor, and Player use John Resig's "simple JavaScript inheritance" library, so you can extend them to create new classes with modified functionality.

• Class: Supports OOP-style inheritance.
• Box: A box shape. This is the basic building block for most interactive entities. It has a size, position, orientation, and display, and it supports collision and various events.
• Actor: Actors inherit from Boxes and add sophisticated built-in support for various kinds of movement. They also support mouse-draggability.
• Player: Players inherit from Actors and add support for control via user input (using the keyboard by default).
• Collection: A container to keep track of multiple Boxes. It has various helper methods to easily work with all the Boxes in the Collection, including batch drawing, collision checking, and other operations.
• TileMap: A utility for rapidly initializing and manipulating grids of tiles. This makes it easy to quickly lay out an environment and process the objects in it.
• Sprite, SpriteMap: Manage sprite images for animation and convenient display. These classes are provided by a library by the same author.
• World: The complete playable game area. Contains information about the environment and helpers for controlling the viewport.
• Layer: An intermediate graphics layer (useful for drawing performance). Supports parallax scrolling.
• Timer: A timer for all your timing needs.

Drawing

The normal canvas drawImage() method is enhanced in order to be able to draw any kind of image while utilizing the image cache for performance. Use it to draw any of the following:

• The file path of an image
• A Sprite or SpriteMap object
• A Layer object
• An HTMLCanvasElement
• An HTMLImageElement (same thing as an Image)
• An HTMLVideoElement

Or, just assign one of these things to the "src" attribute of a Box, Actor, or Player instance to have its draw() method display the image.

Events

A number of events are triggered on the document, on Boxes, and on Actors for various mouse, touch, drag-drop, and game events. You can also add your own custom events.

Objects in a Canvas are not represented in the DOM and so they don't benefit from the traditional JavaScript event model. A similar replacement event system is provided so you don't have to worry about this problem. Specifically, the Box class provides the listen(), once(), and unlisten() methods to bind and unbind event handlers.

Wrappers and Automatic Handlers

• Keyboard Input: For many use cases, keyboard input is handled automatically via the "keys" object defined in main.js. Additionally, Actors can use a "keys" property structured the same way as the global "keys" object; use this to assign different keys to different Actors (useful for multiplayer on the same keyboard, for example). You can also bind directly to key event combinations using natural descriptions of the keys: $(selector).keypress('ctrl+a down', function(event) { });

  Other ways to handle keyboard input are described in the documentation.

• Mouse Input: Most mouse input can be handled by listening to mouse events on Box objects or by using the isHovered() instance methods. The mouse coordinates relative to the canvas are also available in Mouse.Coords. There is additional support for zooming using the mouse scroll wheel.

• Storage: App.Storage provides a wrapper for localStorage that allows storing any kind of object (not just strings).

• Visibility: By default, animation stops when the tab or window loses focus. This reduces CPU impact when the app is not in view (and preserves your sanity if you are developing with the browser open in one window and your editor in another). If you don't want this behavior, $(window).off(".animFocus"); will disable it.

• Automatic Canvas Resizing: It is easy to make your canvas the size and shape you want by setting various attributes on the <canvas> tag.

• Scrolling: By default, if the world is bigger than the canvas, the viewport will scroll as the player approaches its edge. You can switch to scrolling the viewport with the mouse with Mouse.Scroll.

• Caching: Images will be cached on the fly if necessary, or it's easy to pre-load them with the "preloadables" array in main.js. Pre-loading is recommended to avoid images "popping" into view on the canvas as they load. If you need to, you can manipulate the Caches manually.

• HTML Integration: App.Utils.positionOverCanvas() allows you to position any DOM element at a specific position over the canvas. This allows you to place HTML forms, buttons, labels, or anything else directly onto the canvas.

Miscellany

• Global Variables: Some frequently used variables, like player, canvas, context, and world, are provided globally for ease of reference.
• Debugging: Steven Wittens' console-extras.js is included in the "js/libraries" folder for convenient debugging within the main loop. It provides utilities to limit and analyze console output.
• Other Utilities: A number of helper methods are available in App and App.Utils, as well as several custom methods added to the default Array, Number, and CanvasRenderingContext2D classes.

CSS

Put your application's primary styles in main.css and responsive styles for different types and sizes of screens in media.css. print.css will kick in automatically when the page is being printed. reset.css normalizes styles across browsers to sensible defaults. utilities.css provides some helpful classes to use in your markup.