Feature Proposals/Multi-Region OARs

UPDATE: this feature has been implemented. See OAR Format 1.0.

This feature extends the OAR format to allow saving multiple regions in a single file.

The save-oar command still creates single-region OARs by default (OAR version 0.8). It saves the new format if the "--all" parameter is specified. The new format has version number 1.0 because older versions of OpenSim can't read it.

The load-oar command supports both OAR formats (0.x and 1.x). When it's given a 1.x OAR file it loads all the regions in the OAR into the corresponding regions in the simulator, according to their position relative to the root region. If the simulator doesn't have a region in a location that is present in the OAR then that region isn't loaded.

The layout of the OAR file is as follows. Each region is stored in a separate directory, but the assets are shared:

archive.xml
assets/
regions/
  1_1_Arizona/
    landdata/
    objects/
    settings/
    terrain/
  2_1_New_Mexico/
    landdata/
    objects/
    settings/
    terrain/
  1_2_Utah/
    landdata/
    objects/
    settings/
    terrain/
  2_2_Colorado/
    landdata/
    objects/
    settings/
    terrain/

The regions' directory names include the region's location (relative to the root region) in order to ensure uniqueness even if regions have duplicate names.

The file archive.xml contains a manifest of the included regions. The list of regions always describes a rectangle, with the root region (the region where the "save-oar" command was run) in the SW corner. The regions are listed in the following order: rows from South to North, and within each row regions are listed West-to-East. Missing regions are supported: they're represented by empty elements.

For example:

<?xml version="1.0" encoding="utf-16"?>
<archive major_version="1" minor_version="0">
  <creation_info>
    <datetime>1343204139</datetime>
  </creation_info>
  <assets_included>True</assets_included>
  <regions>
    <row>
      <region>
        <id>12345678-1111-1111-1111-111111111111</id>
        <dir>1_1_Arizona</dir>
        <is_megaregion>False</is_megaregion>
        <size_in_meters>256,256</size_in_meters>
      </region>
      <region>
        <id>12345678-2222-2222-2222-222222222222</id>
        <dir>2_1_New_Mexico</dir>
        <is_megaregion>False</is_megaregion>
        <size_in_meters>256,256</size_in_meters>
      </region>
    </row>
    <row>
      <region>
        <id>12345678-3333-3333-3333-333333333333</id>
        <dir>1_2_Utah</dir>
        <is_megaregion>False</is_megaregion>
        <size_in_meters>256,256</size_in_meters>
      </region>
      <region>
        <id>12345678-4444-4444-4444-444444444444</id>
        <dir>2_2_Colorado</dir>
        <is_megaregion>False</is_megaregion>
        <size_in_meters>256,256</size_in_meters>
      </region>
    </row>
  </regions>
</archive>