This is a refreshed version of my previous tutorial, where I explained the important differences you need to know to get started with FlashDevelop and Sandy 3D. I won’t go into setting up FlashDevelop, all details mentioned in the previous post are still valid.

But the Sandy 3D Engine has changed slightly (for the better, mind you). I’ll point out what’s new and give some additional examples. But first, lets look at the result:

The code consists of 4 main parts, I’ve split them up, but if you want, you can go right ahead and download the entire FlashDevelop workspace:

download the full source and FlashDevelop project

1. Using bitmaps

I’ve gone over this a few times, but it bears repeating as this is something you won’t use in CS3. In FlashDevelop, you add a bitmap in the lib directory. With this done, you put an embed tag in your code (or double click, FD can usually do this for you) and on the next line you put the class name you want to assign to this embedded resource. As a final step, you need to instantiate the object.

It sounds much more complicated then it is, just look at the code:

1
2
3

[Embed(source = '../../../../lib/aqua.png')]
private var aquaClass:Class;
private var aquaBitmap:Bitmap = new aquaClass();

2. Creating and texturing the 3D objects

With the bitmaps imported, we can use them to texture objects. This is done by setting the objects appearance. The appearance has a few options, but for now, we’ll only set one material on it. The material is the object that actually contains the texture.

For instance, the background image when you move over the cube is a Plane3D object on which we set an appearance that consists of a BitmapMaterial:

1
2
3
4

plane = new Plane3D( "thePlane", 200, 200);
material = new BitmapMaterial(beamsBitmap.bitmapData);
material.lightingEnable = true;
plane.appearance = new Appearance(material);

More complicated objects can contain multiple surfaces. If you want to set them all alike, just use the code above, but you can also address them individually. You use the “aPolygons” collection for that. Depending on the object and the parameters you choose, you might need to experiment a little to find the correct polygons.

For instance, this code sets the front and back side of the box in the example:

1
2
3
4
5
6

var material:Material = new BitmapMaterial(logoBitmap.bitmapData);
material.lightingEnable = true;
var app:Appearance = new Appearance( material );
var i:int;
for (i = 0; i < 4; i++ )
    myBox.aPolygons[i].appearance = app;

3. Listening to events

While the way you handle events hasn’t changed since previous versions of Sandy, the MOUSE_MOVE event was removed. It is no longer handled, probably because of performance reasons, but I’m not entirely clear on the reasons.

The official tutorials also now suggest to put the event handling on the container, this is part of your object that is actually displayed. If you can, I would suggest to use this, because it’s probably a lot quicker.

There are cases where you might like to obtain the Shape3DEvent. Take a look at the tutorial on the Sandy site to decide if you’d need that. But to reiterate, the Sandy event system no longer supports the MOUSE_MOVE event.

In the example, the event listener for the mouse over event looks like this:

1
2
3
4
5

    myBox.container.addEventListener(MouseEvent.MOUSE_OVER, overHandler);
private function overHandler(event:MouseEvent):void {
    if(!zoomedIn)
        g.addChild(plane);
}

4. Setting up the scene and camera

New in Sandy3D (although it’s not that new any longer) is the removal of World3D. World3D was a singleton class, which meant that you could have only one in your program. It has now been replaced by Scene3D, of which you can create and render multiple in your program.

So if you want, you can have different scenes or different cameras in your program. Cool, but don’t overdo it, keep in mind that every scene you add will also add to the processing power required.

Setting up the camera is exactly the same as before:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

private function init(e:Event = null):void
{
    removeEventListener(Event.ADDED_TO_STAGE, init);
    // entry point
    camera = new Camera3D( 300, 300 );
    camera.x = 0;
    camera.y = 50;
    camera.z = -200;
    camera.lookAt(0,0,0);
 
    var root:Group = createScene();
 
    scene = new Scene3D( "scene", this, camera, root );
 
    addEventListener( Event.ENTER_FRAME, enterFrameHandler );
}

I haven’t discussed the tweening used to move the cube in the program. If you’re interested, please let me know and I’ll write another blogpost. Otherwise, you now have all parts to get started with 3D development in FlashDevelop.

Good luck and don’t forget to show those results!

download the full source and FlashDevelop project

A recap of the ActionScript 3.0 YouTube player series:

• Getting a list of videos (and some project setup)
• A bit about how the Flash stage works and fullscreen
• Install a php script to get the video parameters
  
• Getting the parameters for a video
• playing the video using Flash’s FLV player classes [this post]

Constructing the YouTube video URL

There are several ways to get to this one. You could fire up FireBug and check the network logs, or you could check Shane’s code and open his Main.as class. Skip to line 67 and you’ll see:

1
2
3

case YouTube.VIDEOID :
	fvc.play(YouTube.FLVUrl + e.value.id + "&t=" + e.value.t);
	break;

What this means: to construct the full URL to a YouTube Flash video file, you take the base URL and add both the video id and the T-parameter as arguments. An example URL might look like this:

http://www.youtube.com/get_video?video_id=v6ICEpYEcD8&t=OEgsToPDskIltmXs7gZ89kc2a3Z1SRGN

(I have not linked the URL, as it probably won’t work, because the T-parameter changes over time)

Streaming the FLV

For this one I’m going to use the existing ActionScript 3 classes. In particular flash.net.NetConnection and flash.net.NetStream. In the following code I’m adding the language reference example to the already existing code.

What happens might not be clear when you look at the code. That’s because we use a lot of event handlers. But if you take your time and go over the code it will become clear. What goes on is this:

1. We create a NetConnection.
2. If this goes well the netStatusHandler is called with the event “NetConnection.Connect.Success”. This in turn will launch the YouTube query to locate a video and create the URL to play it.
3. This part we’ve already discussed in previous posts:
   1. Create the YouTube object and add listeners.
   2. Get a list of videos for a tag.
   3. When that lists returns, select the first one and get the T-parameter from our PHP script
4. We construct the YouTube FLV URL (see above) and call the play method.
5. The play method creates a NetStream and Video object and starts the play the video.

Everything else you see is basically code to handle possible errors:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

package
{
  import com.flashdynamix.events.CustomEvent;
  import com.flashdynamix.services.YouTube;
  import flash.display.Sprite;
  import flash.events.AsyncErrorEvent;
  import flash.events.ErrorEvent;
  import flash.events.Event;
  import flash.events.NetStatusEvent;
  import flash.events.SecurityErrorEvent;
  import flash.media.Video;
  import flash.net.NetConnection;
  import flash.net.NetStream;
 
  public class Main extends Sprite {
    private var connection : NetConnection;
    private var stream : NetStream;
    private var video : Video;
    private var yt : YouTube;
 
    public function Main():void {
      if (stage) init();
      else addEventListener(Event.ADDED_TO_STAGE, init);
    }
 
    private function init(e:Event = null):void {
      removeEventListener(Event.ADDED_TO_STAGE, init);
 
      trace("creating NetConnection");
      connection = new NetConnection();
      connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
      connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
      connection.connect(null);
    }
 
    private function netStatusHandler(event : NetStatusEvent):void {
      switch (event.info.code) {
        case "NetConnection.Connect.Success":
          connectStream();
          break;
        case "NetStream.Play.StreamNotFound":
          trace("Unable to locate video");
          break;
        case "NetStream.Play.Start":
          trace("start playing");
          break;
        case "NetStream.Play.Stop" :
          trace("stop playing");
          break;
      }
    }
 
    private function securityErrorHandler(event:SecurityErrorEvent):void {
      trace("securityErrorHandler: " + event);
    }
 
    private function connectStream():void {
      trace("start YouTube search");
      yt = new YouTube();
      yt.addEventListener(Event.COMPLETE, onLoaded);
      yt.addEventListener(ErrorEvent.ERROR, onError);
      yt.videosForTag("lego");
    }
 
    private function onLoaded(e:CustomEvent):void {
      switch (e.id) {
        case YouTube.SEARCH :
          trace("search finished");
          try {
            trace("first item : " + e.value.items[0].title + " - " + e.value.items[0].link);
          } catch (evt:ArgumentError) {
            trace("ERROR : No Videos For Tag");
          }
          trace("requesting the video id and t-parameter");
          yt.videoId(e.value.items[0].link);
          break;
        case YouTube.VIDEOID :
          trace("loaded: video id = " + e.value.id + " and T-parameter = " + e.value.t);
          play(YouTube.FLVUrl + e.value.id + "&t=" + e.value.t);
          break;
      }
    }
 
    private function onError(e:ErrorEvent):void {
      trace("IOError : " + e );
    }
 
    private function play(url:String):void {
      trace("playing: " + url);
      stream = new NetStream(connection);
      stream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
      stream.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler);
      video = new Video();
      video.attachNetStream(stream);
      stream.play(url);
      addChild(video);
    }
 
    private function asyncErrorHandler(event:AsyncErrorEvent):void {
      // ignore AsyncErrorEvent events.
    }
  }
}

I’ve put all files we used in the tutorials in a handy zip file. Just expand and open in FlashDevelop.

Conclusion

In this 5th and final post of the series I have shown how to actually stream the YouTube FLV. It was particularly easy because Flash already has everything you need. It’s a matter of finding the right classes and using them.

That wraps up the 5 part tutorial. Feel free to leave a comment if you found this useful or not. I’m also open for suggestions for improvements or other subjects for future tutorials.

Image credit.

One of the main bumps you will run into when coding Sandy3D, or basically any kind of graphical applet is loading resources, such as images. If you are working inside Adobe’s Flash environment, this all comes pretty naturally. But open source tools such as FlashDevelop do not have a graphical component, so you have to create your multimedia assets in other applications (Paint.NET is nice).

Before you get started, have a look at this MovieClip vs Sprite comparison and this tutorial on starting with AS3 to understand why our base class extends Sprite and how events are handled. And if you want to know where all this is going, the idea is to recreate something similar to this in ActionScript 3 and FlashDevelop and then afterwards add some 3D goodness to it (3D objects, maybe 3D camera).

One important thing to know about event handlers is: don’t attach them to your main Sprite. This won’t work:

1
2
3
4
5
6
7
8
9
10
11

public class Test extends Sprite {
  public function Test() {
    graphics.lineStyle(1);
    graphics.beginFill(0xFF8000);
    graphics.drawCircle(50, 50, 10);
    addEventListener(MouseEvent.MOUSE_DOWN, down);
  }
  private function down(evt:MouseEvent):void {
    trace("down");
  }
}

My intuition was that it would attach mouse down events to the circle. But it does not. In most cases you would want to capture the whole sprite anyway. The solution is to add your listeners to the “stage” object. See the the examples below for a demonstration of this.

In Flash, images come in 2 types. Vector drawings or bitmaps. Pretty much all graphics you see on the Internet are bitmaps, every pixel in the bitmap is defined. A program such as Paint.NET will create those for you. Vector images are a different beast. Those images define the lines and forms that are used. In the example above, a circle is drawn, not a collection of points. The advantage is that the image quality will be a lot higher and it is possible to zoom in on the Flash applet without loosing quality. But (there always is a but) you can only draw those in the Adobe Flash editor. You can use existing .fla files with vector drawings in them, but you can’t make your own, unless you pay for the program. Either that or you would have to handcode everything. A future post will probably deal with that.

But this post deals with bitmaps. We will start from the following simple mouse-follow applet and replace the circle with a bitmap:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

package  {
  import flash.display.Sprite;
  import flash.events.Event;
  import flash.ui.Mouse;
 
  public class Test extends Sprite {
 
    private var circle:Sprite = new Sprite();
 
    public function Test() {
      Mouse.hide();
 
      circle.graphics.lineStyle(1);
      circle.graphics.beginFill(0xFF8000);
      circle.graphics.drawCircle(0, 0, 10);
      addChild(circle);
 
      stage.addEventListener(Event.ENTER_FRAME, mouseMove);
    }
    private function mouseMove(evt:Event):void {
      circle.x = mouseX;
      circle.y = mouseY;
    }
  }
}

This is the result:

I like to store all my resources in a separate directory, called “library“. It’s not a the “real” library that you have in the Flash IDE, but it’s close enough. I’m using this crosshair bitmap:

Once we have an image, it’s time to embed it. ActionScript 3 has an “Embed” tag that will allow you to put images in an applet. See this link for the complete explanation. Basically, you define a private Class variable, put the cursor just above it and double click on your image. FlashDevelop will automatically insert the correct “Embed” tag in your code. A little tweaking to get the correct size and there you are:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

package  {
 
	import flash.display.Bitmap;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.ui.Mouse;
 
	public class Test extends Sprite {
 
		[Embed(source='library/crosshair.png')]
		private var crosshairClass:Class;
		private var crosshair:Bitmap = new crosshairClass ();
 
		public function Test() {
			Mouse.hide();
 
			crosshair.height = 30;
			crosshair.width = 30;
			addChild(crosshair);
 
			stage.addEventListener(Event.ENTER_FRAME, mouseMove);
		}
 
		private function mouseMove(evt:Event):void {
			crosshair.x = mouseX - 15;
			crosshair.y = mouseY - 15;
		}
 
	}
 
}

As you will notice, the quality of the scaled down image is not that good, but using a larger sprite allows you to zoom in with little quality loss. Next time, I’ll show you how to fix this.

Before I continue any Sandy3D or Flash tutorials, I’d like to go into another method of getting multimedia content in the browser: Java applets. One major advantage of applets is the possibility to use hardware acceleration inside the browser. This will tremendously increase the capabilities, quality and speed of the displayed pictures. None of the Flash 3D engines even come close.

As always, there is a drawback. Access to hardware requires more security privileges and is operating system dependant. Java solves a little, but at some point you need to go to the hardware. Enter Lightweight Gaming Library (LWJGL). It allows crossplatform access to the OpenGL library. Combine this with some of the Java security features and you’ve got a winner.

If you click on the image above, a new window should open that loads the applet. After everything’s done loading, you should get a security warning. I haven’t paid for a certificate, so you will have to trust me that the applet won’t mess with your system. Let me know if you see any errors. If you get a red cross, right click and open the Java console. I’m very interested in seeing how well everything performs across different browsers and OS’s.

OpenGL is still pretty lowlevel so to make things a little easier, I’ve added jMonkeyEngine into the mix. At the core jME is a scenegraph based 3D engine, but it adds many more libraries that are useful for 3D and game development, such as the physics library.

jME already has a nice tutorial on the WIKI, however there are a few things mising. If you want to get the tutorial running, you can just follow along with the example right until you’ve build the example and packaged it into a jar file (using a IDE like NetBeans or Eclipse will make this very easy). Now lets assume you have the jar file with your applet class. Copy it into your ‘release’ directory. This is the directory you will upload to your site. To get it running, you need a few libraries (most of these you probably already have downloaded during the development of the applet):

• LWJGL applet libraries: From that link, download from release 1.1.4, the file lwjgl_applet-1.1.4.zip. Unzip it and copy lwjgl.jar, lwjg_applet_util.jar and natives.jar into your release directory.
• JME libraries: Download and unzip version 1.0 and copy jme.jar and jme-awt.jar in the directory.
• JME test libraries (give you easy access to a few images and objects): Again get version 1.0 and copy jmetest.jar and jmetest-data-images.jar into the directory.

Because jME needs to access the texture file, the applet needs to be signed. LWJGL is alrady signed, so no problem, however, the jar file you created yourself also needs to be signed. Open a command prompt window:

• If you don’t have a certificate, create one: keytool -genkey -alias key_name
• Change to the path where the jar file is located
• Sign the file: jarsigner my_jar.jar key_name

Now you can go ahead and create the index.html. You can take the one from the tutorial, however, you need to add a few libraries to the “archives” parameter. Make sure all jar files mentioned above are referenced:

archive=”lwjgl_util_applet.jar,lwjgl.jar,natives.jar,jme.jar,jme-awt.jar,jmetest.jar,jmetest-data-images.jar,my_jar.jar”

And that should do it. Load the index page in your browser to see the result. Here’s a screenshot of what you should see:

3D for the web, it has been coming to you ever since virtual reality was the mot-du-jour and VRML the format to support, but it’s still not there yet. The latest craze now are Flash 3D engines. There are three worth mentioning: Papervision3D, Away3D and, the one I’ll be talking about here, Sandy3D.

Flash development (or more specificically Action Script) is all fine and dandy, but it does require an investment in some software products. If you’d go the route of least resistance, you need Adobe Creative Suite 3 ($999 for the web standard edition) and some 3D software, Autodesk 3ds Max ($3495 for 2009 edition) is the most widely supported. I don’t know about you, but as a hobbiest that leaves me only 2 options. Pirate the software, or go look in the free and open source community.

Luckely there are a few options for creating Flash and 3D. This post is about the Flash part. FlashDevelop is an open source development environment for Flash Actionscript and integrates seamlessly with the Flex SDK (free from Adobe). As you will see in this post, it is missing the designer features that the CS3 tools have (vector graphics, timeline editing), but as far as Actionscript editing goes, it’s on par with anything out there and better than most.

As an introduction, here is a short tutorial on how to get the Sandy3D getting started video example working on FlashDevelop.

First set up your environment

1. If you want to use the latest release of Sandy3D, as we will do in this tutorial, get and install TortoiseSVN.
2. Get FlashDevelop (currently 3.0.0 beta 6) and the Adobe Flex SDK. Install both.
3. Start up FlashDevelop and open Tools > Program Settings… Click on AS3Context on the left and fill in the Flex SDK location:

Lets get started

1. Watch the getting started video and follow along.
2. Create a project directory, eg “New Sandy Project”.
3. Inside it, create a “sandy” directory and use TortoiseSVN to check out the latest Sandy3D release, as shown in the video. Use the current release URL here at your own risk (best to follow the video and find the latest release yourself)
4. In your project folder, create a Demo1.as file.
5. No need to create the Demo1.fla file as this is not used by FlashDevelop.
6. Unlike with CS3, you will need to manage your resource library (images, etc) by hand. So create a “library” directory inside your project folder.
7. Search two images on the Net and place them in the library directory. One will be used for the background, one will be used as a texture for the plane object we are going to draw.
8. Open FlashDevelop and start a new Project: Project > New Project...
9. Choose an empty ActionScript3 project. Enter any project name you like. In the location field browse to the project directory you created. Leave the package name empty and click OK.
10. Select an output file name in Project > Properties…. For instance “New Sandy Project.swf”.
11. In the Project view, open the library directory and right click on both images and select “Add to library“.
12. Again in the Project view, right click on Demo1.as and select “Always compile“. Double click on the file to open it. You should have a view similar to this one:

Enter the code

This one is the bulk of the work. In the Demo1.as view, type the code for the example:

package
{
	import flash.display.Sprite;
	import sandy.core.scenegraph.Camera3D;
	import sandy.core.scenegraph.Group;
	import sandy.core.scenegraph.Shape3D;
	import sandy.core.World3D;
	import sandy.materials.Appearance;
	import sandy.materials.WireFrameMaterial;
	import sandy.primitive.Plane3D;

	public class Demo1 extends Sprite
	{
		private var world:World3D;

		public function Demo1()
		{
			world = World3D.getInstance ();
			world.container = this;

			world.camera = new Camera3D (this.width, this.height);

			var scene:Group = new Group ('scene');
			var shape:Shape3D = new Plane3D ('plane', 100, 100, 10, 10);
			shape.appearance = new Appearance (new WireFrameMaterial ());

			scene.addChild (shape);
			scene.addChild (world.camera);
			world.root = scene;
		}
	}
}

Hit ctrl-enter or select the little play button (test movie). Everything should compile and run fine, but you will see an empty movie. FlashDevelop automatically imports classes for you, so if you typed in everything by hand, like in the video, you could skip the step where you locate the missing import statements.

There are two reasons the code is not displaying anything:

1. The “this” object does not have a width and height. In the demo video a vector image is attached as background. I don’t think this is possible with FlashDevelop only (let me know if it is), so my option is to get a bitmap from the net “gradient.jpg” in this case and use that one. We can do this by embedding an image. Just before the “private var world:World3D;” line, add this:

[Embed(source = 'library/gradient.jpg')]
private var gradient:Class;

And now add this to the main sprite class. Just before “world = …” add

this.addChild (new gradient ());

Run again and you should already see your background.

2. The second issue is that the camera is not pointed in the right direction. Add the code as instructed in the video. Your entire program should now be:

package
{
	import flash.display.Sprite;
	import sandy.core.scenegraph.Camera3D;
	import sandy.core.scenegraph.Group;
	import sandy.core.scenegraph.Shape3D;
	import sandy.core.World3D;
	import sandy.materials.Appearance;
	import sandy.materials.WireFrameMaterial;
	import sandy.primitive.Plane3D;

	public class Demo1 extends Sprite
	{
		[Embed(source = 'library/gradient.jpg')]
		private var gradient:Class;

		private var world:World3D;

		public function Demo1()
		{
			this.addChild (new gradient ());

			world = World3D.getInstance ();
			world.container = this;

			world.camera = new Camera3D (this.width, this.height);

			var scene:Group = new Group ('scene');
			var shape:Shape3D = new Plane3D ('plane', 100, 100, 10, 10);
			shape.appearance = new Appearance (new WireFrameMaterial ());

			scene.addChild (shape);
			scene.addChild (world.camera);
			world.root = scene;

			world.camera.setPosition ( -100, -100, -100);
			world.camera.lookAt (0, 0, 0);
			world.render ();
		}
	}
}

Run the movie again and the plane should be visible.

There’s a little more in the video than that, but that’s for another post. At least you should already be well on your way to running all the other Sandy3D tutorials.