A lightweight JavaScript library for interacting with HTML Canvas drawables as if they were separately animatable, interactive objects. zCanvas is optimized for mobile devices, relying on optimal use of resources and works well with touch events; as such zCanvas can be an excellent resource for creating (mobile) browsed based games. It is however also equally useful for creating complex graphical interfaces.
The concept of zCanvas encourages an object oriented approach, where each custom drawable you create for your project inherits its prototype from the sprite-class. Don't be frightened by the mention of OOP however, zCanvas is equally useful if you prefer functional programming.
zCanvas will provide an API that takes care of all animation and update logic you'd associate with, for instance, a game loop, rendering images or even using animated spritesheets. You'll find that in regular use you'll hardly ever have to override the basic sprite behaviour. However, the rendering logic (i.e. the "drawing" of the visual content) can be as low level as you'd like, by drawing straight onto the HTMLCanvasElement using the browsers CanvasRenderingContext2D-API.
zCanvas has been written in vanilla JavaScript (ES2018 dialect) and thus works independently from (and should work with) any other JavaScript framework.
Where the HTMLCanvasElement differs from other HTML elements (in that its contents aren't visible as individual nodes in the DOM but are directly drawn as pixels onto a single surface), zCanvas provides an API that allows you to interact with drawable objects as individual entities (called Sprites), attaching logic to individual elements, leaving you as a developer without the hassle of managing the (lack of) relationship between the canvas contents and the surrounding DOM.
zCanvas follows the concept of the DisplayList where drawable objects become visible on screen once they have been added to a container. Sprites are also containers, so you can stack Sprites onto other Sprites, without having to worry about z indices.
zCanvas has been written to work within a CommonJS/ES6-module structure, but comes prebuilt and transpiled to work in modern browsers from IE9 onwards. It has been tested and verified to work on:
- Internet Explorer 9+ (note: requires polyfill for requestAnimationFrame and Promise)
- Chrome for Windows, OS X and Linux
- Apple Safari 6+ (including Mobile Safari)
- Firefox 3.6+
- Android browser 4+
- Chrome for Android 4+
zCanvas has been optimized extensively for the best performance and works a treat on mobile devices too. The amount of event listeners attached to DOM elements are limited to the HTMLCanvasElement only, where the internal interactions are delegated to the sprites by the canvas. Events triggering updates on the display list are automatically debounced to only render once per animation frame.
As all rendering logic resides within a single method of your Sprite, you can easily attach animation libraries such as the excellent TweenMax by Greensock to alter the visible properties of your sprites for maximum eye candy.
You can get zCanvas via NPM:
npm install zcanvas
zCanvas is compatible with CommonJS, AMD/RequireJS or can be included in a document via script tags:
import { canvas, sprite, loader, collision } from "zcanvas";
const zCanvas = require( "zcanvas" ); // CommonJS
const { canvas, sprite, loader, collision } = zCanvas;
After which you can subsequently use a tool like Webpack to build your application for the browser.
Use zcanvas.amd.js inside the dist/-folder for a prebuilt, minimized RequireJS library transpiled to ES5.
require( [ "zcanvas.amd" ], function( zCanvas ) {
// do something with zCanvas-properties:
// "canvas", "sprite", "loader", "collision"
});
Use zcanvas.min.js inside the dist/-folder for a prebuilt, minimized library transpiled to ES5.
<script type="text/javascript" src="./dist/zcanvas.min.js"></script>
<script type="text/javascript">
// do something with globally available actors:
// "canvas", "sprite", "loader", "collision"
</script>
The project dependencies are maintained by NPM, you can resolve them using:
npm install
When using CommonJS for your project, it is recommended to require the source code directly. However, the project can also be built directly for the browser using a simple NPM task:
npm run build
After which a folder dist/ is created which contains the prebuilt AMD/RequireJS library as well as a script that can be included directly in a document. The source code is transpiled from ES6 to ES5 for maximum compatibility.
Unit tests are run via jest, you can run the tests by running:
npm run test
Unit tests go in the ./test-folder. The file name for a unit test must be equal to the file it is testing, but contain the suffix ".spec", e.g. functions.js should have a test file functions.spec.js.
You can view some basic features in the down-and-dirty demos here, note the demos were written in ES5 without the use of any libraries (other than RequireJS to load zCanvas), to make them instantly available to the browser:
- Demo #1: Spritesheets and pixel-perfect collisions
- Demo #2: Custom game loop and fast collision detections
- Demo #3: Layers and interactions
- Demo #4: Integrating 3rd party animation libraries
- Demo #5: Local image manipulation
Want to view the API? You can check the zCanvas Wiki
(or view the source contents of the demos listed above).