Now what we have all be waiting for: how to get your first world up and running. In the following, there will be references to VRML and Java. If you have difficulty with either of these, consider browsing the VRML tutorial at Floppy's Web 3D Guide and The Java Tutorial as issues arise.
When a client first logs into the VRSpace server, the server responds to the client with a list of the objects that populate their scene. The two objects that we will be most interested in here are called VrmlFile and Transform. A VrmlFile contains the URL of a VRML file, and the second, Transform, can be used to specify where the contents of this file are to be located in the world. We will be building our first world out of the following sample.wrl VRML file which consists solely of a ground for the user to stand on, and a small platform.
The objects that the server responds with are located in a database. The simplest database we can work with (and, as of yet, the only stable one) is the text database, vrspace.db (located in c:\vrspace, or c:\vrspace\bin), that we already encountered in Getting Started With VRSpace. Following those installation instructions, the following lines should be in that file:
Tomcat 1 url Dolphin.wrl;
Tomcat 1 installDir c:\vrspace\tomcat\;
Tomcat 1 shutdown false;
Transform 1 permanent true;
Transform 1 active true;
Transform 1 x 0.0;
Transform 1 y 0.0;
Transform 1 z 0.0;
Transform 1 members [org.vrspace.util.ID(Tomcat 1)];
Transform 1 rotx 0.0;
Transform 1 roty 0.0;
Transform 1 rotz 0.0;
Transform 1 angle 0.0;
Here we see a new type of object: Tomcat, and see that is placed it into the world with a Transform. If you have a seen a Dolphin floating in the midst of your space and wondered where it came from, its Tomcat: the transform object places "Tomcat 1" at the location (0,0,0) in the world (the x, y, and z entries). In fact, you will see that every line in the database file has the exact same format:
The combined "type identifier" uniquely identifies an object in the database. Then for each of these objects, fields are set with the given values. For example, above, Tomcat 1 is defined to have a url of Dolphin.wrl, installDir of c:\vrspace\tomcat, and shutdown is set to false.
Now that we have seen vrspace.db up close, let's put the objects into it that will place sample.wrl into your world. Open vrspace.db in your favorite text editor (Note: in the following, always save vrspace.db as simple unformatted text, and make sure that the file is not saved as vrspace.db.txt as some editors like to do. If you want a nice platform independent editor, consider using jEdit). Places these lines at the end of the file:
VrmlFile 1 name sample.wrl;
VrmlFile 1 url sample.wrl;
VrmlFile 1 _uploads 0;
VrmlFile 1 _downloads 0;
VrmlFile 1 _lastUpdate 0;
(Note: There could be a problem here. If you have been playing around with the server since the previous two tutorials, your database file could already contain multiple VrmlFile objects. If you already see VrmlFile objects, choose another id number (i.e., not 1) for the entries).
This entry lets the server know that the file exists and where to find it. Specifically, it instructs the server where to tell a client to look for the file when their browser wants to download it. This location is set by the url field. In our example, the url is relative (because it doesn't begin with a slash or protocol). Since a client's browser will enter VRSpace itself from http://yourDomain:8080/vrspace/vrspace.html, the server is being told that the file can be requested from http://yourDomain:8080/vrspace/sample.wrl. All we have to do then is save the file to that location, i.e. save sample.wrl to the VRSpace client directory (c:\vrspace\tomcat\webapps\ROOT\vrspace).
So the server understands that there is a VrmlFile called sample.wrl that it can access. We want to actually display this file in the world, and this requires creating a Transform object. Place the following at the end of vrspace.db (again, making sure Transform 3 is replaced by a unique identifier if it is already taken).
Transform 3 permanent true;
Transform 3 active true;
Transform 3 members [org.vrspace.util.ID(VrmlFile 1)];
There are other fields of the Transform that we have not specified, but they will be filled in with default values. For example, our file will be displayed at the origin (x=0,y=0,z=0).
Lets take a look at our creation. Save the database file, exit the editor, start the server, and log in to your world as admin. You should see a new world around you. After you play a bit, shut down the server, go back to vrspace.db, and see how the unspecified fields of the Transform have been filled in.
So now we see how to load objects into the world. For each VRML file you want in the world, create a VrmlFile object, and for each location, use a Transform object, updating the reference to which VrmlFile it is transforming. To change the location of the object, alter the x,y, and z fields of the Transform. For rotation, change rotx, roty, rotz, and angle. See above for an example Transform entry.
Now, the way this is set up, it seems that every time you want to change the property of an object, you have to restart the server. That would be very bad. Fortunately, you can alter the field of an object (such as its location) while logged in, through the console, and immediately see the effects. Read on to learn how.
Before we continue, it is important that we take a closer look at what database objects really are, and this leads us to Java. The objects above aren't just any old objects, they're Java objects, in particular, subclasses of VRObject. Take a look at this VRObject Class Diagram to see a selection of objects that are understood by the VRSpace server, and how VrmlFile and Transform fit in. For a complete list of current VRObjects go here.
What the database is really storing are the fields of Java objects. How can you know what fields are available to be set in the database? Look directly at the javadocs. Open up the link and scroll down to Transform in the lower left frame. Clicking on Transform, you will be brought to its javadoc. Scroll down a bit in the right frame until you see "Field Summary". Here you see a list of the possible field values that can be stored in the database (many of these appeared above). Try this again with VrmlFile (listed in the lower left frame). These Java documents (the API) can be directly accessed and downloaded from the documentation main page.
The console is set up to allow you to change the values of object's fields. Logging in as admin, type the following into the console:
This should move the platform way down beneath your feet. As you can see, the syntax for changing fields is the same as the format of entries in the text database:
Experiment away with moving the platform around. When you are done, place it back at the origin (0,0,0).
At this point, you might be bothered by the fact that Tomcat is floating there as a dolphin. Would you like to get rid of him (or at least make him disappear)? Type the following:
You won't see Tomcat disappear until you restart the client. Try it. What did we actually do? Well, it's a bit of a trick, the url of Tomcat used to be a relative reference to the file Dolphin.wrl stored in the client root directory. We changed it to the file empty.wrl, which doesn't exist, so the Transform is never displayed.
There is another way to change the fields of a Transform object when logged in. Log in as admin and type:
The active field specifies whether you are still working on the object. When you set it to false a window should pop up: the Administrative GUI. Change the position of the object and click submit to see the changes. You can keep this window up as long as you desire. When you are finished with it, click close. If you want to delete the Transform permanently, click remove. Note that as long as you check active, the active field will be set to false for this Transform, and so this window will open each time you login.
That's enough to get you started putting together your first world. After reading the next tutorial though, you'll understand how to use the uploader. With the uploader you will be able to send files to server and it will put the entries for the VrmlFile and the Transform in the database for you. Less work, more world building.