OpenSim Tech Basics: OARs - Opensim region ARchives
OAR 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.
OAR Internals
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
archive.xml
assets/
objects/
terrains/
e03b08f7-9bf5-43b7-839e-ba90d42d04a4_script.lslThis 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.
OAR Futures
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.
Nice OAR useage outline - thanks Justincc
I hope to donate some of my OpenSim assets to the project soon - and of course I’ll be making them available in OAR format
Hello Justin,
Thank you for your blog. I read it weekly to see what the progress areas are. It truly stinks when it’s not updated.. :)..
Just a note from my testing with both OAR and xml2 saving and restoring… From what I see, you cannot use the functions to duplicate a simulator instance on a single server. What happens is when trying to restore another sim from the archives (targz) or xml2, it removes all the prims on the sim you saved it from. It doesn’t appear to like to have two duplicate sims with scripts etc.. on the same server instance. What would be nice is if you could use this to duplicate a sim. Not just for transport to another server.
My setup is deb4.0 stable - mono1.9.1 - ode compile from source - standalone recent svn
I’ve not created a ticket on the situation at this point, because I am not quite sure if anyone has even tried to duplicate a sim and all contents then restore on the same server. But unfortunately I cannot get this to work this way. The OAR does work to archive and unarchive. It will restore a sim. But something is holding up allowing for an exact duplicate sim on the same install. At least on this end.
Thanks Justin,
We do love OpenSim.
–rjs
@rjs Interesting - I think I’ve heard that before although not a firm report. I’ll keep it in mind, though if you make a Mantis someone is more likely to get round to thinking about it eventually
Nice picture Justin
Tell me if you need more… I can make video too.
Ok it’s mine
Thanks.
I did a test with “partial content” yesterday. I just wanted to upload a lot of textures (moving them from one region in one grid to a different grid), so the trick seemed to be just to use the “assets” directory and fill it with textures.
This… sort of works. For some reason (I haven’t inspected the code that does the load-xml!) the import is assynchronous and it hangs on the lack of primitives or heightmaps… so it’s a matter of time until the textures fail to be uploaded. Sometimes I get 2-3 textures to upload until OpenSim notices that it’s importing an incomplete OAR and stops.
Ah well. I guess I have to look into the code doing this
@Green. For some wierd reason I thought that I had originally made that picture (from opensimulator.org), but I see from the wiki history that you did it
Thanks very much for that. A video of the process of saving and loading an OAR would be nice, if this is what you meant (but I know these things can be quite a bit of work, and it’s difficult to see fiddly console screens in videos).
@Gwyneth. That’s interesting - in theory loading an oar that contained only assets should have worked, unlike the save process, the load process is completely synchronous and shouldn’t blow up if there are no scene objects (I presume you did execute load-oar rather than load-xml). If you want to open a Mantis to keep track of this problem please feel free - or of course a code patch to fix things is always very welcome as well
Hi Justin,
I made a video to show some opensimulator 0.6 functions. There is 2 load-oar in it. You can watch it on http://www.youtube.com/watch?v=2G5tspAy77M
As you said it’s difficult to see console screens so I add some annotations. Thank you youtube
Nice work, Green Tamura!
-
-
- Hi, I was wondering if there was a way to invoke the ‘load-oar’ from a script?
-
-
@Sim - If you’re talking about an LSL script, then I’m afraid the answer is no at the moment. From a script external to OpenSim, an oar could be loaded via the XmlRpcAdmin facility.
Justin -
I’ve searched a way back and can’t locate a reference, so I’ll ask here - is anyone updating the OAR info to reference the new command format “load oar” “save oar” without the hyphens? That was driving me batty for a week until I finally woke up and typed “help”.
Hi Tim. I’ve update this article in response to your comment :). The actual OpenSimulator wiki page on this had already been updated but I didn’t think about this post.
Justin.
Another tip -
When loading, I often use drag and drop from the folder window of the download location to save a bit of typing. One thing to be aware of is that the result of the DnD will be quoted in single quotes (apostrophes) on Linux. The Region Console doesn’t like these quote marks, so you’ll need to make sure you remove them before hitting enter. Also, it doesn’t appear to like spaces in the path - even when escaped with a backslash, so save the tar.gz files into a folder that’s free of spaces in the path.
Tim
It should be possible to use paths with spaces if you surround the whole path with quotes (”). It sounds like it would be convenient if single quotes worked as well?
Ah - never tried with double quotes instead of apostrophes.
So yes, it would be nice to support both types of quoting mechanisms.
Tim
[...] by justincc in opensim. trackback Hello there. I originally wrote about Opensim ARchives (OARs) back in October last year. To recap, OARs are a way of saving an entire OpenSim region to a single file, which can then be [...]
[...] folks. A little known feature of the “load oar” command for loading OpenSim region archives is the ability to load an OAR directly from the [...]
Very interesting. Perhaps I should look into enhancing this is a bit different direction. My background is very strong in distributed and persistent object systems. So I see the problem primarily as one of destructively or additively with merging persisting a collection of objects and their relationships and loading this collection. In principle it would seem that any closure over a set of objects and relationships should be workable.
Please feel free to contact me and we can chat on how this sort of functionality might be extended and what I might do to help.
I really really want is to be able to do things like:
1) Run something that spools off everything that it not locked down with permission problems in my inventory;
2) allow me to pick and choose any arbitrary collection of things without all the manual intervention of SI;
3) or simply load it all in one go without any further futzing around.
And of course do this from OS to SL as well where possible. (If it can automagically break my lovely oversized prims in OS down to best fit puny SL equivalents then so much the better. :))
Ideally we could say something like “fetch completely folder named XXX from regionURL”, right? Or “replace with contents of regionURL [merging]” or “merge inventory from on regionURL”.
OK, a girl can dream.
@Serendipity - You might want to check out the work that Zonja has done with OAR manipulation (http://zonjacapalini.wordpress.com/) which might address some of your thoughts.
To my knowledge, there’s no public code for loading/saving OARs directly from Linden Lab’s Second Life implementation, though Rezzable do have some relevant unreleased software.