In this first tutorial we will see how to work with a simple primitive: the Box. The same tutorial can be used to create all the other primitives. Before starting the tutorial we need to have a “code strategy”, to me this means we need to define a way we will write our code. In order to achieve this goal I will follow the suggestion given by Petit. Basically the idea is this one:

• In the constructor of the class we create the Camera and Scene
• We place the creation of all the objects in a private method named “createScene()”
• We add an EventListener that will take care of the rendering and user interaction (if any)

We will use the same approach for all our tutorials.

We need to define two class: one called Example001.fla and one called Example001.as. You will find both files in the attached archive.

example001.rar

The first file represent the CS3 object that holds basic information about frame rate, dimension of the stage and the link to the Document class. The first files only required two important things to set up: the dimension of the stage and the name of the Document class.

We will set up the dimension of the Stage as: 300px X 300px, while the Document class will be called Example001 (without the extension .as).

The new updated version can be found here:

example001_v3.1.1.zip

In this section we report the AS code as a reference, and it will be explained in the next paragraph.

package {
  import flash.display.Sprite; 
  import flash.events.*;
  import sandy.core.Scene3D;
  import sandy.core.data.*;
  import sandy.core.scenegraph.*;
  import sandy.materials.*;
  import sandy.materials.attributes.*;
  import sandy.primitive.*;

  public class Example001 extends Sprite {
    private var scene:Scene3D;
    private var camera:Camera3D;

    public function Example001() { 
      camera = new Camera3D( 300, 300 );
      camera.z = -400;

      var root:Group = createScene();

      scene = new Scene3D( "scene", this, camera, root );

      addEventListener( Event.ENTER_FRAME, enterFrameHandler );         
    }

    private function createScene():Group {
      var g:Group = new Group();
 
      var box = new Box( "box",100,100,100);

      box.rotateX = 30;
      box.rotateY = 30;

      g.addChild( box );

      return g;
    }

    private function enterFrameHandler( event : Event ) : void {
      scene.render();
    }
  }
}

Let's see what the code does:

• First of all we have the declaration of the package. For now, we will leave it blank.

package {
   ...
}

• Next there is a section for importing Sandy and Flash classes. You can identify all the Sandy classes since they start from the sandy package (and if you will browse sandy folder, you will find the classes source there).

   import flash.display.Sprite; 
   import flash.events.*;
   import sandy.core.Scene3D;
   import sandy.core.data.*;
   import sandy.core.scenegraph.*;
   import sandy.materials.*;
   import sandy.materials.attributes.*;
   import sandy.primitive.*;

• Inside the class declaration, you can find two private variables of type Scene3D and Camera3D.

  private var scene:Scene3D;
  private var camera:Camera3D;

The first variable represents the “scene” of the objects. Think of it as the container of everything you are going to display/use. In a previous Sandy version, you used to define a “World” object, now it's not required anymore, and I think this is a clearer way to build projects.

• Inside the constructor, the first thing we do is to set-up the Camera3D. In the next section, we'll move it backward 400px to have a wider picture of the entire scene.

camera = new Camera3D( 300, 300 );

The camera is the user view point into the scene. It can be located inside the scene and we can tell the camera where to look at. (We will discuss how the camera works, in another tutorial). It's important to note that the setting of the camera Camera3D( 300, 300 ) is the same as the setting we have placed in the .fla files. Indeed, it is common to have the viewport with the same dimension as the stage.

• Next, we need to position the camera: the default position of the camera is on point(0,0,0).

camera.z = -400;

Setting camera to -400 just means that we are stepping backward of 400px from the origin of the Scene. The Origin of the Scene is always placed in the middle of the viewport.

• Next we create a “Group” object.

var root:Group = createScene();

This is the root group of all our objects inside the Scene. You must think to model all the relationship between our objects as a “tree” where each node of the tree can be: a transformation group, a simple group, or a shape3D object. This root group is defined in the private method called createScene(), that will be discussed later.

• Next we define the Scene3D.

scene = new Scene3D( "scene", this, camera, root );

In this case we pass 4 variables in its constructor: the name of the scene, the container of the scene ( we use “this” since our class extends the basic AS class called Sprite, which is a container), the camera to watch the scene, and the root node of our object tree.

• Last but not least we add an event listener that will render the scene.

addEventListener( Event.ENTER_FRAME, enterFrameHandler );

In this particular case we do not need to have an event listener since we are not doing anything and we could just place the command scene.render(); here, but for good practice we will push this command inside the event handler.

• We now consider one of the main part of this tutorial: how to build the objects of the scene? in our example a simple cube. The first thing we do in the createScene() method is to define the Group element that will be passed back in the class constructor to be used as a parameter for the scene3D object.

var g:Group = new Group();

• We then create a simple “cube” of 100 px for each side.

var box = new Box( "box",100,100,100);

• We then rotate the cube 30 degrees about the X and Y axes to create the illusion of 3D; otherwise, the rendering of the box will look like a flat square.

box.rotateX = 30;
box.rotateY = 30;

• And at the end, we need to add the created object to the Group, otherwise our engine will not know what to render.

g.addChild( box );
return g;

Enough for coding, let's see the result.

Well that's all for the first basic example. I wanted to guide the reader to all the basic steps since I know how difficult is to start to learn a new API. Do not worry, in the next tutorial I will not use so many words, and will concentrate on code.