There are quite a few articles out there discussing Papervision3D and
sharing source code, etc. but very few explain in plain English how to
actually get started with PV3D. For those of us that aren’t geeky
enough to guess our way into getting it to work we are usually left in
a dust of confusion. Papervision3D, if you aren’t familiar with it, is
a way to do 3D inside Flash - it’s extensive, cutting edge and very
well laid out. More and more sites are popping up on the web utilizing
this technology… so what are you waiting for?
It is up to you to decide which IDE you are going to use to do
Papervision3D development. I will be explaining how to install it in
both Flash and Flex, afterwards you’d be ready to start creating
projects and learn from other examples.
Getting Started
The first thing you need to understand is that in both Flash and Flex
there are 2 ways to access the source needed for your Papervision3D
project. One way of doing this is getting the compiled source code that
you’d use in Flash as an .mxp component or in Flex as a .swc library.
The other method is using the non-compiled source code. I am going to
suggest that you stick to using the non-compiled source code since the
code is not encapsulated, you can easily go into your classes and
modify them if needed. If you do not care about modifying the source
code then you can stick to using the compiled versions. I will be
explaining how to get the compiled versions for the application
specific steps, if you’re planning on using that then skip the
Subversion Control step (Flex needs Subversion in either case). If
you’re going to use the non-compiled source in Flash or setting up in
Flex then continue.
Download the source through SVN(Subversion Control)
You need
to get the source from a SVN. To some Windows and Mac users this
concept may sound confusing. It’s not like downloading a zip from a
hyperlink or a specific file. It’s a well known concept in the
open-source community so if you’ve used Linux before this is probably
familiar to you.
The official
Papervision3D SVN is hosted at
Google Code:
You can get the SVN URL for all the links by going to
http://code.google.com/p/papervision3d/source/checkout but you can just type this in your SVN application (which I’ll explain below) to get the files you need.
http://papervision3d.googlecode.com/svn/trunk/branches/ GreatWhite/
Windows
Many other Papervision3D users have recommended TortoiseSVN and I agree
with them, It’s a great tool for SVN source downloading using Windows.
You can go to TortoisSVN’s site here:
Click here
Download the latest version directly from sourceforge:
Click here
Proceed with the article once you’ve downloaded and installed you can
the package. What you need to do now is create a folder, for example
inside your work directory or root drive, called “Papervision3D” or
“PV3DSource”. You’ll be using this folder to download the SVN. Once
you’re inside you need to right click to open the folder properties
menu; you’ll notice that there is 2 new options. Select “SVN Checkout”
to proceed.
You’ll see a input box labeled: “URL of repository” - (This is all you
need to be concerned about). Add the SVN URL and let it run, it might
take a couple of minutes to complete depending on your connection.
Now you have the needed files to continue.
Mac
I’m not a Mac user but I did some investigation, this might or might
not be useful, so if there is anyone that would like to contribute to
this part of the article just leave a comment.
I found this SVN client called “svnX” and its opensource so it should
get the job done. Here’s a quote from their site:
An open-source GUI for Subversion, the compelling
replacement for CVS. It allows you to browse your working copies, spot
changes, and operate on them, but also to browse logs and revisions of
your repositories!
You can go to svnX’s site here:
Click here
The first thing you need to do is click on “SVN Checkout” and set a
directory for your Papervision source directory. Once you have done
that you should be ago to the “Repositories” window and add the SVN
URL.
Let the download run and once it’s finished and you see all the files
you are ready to continue.
Installing on Flash
This will be split into 2 parts depending
on which source you decided to settle on. If you decided on using the
Flash Component then continue, if you prefer using the non-compiled
source code skip the following step.
Using the .mxp Component
(NB: At the time of writing this the .mxp is Version 1.5 and not 2.0)
If
you’re still not 100% whether you want to use the component, I might be
able to put your mind to rest. There are some benefits to using the
component and John Grden from
Rock On Flash explains it very well
here
# Design-time render and editing in Flash IDE
# 3 Material types supported - BitmapFileMaterial, BitmaAssetMaterial and MovieAssetMaterial
# Creates MovieScene3D and Free or Target camera
# Manages resizing / centering of Papervision3D scene [optional]
# Dynamic masking to constrain the viewable render area to the bounds of the component [optional]
# Full API and access to Scene, Camera, Collada objects to code around
# Automatically loads materials via Collada file [when materials list is not given]
# New Custom Panel for modifying rotation, camera zoom, camera focus, camera Z at design-time
You can download the Flash components from
Google Code
under the downloads tab. Download the latest file, it should look
something like this - PV3DComponents_v#####.mxp
Once you’ve downloaded the file you can run the .mxp as an executable.
It will automatically open “Adobe Extension Manager” and ask you to
accept an agreement and then it will install itself. If you have Flash
already running you’ll have to restart to see the changes.
You can create a new document inside Flash (AS3 Document) to get
started. I won’t be showing you how to create anything in this article
as the purpose is to show you how to install. What I will do, however,
is show you which menus you can access with the Papervision3D .mxp.
First off, everything is listed under Window > Components, there you
can either choose to create a Papervision 3D scene or Papervision 3D
Collada scene. If you’re planning on using the Collada component you
can access a very nice GUI menu which lets you set the location,
camera, rotation, etc. You can access this by going to Window >
Other Panels > PV3DPanel.
When you’ve installed the .mxp you already have complete access to the
classes in Papervision3D so there is nothing else you need to worry in
terms of set-up.
Using the non-compiled source code
If you’ve already installed
the .mxp file you can skip this part. Getting the non-compiled source
code running with Papervision is painless. You can decide whether you
want to set up Papervision3D for any project you create or for
individual projects. It is best practice to set up PV3D on each
individual project so I’ll explain how to do this. Create a new
document inside Flash (AS3 Document) to get started. Click on “Publish:
Settings” in your properties menu, if you don’t have a properties menu
you can open it through Window > Properties. A publish settings
window will open on the “Flash” tab; select “Actionscript” on the left
hand side.
All you need to do now is click on the “+” symbol and specify the
directory of your source. If you used the “svn/trunk/branches/
GreatWhite/src” URL in your SVN client then you can link to the folder
you created to download the files, otherwise you need to navigate to
the /src dir.
And that’s it! Your scene file will now work with the Papervision3D
classes.
Installing on Flex
The implementation of Papervision3D in Flex
is similar of that in Flash in terms of the fact that you can choose
between compiled and non-compiled source. We’ll start with the compiled
version, (.swc file)
Using the compiled .swc library
(NB - The compiled .swc has been removed from
the SVN until it goes out of Alpha, it is recommended you use the
non-compiled source-code in the meantime since its easier to update. If
you still want the .swc you can download it from here)
Lets get started - Create a new project by going to File > New >
Flex Project Specify a name for your project and a project location and
leave the rest on default, click Next, specify a debug directory and
click Next again. Select the “Library” tab and click the “Add SWC”
button. Navigate to the directory you created for your Papervision3D
source, go to your Greatwhite directory in branches and click on the
bin folder, which contains the swc file you need. All that’s left to do
now is click “Finish” and your project is Papervision3D ready.
Even though your project will run fine with the .swc file specified as
a library it is best practice by creating a Flex library project which
you can re-use. In describing how to set up the non-compiled source
code with a Flex Library project below you can apply the same principle
using a .swc file.
Using the non-compiled source code
The first thing we need to
do is set up a Flex Library project so that we can re-use the same
Papervision3D source for every project. This practice is better since
you can update, modify and manage the source code all from one
location.
Create a new Library Project by going to File > New > Flex
Library Project
Specify a name, something like “Papervision Library” would do, you need
something that is descriptive so you can refer back in future projects.
The project folder should navigate to the Greatwhite directory under
branches in your source folder. Click Next.
If you specified the folder correctly you will notice that you have
classes listed in your classes tab. Select “src” and you will notice it
populating. After you have done this you have to browse to the main
source folder and select “src”. Click Fnish and your Papervision3D Flex
library project is ready to go!
Now that you have your Flex Library Project ready we need to have a
project utilize this library.
Create a new Project by going to File > New > Flex Project.
Specify a name for your project and a project location and leave the
rest on default, click Next, specify a debug directory and click Next
again. Under the Library path tab click on “Add Project” and you will
see that your newly created Flex Library Project for Papervision is
listed, select your library project. Click Finish and you’re ready to
go!
Your Flex Project should now communicate with your Flex Library
project, review the image below and see whether your project structure
looks similar.
Conclusion
When I started this guide I was not aware that there would be so many
ways to set up a Papervision3D project, hopefully this is as
informative to you as it has been for me. I have done a lot of research
on Google and I keep finding what I just explained to you described in
3-4 short sentences, maybe I’m the only one that found this complicated
in the beginning. I would love to hear back from you to know whether
this article has proved useful.
Below are some links to sites discussing how to set up Papervision as
well as other related topics: