OpenSim Archives
From OpenSimulator
Technical Reference -> Terms -> How do I use the OAR Function?
Contents |
How do I use the OpenSim Archive Function?
Introduction
The OpenSim Archive (OAR) function has existed since OpenSim 0.5.9. Basically, it does a similar job to load-xml2/save-xml2 in that it saves prims so that they can be later reloaded. However, OpenSim archives (OAR) go a step further in that they can save all the necessary asset data so that you may fully restore the terrain, region parcel data, the textures of objects and their inventories when loaded onto a completely different system using a different asset database.
Usage
From the region console, one can type
save oar [<filename>]
to save an OpenSim archive. If no filename is given, then the name region.oar is used in the current directory.
EXAMPLES:
save oar save oar my.oar save oar c:/mybackups/filename.oar save oar oars/11nov.oar
To load an archive, type
load oar [--merge] [<location>]
at the console. The location can be a filesystem path (as for "save oar") or an HTTP address to load an oar directly over the web. If no location is given, then the server looks for a file called region.oar in the current directory.
EXAMPLES:
load oar load oar my.oar load oar --merge oars/3rd-party.oar load oar http://path.to/oarfile.oar
By default, loading an archive will delete all the existing objects in the regions and replace them with the archive contents. It's like being in the Matrix (when they swap environments), except much slower (all the scene objects are slowly deleted before the new environment is loaded :-)
When an archive is loaded, owners will be restored if the relevant uuids can be found in the OpenSim installation's user database. Otherwise, prim ownership will default to the master avatar for the region.
I recommend that you use filenames with the extension .oar. The filename extension of the download links on this page is .tar.gz which illustrates that the .oar format is actually a zipped tar file.
Switches
Saving
If the --noassets option is specified, then the oar will be saved without assets. This can be handy if you're backing up the asset database separately and don't want the expense of including all the assets in each OAR. *dev branch only*
Loading
If the --merge option is specified, then the oar will be merged with the existing region objects rather than replace them. The existing terrain, region settings and parcels will be left in place.
Example OARs
cyberlandia.tar.gz - cyberlandia landscape designed by the architect Simone Riccardi aka turboy. Contemporary architecture surrounded with a natural/synthetic context image_1 image_2 (work under Creative Commons by attribution).
OpenVCE 3D Assets OAR
The OpenVCE.net virtual worlds assets described at http://openvce.net/vwassets provided by Clever Zebra and the OpenVCE.net team at AIAI in the University of Edinburgh are available as an OAR (Opensim Archive) file.
http://openvce.net/resources/downloads/
Get file "opensim-openvce.oar" from there (right click on the file in the above directory in your browser, and select download is the easiest way to obtain the materials). A "full" set of the buildings with a large 400 seat amphitheatre intended to be placed on the corner of 4 sims is also available via "opensim-openvce-full.oar". Images of the buildings in place in Opensim are at: Image 1, Image 2
Others
Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.
http://www.opensimworlds.com/index.php?part=worlds
http://www.rexxed.com/category/sim/
http://forums.osgrid.org/viewforum.php
Further Information
- http://justincc.org/blog/category/oars/ - various OAR related articles from justincc, including background information and possible future development.
Use cases
Possible current uses are
1. To migrate data from an SQLite region database to one based on MySQL
2. To distribute entire regions to other people.
Current limitations
- Performance is not very good, especially with large archives. This will be addressed in the future
- Loading large OARs using the default SQLite database plugin will take a very very long time (in the order of many hours). I highly recommend that you switch to MySQL if you want to load large archives.
Upcoming enhancements
In developers code there is now a new option for save oar:
save oar [-profile=<url>] [<filename>]
<url> is the URL of this world's profile service. If profile information is given, all names of creators from this world will be appended with links to their profiles. It is not required that the profile service be operational; the information will be added and it will be available in all worlds that import this OAR.
Example:
save oar -profile=http://mygrid.com/user my.oar
OAR Format
The region OpenSim Archive (OAR) format is designed with three aims in mind:
- Make it easy for people to read and change individual objects, assets, etc. within an archive.
- Make it easy to compose two region archives into a single region archive.
- Make it easy to compose archives from scratch.
Therefore, all the different entities (assets, objects, terrains, etc.) are packaged in individual files (e.g. one for each asset) with human readable filenames and machine readable extensions (e.g. .jp2 for textures, .txt for notecards).
FAQ
1. What is this .tar.gz format you are using for the internal OAR format? Why not zip?
.tar.gz is a standard unix way of zipping up files into a single larger compressed file for distribution. Windows users should be able to open these files using freeware programs such as 7-zip.
I'm using .tar.gz because all the zip (and tar) libraries for .net are licensed either under the GPL (with exception) or under the MSPL. Unfortunately, not all members of the OpenSim development team are comfortable with the MSPL, so these libaries are not currently an option. It is also significantly easier to write code to create and read tar archives than zip archives.
Also, if you're only ever loading and saving oars (rather than pulling them apart and putting them back together), then you don't need to worry about the internal format at all :)
2. Can you load and save multiple regions to an archive?
Not yet.
3. Can you load and save parts of a region to an archive?
Not yet.
Bugs
- Due to a possible bug in the Mono 1.2.4 libraries, this feature may cause a debug dump when used (the problem appears to be in writing out a compressed stream). Mono 1.2.6 is okay. Since Mono 1.2.4 is fairly old now, this bug will not be addressed.
Current Status
Operational. Bug reports are appreciated Justincc 14:53, 14 September 2009 (UTC)
Though we will strive to maintain compatibilty for old archives with newer OpenSimulator versions, please don't rely on these archives as the only backup for regions.
