OpenSim Tech Basics: OARs – Opensim region ARchives October 10, 2008Posted by justincc in opensim, opensim-tech-basics.
OpenSim archives (OARs) are designed as a mechanism for transporting whole regions from one simulator instance to another. This involves transporting not just XML information about the size and shapes of prims, but also the textures applied to their surfaces and the items (scripts, notecards, sounds, etc.) contained within them. As we are transporting a whole region, OpenSim archives also contain terrain information.
Here is a very simple example archive, a screenshot from which can be seen below
So how would you load this archive? First, you would need to start up an OpenSim instance with a blank region or one that you don’t mind losing (since loading an OAR will replace the entire region). If your region simulator hosts more than one region you will have to make the blank region the ‘current region’ via the command
change region my-region
You can then load the archive with the command
load oar scene_oar.tar.gz
If your avatar is sitting in that region, you’ll first see any existing objects all disappear. Then the terrain will be loaded from the archive and the archived prims will magically pop into existence (this is a bit like scenes from the Matrix except much, much slower :-).
Saving out an archive uses a similar command
save oar my-archive.tar.gz
More details can be found on the OpenSimulator wiki here.
I had three chief aims when designing the file format for OpenSim archives. More details on this can again be found on the wiki.
- Make it easy for people to read and write different OpenSim files within an archive.OpenSim archives are old style UNIX tar.gz files (in the future they may be zips – this just requires us to sort out some license issues. Nonetheless, the tar.gz files can be opened on Windows with software such as 7-zip). This means that anybody can unpack them. Moreover, the files within the archive are laid out to try and make it easy to look at different types of data. For instance, if you unpack the example oar above you’ll see
Inside the assets directory are all the assets for that archive. Each asset filename starts with its UUID and ends with an extension appropriate to that filetype. For instance, the single script in this archive has the filename
This means that it can be read and even edited – though editing isn’t recommended if you’re going to reload the archive to a system which already has that asset (since assets are meant to never change).
- Make it easy to compose two region archives into a single region archive.Because assets and objects are separate files living in separate directories, in principle one could merge two regions into a single region simply by copying the contents of one directory into another. The exception here is the terrains directory.This will be more useful for archives that are collections of objects rather than whole regions.
- Make it easy to compose archives from scratch.In principle one doesn’t need to create an OAR by saving the contents of an existing region. It should be possible to create one from scratch.
There’s still some way to go with region archives. For instance, you can’t currently save multiple regions in a single archive, or parcel information. Patches and bug reports are very welcome. Also, I’d be very interested in any links to people making their OARs publicly available.
In the long term the road map is to implement inventory archives as well as region archives – there is now considerable code that can be reused, and people such as Kayne have already contributed preliminary code. This facility isn’t really meant to compete with products such as Second Inventory – archives can only currently be used if one has adminstrative access to an OpenSIm region (either directly via the region console or through the XMLRPC Admin functionality). However, I feel that it’s important to have a way of transporting inventory that is free and open, and doesn’t rely on the fiddly business of extracting and recreating data via the client protocol.