How to publish content to realXtend Tundra

Introduction

We have gotten some interest for the Tundra project lately. Mostly from the old rex users from the Naali and Taiga days and partly from new people discovering the realXtend project. I think the most asked question on the mailing lists where we developers lurk are “how do i host a tundra world?” and “the server is just a grey world, where is content?”. I think the questions are justified for few reasons: we haven’t gotten into really documenting usage instructions on the server/viewer setup for tundra and secondly I think Tundra is so different from OpenSim/second life/insert vw tech here that it’s confusing even if you have done stuff with eg. OpenSim before.

I’m a developer and am quite up to speed how Tundra works under the hood. So I’ll try to make detailed instructions on the subjects.

Installing Tundra, running server and connecting

Jani already blog posted a copy paste of my instructions from the rex mailing list, I think it is good enough to get you started so check that out How to run your own Tundra virtual world. I might come back to these things in this post also to really clarify some points.

Your content to Tundra

Tundra supports multiple ways of importing your 3D content. The preferred method by the developing companies is Blender. To be more to the point the format we support best is Ogre, Blender has plugins to export its scene/meshes into the Ogre format. Ogre 3D is our rendering engine and anything we push to it for rendering under the hood has to be converted to ogre formats. Tundra also support direct drops of other mesh formats via Assimp like .dae, .ply etc. but how it goes under the hood is we convert them on the fly to the Ogre mesh format at the end, you just wont need to do it. The assimp importer code and flow of import is still work in progress, you can try to drag and drop any mesh that assimp supports but there are no guarantees that it will actually show up. I think .dae and .ply are tested the most.

So the case I will be covering is Blender and its latest 2.5x series. For other 3D modeling software check here for Ogre exporters, seems that there are at least 3DS Max, Maya, XSI etc. exporters available. So you won’t be forced to use Blender :) I can recommend Blender though, as I had never touched a 3D modeling software (I code, I’m not that artistic :) and got some sweet results in few nights of studying and trying things out. Modelling something simple like a ship (yeah, I know its crappy looking but still!) was surprisingly easy with Blender.

Also note that I’m using windows here. If you are a linux user the same instructions apply, but of course some intall steps and exact paths to stuff will be different. I will also be quite specific about the version of software you have to setup. Because I want a dead simple tutorial that you can follow step-by-step, not a generic one that just says “get blender, export stuff, import to Tundra, bye”. If you want to deviate from the versions you can, but you might need to do some composing along the way :)

Setting up the software you need

realXtend Tundra viewer and server

  1. Get the latest Tundra release from http://code.google.com/p/realxtend-naali/downloads/list
  2. Install with the settings you like, there are no special things to consider here.

Blender

  1. Download Blender http://www.blender.org/download/get-blender/
  2. Install it and look out for the following setting (in the picture). This will determine where to put the Blender2Ogre add-on. I recommend the use install directory way, neatly packs all data to program files, instead of semi-hard to find path under the windows user folders.

Blender2Ogre exporter

This project is at google code and is written with python as plugins are for Blender. Big props for Bret and other open-source enthusiasts for making this, I have also contributed some code for the realXtend export part that we will go into later.

  1. Get the latest release from http://code.google.com/p/blender2ogre/downloads/list at the time of writing this it would be blender2ogre-0.3.5-stable.zip
    1. Note: Use the 0.3.6 release if you are going to work with animations as it has some crucial fixes for that. I didn’t recommend this as it does not say “stable”
  2. Open the zip file, go to blender2ogre dir inside it, you should see io_export_ogreDotScene.py file.
  3. Now we need to extract the io_export_ogreDotScene.py file into the correct place, this depends on how you installed Blender:
    1. Installed with “Use Application data directory” – Put the file into C:\Users\<your_username>\AppData\Roaming\Blender Foundation\Blender\2.57\scripts\addons
    2. Installed with “Use installation directory” – Put the file into C:\Program Files\Blender Foundation\Blender\2.57\scripts\addons (might be Program Files (x86), depends what you installed on what system)

For you to export .mesh binary files directly with this exporter you will need the OgreXmlConverter.exe, this converts xml descriptions of ogre meshes into binary .mesh files. Project page is here. Tundra uses 1.7.1 version of Ogre. They seem to have installer for 1.6.3, so we will be using that and cross our fingers. If you have problems I can dig my own build with 1.7.1 ogre for the current tool. I believe the mesh format has not changed too much so we should be fine with 1.6.3!

OgreXmlConverter 

Inspecting the io_export_ogreDotScene.py file we can find this line “DEFAULT_OGRETOOLS_XML_CONVERTER = ‘C:\\OgreCommandLineTools\\OgreXmlConverter.exe’“. This is unfortunate hard coding as the project has not gotten into making configs yet (they have a config file but no UI to edit it). So lets go with the expected path.

  1. Download the OgreCommandLineTools installer
  2. Install it to the path C:\OgreCommandLineTools (seems to be the default one)

Exporting content from Blender

You might already have a blender scene some where or not. So lets export the basic cube from Ogre to Tundra to see how the flow works, you can use your pre-existing scene if you like. Open blender, you should be seeing a empty scene with a cube in the center.

Next we need to enable the blender2ogre plugin. You should only need to do this once per blender installation.

  1. Inside Blender hit Ctrl+Alt+U this should bring up the User Preferences window.
  2. Select Add-Ons tab
  3. On the left search line search for “ogre
  4. The exporter should pop up to the search, if not you have instelled it to a wrong directory.
  5. Check the small checkbox on the right to enable it.

Next we want to export the default cube. From the Blender menu bar select File -> Export -> RealXtend (.txml). Next you should see the export options. Lets use the path C:\Tundra-export\cube\ for the export. Note that now we have a single object, on bigger scenes you can un-check “Export Selected Only”, or just select everything you want before exporting. Other than that the default settings should be fine. If you haven’t saved your blender project yet the dialog needs a name for the txml file. Other wise it will use the project name here. Be sure on the name line edit on top to have something, eg. cube.txml instead of “.txml” as this will fail to export certain things. After all this hit “Export RealXtend” in the top right corner.

Minimize Blender and navigate with windows file explorer to C:\Tundra-export\cube\ where we exported (or anywhere you exported). You should be seeing cube.txml Cube.mesh Material.material and some other files but those wont be used in the import like Scene.material and Cube.mesh.txml, they are just a side product of the export.

You can simply double click cube.txml to open a new server with rendering enabled to see how it looks. You might see just grey here, as the cube was instantiated in the center of the scene and that happens to be the same place our free fly camera will instantiate too. Mouse left click once to the scene (Tundras 3D view) and press S key to fly the camera backwards. WASD keys move the camera, space flies up and C down. Right click down and drag will rotate the camera with the mouse, you can also move at the same time.

Ok now we see our cube is nicely showing in Tundra, that was easy. Let me explain a bit what actually happens when you double click a .txml file. The server starts up with this “<path_to_tundra>/server.exe –file C:\Tundra-export\cube\cube.txml”. On a server this means it will load this txml scene once its started up. It also adds a new asset storage path “Scene” as “C:\Tundra-export\cube\”, you can see this by pressing Shift+A inside tundra. This is important so the server will find the assets that are referenced in the txml file, if we look inside it has “<attribute name=”Mesh ref” value=”local://Cube.mesh”/>”. local:// means for Tundras asset system that please look for it in the local storage paths. But the local:// refs are not very good if you want to actually show the cube world to others as they dont have “C:\Tundra-export\cube\Cube.mesh” on their computer when they join your scene, so we need to get these assets to the web and change the refs!

Publishing a scene with Tundra to the web: Automatically

This is a bit more advanced step, you need a web server eg. Apache and some knowledge how to configure it. You can do the same with eg. DropBox, ill cover this in the next section. Jump to that if you want to use manual uploading of the assets.

I will cover this step with with Apache as I use that. If you use some other web server this is of course doable but youll have to figure it out your self. For windows users that want to try this out i suggest the xampp installer that install Apache and other stuff and has a nice control UI for all the servers and web UI too.

Essentially what you need to do is allow unauthenticated (yes you read correct :) HTTP POST to a certain path in you web server. This allows Tundra to post aka upload assets to your server.

Navigate to your apache install dir and go to the “conf” folder. You need to enable all the WebDav related modules in this config, I can’t remember them off hand so youll have to do some digging. How I did this I just uncommented the “#LoadModule dav_module modules/mod_dav.so” and “#Include “conf/extra/httpd-dav.conf”” lines and tried to start the server. The server will report errors that are quite easy to understand like “could not load required xxx module” to the “<apache>/logs/error.log” file. So with some try and fix mentality you should be able to brute force it, I still suggest googling it out :)

Now that we have the dav (webdav) module enabled in our Apache, lets add a path that allows people to post files into it. Copy paste this snipped to somewhere in there but change the path to be correct for you.

<Directory "C:/apache/htdocs/assets">
    Dav On
    Order Allow,Deny
    Allow from all
</Directory>

Now go to the htdocs and actually make the “assets” directory there. This now lets POST go trough only to the assets folder so the whole web server is not compromised in a bad way :)

Next lets test if it works. Lets run a headless server and a viewer and log in.

  1. Open a cmd prompt and navigate to the tundra install dir, default is C:\Program Files (x86)\realXtend\Tundra
  2. Run: “server.exe –headless –protocol udp
  3. Start viewer.exe from the same place
  4. Connect with Server: localhost Username: test Protocol: check UDP. Hit connect.
  5. Pop up the Tundra console by pressing F1 (you need to have scene focus first, so left click the 3D scene then F1)
  6. Run this command: “AddHttpStorage(“http://localhost/assets&#8221;, “asset-test”)
  7. Now open a windows file explorer and go to C:\Tundra-export\cube
  8. Drag and drop the cube.txml to the tundra client. A pop up dialog should show up for adding the content.
  9. Make sure the Asset Storage in bottom left corner has “asset-test” selected, this will tell Tundra to upload the files to this provider.
  10. Hit “Add Content” the asset lines should light up green or red depending on if the upload was successful. If it hangs up waiting a long time or they go red you have some apache configuring to do :) See again the <apache>/logs files for indicator what went wrong.

If everything went ok, click Close on the dialog. You should now see a cube in front of you, but more importantly its a cube from the web, the asset reference for the mesh is now http://localhost/assets/Cube.mesh and you can verify this by Alt+E for the entity editor, then click the cube and inspect the Mesh components asset references.

Granted we used localhost to demo it out, so to make this part practical and useful you need to:

  1. Do the same apache configuration to your web server online.
  2. Run the Tundra server with same commands on that server.
  3. Connect from your PC to your live Tundra server
  4. Substitute the “AddHttpStorage(“http://localhost/assets“, “asset-test”)” with a real storage URL or IP, eg. http://jonnenauha.com/tundra/assets/.

Publishing a scene with Tundra to the web: Manually

Not everyone have access to an Apache server to host their assets. But there is another way, you can just do it manually, for a whole scene or with just one asset. Tundra support web drag and drops from the browser directly to your server. You can use a ftp server you have access to, dropbox or just a web server that you have access to but cannot get access to modify the POST permission.

I’ll use dropbox as its quite widely used, but as said you can use anything as long as you can acceess the mesh with you browser then Tundra can too :)

  1. Copy Cube.mesh and Material.material from C:\Tundra-export\cube where we exported into your web location. I’ll use my dropbox location Public/tundra-assets/cube path
  2. Open C:\Tundra-export\cube\cube.txml with a text editor.
  3. Search and replace all “local://” string with your base path where you copied the assets, for me its “http://dl.dropbox.com/u/3589544/tundra-assets/” remember the trailing “/”.
  4. You are all done, save the file as “cube-web.txml”
  5. Open a viewer and connect to your server as before. The server can be local for demo purpouses, but you can also now connect to your live web Tundra server.
  6. Drag and drop cube-web.txml to the viewer. You can now see in the add dialog that the asset refs are greyed out. This means tundra detects that the assets are on the web and it does not need to process them. Tundra just needs to add the entities described in the txml file.
  7. Hit add content and close the dialog.

Now you have a cube in front of you that is really from the web. When other people connect to your server they will also see it! Wasn’t that easy.

For the fun of it: Adding a avatar for the clients and making a terrain to walk on

I wasn’t planning to do this on this post. But what the hell, it’s not trivial for everyone after all to put a avatar to your live Tundra world. So lets cover this also, after all its quite boring to have just a cube in your wonderful Tundra world that your friends will definitely want to check out!

We will be using the “manual way” of doing this. You can also use the tundra upload way, but there are a few cotchas when uploading scripts: you have to check the script content also for local:// refs! Tundra won’t open the scripts for you and edit these when you push the assets. So you have to do it before hand knowing the web base path of the upload.

Lets make a terrain for the avatars to walk on. Connect to your server and add the cube we exported if you don’t have one yet.

  1. Shift+E opens the Entity Editor, click on the cube to fill its data into the editor.
  2. Expand Placeable component, and its Transform attribute.
  3. Set position to 0,0,0 and scale to x = 100, y = 1, z = 100
  4. Now you have a “terrain” but avatars will still fall trough it, we need physics
  5. Add a new component with right click -> Add component in the Entity Editor (the cube selected still)
  6. Find “RigidBody” from the list and add it.
  7. Open the rigid body and expand its “Size” attribute. Set it to 2,2,2 for me this was correct. You can inspect live where the physics box is by typing “physicsdebug” to the F1 console.
  1. Open a file explorer and navigate to the tundra install dir, default is C:\Program Files (x86)\realXtend\Tundra\scenes\Avatar
  2. We will be needing the files: avatarapplication.js, simpleavatar.js, crosshair.js, default_avatar.xml, firstpersonmouseicon.png.
  3. Copy these files again in to your web path, im using Dropbox location Public/tundra-assets/cube again
  4. Open the avatarapplication.js with a text editor. Again replace  “local://” string with your base path where you copied the assets, for me its “http://dl.dropbox.com/u/3589544/tundra-assets/” remember the trailing “/”.
    1. Note that this should touch lines 1 that is the dependency reference declaration that Tundra will detect and download and line 133 that dynamically during run time adds the simple avatar script for all the clients.
  5. Do the same thing for crosshair.js and simpleavatar.js
  6. You don’t need to do this for the default_avatar.xml as assets referenced in it are shipped with Tundra and will be found automatically.

Open a viewer, connect to your live Tundra world (or localhost does not matter) where you have the cube terrain. No we need to create a entity that has the avatarapplication.js in a EC_Script component.

  1. Once inworld Shift+S to get the scene struct, you can also open it via the menus View -> Scene
  2. Right click on the scene view -> New Entity. Select synchronized (the default) and hit OK.
  3. Optional: Right click on the new entity, it should be right up top now in the Scene view with no name. -> Rename. There is a bug that you wont see what you are writing, but just write “avatar-app” and hit enter. It should update.
  4. Double click the newly created entity, this should open a Entity Editor window.
  5. Right click -> Add new component. Name: avatar-app (again optional but nice). Component: search the list for “Script” and select it. Click OK.
  6. Expand the Script component in the Entity Editor view. Check “Run on load” to be true. Write “Type” to be “js“. Write/paste “Script ref” to be the web asset of you avatar application. For me its http://dl.dropbox.com/u/3589544/tundra-assets/avatarapplication.js 

Now we have the avatar application running on the server. There is a bug that you need to relogin to get the avatar for the clients that were inworld while it was launched. Hit file ->disconnect and connect back from the login screen. Once you login back if you are invisible, close the client and go back in. There is some bug in the av app still that sometimes manifests in invisible avatars.

Last words

You should now be standing on your self made cube terrain with a avatar :) Ask your friends to join the party and start building your world!

Holy check it took long to write this, also the length is quite huge. It covers a lot of ground and hopefully will get you to understand the Tundra ideologies how to author worlds. I’m sure some parts might be confusing so please feel free to post question to the comments. I will gladly help and we can modify this post to be more clear for everyone!

Peace out,
Jonne Nauha aka Pforce
Adminotech realXtend developer

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s