Getting Started With DepthJS

The Basic Concept

The basic idea behind DepthJS is not full 3D in the manner of 3D models, geometry, meshes, and such. Rather, it is the simple 2.5D concept of taking your otherwise 2D planes within CreateJS/EaselJS and adding a z coordinate and 3 rotX, rotY, and rotZ rotational abilities. Basically allowing those objects to move and rotate in 3D space.

Setting up DepthJS

Setting up a scene in DepthJS is easy as long as you know how to use the CreateJS package (and more specifically the EaselJS portion) that it utilizes.

You start by setting up a stage with EaselJS and using it as normal (such as updating it on a Ticker "tick" event). But in addition to that you add an instance of the depthjs.Stage3D class to the stage. For example, if we had an EaselJS stage named mystage we would add the following:

var stg3D = new depthjs.Stage3D();
mystage.addChild(stg3D);

That's it, you now have a 3D stage inside your EaselJS stage that will allow other DepthJS defined 3D objects to be used within it.

Adding Some 3D Objects

The main two 3D display objects used in DepthJS are the Shape3D and Container3D classes. The Shape3D is meant to be a 3D object that is drawn on using its graphics property. The Container3D is meant to contain 2D EaselJS objects which then (via their container) get manipulated in 3D space. Note: the Container3D is a 3D object meant to contain normal 2D objects, not other 3D ones. For example you'd put an EaseJS Shape object in it, not a DepthJS Shape3D object in it. For containing 3D objects to be moved/rotated together go down the page to the Group3D class.

var shape3D = new depthjs.Shape3D();
shape3D.graphics.beginFill('#ff0000').drawRect(-40,-30,80,60);

var cont3D = new depthjs.Container3D();
var normalBitmap = new createjs.Bitmap('someImage.jpg');
cont3D.addChild(normalBitmap);

stg3D.addChild(shape3D, cont3D);

Now you have a red rectangle and a bitmap (contained in a Container3D) that you can move around in 3D.

Using 3D Groups

Normally containers in EaselJS can only z-sort against each other as a whole. The individual children of 2 different containers don't sort against each other. Due to this and some other semantic reasons we decided the term "group" more accurately described what was going on. However, the Group3D class in many ways acts like what you'd traditionally consider a "container". 3D elements (such as Shape3D, Container3D, and even other Group3D objects) get added to it via addChild and then move around/rotate with their containing (or in this case grouped) parent. They can nest infinitely deep within each other and create very complex scenes, however each individual child of a Group3D, no matter how deeply nested in groups, z-sorts against every other 3D object on stage. This way you can group without worry.

var g3D1 = new depthjs.Group3D();
var g3D2 = new depthjs.Group3D();

g3D1.addChild(shape3D);
g3D2.addChild(cont3D, g3D1);

stg3D.addChild(g3D2);

Two-Sided Planes

Another neat thing to do in 3D is have a plane with different visuals on front and back sides. This is easy with the PaperContainer3D class. To use it you simply assign a normal EaselJS display object of some type to its front and back properties.

var paper = new depthjs.PaperContainer3D();

var shape1 = new createjs.Shape();
var shape2 = new createjs.Shape();
shape1.graphics.beginFill('#333333').drawCircle(0,0,8);
shape2.graphics.beginFill('#ff0000').drawCircle(0,0,8);

paper.front = shape1;
paper.back = shape2;

stg3D.addChild(paper);

Rotatable Renders With Sprite3D

Another neat thing to do in DepthJS is set up a Sprite3D to go through a sprite sheet containing a 360 degree series of renders and display the frame that corresponds with the object's current rotation within the 3D world.

var sprt = new depthjs.Sprite3D(myCreateJSSpriteSheet);
stg3D.addChild(sprt);

Want To Learn More?

The DepthJS documentation is here.
There's also an example file of how to build quite a few things here.
And if you want to get started, you can download DepthJS here.