Home Labs Galleries PetitOn

Using Sandy 3D Flash Library


This tutorial applies to Sandy 1.1 for AS2.
If you are using the later 1.2 version, you should read the FAQ / Sandy 1.2 Issues

There is an Italian translation of the tutorial by Davide Beltrame.

Here is the tutorial for Sandy 3.0x (AS3), which by no means makes this one obsolete ;)


Part 1, Introduction
Part 2, Primitives
Part 3, The Interactive Camera
Part 4, Transformations
Part 5, Using Interpolators
Part 6, Faces and Skins
Part 7, Working with Sprites
Part 8, Using Lights and filters
Part 9, User Interactions

Later in this series I'll possibly talk about

Part 1, Introduction

This tutorial walks you through Thomas Pfeiffer's Sandy 3D Flash API and how to use it.
New parts are added from time to time, so if you find it useful, make sure to come back.

Sandy is an object oriented ActionScript 3D library, for programming 3D scenes for the Flash Player. It is work in progress, and currently (2006-11-24) the version is 1.1,  ActionScript 2, with a 1.2 version under way.  An upgrade to ActionScript 3 for Flash Player 9 is projected, which will simplify some aspects and presumably run faster.

To work with Sandy, you need to download the Sandy 3D Flash API from Sandy's web site. Take the opportunity to read the tutorials and API documentation at the Sandy site and join in the Sandy support forum.

To run the examples in this tutorial you need Flash Player 8.0 or later. If you need to upgrade your flash Player you'll find it on Adobes site.

You also need a Flash development tool. For this tutorial, I have used the Macromedia ( now Adobe ) Flash 8 authoring tool. If you want to use another ActionScript compiler, such as the MTASC, you will have to slightly change the AS code in the examples.

Example code for this tutorial can be downloaded as ZIP archives, linked at the beginning of each part.

Now let's get down to business! First out is an overview of Sandy in the form of a traditional scene graph. If you are the kind of programmer, who rather jumps head first into the code pool, just jump to Part 2, Primitives!

The Sandy Scene Graph

To understand the structure a 3D world, we must have a way of describing it. Normally the concept of a scene graph or a tree is used. The scene graph describes the relationship between the different parts making up the world. Traditionally the world itself is represented by a "World" or "Universe" object. The tree is comprised of node's,  branches and leaves, rooted in the world object's Root Node, or Locale.

Branches extend from the single Root Node, and contain other Node's with different properties and responsibilities. In Sandy a Node is a Group, that groups together visible 3D objects or applies transformations to its children.

There are three types of nodes in Sandy, the Group, the TransformGroup and the Object3D.

The Group and TransformGroup are branch nodes, which means they can have children in a sub tree or branch. A Group is a general grouping object, while a TransformGroup is used to apply a transformation, such as a rotation or translation to all its children.

An Object3D represents a visible 3D object in the world. It is a Leaf node, i.e. it cannot have any child nodes.

If we look at the simple scene graph above, on the left we have a branch with a TransformGroup and another branch group. It ends in a Leaf node, the Object3D, with two associated property objects called Geometry and Appearance. The Geometry contains the data necessary to build the geometrical shape of the object, and the Appearance contains data for the looks of the object, such as textures and colors.

To the right in the graph we have the View Platform, responsible for the users view of the world. The groups we see here are not really part of the visible world, but represents the users view of the world and the physical environment, such as screen and user input. Interaction with the user is handled by an event handling system, and most of the objects and can take event subscribers and broadcast events.

In Sandy's view platform the branch and transform groups are part of the Camera3D object, and the View Object doesn't exist as a concrete object, so don't search for it ;). The View represents the data necessary to calculate the users 2D view of the world. It contains the Camera3D and and is associated with a screen object, on which all visible objects render themselves. You can have multiple cameras with associated screens.

Coding the Scene Graph

After the abstract description of the Sandy world, let's make it simpler by coding the scene graph in ActionScript!

It may not be an application to run, just a sketch to show the principles. You'll find plenty of both runnable and running applications, when we get to the examples.

var world:World3D = World3D.getInstance(); 	// Our 3D world
var root:Group = new Group(); 		// Create a new branch group
world.setRootGroup( root );		// Set it as the world's root group

// === The visible branch ===
// Create a transform group and a transform to apply
var tGroup:TransformGroup = new TransformGroup();
var rotation:Transform3D = new Transform3D();
// Tell it to rotate its children 
// Set the transform to the TransformGroup
tGroup.setTransform( rotation );

// Create the visible object, a cube
var cube:Object3D = new Box( 50, 50, 50, 'tri' );
// Add the cube as a child to the TransformGroup 
tGroup.addChild( cube );
// Add the TransformGroup as a child to the root group
root .addChild( tGroup );
// === The view branch ===
// Create the screen to draw on
var screen:ClipScreen 		
	= new ClipScreen( this.createEmptyMovieClip('screen', 1), 200, 200 );
// Create the camera and associate the screen
var camera:Camera3D = new Camera3D( 700, screen );
// Set the position of the camera within the world
// Add the camera to the world
world.addCamera( camera );
// Finally, tell the world to start rendering

Still there? Thanks for staying with me.
It's time to start programming, and in the first coding session we will meet the primitives of the Sandy world, such as Boxes, Cylinders and Hedra.

But first Let's a nice cup of Java!