sheetengine Wiki Rss Feed

New Comment on "Rendering large scenes"

Freid001 — Sun, 03 Jan 2016 00:50:16 GMT

Hi, I'm having some problems moving the camera view around a large scene map I have created. I am creating and destroying tiles using the loadAndRemoveSheets() as demonstrated in the demo files. When I use the around keys to move around the map the correct tiles are being destroyed and create but they no not get set to the center of the canvas. Thus I can see other tiles on the map but only for as far as the canvas's height and width. Is it possible to position the newly selected center tile at the center of the canvas? Thanks

New Comment on "Collision detection"

damdirt — Sun, 05 May 2013 10:01:02 GMT

"densityMap.sheetengine.addSheets(sheetengine.sheets);" You wanted to say densityMap.addSheets(sheetengine.sheets); isn't it ?

Updated Wiki: Home

dobsonl — Fri, 22 Feb 2013 16:20:39 GMT

Sheetengine is an HTML5 canvas based JavaScript display engine for rendering isometric scenes built up of sheets. Features include:

z-ordering,
shadows with adjustable light source,
sheet intersections,
custom textures with transparent regions,
custom view transformations,
density map for collision detection,
server side support for node.js and node-canvas.

Sheetengine is the display engine of https://www.crossyards.com, the online building and gaming platform. Watch the Crossyards intro video to get a picture of what sheetengine is capable of:

Launch in another window

Examples

You can find offline examples in sheetengine-examples.zip on the Downloads page.

Documentation

Full documentation is available on the Documentation page.

A quick example: a moving/rotating object

The html markup will be very simple. We use an HTML5 canvas, and reference two javascripts: the sheetengine and our custom script in example.js:

<html>
  <head></head>
  <body>
    <canvas id="mainCanvas" width="500" height="300">
    </canvas>
    <script src="sheetengine.js"></script>
    <script src="example.js"></script>
  </body>
</html>

The following is the contents of the example.js - the implementation of our custom logic. After initializing the sheetengine we create a basesheet and a custom object made up of two sheets. We define a function to be called periodically in which we move/rotate the object and render the scene:

function init() {
  // initialize the sheetengine
  var canvasElement = document.getElementById('mainCanvas');
  sheetengine.scene.init(canvasElement, {w:600,h:400});
  
  // define a basesheet
  sheetengine.scene.tilewidth = 200;
  var basesheet = new sheetengine.BaseSheet({x:0,y:0,z:0}, {alphaD:90,betaD:0,gammaD:0}, {w:200,h:200});
  basesheet.color = '#70a050';

  // define a custom object
  var sheet1 = new sheetengine.Sheet({x:0,y:-14,z:14}, {alphaD:45,betaD:0,gammaD:0}, {w:40,h:40});
  sheet1.context.fillStyle='#F00';
  sheet1.context.fillRect(0,0,40,40);
  sheet1.context.clearRect(10,10,20,20);

  var sheet2 = new sheetengine.Sheet({x:0,y:14,z:14}, {alphaD:-45,betaD:0,gammaD:0}, {w:40,h:40});
  sheet2.context.fillStyle='#FFF';
  sheet2.context.fillRect(0,0,40,40);
  sheet2.context.clearRect(10,10,20,20);

  var obj = new sheetengine.SheetObject({x:-50,y:-50,z:0}, {alphaD:0,betaD:0,gammaD:0}, [sheet1, sheet2], {w:80,h:80,relu:40,relv:50});
  
  sheetengine.calc.calculateChangedSheets();
  sheetengine.drawing.drawScene(true);
  
  // move object around
  var maxsteps = 20;
  var steps = 0;
  var direction = {x:5, y:0, z:0};
  var rotate = false;
  setInterval(function() {
    if (rotate) {
      obj.rotate({x:0, y:0, z: 1}, Math.PI/2/maxsteps);
      if (++steps >= maxsteps) {
        steps = 0;
        rotate = false;
      }
    } else {
      obj.move(direction);
      if (++steps >= maxsteps) {
        if (direction.x == 5) { direction.x = 0; direction.y = 5; }
        else if (direction.y == 5) { direction.x = -5; direction.y = 0; }
        else if (direction.x == -5) { direction.x = 0; direction.y = -5; }
        else if (direction.y == -5) { direction.x = 5; direction.y = 0; }
        steps = 0;
        rotate = true;
      }
    }
	
    // calculate sheets and draw scene
    sheetengine.calc.calculateChangedSheets();
    sheetengine.drawing.drawScene();
  }, 30);
};

init();

New Comment on "Creating objects"

Josenzo — Wed, 13 Feb 2013 22:16:10 GMT

Have you think in create some script to convert obj in sheet object? Or take the Three.js format to render objects in sheetengine? Have a look this links: http://mrdoob.github.com/three.js/examples/canvas_materials_normal.html http://mrdoob.github.com/three.js/examples/obj/WaltHeadLo.js https://github.com/mrdoob/three.js/blob/master/utils/converters/obj/convert_obj_three.py Very nice library! :)

New Comment on "Moving / rotating objects"

dobsonl — Sun, 27 Jan 2013 01:32:39 GMT

I meant obj.centerp, sry.

New Comment on "Creating objects"

dobsonl — Sun, 27 Jan 2013 01:31:57 GMT

No, it is designed to always be positioned relative to the object center as reflected by obj.centerp. You should set canvasSize initially to a value that is big enough to enclose the object after sheet rotations. Also make sure that sheets are always positioned so that obj.centerp always stays at the center of the object (you could move all sheets relative to centerp to a distant location, but I would not consider it as a correct object model, centerp should always fall near to the geometrical centrum of sheets).

New Comment on "Moving / rotating objects"

dobsonl — Sun, 27 Jan 2013 01:27:03 GMT

Ok, I took note of the polygonorder and shadow issue. Thanks for the comments. About rotation with a distance: you could use the geometry.rotateAroundArbitraryAxis function on the obj.center object as first parameter, the axispoint as the second, axisdirection as third and angle as fourth. And also set the orientation of the object using obj.setOrientation.

Updated Wiki: Moving / rotating objects

dobsonl — Sun, 27 Jan 2013 01:00:23 GMT

Moving / rotating objects

To move an object to a specific position you can use the following function:

obj.setPosition(targetp);

where targetp is a JSON with x,y,z keys. To move an object with a displacement vector use the following syntax:

obj.move(displacement);

where displacement is a JSON with x,y,z keys. To set the absolute orientation of an object use the following:

obj.setOrientation(orientation);

where orientation is a JSON with alpha, beta, gamma keys with radian values or alphaD, betaD, gammaD keys with degree values. To rotate an object relative to its current orientation, use the following function:

obj.rotate(axis, angle);

where axis is a JSON with x,y,z keys and angle is given in radians. Please note, that the axis must be normalized before passing it to the rotate function (meaning length of axis must be equal to 1).

Examples:

obj.setPosition({x:100,y:150,z:10});
obj.move({x:10,y:0,z:0});
obj.rotate({x:0,y:0,z:1}, Math.PI / 2);
obj.setOrientation({alphaD: 0, betaD: 0, gammaD: 60});

To render the scene after changing the states of objects use the following function calls:

sheetengine.calc.calculateChangedSheets();
sheetengine.drawing.drawScene();

Be sure to only call these functions once in every frame iteration - after you have moved / rotated all your objects.

New Comment on "Moving / rotating objects"

Obi2Kenoby — Tue, 15 Jan 2013 11:21:11 GMT

Hi there, I discovered (with trial and error) that the method 'calculatePolygonOrder(polygon) is a very expensive method. Even when shadows are off, it still calculates polygon order for shadows. So maybe, make sure he doesn't calculate unnecessary shadow calculations, when shadows are off? Great library by the way!

New Comment on "Moving / rotating objects"

Obi2Kenoby — Fri, 04 Jan 2013 16:22:01 GMT

Hi, Is there an easy way to rotate an object the same way as the object.rotateSheet method? So you can add a distance from the rotation vector to it? obj.rotateSheet(sheet, AXISPOINT, axisDirection, angle); I've tried it manualy with a combination of rotation (around its own axis) and translation, but I get to many rounding errors, and it is not a very efficient way to do it. grtz.

New Comment on "Moving / rotating objects"

Obi2Kenoby — Fri, 04 Jan 2013 16:21:26 GMT

Hi, Is there an easy way to rotate an object the same way as the object.rotateSheet method? So you can add a distance from the rotation vector to it? obj.rotateSheet(sheet, <b>axisPoint<\b>, axisDirection, angle); I've tried it manualy with a combination of rotation (around its own axis) and translation, but I get to many rounding errors, and it is not a very efficient way to do it. grtz.

New Comment on "Creating objects"

Obi2Kenoby — Thu, 03 Jan 2013 11:56:06 GMT

I have a problem when I rotate all the sheets of an object. (obj.rotateSheet('allsheets..')) The bounding box of the 'canvasSize' is never changes and always stays in the same place. Is there an easy way to 'refresh' the 'canvasSize' parameter of an object? (So that the 'relu' and 'relv' parameters are calculated from the new center of the object after rotation.)

Updated Wiki: Selecting locations and objects

dobsonl — Wed, 26 Dec 2012 01:48:14 GMT

Selecting locations and objects

To determine the world coordinates of the location selected by the user we can use the following function:

var pxy = sheetengine.transforms.inverseTransformPoint(pointuv);

Parameters are:

pointuv: point in camera coordinates. JSON with u,v keys.

This can be combined with a click event to determine world coordinates the following way:

canvasElement.onclick = function(event) {
  var puv = {
    u:event.clientX - sheetengine.canvas.offsetLeft + pageXOffset,
    v:event.clientY - sheetengine.canvas.offsetTop + pageYOffset
  };
  var pxy = sheetengine.transforms.inverseTransformPoint({
    u:puv.u + sheetengine.scene.center.u, 
    v:puv.v + sheetengine.scene.center.v
  });
}

To determine if an object is selected in the scene simply use the getPointuv function to determine the object's u-v coordinates and compare it to the u-v coordinates of the mouse:

canvasElement.onmousemove = function(event) {
  // get the hover coordinates
  var puv = {
    u:event.clientX - sheetengine.canvas.offsetLeft + pageXOffset,
    v:event.clientY - sheetengine.canvas.offsetTop + pageYOffset
  };
			  
  // check if the object has been hovered
  var objhovered = isObjectHovered(puv);
}

function isObjectHovered(puv) {
  var ouv = sheetengine.drawing.getPointuv(obj.centerp);
  if (puv.u > ouv.u - 20 &&
    puv.u < ouv.u - 20 + 40 &&
    puv.v > ouv.v - 30 &&
    puv.v < ouv.v - 30 + 40)
    return true;
			
  return false;
}

Updated Wiki: Home

dobsonl — Sat, 15 Dec 2012 11:37:31 GMT

Sheetengine is an HTML5 canvas based JavaScript display engine for rendering isometric scenes built up of sheets. Features include:

z-ordering,
shadows with adjustable light source,
sheet intersections,
custom textures with transparent regions,
custom view transformations,
density map for collision detection,
server side support for node.js and node-canvas.

Sheetengine is the display engine of http://www.crossyards.com, the online building and gaming platform. Watch the Crossyards intro video to get a picture of what sheetengine is capable of:

Launch in another window

Examples

You can find offline examples in sheetengine-examples.zip on the Downloads page.

Documentation

Full documentation is available on the Documentation page.

A quick example: a moving/rotating object

The html markup will be very simple. We use an HTML5 canvas, and reference two javascripts: the sheetengine and our custom script in example.js:

<html>
  <head></head>
  <body>
    <canvas id="mainCanvas" width="500" height="300">
    </canvas>
    <script src="sheetengine.js"></script>
    <script src="example.js"></script>
  </body>
</html>

function init() {
  // initialize the sheetengine
  var canvasElement = document.getElementById('mainCanvas');
  sheetengine.scene.init(canvasElement, {w:600,h:400});
  
  // define a basesheet
  sheetengine.scene.tilewidth = 200;
  var basesheet = new sheetengine.BaseSheet({x:0,y:0,z:0}, {alphaD:90,betaD:0,gammaD:0}, {w:200,h:200});
  basesheet.color = '#70a050';

  // define a custom object
  var sheet1 = new sheetengine.Sheet({x:0,y:-14,z:14}, {alphaD:45,betaD:0,gammaD:0}, {w:40,h:40});
  sheet1.context.fillStyle='#F00';
  sheet1.context.fillRect(0,0,40,40);
  sheet1.context.clearRect(10,10,20,20);

  var sheet2 = new sheetengine.Sheet({x:0,y:14,z:14}, {alphaD:-45,betaD:0,gammaD:0}, {w:40,h:40});
  sheet2.context.fillStyle='#FFF';
  sheet2.context.fillRect(0,0,40,40);
  sheet2.context.clearRect(10,10,20,20);

  var obj = new sheetengine.SheetObject({x:-50,y:-50,z:0}, {alphaD:0,betaD:0,gammaD:0}, [sheet1, sheet2], {w:80,h:80,relu:40,relv:50});
  
  sheetengine.calc.calculateChangedSheets();
  sheetengine.drawing.drawScene(true);
  
  // move object around
  var maxsteps = 20;
  var steps = 0;
  var direction = {x:5, y:0, z:0};
  var rotate = false;
  setInterval(function() {
    if (rotate) {
      obj.rotate({x:0, y:0, z: 1}, Math.PI/2/maxsteps);
      if (++steps >= maxsteps) {
        steps = 0;
        rotate = false;
      }
    } else {
      obj.move(direction);
      if (++steps >= maxsteps) {
        if (direction.x == 5) { direction.x = 0; direction.y = 5; }
        else if (direction.y == 5) { direction.x = -5; direction.y = 0; }
        else if (direction.x == -5) { direction.x = 0; direction.y = -5; }
        else if (direction.y == -5) { direction.x = 5; direction.y = 0; }
        steps = 0;
        rotate = true;
      }
    }
	
    // calculate sheets and draw scene
    sheetengine.calc.calculateChangedSheets();
    sheetengine.drawing.drawScene();
  }, 30);
};

init();

Updated Wiki: Documentation

dobsonl — Tue, 11 Dec 2012 23:13:05 GMT

Introduction

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!

Topics

Examples

You can download examples from the Downloads page.

Features

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

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.

Z-ordering

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.

Intersections

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.).

Updated Wiki: Documentation

dobsonl — Tue, 11 Dec 2012 22:20:27 GMT

Introduction

Topics

Features

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

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.

Z-ordering

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.

Intersections

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.).

Updated Wiki: Documentation

dobsonl — Tue, 11 Dec 2012 22:16:50 GMT

Introduction

Topics

Features

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 form with the help of transparent colors.

Shadows

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.

Z-ordering

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.

Intersections

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 in the scene 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 one.

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.).

Updated Wiki: Documentation

dobsonl — Tue, 11 Dec 2012 21:58:00 GMT

Introduction

Topics

Features

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 form with the help of transparent colors.

Shadows

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.

Z-ordering

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.

Intersections

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 in the scene 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 one.

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.).

Updated Wiki: Documentation

dobsonl — Tue, 11 Dec 2012 21:57:31 GMT

Introduction

Topics

Features

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 form with the help of transparent colors.

Shadows

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.

Z-ordering

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.

Intersections

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 in the scene 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 one.

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.).

Updated Wiki: Documentation

dobsonl — Tue, 11 Dec 2012 21:55:54 GMT

Introduction

Topics

Features

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 form with the help of transparent colors.

Shadows

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.

Z-ordering

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.

Intersections

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 in the scene 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 one.

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.).