Opensim in the Classroom: How To Get Started

I've run sims with Opensimulator in my school for eight years now (!). I think it's immensely rewarding for students and well worth the effort. It's come a long way as a practical technology for schools. I'm not a techno-wizard but I'm so familiar with it now that it's pretty easy for me to run saved worlds or set up a sim from scratch, so I'm documenting the steps here for newcomers to the technology to use in their own forays into Opensim work.

1. Set Up a Server Computer

Opensim server runs native on Windows. It can run on a Mac but that requires Mono to run Opensim.exe, a setup that adds it's own complications to an already pretty involved list.

1. Connect your Windows machine to your LAN with ethernet and have your Network Administrator assign it a fixed IP.
2. Download the latest Diva Distribution of Opensim. This comes with a splash screen that allows account creation and password resetting. Unzip it to any place you like on the computer.
3. Open and read INSTALL.txt to get an overview of the setup process. I do not set up a domain name for the server (step 2), I just use the computer's IP, but I don't access it outside of our school. I used to, but at some point the forwarding IP stopped working, so maybe that was the problem. I also do not use an email for notifications (step 3) because my users are our students.
4. MySQL database: The sim data, including accounts, prims (objects), and other stuff gets stored in a MySQL database, so before you can start the sim you have to install MySQL and create a database and user for it. Look in the docs folder for MYSQL.txt and follow the instructions in it. If the database or user are not set up correctly, you will find out when you first run Opensim.exe in a couple steps.
5. Configure the sim: For step 4, open the bin folder and run Configure.exe, following the steps given in the INSTALL document. At the questions regarding the Wifi Admin name, which you can choose yourself, keep in mind this will be your master level user account. This account will have more privileges than the normal student accounts will have. Although I have a normal account with my own name I often use the master account as it is more convenient. It is also possible to increase the user level of any user by typing the command "set user level firstname lastname 100" into the console, giving them authority over all objects in the sim and the ability to change sim permissions.
6. Run Opensim.exe, answering the questions as described in OSQUESTIONS.txt. If you don't get to the questions and instead the console window closes, the database connection could be the culprit. You can look in the bin folder at Opensim.log for the most recent output messages. If you see this embedded among the final lines, you need to make sure MySQL is running and has the name, user, and password you gave it in the configure process. "Exception has been thrown by the target of an invocation. --->MySql.Data.MySqlClient.MySqlException: Unable to connect to any of the specified MySQL hosts. ---> System.Net.Sockets.SocketException: Connection refused". If a setting was put in incorrectly during the config, you can either run configure.exe again, or edit bin/config-include/MyWorld.ini directly and run Opensim.exe again.
7. If you get to INITIALIZATIONS COMPLETE FOR (your world), LOGINS ENABLED,  you've conquered the hard part! Now on to connecting with a sim viewer.

2. Configure a Viewer

Now on your client computers, what you and your students will use to log in to the sim, you will set up a viewer. There are many sim viewer programs. For most student projects, I use Imprudence Viewer or Singularity Viewer on laptops or desktops. The Imprudence download page is here, but the download links have been broken for some time. I found them here, though. However, I am moving over to Singularity as Imprudence is no longer being supported by its developers and does not support viewing mesh objects if you get into that, which I have been, and Singularity does. They both look pretty similar and are set up in the same way.

1. Once you start Imprudence/Singularity, click the Grid Manager, and Add New Grid. 
2. Add the grid name.
3. For Login URI, add the IP address of the server computer in this form; http://ip.add.re.ss:9000/wifi
4. Add that same entry in the Login page field, and click OK.
5. Now log in to the sim at the bottom of the splash page. If all goes well you will be standing with the default "Ruth" avatar on a flat plane.
6. Once the viewer is configured to log in to this world it will be saved as the default world for that account, but not for all accounts on the computer. If students are using their own computers it would be more practical for them to configure the viewer themselves.

3. Make and Get Some Content

Here is a reference for learning most of the basic skills in Opensim. It refers to Second Life because Opensimulator was built as a reverse engineered open source version of Second Life. And here is a reference for changing an avatar's appearance (clothing, body type, etc.). You can find clothing templates easily by googling "second life clothing templates" and even edit your own in a graphics editor. Import the image files (File > Upload > Upload image) and apply them in the appearance editor. 

I create an outfit appropriate to the project we're doing beforehand using a default "Female Avatar" account (I work in a girls school), so when students create their account it is built using that as a template. See the Diva document WIFI.txt for how to assign default avatar types. 

WIFI.txt also explains that you can edit your splash screen. It takes a little poking around in the html but I put in some snapshots of past projects to make it more inviting. 

I've built a lot of stuff (prims) over the years, but more recently I have found it useful to download other content people have posted online. The two easiest ways to get free content is to download and import an entire sim in the form of an OAR (OpenSim Archive), or to download textured prims and import them into an existing world. A couple good resources for both are Zadaroo and OutWorldz. 

Loading An OAR File

It's pretty cool to load an entire sim and watch it materialize in front of you. I do this sometimes to use the sim itself for an activity and sometimes just to get objects out of it to use elsewhere. Do not load an OAR file into an existing sim you want to keep; it will wipe out everything there and there's no getting it back save what you had in your inventory. Rather, copy your entire Diva folder and run a second sim you can import it to. To do this you will change its port number and its grid location.

1. Edit bin/config-include/MyWorld.ini in a text editor. Search and replace "9000" with "9001" and save.
2. Edit bin/Regions/RegionConfig.ini. First change the region's UUID. Go to https://guidgenerator.com/ and generate a UUID, pasting it in place of the existing one.
3. Next add 1 to either the X or Y coordinate in the location. For example, one of mine says Location = "921,1031", so I could change it to Location = "922,1031". This will make the new sim appear adjacent to the existing one. You will even be able to fly between the two!
4. Finally, in this doc change the Internal Port to 9001.
5. Note you can still log in through port 9000 as configured in the viewer, but both of these worlds will be available to visit. 

Here are the steps to loading an OAR. 

1. Make sure you are in the correct sim console. It looks like this to have multiple sims running at once.
2. Download the OAR file to the bin folder.
3. In the console, type "load oar filename.oar"
4. You can be logged in to the sim while it loads, just be sure to fly up a ways before you start in case the terrain overtakes you.
5. I have found glitches in loading some oars from other sources, most likely because they were made in a much different version of Opensim, and I don't know if it's possible to troubleshoot. Just move on and look for another that suits your purpose.
6. If you want to get items out of the sim to use, you can right click something, take a copy, and place (or "rez") it where you like. 
7. If you build a sim you want to share, simply type in the console "save oar nameOfOar.oar" and a file will be created with all the stuff in it, which you can post somewhere for others to use.

Importing Textured Prims

Prims are usually posted in zip files on sites like Zadaroo and OurWorldz, which you download and unzip. Then in your sim, click File > Import With Textures (Singularity) or Import + Upload (Imprudence) and locate the xml file in the folder you unzxipped. The whole object will materialize in front of you. 

Some Tips

Here are some fairly random things that might be helpful.

1. Try scripting objects! It's fun to animate things and you can do some surprising things inworld. An easy way to get started is using this script generator. One idea for a scripted object is an item that gives students something they need for a task when they click on it.
2. Do not tell students about the edit avatar appearance option. It's a huge time suck and they can get kind of obsessed. 
3. Make sure laptop batteries are charged before a session, it drains them fast.
4. One common mistake students make is attaching a prim on a avatar body part. It can be disconcerting to suddenly have a tree stuck on your elbow. This happens because they have accidentally dragged a prim from their inventory to their avatar rather then to the ground where they meant to put it. To detach it, find the object in their inventory (it will say "attached to elbow"), right click it, and choose detach.