Friday, June 18, 2010

Mars Simulation for distribution

This is the quick-and-dirty version of this tutorial for creating a 3D simulation of the Mars crater Tharsis Tholus from scratch. Actually it's really long, but this is a big project, at least an hour's worth if all goes well. I'll do something more extensive soon in some form, but I just finished making the distributables (OAR and IAR files) so I wanted to get it out there. No previous OpenSimulator experience is required, but some command line stuff will be necessary and there are many opportunities for getting stuck, which I may or may not be able to help with.
This is a standalone 2x2 sim run on Windows XP SP2 that one would connect with using a client viewer like Second Life that is configured to connect over a wired LAN to the IP address of the computer running the sim. All this is detailed below, but there are many other configurations you could have, so I just wanna make that clear. One thing, for the client computers using the viewer app, you MUST use computers with high end video cards. Desktop PCs will tend to have them, as will all (in my experience) newer Macs, from MacBook Pros to iMacs. If you don't have a good video card, the orange sky effect created in step 26 just won't happen, which almost makes it not worth it in my opinion. The space station is set up for 7 astronauts, or a class of 14 students working in pairs to direct the avatars. The lesson I've implemented is documented here. So let's go!
Permissions: "One or more textures on this 3D model have been created with images from These images may not be redistributed by default, please visit for more information."
  1. Choose a host computer for the sim. Preferably a desktop, definitely wired to your LAN. Assign--or have your network administrator assign--a static IP to that computer.
  2. Download .NET framework 3.5. OpenSimulator requires this on a PC to compile and run. Install it (takes a while, requires a restart). If you're running this on Windows 7 skip this step as .NET 3.5 is included in the OS.
  3. Download MySQL server, Windows Essentials version. Make sure you check the box for including mysql bin folder in the Windows path. This will allow you to easily start the mysql command line later on. Don't forget the password you set for the root user! (The installation should be fine as is, but if at some point you find the sim crashing and red console messages reference inability to connect to database, you may have to increase the 'wait_timeout' value in MySQL from 28800 seconds to 604800 seconds (google it). After a crash and the first restart of the sim you'll see a lot missing, probably much of the space station, but shutting down and restarting a second time will bring it all back. I think this issue was fixed in a recent opensim update, but I'm not sure.)
  4. Download OpenSimulator, Diva distro (at this time version 0.6.9 r17521), a little down on the right. As you see there are many versions. OpenSim will run on a Mac or Linux, but for those you have to deal with Mono as the code framework and I've seen lots of people have trouble. I tried and failed. Also, Diva has created a binary version with actual helpful documentation and configuration and update utilities in the bundle.
  5. Once downloaded, extract Diva to a folder in your Program Files, say "OpenSim."
  6. Once extracted, open that folder and go into the version folder inside (currently diva-r12751). There you'll find several help files. Open "MySQL.txt" and follow the directions for creating a database and a user with full permissions. If "start the command line console for the mysql root account" makes your head spin, I can get you started with this: Click Start > Run. Type "mysql -u root -p -h localhost". You'll be prompted for the password you gave when you installed MySQL. Where Diva gives two options in her instructions here just do the first. Then type 'exit' and again 'exit'. It can't hurt to read the other help files in there, too.
  7. Now, using Windows Explorer, go into the bin folder inside your OpenSim installation in Program Files. Double click "Configure.exe". If on Windows 7 make sure to give full perms to all users for the bin folder and its contents. You'll be asked to enter some details about your sim. I named my sim "Mars". For the IP address, give the static IP assigned to the computer, numbers only. Give the other appropriate info, like the password for the 'opensim' mysql user you set earlier. Hit enter when it says it's done.
  8. Now, in the same folder, double click "OpenSim.exe" and watch all the pretty colors. It will take a minute or so as it creates more than two dozen tables in the database and sets a lot of other things in motion. Hopefully you'll have no errors at this point. If you do and it has to crash, look in the bin folder for the OpenSim.log file, open it, and see if you can figure out what crashed it by skimming the code at the end. It's usually an error connecting to the database or wrong version of .NET. Good luck if you're seeing red.
  9. Once it says "logins enabled for Mars 4" and stops spewing jargon leave it alone and install Second Life on another computer. WARNING: Second Life's new viewer version 2.1 isn't yet compatible with OpenSim. Look further down and download version 1.23. Once installed, don't start it yet. For a PC, right click on the desktop icon, click properties and add the following flag in the 'target' field: "-loginuri". That reroutes the viewer to your sim rather than actual Second Life on the web. If you don't want the occasionally racy SL screenshots showing up either you can add "-loginpage". On a Mac, follow these steps.
  10. Save and now open Second Life. If you used both flag in the previous step you'll see two login fields. Don't log in at the top, but at the bottom. First name 'master', last name 'avatar', password whatever you set when you ran configure.exe.
  11. When it finishes logging in, you'll be a female avatar (Ruth) standing on a mound in the ocean. Now let's load some content. You'll be adding terrain and the space station straight from the opensim command line but it's cool to watch through the viewer.
  12. Download and extract this zip file to the server computer. A convenient place to extract to would be OpenSim\...\bin\Terrain. It contains 4 OAR (archive) files, one for each of four regions, and two IAR (inventory) files, for the space suit and basic avatar body.
  13. Now in the viewer, press and hold the Page Up key to fly up to about 150 meters. You can see your altitude (and X, Y position) at the top of the screen. If you don't your avatar may get knocked a thousand meters up as the ground elevation suddenly increases. 
  14. Back at the command line, type "load oar Terrain\Mars1.tar.gz" and hit enter. Watch the crater begin to materialize beneath you. You can get a better idea of what's going on by clicking "mini-map" in the viewer and it will show you the terrain loading. This terrain was first given to me by Drew Crow, who created terrain files from Mars satellite data available from NASA.
  15. Now type "change region Mars 2", hit enter. Instead of typing a new load oar command, hit the up arrow until you see the previous load oar command and change Mars1.tar.gz to Mars2.tar.gz. Change region to Mars 3, load that OAR, and the same with Mars 4. As you fly around and explore you may notice some holes in the ground. To get everything to settle in properly, log out of the sim (File > Quit) and shut down the sim from the command line (type shutdown). When it's finished, open Opensim.exe again (you may want to put a shortcut to the desktop) and log in when it's ready. The ground should be in better shape. 
  16. Go find the space station. If you need to get your bearings, open the Mini-Map again. You *should* be able to click the door to open it. If it's not clickable, right click on the outer door, click edit and locate the contents tab and click it. Open the 'sliding door script'. Make a small change to the script, like adding a space, then removing it, with the goal being enabling the 'save' button in the lower right. Click the save button and it should say "Compiled successfully!" You can now X out of the script window and the edit window. Repeat the previous step for the inner door. You won't have to do any of this again now that they've been activated. Now log out. You'll be adding some inventory items next.
  17. Shut down the sim again. Navigate to the Terrain folder. Move the "Clothing Library spacesuit.iar" and "BodyParts Library astronauts.iar" files out of the Terrain folder and into the Libraries folder. Now start the sim.
  18. When it's ready, log in again. Open the Inventory on the lower right. Your avatar's inventory is open at the top and below are standard Diva inventory items you can copy into your inventory if you like. Open the Diva inventory and open Body Parts. Open the boy or girl folder, depending on which you want to be. Ruth is the default, uneditable avatar, so even if you're female you'll need to add your own editable body parts to make any changes in your appearance. Drag all four items in the folder you chose up to your own body parts folder and drop them in. Select them all, right click, and click 'wear'. If you want to play around with editing your features, right click on your avatar, and click appearance. 
  19. Now you need a space suit. Open the Clothing folder in the Diva inventory. Drag everything in the space suit folder up into your clothing folder and 'wear' them. Cool, right? If you want, you can put on your helmet and backpack now. Leave the ones that are out, as they are for the astronauts you'll be making, and instead open your Objects folder in your inventory, right click the helmet, click attach, and skull. Then attach the backpack to your spine.
  20. Next go back to the opensim console. Type 'create user mars one', hit enter, give it an easy password, and hit enter three times until the user is created. Do the same for mars two - seven. Give them all the same password to make it easy for the students. Now back in the viewer you'll have to log out and log in as each astronaut. Take each one to the space station so it will be there when the students log in and make them wear the body and space suit like you did for your Master Avatar. Also, have each one take a copy of the helmet and backpack (right click, more, take copy), then drag their OWN helmet from their inventory into their OWN cubby hole and the same with their own backpack. They will not be able to attach an object, called a prim, to their avatars unless they own them, which they do by taking a copy.
  21. One note about the Master Avatar. It alone can delete or edit anything. The other avatars can't edit or attach what belongs to the MA. Students shouldn't use the MA account.
  22. So now your astronauts should be ready for students to use, with their space suits on and body configured to your liking, and their own helmet and backpack in their cubby.
  23. Just a couple more things to do. First let's lower the gravity. Make sure you are logged out and shut down the sim. Inside the bin folder find the Opensim.ini file. Open it in Wordpad (not Notepad). Ctrl + F to find 'gravity'. Change it from -9.8 to -3.8. The gravity on Mars makes us about half as heavy but I found this number to have a good, weightless effect, especially when walking over bumps. Save and close. Start the sim.
  24. Now download these sky and water settings files to the computer where you're running the viewer. These will make the atmosphere look more like Mars. They were also given to me by Drew, who made them. Put "Mars-sky.xml" in C:\Program Files\Second Life\app_settings\windlight\skies and put "Mars-water.xml" in C:\Program Files\Second Life\app_settings\windlight\water, renaming both to "Mars.xml" when they've been placed.
  25. Now log in.  First, in the Edit menu > Preferences > Graphics tab, set Quality and Performance to High, or check Custom and make sure Atmospheric Shaders is checked. Then go to World menu > Environmental Settings > Environment EditorClick the Advanced Sky button and choose Mars from the extensive list. You'll see the difference immediately, especially if you're outside. Click Advanced Water and choose Mars there, too. If the sim doesn't look remarkably Mars-like at this point, you don't have the good graphics card I mentioned above. While the high quality and performance setting will stay set between logins, unfortunately the Mars sky and water have to be set each time a student logs in, which I did for them, running from station to station.
  26. Before you let your students loose in the sim you might want to use the master avatar account to disable the copy permissions from the space station. You wouldn't want students copying it into their inventory and dropping new ones all over the sim. Do do this, right click on the space station, click edit, and under the general tab uncheck 'allow anyone to copy.'
Finally, here is a handout I made for my students doing the mission (Mac, PC). Again, read this post for details on how that was set up.
    Now you should have a functioning sim ready for use! If you try it out, let me know. I'd love to hear how it goes and what improvements you can think of.


      MikeW said...

      Eric, I am putting together a demo based on your Mars sim. for a local ScFi convention (Coppercon, Mesa AZ Sept4-6).

      A follow on (hopefully) is the local Gifted Kids group.

      The test version is at

      I would like to add some sort of attribution to acknowledge your work, do you have any suggestions?

      Erik N. said...

      Mike, thanks for asking. I should get around to specifying a CC license but in the mean time you can say original terrain and windlight files by Drew Crow and OAR and IAR files by Erik Nauman. You are free to modify them any way you like. also requests that "When selling or redistributing a 3D model bundled with textures from CGTextures please add the following text in the documentation accompanying the model:

      'One or more textures on this 3D model have been created with images from These images may not be redistributed by default, please visit for more information.'" So if you plan to redistribute your work you should include that.

      MikeW said...

      I have added your attribution line to the web screen, and will also include the CGTextures text if I redistribute files.

      I would be interested in any suggestions or comments you might have as well.

      Since the world is hypergrid enabled and I have already had one "alien visitor" I plan to add an "Alien Visitor Welcome" station and a HG "Stargate" too. :-)

      Great for a demo, but beyond what you want for any serious classroom work.

      Lynne Hand said...

      Hi, Thanks for this, it's very inspirational.

      I'm actually building a space colony for my ESL students as a background to discussing the Mars Colonization project. I was trying to use your .iar files for the space suits, but haven't managed to find the helmet, boots or backpack. I'm using Simona Stick to upload the .iar files, so I might have made a mistake. Should these items be in the .iar file, or do I need one of the .oar files?


      Erik N. said...

      Hi Lynne,
      You project sounds so cool! I haven't used this sim for a while so I fired it up, found the jacket, pants, boots, and gloves in the Clothing folder in Diva Inventory. The helmet and backpack are objects in the space station, which you have to load the Mars1 OAR file to get. I noticed that unfortunately the sliding door scripts have some kind of error so you just have to move them out of the way to get in.

      Lynne Hand said...

      That's great, thanks. I haven't uploaded an oar file this way before, so wish me luck.

      So far everyone has enjoyed the experience, and it's a real conversation starter.

      Michael Timeless said...

      Are these .oars still available anywhere?