This project is read-only.


Sheetengine was originally designed to be the display engine for a social building and gaming project called Crossyards. This project allows users to build custom scenes made up of stand-alone sheets - that can be positioned and oriented according to the user's will - using a basic HTML5 editor interface. To create the editor I was looking for something that was light-weight, cross-browser compatible (HTML5) and could handle isometric projections with the following three features: shadows, z-ordering, intersections. I deliberately chose isometric as I believe real 3D is simply too much for the web and I also wanted to be able to visualize the rendered scenes with extremely performant HTML4 methods (image pyramids) that require the projection output be independent of the camera position. As I introduced custom applications and games in Crossyards the engine soon was somewhat turned into a game engine with extended functionality to support object and camera movements also including collision detection. Since I am a fan of open source I decided to release it under the MIT license, maybe it will be useful for others as well!




You can download examples from the Downloads page.


Isometric rendering

The concept of sheetengine is to draw a 3D world with isometric projection by defining sheets. A sheet is basically a (small) rectangular HTML5 canvas that is drawn onto the main canvas using isometric transformations. This means that defining texture of a sheet can be done by simply drawing on the 2D rendering context of the sheet canvas. The engine supports opacity, but shadows will only take fully transparent or opaque pixels into account. Therefore the sheets can take any shape with the help of transparent colors.


Shadows are generally very important when rendering 3D scenes but when using isometric projections they are crucial. If you don't draw shadows you are simply unable to tell where the objects are located in space by looking at the rendered image. Sheetengine draws shadows cast by sheets both on the static ground and on other sheets taking fully transparent colors into account. For this a single directional light source is used that can be adjusted in terms of direction and the darkness of drawn shadows.


Sheetengine is not a tile-based display engine: the position of sheets can be arbitrary, therefore z-ordering of sheets is a bit more complex problem than a simple equation. The algorithm used guarantees that sheets will be drawn onto the main canvas in the correct order.


Since the position of sheets is allowed to be arbitrary, it can easily happen that the z-order of two sheets can not be determined in case they intersect each other. The library will automatically calculate the intersections of sheets and the resulting polygons can be rendered in the correct order. This algorithm is quite resource-intensive so intersection of moving objects and static sheets is disabled by default (objects are usually not allowed to go through sheets anyway) but can be turned on manually.

Object animation

SheetObjects are objects made up of sheets. These objects are allowed to be moved/rotated/animated in the scene allowing simple games to be implemented using the library. For every object a temporary canvas is created for rendering - this canvas is used by the engine to update the modified regions only, for optimized performance.

Collision detection

Detecting if an object has bumped into a wall or is moving up a stairway is done using a density map. The density map contains points of all sheets in the scene sampled using a specified granularity.

Rendering customizations

Many rendering attributes can be customized. Size of sheets and base sheets, colors of shaded sheets and shadows, direction of light source, etc. It is also possible to define your own projection model by providing custom transform functions in case you didn't like the built-in view.

Rendering on server-side

The library is built in a way so that it can be used to render isometric scenes on the server-side using node and node-canvas. This can come very handy if you want to generate images on the server-side to create image pyramids and display isometric scenes in pre-HTML5 browsers (IE8, etc.).

Last edited Dec 11, 2012 at 11:13 PM by dobsonl, version 10


No comments yet.