Away3D Basics 1 - A simple Away3D class explained
This tutorial is the first in a series about Away3D, a powerful real-time 3D engine for Flash or Flex. This tutorial explains a very simple Away3D class line by line so that those that still use Actionscript 2 or have a designer background will be able to understand what is going on in the rest of the tutorials.
No matter what you want to do in Away3D, there's some things that you'll always need to set up. The "Basic" tutorials will explain the Scene, View, Camera, Primitives, Textures and explore some of the possibilities. Each example in the series will be organized as Actionscript Classes so they can be used in both Flash and Flex.
If you are new to 3D on computers, you might want to read our introduction that explains the core 3D concepts. This tutorial also contains the source for 6 other Away3D projects that may be worth checking out. To run the example files, you will first need to set up Away3D on your computer. When you have the Away3D source files and your software is set up, you can open, explore and export the examples in this tutorial by just placing them in your project directory. 3D is processor intensive, so all the examples use a file called Cover.as that you must also download to your project directory to be able to run the examples.
3D on computers use cliches that we are used to from the movies. The four things we will always need is a Stage, a Camera, a View and something to look at. Thanks to a lot of "default" properties, you only need to set up a view to get get started with Away3D.
A minimal Away3D class
The following is a minimal class that makes use of the default camera and stage in Away3D. If you understand what happens in the file listing below, just skip ahead to the next tutorial about the View. For those that are not too familiar with reading Actionscript 3 (AS3) code, read on and we'll explain this line by line.
package {
import away3d.containers.View3D;
import away3d.primitives.Sphere;
import flash.display.Sprite;
public class Basic01 extends Sprite {
public function Basic01() {
var view:View3D = new View3D({x:200,y:200});
addChild(view);
var sphere:Sphere = new Sphere();
view.scene.addChild(sphere);
view.render();
}
}
}
Line 1: AS3 requires that all classes must be in a package. For simplicity, we are using an unnamed package (also called the default package).
Line 2-4: To be able to use Away3D, we need to import the classes containing the functionality we are going to use, as well as the standard Sprite class.
Line 5: This is the name of our example class. This class "extends" the Sprite class, meaning that our class can do everything a Sprite can.
Line 6: A function that has the same name as the class is called the "constructor" function. Every time a new instance of this class is created, the contents of this function (Basic01) will be executed.
Line 7-8: Here we create a new View(3D). This is our viewport into the virtual 3D world. The x and y parameters tell Away3D where to set the centre of our 3D world. We then add this view to our class, so it will appear on the Flash stage.
Line 9-10: Here we create something to look at - a simple sphere. Next, we add this sphere to the default 3D Scene in our View (Just as other DisplayObjects in Flash, only what is added to the Scene is visible). Since we don't pass in any parameters for the X, Y and Z position, the sphere will be created in the center of our view (X=0, Y=0, Z=0).
Line 11: Away3D allows you to decide when to render the View. Rendering is the process of converting the virtual 3D content into a 2D viewable image. Rendering is a CPU intensive process and being able to decide when to update is extremely useful. A great use is to only render the View when the user has the mouse over the Flash movie.
The result is something like this:
movie: Basic01.as
This was the simplest possible 3D scene I have been able to create in Away3D. You could of course compress this a little more by removing the comments, placing curly brackets on the same line and removing whitespace lines, but I find code easier to read this way.
If you are new to AS3, you may wonder where Away3D appears on stage and how you can manipulate it? Since this class extends the default Sprite class, it will behave almost like a MovieClip. Sprites are essentially MovieClips without a timeline. Since the Class is based on Sprites, it can easily be moved around the stage using the X and Y coordinates, rotated using the rotation property and so on.
If you use Flash and set this example file as your "Document Class" (or "Default Application" in Flex), a copy of this "extended Sprite" will be added to the Stage. If you add other Sprites, Movieclips or components using the "addChild" method inside this class, they will be added to this Sprite and not the Stage itself. If you want something to show above your 3D world, you just add it to the DisplayList after you add the View. You can also toggle the display order using the setChildIndex or swapChildren methods, just as for any other DisplayObject.
Next, let's expand a bit on what we've learned this far by looking closer at the View. From here on, we'll assume that you know AS3 or have a way to look up things you wonder about Actionscript 3 programming.
NOTE: If you have never used the Doument class in Flash, make sure you also read this tutorial and scroll down to the CS3 heading. This will explain how you use the actionscript class files in these tutorials together with Flash.
Comments
Hi efactorial,
Which software do you use? I’ve tested this on CS3, CS4 and Flex 3 and I’m unable to reproduce your error.
Could it be that you’re using Flex 3 and are trying to compile the SWF to Flash Player 10?
J
I was using Flash Develop 3.0.0 and CS4. I even tried to paste the code directly into the frame in CS4 and CS3 and still got the error. Actually in CS3, the error message was different.
Here is the code I put in the time frame:
import away3d.containers.View3D;
import away3d.primitives.Cube;
import flash.display.Sprite;
// create a viewport
var view:View3D = new View3D({x:250,y:200});
addChild(view);
// create a sphere and put it on the 3D stage
var cube:Cube = new Cube();
view.scene.addChild(cube);
// render the view
view.render();
Error in CS4:
1067: Implicit coercion of a value of type away3d.core.math:Matrix3D to an unrelated type flash.geom:Matrix3D.
Error in CS3:
Error: Error #2099: The loading object is not sufficiently loaded to provide this information.
at flash.display::LoaderInfo/get width()
at away3d.core.clip::Clipping/screen()
at away3d.containers::View3D/get screenClip()
at away3d.cameras::Camera3D/update()
at away3d.containers::Scene3D/update()
at away3d.containers::Scene3D/onUpdate()
at flash.events::EventDispatcher/dispatchEventFunction()
at flash.events::EventDispatcher/dispatchEvent()
at away3d.containers::View3D/notifySceneUpdate()
at away3d.containers::View3D/render()
at Untitled_fla::MainTimeline/frame1()
TypeError: Error #1009: Cannot access a property or method of a null object reference.
at away3d.core.render::SpriteRenderSession/clear()
at away3d.containers::View3D/render()
at Untitled_fla::MainTimeline/frame1()
I’m really new to scripting and I have yet to get these to work. I installed the away3d files and I believe i’m doing everything they tell me to and flash tells me the the file can’t be nested. what am I doing wrong???
Hi Kyler,
Did you follow the instructions in this tutorial? http://www.flashmagazine.com/Tutorials/detail/using_actionscript_projects_in_flex_or_flash/
I’ll help you if you can tell me a bit more about your setup. What editor do you use (Flash/Flex/FlashDevelop/FDT) and how did you set up the class?
J
Ya I have flash cs4 and I just copied the fils into the flash directory like it said in the install tutorial.
it says package can not be nested and give the { on the second line as the source.
i am getting the same thing as hiyh:
Packages cannot be nested. Source {
Folders are in the proper directory (I just did the earth tutorial and I am using the same folder).
Exporting Flash Player 9, AS3.
Uggh. Damn I rushed this one, thought it was sturctured the same as the earth tutorial. After I set up the document class everything worked fine. New to AS3, will be more careful next time.
Works fine.
@efactorial you shouldn’t get those errors? Would you mind downloading the latest version (2.3) and try again? http://away3d.com/downloads/
J
Hey guys, I’m a total noob to away3D but NOT AS3!
I have created a new document, referenced my away3D src files through the publish settings and used my .as file’s name in the document class…
Whenever I typed the SAME code above I get many errors…however when I copy and paste the code from your .as file, the thing works!!!???! What is going on?!?!
This is what I type:
package {
import away3D.containers.View3D;
import away3D.primitives.Sphere;
import flash.display.Sprite;
public class Charlie extends Sprite
{
public function Charlie()
{
var View:View3D = new View3D({x:250,y:200});
addChild(View);
var sphere:Sphere = new Sphere();
View.scene.addChild(sphere);
View.render();
}
}
}
These are the errors I get:
1046: Type was not found or was not a compile-time constant: View3D.
1046: Type was not found or was not a compile-time constant: Sphere.
1180: Call to a possibly undefined method View3D.
1180: Call to a possibly undefined method Sphere.
5001: The name of package ‘away3d.primitives’ does not reflect the location of this file. Please change the package definition’s name inside this file, or move the file. D:\dev\libs\as3\3d\away3d\src\away3D\primitives\Sphere.as
5001: The name of package ‘away3d.containers’ does not reflect the location of this file. Please change the package definition’s name inside this file, or move the file. D:\dev\libs\as3\3d\away3d\src\away3D\containers\View3D.as
Anyone out there…..PLEASE help, this is so simple yet stupid! Why is this happening to me :(
@ctaminian You will get those errors if Flash can’t find the Away3D source code. As for why it works when doing a copy/paste - I really have no idea.
J
sorry but this is another chaotic tutorial about away3d…......I’m FlashCS3 user. where put the first code??????: (“package {
import away3d.containers.View3D;
import away3d.primitives.Sphere;
import flash.display.Sprite;
public class Basic01 extends Sprite {
public function Basic01() {
var view:View3D = new View3D({x:200,y:200});
addChild(view);
var sphere:Sphere = new Sphere();
view.scene.addChild(sphere);
view.render();
}
}
}”)
into first frame as action????
Which document class do I have to use?? Basic01 or Cover?
If this is tutorial for beginners You should explain what to do, step by step….. I don’t see sphere, only errors:
1131: Classes must not be nested.
1159: The return statement cannot be used in package initialization code.
so its very nice effect hahahahahahahahahahaha. I’m so sorry I can imagine this sphere in my mind only…........
Hi Obirajt,
I’m sorry that you have a problem here. If you just read the Flash-part of this tutorial, you’ll find exactly what you need:
http://www.flashmagazine.com/Tutorials/detail/using_actionscript_projects_in_flex_or_flash/ These tutorials are laid out using Class files to make them possible to use across more tools that just Flash.
If you look in this tutorial:
http://www.flashmagazine.com/Tutorials/detail/create_the_earth_and_heavens_in_less_than_an_hour_with_away3d/ You’ll see how to work with Away3D using only timeline code as well. You can use the approach you want, but keep in mind that 3D requires programming, so you will have to learn a little more than just timeline scripting to make what you want.
J
Submit a comment
Join the list
Stay current on what's happening in Flash business. Sign up now for the Flashzine newsletter.
Featured Articles
Beta versions of Flash Catalyst and Flex on Labs
Hi, I am new to away3d. While going thru these great tutorials, I found an error and wanted to share.
I just downloaded the source code 2.2 and tried the above minimal class example. I got an error in
View3D.as, Line 202:
inv = camera.invViewMatrix;
1067: Implicit coercion of a value of type away3d.core.math:Matrix3D to an unrelated type flash.geom:Matrix3D.