1. Code
  2. 3D

Journey to the Next Dimension With Papervision3D: Part 1


To tie in with our Papervision3D Essentials giveaway, today's tutorial also features a PV3D theme.

This two-part tutorial will show you how to get started with the Papervision3D engine, then how to make your creation jump out of the screen using an anaglyph effect in combination with 3D spectacles.


Got a pair of 3D glasses lying around? Here in the UK, Channel 4 is running a special 3D Week - seven days of TV programmes broadcast in 3D - so plenty of people here do. Let's put them to use.

This two-part tutorial will show you how to get started with the Papervision3D engine, and then how to make your creation jump out of the screen.

In this first part, you'll learn the basics of PV3D, ending up with something like this:

Cube of cubes

...and in the second part, you'll learn about the anaglyph effect for 3D glasses, and apply it to what you've made like so:

In three of the glorious dees

Step 1: The Setup

If you're using Flash, create a new ActionScript 3.0 Flash file. Set the size of the stage to be whatever you like - I'll stick with the default 550 by 400 pixels.

While you're at it, create a new ActionScript file, and save it as in the same folder as your FLA. We're going to use this AS file as the FLA's document class, so click a blank space in your FLA file, and enter Main in the "Document class" box of the Properties panel.

Document class

(If you're not using the Flash IDE, just create a new AS3 project.)

Step 2: Download Papervision3D

Head over to the Papervision Download Page. There are lots of different versions and a few different types of files (zip, swc, mxp). Just grab the latest .zip file (it should say Featured next to it). The one I'm using is called Papervision3D (for use with "Papervision3D Essentials" book).

Step 3: Extract the Zip

Extract the zip file you just downloaded to anywhere on your hard drive. I like to keep all the different engines I use in the same folder, but it's up to you.

Step 4: Set a Classpath

Flash needs to know where you extracted Papervision before it can use it. We use a classpath for this: click Edit > Preferences, select ActionScript, then click ActionScript 3.0 Settings....

In the box that appears, click the little "crosshair" icon, then find the folder where you unzipped Papervision and click OK. Click OK to the other boxes until you get back to the FLA.


If you're not using the Flash IDE, you'll have to set this in a different way. For example, in FlashDevelop, you should click Tools > Global Classpaths.

Step 5: Set the Scene in Papervision

In Papervision, all your 3D objects must be placed inside a scene. It's kind of like the Stage in regular ActionScript. So, before we do anything we need to create a Scene3D object that will contain everything else.

Switch to your file. Let's quickly add the base code needed for any document class:

The Scene3D object is in org.papervision3d.scenes.Scene3D, so we need to import that, then create a new public var to hold the scene, and finally create the actual scene object: (lines 4, 8 and 12)

Step 6: Add a Cube

To start with, let's just create a big plain cube sitting in our scene.

We'll follow the same sort of steps as above to create it, then add it to our scene: (lines 5, 10, 15, 16)

Note that we use "addChild()" to add the cube to the scene, just as we do when adding a MovieClip to the Stage.

Step 7: Color the Cube

The above code will give you an error if you try to run it. That's because we haven't told the cube what its face surfaces should look like.

Papervision uses materials to describe how a surface looks. We can make a very simple, single-colored material using a ColorMaterial:

The "0xCCCCCC" represents the color gray; just take the color code of any color and replace the # with 0x:

color code for gray

Because a cube has six faces, we need to give it six materials. To do this we put all six in a list:

...and then pass that list to the cube when we create it:

So, your whole code should end up looking like this: (don't forget the import statements!)

Step 8: Add a Camera

So we've got no errors, but in order to see anything, we need to add a camera to the scene. We'll see everything through the camera's "lens".

Adding a camera is just as simple as adding a cube - simpler, in fact, as we don't have to addChild() it to the scene:

Now a camera's on the scene, but it's not hooked up to any output, so we still can't see the cube!

Step 9: Add a Viewport and a Renderer

By default, the cube is placed right smack in the middle of the scene (at x=0, y=0, z=0), and the camera is positioned 1000 units back from it (at x=0, y=0, z=-1000).

How can we get the image that the camera sees into the Flash Player window?

How to link camera to stage?

The answer is, we use a viewport. This is a type of DisplayObject, like a MovieClip, so we can addChild() it to the stage. But we can also make Papervision render (i.e. draw) the camera's view to this viewport - it's a bit like having an artist draw what he can see through a camera lens, then taking his drawing and sticking it to a TV set. Except faster.

So we need to create a viewport and a renderer:

Step 10: Render the Scene

Now all we need to do is make the renderer do the actual rendering. For this, it needs to know the scene, the camera, and the viewport:

At last! We can finally test out the SWF. Drum roll, please...

The Incredible gray Square, ladies and gentlemen

Incredible! Astounding! OK fine, it's actually quite lame. How can we even tell it's a cube? It looks like a square.

Step 11: Rotate the Cube

If we rotate the cube, we'll be able to tell whether it's actually a cube or not.

Since the cube is in three dimensions, the word "rotate" is a little confusing - which direction do we mean? We need to specify whether we're rotating around the x-axis, y-axis, or z-axis.

The Cube object has three properties we can use to define this, called (unsurprisingly) rotationX, rotationY and rotationZ. Let's change a couple of them:

The Incredible gray CUBE, ladies and gentlemen

It's better, but since all the faces are exactly the same color, they just merge into each other. Let's fix that.

Step 12: Reskin the Cube

Instead of gray, I'm going to paint the sides with the ActiveTuts+ logo.

If you're using the Flash IDE, create a new movie clip and draw or paste the image you'd like to use. I've included the logo in my FLA's library inside the zip.

Right-click your movie clip and select Properties. Check "export for ActionScript" and give it a Class name. This will let you access it using code. (If you're not using the Flash IDE, the zip also contains a SWC with a MovieClip called ActiveTutsLogo that you can use. Or, you can create a new MovieClip in code and add your image to it. I'm not going to go into the details of that here, though.)

Instead of a ColorMaterial we're going to use a MovieMaterial, and instead of specifying a color, we'll specify a movie clip. So replace this:

...with this:

You'll also need to import the MovieMaterial:

Test it again:

Dented cube

Well, it works, but it looks a little dented.

Step 13 (Optional): Remove the Dents

The "dented" look is because Papervision is set by default to draw things quickly rather than accurately. I want to make sure this tutorial will run on slower computers, so I'm going to leave it at that, but here's how you can improve it:

When you create the cube, you can pass it parameters to define how many segments each face is split up in to. The more segments you choose, the more accurate the cube looks - but the slower it gets rendered.

I've found that 10 is a good number of segments to use in each direction. Here's how code for that looks:

The fifth, sixth and seventh parameters define the number of segments used in each direction. To set them, though, we have to specify all the parameters before the fifth as well.

We're already specifying the first parameter - that's the material list. The second, third and fourth parameters define the width, depth and height of the cube. These are set to 500 by default, so I've kept them the same here.

If you use the above line of code, your cube will look like this:

Smart cube

Much neater!

Step 14: Make the Cube Spin

We can make a regular MovieClip spin around by increasing its rotation property every frame - and of course, we can do the same with the cube and its rotationX/Y/Z values.

Create an ENTER_FRAME event listener, which will run every frame:

This will make the cube turn a little bit more each frame. So if you test the SWF out now... the cube will stay completely still. Huh?

Step 15: Re-render the Scene Every Frame

Think back to the painter. We're still looking at his old picture - we need him to draw us a new one every frame, or we won't see any changes!

So, modify the onEnterFrame() function:

Check it out now:

Step 16: Add More Cubes

One cube's great, but as Roman already showed you how to do that with Away3D, let's take things a bit further.

Let's add a few more, to form a horizontal line of cubes. We can use a simple for loop to do that; just replace this code:

...with this:

Note that I'm making the x-position of each cube depend on how far we are through the loop. If you run this, you'll get the following:


Step 17: Shrink the Cubes

Whoops, the cubes are too close together. We can shrink them to get around this; just change the scale property of each cube:

One odd cube

Step 18: Add the Cubes to an Array

So that fixes the intersection problem, but only one of our cubes is spinning. How come?

It's because the cube variable always refers only to the last cube created - and our onEnterFrame() function only changes the rotations of that one cube.

So to fix this, we'll need an Array. Just as our materials list stored several materials, our Array will store several cubes.

("Push" just means "add to the end of the list".)

Step 19: Make All the Cubes Spin

Now that every cube is in the Array, we can loop through the Array each frame and rotate each of them:

The "for each" loop makes the cube variable refer to each cube in turn, one at a time, rather than just to the last cube created as it did before. Here's the result:

Three cubes in a row


Step 20: Make a Square of Cubes

We've made a line of cubes, so a square isn't going to be difficult. Instead of just making three cubes, we'll make three lines of three cubes.

To do this, we can use a loop-within-a-loop, like so:

Test it out:

Square of cubes

Nice. And note that we didn't have to change the code inside onEnterFrame() at all; the loop that runs every frame just rotates every cube inside the Array - and we're still pushing every single cube onto the Array.

Step 21: Make a Cube of Cubes

Well, it'd be disappointing to stop at a square, wouldn't it? After all, this is a 3D tutorial.

I expect you can figure out how to do this step on your own. But in case you want to compare:

I've been a bit sneaky here. I've started k at 0 instead of at -1, because otherwise the front-most layer of cubes would be too close to the camera. Of course, you can use whichever numbers you like.

Hey, did you notice that the "dented" effect has basically vanished now that we're using smaller cubes?

Cube of cubes


Further Ideas to Try

This is only scratching the surface of what you can do with Papervision3D. Before we move on to 3D glasses, here's a few things you could experiment with:

  • Moving the cubes, instead of rotating them: you can just alter the x, y and z properties of each cube.
  • Replacing the cubes with spheres: if you import org.papervision3d.objects.primitives.Sphere you can use the Sphere class. Check out the docs on this here.
  • Controlling the camera with the mouse: you can get the mouse's x- and y-position at any time with the mouseX and mouseY properties. You can move the camera by changing its x, y and z properties. Why not link the two together?

To Be Continued...

In the second part, you'll learn how to make your scene work with 3D glasses. So if you have a pair, don't throw them away!

In the meantime, thanks for reading the first part. I hope you found it useful. If you've got any questions, or if anything was confusing, please post a comment below.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.