Compact JavaScript library that provides an Object based solution for working with HTMLCanvas drawables as if they were tangible, separate objects. Good for lightweight game engines and mobile friendly.
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) browser based games. It is however also equally useful for creating complex graphical interfaces.
zCanvas is written in TypeScript, has no dependencies and works independently from (and thus works with) any other JavaScript framework.
zCanvas sure isn't the first JS Canvas rendering library, so to summarize:
15K gZippedYou can view some basic features in the down-and-dirty demos here.
Note these demos were written in vanilla JavaScript without the use of any libraries (other than a transpiled version of zCanvas). You can have a peek at the source to see what's going on.
zCanvas is used in proprietary image editing software, but is also the rendering engine behind Bitmappery (image editor) and Pinball Schminball (2D pinball game).
Where the HTMLCanvasElement differs from other HTML elements (in that its content isn't represented as individual nodes inside the DOM but 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 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, albeit with an abstraction layer that handles performance optimizations under the hood.
zCanvas has been optimized extensively for best performance and works a treat on mobile devices. The amount of event listeners attached to DOM elements are limited to the HTMLCanvasElement only, where the internal interactions are delegated to the Sprites visible on the canvas. Events triggering updates on the display list are automatically debounced to only render once per animation frame.
In environments where OffscreenCanvas is supported, the rendering will automatically be offloaded onto
a Worker, freeing up the main thread of your application considerably.
As mentioned before, zCanvas is also tiny and adds little overhead to your application size.
As all rendering logic resides within a single method of your Sprite, you can easily attach animation libraries such as the excellent GreenSock Animation Platform to alter the visible properties of your sprites for maximum eye candy.
Additionally, zCanvas comes with built-in frame throttling logic that allows game like implementations to update at the same speed, regardless of the rendering capabilities (e.g. achievable frames per second) of the environment.
zCanvas has been written to work within a ES module structure, but comes prebuilt and transpiled to work in either a module, CommonJS or a browser environment. zCanvas has been tested and verified to work on all half-decent, half-recent browsers.
Should you however wish to support one of the ancient browsers listed below, zCanvas up to version 5.1.10 can cater to the following:
requestAnimationFrame)*Note IE9 and some other browsers might need a polyfill for Promise at the versions listed above, but it is
likely any of those are on auto update channels and at way higher versions in the wild. It just works.
Want to view the API? You can check the zCanvas Wiki which describes all the common actors, functions and utilities while also providing documentation with regards to performance optimizations as well as catering for several use cases.
(for those craving a more hands-on approach, you can also view the source contents of the demos listed above)
You can get zCanvas via NPM:
npm install zcanvas
zCanvas is compatible with ES6 modules, CommonJS, AMD/RequireJS or can be included in a document via script tags:
import { Canvas, Loader, Sprite } from "zcanvas";
After which you can subsequently use a tool like Webpack to bundle your application for the browser.
Use zcanvas.umd.js inside the dist-folder for a prebuilt, minimized RequireJS library transpiled to JS.
require([ "zcanvas.amd" ], zCanvas => {
const { Canvas, Loader, Sprite } = zCanvas;
});
Use zcanvas.iife.js inside the dist-folder for a prebuilt, minimized library transpiled to JS.
<script type="text/javascript" src="./dist/zcanvas.min.js"></script>
<script type="text/javascript">
const { Canvas, Loader, Sprite } = zcanvas;
</script>
To those willing to contribute, the following build targets exist. The project dependencies are maintained by NPM, you can resolve them using:
npm install
You can build the module, AMD and IIFE versions of the library using:
npm run build
After which a folder ./dist/ is created which contains the different formats.
Unit tests are run via Vitest, 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.ts should have a test file functions.spec.ts.
Run
npm run typecheck
To verify whether the code contains valid TypeScript.
To generate the type definitions file, run :
npm run types
after which types/zcanvas.d.ts is created in the ./dist/-folder.
FAQs
Compact JavaScript library that provides an Object based solution for working with HTMLCanvas drawables as if they were tangible, separate objects. Good for lightweight game engines and mobile friendly.
We found that zcanvas demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.