Building your First Papervision Application

What goes into a Papervision Scene?

At first it can be a little bit overwhelming when looking at the sheer number of classes that come with Papervision. But fear not, these are of no concern to you (yet).

Think of a Papervision world as a movie set, there are actors, props, cameras, costumes, and a ton of other things. You as a director just have to look/ask around to see who and what you need for this particular scene. There are always the basic necessities though: a camera and a stage.

Fortunately, the developers of Papervision thought of that for you and set up some basic classes that you can use to get started with all the necessities in them already; the most common of them being the BasicView.

Setting up the Basics

Let’s start off by taking advantage of the BasicView class by extending it, because BasicView extends Sprite we can make it our document class in Flash.

We will create a main class for our application and call it HelloPapervision.as and enter the following:

package {
  1.  import org.papervision3d.view.BasicView;
  2.  public class HelloPapervision extends BasicView {
  3.   public function HelloPapervision() {
  4.    trace("hello papervision");
  5.   }
  6.  }
  7. }

That is all well and good, but it didn’t do anything other than set up a scene and trace a couple things to the output window. So now we will work on adding some content to the scene.

Working with Primitives

The first thing that we need to do is figure out what we want to add, here I will show you how to add some basic shapes (primitives). You can take a look at the documentation for the included primitives here: http://www.papervision3d.org/docs/as3/org/papervision3d/objects/package-detail.html

Adding primitives is simple, it is just like creating an instance of anything else on the stage. You simply import the correct class, create an instance and add it to the scene.

package {
  1.  import org.papervision3d.objects.primitives.PaperPlane;
  2.  import org.papervision3d.objects.primitives.Sphere;
  3.  import org.papervision3d.view.BasicView;
  4.  
  5.  public class HelloPrimitives extends BasicView {
  6.  
  7.   // create a sphere and a paper airplane
  8.   // create these at class level in case they are to be used in other functions later
  9.   var myFirstSphere:Sphere;
  10.   var myFirstPlane:PaperPlane;
  11.  
  12.   public function HelloPrimitives() {
  13.  
  14.    myFirstSphere = new Sphere();
  15.    myFirstPlane = new PaperPlane(null, 3);
  16.    // move the plane in 3d space
  17.    myFirstPlane.x = 150;
  18.    myFirstPlane.y = 150;
  19.    myFirstPlane.z = -50;
  20.    // add the objects to the Papervision scene
  21.    scene.addChild(myFirstSphere);
  22.    scene.addChild(myFirstPlane);
  23.    // this is an inherited method (onRenderTick) that starts an
  24.    // enterframe event to render the scene
  25.    startRendering();
  26.   }
  27.  }
  28. }

Hopefully this little addition didn’t scare you off. All that I have done is created a Sphere and a Paper Plane, moved the plane and added the items to the scene. Simple, right? But what are shapes without materials? Boring !

Working with Materials

It is possible to get away without using materials on most objects, but it because a very confusing scene if everything is sitting there without proper textures. Papervision allows for numerous types of materials that you can apply to different parts (or all) of your objects. You can take a look at the documentation for the materials here: http://www.papervision3d.org/docs/as3/org/papervision3d/materials/package-detail.html

Creating a material is much like creating a primitive, just instead of adding the material to the scene, you apply it to the object.

package {
  1.  import org.papervision3d.materials.ColorMaterial;
  2.  import org.papervision3d.materials.MovieAssetMaterial;
  3.  import org.papervision3d.objects.primitives.PaperPlane;
  4.  import org.papervision3d.objects.primitives.Sphere;
  5.  import org.papervision3d.view.BasicView;
  6.  
  7.  public class HelloMaterials extends BasicView {
  8.   // create a sphere and a paper airplane
  9.   var myFirstSphere:Sphere;
  10.   var myFirstPlane:PaperPlane;
  11.  
  12.   public function HelloMaterials() {
  13.    // create a movie material for the sphere from the library
  14.    var sphereMaterial:MovieAssetMaterial = new MovieAssetMaterial("sphereMaterial");
  15.    // create a color material for the plane
  16.    var planeMaterial:ColorMaterial = new ColorMaterial(0×55FF11);
  17.    // set the properties of the sphere instance
  18.    // set material, radius and segements
  19.    myFirstSphere = new Sphere(sphereMaterial, 100, 12, 12);
  20.    // set the properties of the paper plane instance
  21.    // set the material and the scale
  22.    myFirstPlane = new PaperPlane(planeMaterial, 3);
  23.    // move the plane in 3d space
  24.    myFirstPlane.x = 150;
  25.    myFirstPlane.y = 150;
  26.    myFirstPlane.z = -50;
  27.    // add the objects to the Papervision scene
  28.    scene.addChild(myFirstSphere);
  29.    scene.addChild(myFirstPlane);
  30.    // this is an inherited method (onRenderTick) that starts an
  31.    // enterframe event to render the scene
  32.    startRendering();
  33.   }
  34.  }
  35. }

All that we did here was we took what we did in the HelloPrimitives class and brought in a couple of materials. One thing to note is the use of the MovieAssetMaterial, for this I had to create a MovieClip in the Flash library and export it for actionscript (Linkage). Once defined, the materials can be used on any object, over and over again. You can even compound materials if you want to, but that is beyond the scope of this tutorial.

Playing in 3D Space

So now you know how to create objects and make them look half-way decent. But what about animation? I am sure that you don’t want to stop with static objects on your stage, what a boring movie that would be.

Well, little do you know, you have already started the animation when you wrote startRendering. That told Papervision to call its renderer and renders the scene every frame that passes.

package {
  1.  import flash.events.Event;
  2.  import org.papervision3d.materials.ColorMaterial;
  3.  import org.papervision3d.materials.MovieAssetMaterial;
  4.  import org.papervision3d.objects.DisplayObject3D;
  5.  import org.papervision3d.objects.primitives.PaperPlane;
  6.  import org.papervision3d.objects.primitives.Sphere;
  7.  import org.papervision3d.view.BasicView;
  8.  
  9.  public class HelloAnimation extends BasicView {
  10.  
  11.   // move the definitions out here so the whole class can get them
  12.   private var myFirstSphere:Sphere;
  13.   private var myFirstPlane:PaperPlane;
  14.   private var pivotContainer:DisplayObject3D;
  15.  
  16.   public function HelloAnimation() {
  17.    // create a movie material for the sphere from the library
  18.    var sphereMaterial:MovieAssetMaterial = new MovieAssetMaterial("sphereMaterial");
  19.    // create a color material for the plane
  20.    var planeMaterial:ColorMaterial = new ColorMaterial(0×55FF11);
  21.    planeMaterial.doubleSided = true;
  22.    // create a sphere and a paper airplane, increase the triangles on the sphere
  23.    myFirstSphere = new Sphere(sphereMaterial, 100, 12, 12);
  24.    myFirstPlane = new PaperPlane(planeMaterial, 3);
  25.    // move the plane in 3d space
  26.    myFirstPlane.x = 150;
  27.    myFirstPlane.y = 150;
  28.    myFirstPlane.z = -50;
  29.    // set an initial rotation for the plane
  30.    myFirstPlane.rotationY = -135;
  31.    // add the sphere to the scene
  32.    scene.addChild(myFirstSphere);
  33.    // add a container to use for pivoting the plane rotation
  34.    pivotContainer = new DisplayObject3D();
  35.    // add the plane to the container
  36.    pivotContainer.addChild(myFirstPlane);
  37.    // add the container to the scene
  38.    scene.addChild(pivotContainer);
  39.    // this is an inherited method (onRenderTick) that starts an
  40.    // enterframe event to render the scene
  41.    startRendering();
  42.   }
  43.  
  44.   override protected function onRenderTick(event:Event = null):void {
  45.    // rotate the pivot container (will offset the plane rotation)
  46.    pivotContainer.rotationY += 1;
  47.    // rotate the sphere
  48.    myFirstSphere.rotationY -= 1;
  49.    // make sure that it is calling the renderer
  50.    super.onRenderTick();
  51.   }
  52.  }
  53. }

Now things are getting interesting ! Lets break down what happened here. In an attempt to make the paperplane orbit around the sphere, we had to create a container for it to act as a pivot point. To do this, we created a DisplayObject3D (do3d) object in the scene which is basically like a blank MovieClip. The reason we use the do3d is because it is empty but it can have children and maintains properties that we can then animate (just like in this example).

This is our first time using the onRenderTick method. Since the method is protected, we had to override it and we eventually call the super at the end. This method is what that startRendering call starts. It is just an onEnterFrame that tells the renderer to render the scene, overriding and using this method is helpful for many types of animation and interactivity in the Papervision world. We have added two lines of code here that simply rotate our object. Notice that the Plane isn’t listed, but it is animating. That is because it is a child of the pivotContainer and the pivotContainer is set to rotate.

Page 1 Page 2 Page 3 Page 4 Page 5