OpenSimulator - User contributions [en]

Varregion

2014-03-06T02:23:28Z

Riebling:

'''Varregion'''

__TOC__
"Varregion" is a feature of OpenSimulator that enables region sizes larger than 256x256. The region is just larger so it acts like a regular region but with borders farther apart.

The implementation uses the [http://aurora-sim.org Aurora] large region protocol extensions so the existing [http://firestormviewer.org Firestorm] and [http://singularityviewer.org Singularity] Aurora support will now work for OpenSimulator.

This is different from the older [[Megaregions]] large region feature which does not require extra viewer support (above that already implemented by Linden Lab) but which relies on a number of fragile hacks to make a viewer work in a way that Linden Lab never supported. Megaregions also contain a number of extant simulator-side bugs.

A growing list of protocol changes to implement "varregion" is at [[varregion/Protocol|Varregion Protocol]].

==Restrictions==
Some restrictions apply:
* The dimensions must be a multiple of 256 and less than or equal to 8192.
* The dimensions must be square (as of 20131104)
* Adjacent regions must be the same size. For instance, you can have multiple 512x512 regions adjacent (and see into the other region and border cross). There seems to be a viewer problem where, if regions of different size are within view distance, crashes can happen. Consider having regions of only the same size 'in view'. Remember that the region coordinates are specified in 256m region count so a group of four 512x512 regions would be specified at 8000/8000, 8000/8002, 8002/8000, and 8002/8002, for instance.
* You must use BulletSim (as of 20131104, ODE has not been modified for varregions)
** You must use BulletSim's height map terrain implementation. As of 20140128, BulletSim has been modified to force heightmap terrain implementation if region size is greater than 256 on any side. The setting can be forced by adding to your INI files:
<pre>
[BulletSim]
TerrainImplementation = 0
</pre>

==Configuration==
The size is be specified in the <tt>Region.ini</tt> file:
<pre>
[MyRegionName]
RegionUUID = 95ec77ec-58c5-4ce2-9ff3-b6d1900d78a2
Location = 1000,1000
SizeX = 1024
SizeY = 1024
InternalAddress = 0.0.0.0
InternalPort = 9200
AllowAlternatePorts = False
ExternalHostName = SYSTEMIP
</pre>
If size is not specified, it will, of course, default to the legacy size of 256.

If the given dimensions do not fit the restrictions, acceptable values are computed and warning and error messages are output into the log.

If converting from a mega-region, remember to set "<tt>CombineContiguousRegions = false</tt>".

for llRezObject to work beyond 256m set "ScriptDistanceLimitFactor = 52.0" (for 512mx512m) in the [Xengine] section of OpenSim.ini.

The terrain heightmap is stored in the database as an array of 'shorts' (two bytes) so, if you have a very large region you might need to set the database maximum size to a larger value. For instance, a 2816x2816 region (11x11 legacy regions) turns into a 56 megabyte heightmap and, for MySQL, you would need to set <tt>max_allowed_packet</tt> to something like 64M.

==Loading Terrain==
The usual terrain console commands work with varregions. If you have set up a larger region, you can load BMP/RAW/PNG heightmap files of the dimensions of the region and fill the whole region. For instance, a 1024x1024 region terrain would be completely initialized by "terrain load 1024.bmp" if '1024.bmp is a 1024x1024 bitmap.

==Varregions and OAR Files==
The objects and terrain are stored in an OAR file as if it was one region. That is, if you save a 1024x1024 region in an OAR file, you can later restore the objects and terrain into a 1024x1024 sized region. If you load an OAR file from a smaller region into a larger region, the unspecified terrain space will default to 25m.

To make conversion to varregions easier, 'load oar' now has a '--displacement "<x,y,z>"' parameter. This displaces all of the objects and the terrain from the oar file when loading them into the new region. For instance, say you have four
OAR files from four adjacent 256x256 regions (oar00.oar, oar01.oar, oar10.oar, and oar11.oar). You create a new 512x512 varregion named 'bigregion'. The following commands place the four regions of objects, terrains and parcels
into the new larger region:

<pre>
change region bigregion
load oar oar00.oar
load oar --displacement "<0,256,0>" --merge --forceterrain --forceparcel oar01.oar
load oar --displacement "<256,0,0>" --merge --forceterrain --forceparcel oar10.oar
load oar --displacement "<256,256,0>" --merge --forceterrain --forceparcel oar11.oar
</pre>

Note the new "--forceterrain" and "--forceparcel" parameters. "--merge", used by itself, is for merging together the objects from multiple OARs. Merging also suppresses the loading of terrain and parcel data which is just what you want when merging objects. But, if loading multiple OARs to create a new, larger region, the terrain and parcel information must be loaded. Thus the new parameters.

==Things Known to be Broken==
* There is some problem with teleporting in an out of larger region. It works for some configurations and not others.
* While adjacent regions are usually viewable, sometimes they are not. They appear when you cross over into the region.

==Implementation Discussion==
Since this will be a major change to OpenSimulator that touches a
lot of different parts, subsequent posts, will discuss the changes I'm making.

===TerrainData===
One major problem is passing the terrain data from the region to the
protocol stack. The existing implementation passed an array of floats
that were presumed to be a 256x256 array of region terrain heights.
The
<tt>TerrainChannel</tt>
class is an attempt to hide the terrain implementation
from
<tt>TerrainModule</tt>
.
<tt>TerrainChannel</tt>
can't be passed into the protocol
stack (LLClientView) because
<tt>TerrainChannel</tt>
is defined as part of
<tt>OpenSim.Region.Framework</tt>
which is not visible to the protocol code.

My solution is to create the
<tt>TerrainData</tt>
class in
<tt>OpenSim.Framework.</tt>
<tt>TerrainData</tt>
just wraps the data structure for the terrain and additionally has
the attributes giving X and Y size.

I didn't want to change the signature of IClientAPI since so many external modules
rely on it.
It should be changed to pass <tt>TerrainData</tt> rather than a <tt>float[]</tt>.
I decided to not change IClientAPI but rather have <tt>LLClientView</tt> ignore
the passed array and instead reach back into the associated scene and fetch the
<tt>TerrainData</tt> instance.

There is one subclass of <tt>TerrainData</tt>: <tt>HeightmapTerrainData</tt> which keeps the terrain as a compressed heightmap. The height of each point is stored as a <tt>short</tt> which is <tt>height * compressionFactor</tt> where <tt>compressionFactor</tt> is usually "100". This creates a compact storage of the terrain heights with two decimal points of resolution.

The LLLP ("Linden Lab Legacy Protocol") sends terrain height data in
compressed "patches" of 16x16 areas of the terrain
height. This is a protocol feature that is implemented in <tt>TerrainChannel</tt>.
I feel that underlying protocol optimizations shouldn't appear up the
stack so, in creating <tt>TerrainData</tt>, I tried to hide terrain patches.
I mean, someday terrain will be generalized meshes. Right?

===Terrain in the Database===
Previously, terrain height maps were saved in the database as a blob of 256x256 doubles. To have different region sizes, that format had to change. There is an existing database field <tt>revision</tt> that stored the time the terrain was saved. This revision information wasn't used for anything so this field was co-opted to contain a revision code for the height field blob.

There are three forms for the height map blob: legacy, compressed2D and regular2D. "legacy" is, of course, the previous 256x256 collections of doubles. "regular2D" contains the X, Y dimensions and enough floats for that area's heights. "compressed2D" contains the X,Y and compressionFactor followed by enough shorts for the height map.

The database readers and writers default to the legacy format and, if the region happens to have the dimensions 256x256, it is stored using the legacy format. This is an attempt to keep downward compatibility.

All of the database modules (MySQL, SQLite, MSSQL and PSQL) have been modified to store terrain this new way.

===Sensing Border Crossing===
Most of the ‘move to new region’ code is based on checking boundaries. There is much code related to computing if an object or avatar has crossed a region boundary and then computing the address of the next region from same. Introducing variable sized regions messes a lot of this computation up. That is, the code doing the arithmetic usually assumes it knows the address of the next region based on a known region size and them can compute the location of the next region based on that. With varregions those assumptions no longer hold. Varregion implementation means that the computation of region base locations and border locations moves to the GridService who is the entity who really knows the size of all the regions and what is adjacent to what.

The realization that location to region computation is really a GridService operation lead me to totally rip apart the grid boundary checking code and replace it with two functions: <tt>Scene.PositionIsInCurrentRegion(Vector3 pos)</tt> and then <tt>EntityTransferModule.GetRegionContainingWorldLocation(double X, double Y)</tt>. The former function tests to see if the object/avatar has moved out of the current region and the latter gets the region moved into. (Side note: <tt>GetRegionContainingWorldLocation</tt> should really be a function on <tt>IGridService</tt> but that exercise is left for future hacking).

These changes leave all the 'border' code in limbo -- the generation of the border lists is still there but it is not being used. This should eventually be cleaned up. Also, the computation of neighbor regions is scattered around with routines on <tt>IGridService</tt>, in <tt>EntityTransferModule</tt> and a bunch of bookkeeping in <tt>Scene</tt>. This too should be cleaned up.

==Implementation Notes==

As of January 27, 2014, varregion is a feature of the 'master' repository branch.

===Stuff to Work On===
What follows are notes I am making as things that might need work are found in OpenSimulator.

* Consolidate neighbor region computation code (Scene, EntityTransferModule and IGridService all have 'get neighbor' code)
* Clean up/eliminate border list creation and use code
* Region handles are world coords and also the base of the region
** verify that everyone who converts coords to handle (Util.RegionWorldLocToHandle) is supplying the base of the region. (mostly done)
* ITerrainLoader implementations (mostly done)
** How to handle tiles.
** How to handle large regions sizes.
** Terrain/FileLoaders/*.cs all return an ITerrainChannel
** Need to fix all the file reader/writers
** FileLoaders/LLRAW.cs has several "256"s rather than constant references
* Teleporting: should be able to teleport to anywhere in a large region
** "MyRegion/550/687/40"
* HG code needs to allow addresses anywhere into large regions
* When GridService return adjacent regions, make sure it does the right thing for large regions
* Consider moving terrain XML serialization into TerrainData
* Consider removing all instances of TerrainChannel.GetFloatsSerialized()
** Replace with passing around TerrainData
* Code in EntityTransferModule that checks distance to decide if to make new connection
** search for references to 'Constants.RegionSize'
** Consider removing the distance code and replacing with call to grid service
* WorldMapModule.cs does a lot of arithmetic depending on constants that are really Contants.RegionSize
* Util.IsOutsideView uses Constants.RegionSize. Is use in ScenePresence a problem?
** Used in ScenePresence.AdjustKnownSeeds()
** Is this another instance like EntityTransferModule that needs to goto the grid service?
* Move all the short[] heightmap representation stuff into TerrainData.cs (partially done)
** Is it possible to move all the patch stuff out of TerrainModule/TerrainChannel?
** Clean up the use of m_revert. It looks like it is not saved after terrain is modified.
* Need to look through RegionCombinerModule.cs and see what safety checks are needed
** Maybe just prevent combination if not legacy region size
* In LSL_Api.cs, llEdgeOfWorld() does some neighbor computation. Check for ok'ness.
* LandManagementModule.SendParcelOverlay sends land sale/ownership info for 4x4m areas
** Looks like it expects to send exactly one 1024 byte block (for the 256x256 legacy region
** Check viewer code for what will happen for larger regions
* The code for cloud and wind needs to be enhanced for larger regions
** New overlay types added
* LLClientView.SendMapBlockSplit() needs to have region size to send with the map info
* Region/Framework/Scenes/Tests/BorderTests.cs might need work if non-standard regions are tested
* Verify terrain tests still work (for 256m regions)
* Region coords are sometimes 'int' and sometimes 'uint' with conversions EVERYWHERE
** pass over everything and convert region coordinates it 'uint's
** consider creating structures for world and region coordinates so there can be compile time checking

====Viewer====
* LLSurface is wired to expect adjacent regions of same size
* Terrain surface image is sized with a 'static": " static S32 sTextureSize; // Size of the surface texture"
* From FreeNode:#SingularityViewer 20131125:
<pre>
<Aleric> radams1, SianaGearz, frnic : I couldn't help myself doing a profile anyway.. The reason the viewer is slow is because it's busy "drawing" the terrain. "drawing" between quotes because my guess is that it is trying to draw ALL terrain and then clip that afterwards to the frustrum...
<Aleric> So, this could be greatly improved by disregarding terrain way way earlier when it is beyond the drawing range anyway.
<SianaGearz> OK
<Aleric> I disabled all rendering, even added a 'return' in terrain render
<Aleric> but.. no improvement of FPS!
<frnic> oops
<Aleric> LLSurfacePatch::updateVisibility() is still eating a lot of cpu.
<Aleric> LLSurface::updatePatchVisibilities does 97% of the calls to LLSurfacePatch::updateVisibility
<Aleric> which then spends most of it's time calling LLCamera::AABBInFrustumNoFarClip
</pre>
* Singularity commit for varregion: https://github.com/singularity-viewer/SingularityViewer/commit/ad8ea07a

==Testing==
* Terrain/parcel operations
** Default 256 standalone region
*** Clean database. Start single standalone region. Verify 'pimple' region. Verify one parcel. Flatten region.
*** Create parcels adjacent to each edge and standalone in middle. Change names of each parcel and verify. Restart simulator and verify parcels exist and work correctly.
*** Save five parcel region as OAR. Clear database. Restart region. Load oar. Verify 5 parcels of correct location, name and features.
** Adjacent 256 standalone regions
** 768x768 standalone region
** Changing land from 256 to 768
* Teleporting
* Adjacency
* Hypergrid

==Tips on Migrating Existing Sims to VarRegions==
* When you start the sim, you have to have either no regions nearby, or identical sized regions. otherwise, it locks your movement to the size of the smallest region
* When you load your oars, it's like Aurora sim. You need to load them by displacement first, load each one in place to get the terrains.
* When you merge, you lose the terrain.
* The second round, you reload each oar, this time with merge to load the objects.
* If you don't use merge, you lose all the objects with each oar load.
* When you load your oars, in format "<0,0,0>" the first number is east/west, or x.
* The second number is north/south, or y
* The third number is up or down, or z.
* The location must be in increments of 256.

Freeswitch Module

2010-02-23T23:13:18Z

Riebling: /* OpenSim Config */ This example misled me for DAYS. Is 192.168.0.2 a "magic number?"

__NOTOC__
{{Template:Quicklinks}}
<br />

The FreeSwitch module enables voice in opensim with no changes required to the SL or Hippo clients (must be over 1.22 for SL and 0.5 for Hippo)

== FreeSwitch Install ==

Follow the instructions [http://wiki.freeswitch.org/wiki/Installation_Guide here] on how to compile from source. We need to enable two specific modules.
'''
please ensure you compile from the freeswitch trunk for now until we can post a minimum version number (there are known issues with older versions)'''

When you get to the part in the instructions where it says "'''Edit modules.conf so that it will build the modules you desire.'''" edit the modules.conf file and uncomment out the entries for xml_curl and the siren14 codec

codecs/mod_siren
and
xml_int/mod_xml_curl

* You can also use this [http://madhawa.com/?p=10 guide] for setting it up in a quick way -- [[User:Fly-man-|Fly-man-]]

==FreeSwitch Config==

Install and compile Freeswitch, making sure you enable the xml_curl module and also the siren14 codec.

=== enable mod_xml_curl ===

Next, do not forget to activate mod_xml_curl in /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml. mod_xml_curl is disabled by default on fresh install.

uncomment the lines...
<load module="mod_xml_curl"/>

and

<load module="mod_siren"/>

=== configure mod_xml_curl ===

the xml_curl module configuration should point to an opensim region that has the freeswitch voice module enabled (voice also needs to be enabled in the estate setting for all regions)

example xml_curl.conf.xml found in /usr/local/freeswitch/conf/autoload_configs

<configuration name="xml_curl.conf" description="cURL XML Gateway">
<bindings>
<binding name="example">
<param name="gateway-url" value="http://youropensimregion:9000/api/freeswitch-config" bindings="directory"/>
<param name="gateway-credentials" value="freeswitch:password"/>
<param name="disable-100-continue" value="true"/>
</binding>
<binding name="local">
<param name="gateway-url" value="http://youropensimregion:9000/api/freeswitch-config" bindings="dialplan"/>
<param name="gateway-credentials" value="freeswitch:password"/>
<param name="disable-100-continue" value="true"/>
</binding>
</bindings>
</configuration>

The /usr/local/freeswitch/conf/vars.xml requires modification to enable the siren14 codec

search within vars.xml for the global_codec_prefs and change the line to read

<X-PRE-PROCESS cmd="set" data="global_codec_prefs=G7221@32000h,G722,PCMU,PCMA,GSM"/>

or

<X-PRE-PROCESS cmd="set" data="global_codec_prefs=G7221@32000h,G7221@16000h,G722,PCMU,PCMA,GSM"/>

G7221@32000h is the siren14 codec

=== configure conference.conf.xml ===
By default, FreeSwitch plays hold music when there is only one avatar in the conference and beeps for everyone when avatars arrive and leave. To disable, edit /usr/local/freeswitch/conf/autoload_configs/conference.conf.xml. Locate the "default" profile and comment out the following lines as shown below:

[...]


[...]








[...]

==OpenSim Config==

Add the following section to OpenSim.ini. You will also need to enable voice in the regions estate settings. Make sure the freeswitch server is started BEFORE bringing the region up.

[FreeSwitchVoice]
enabled = true
;FreeSwitch server is going to contact us and ask us all
;sorts of things.
freeswitch_server_user = freeswitch
freeswitch_server_pass = password
freeswitch_api_prefix = /api
;The IP address of your opensim voice region
freeswitch_service_server = youropensimexternalIP
;the port your region is running on
freeswitch_service_port = 9000
;your freewitch IP address
freeswitch_realm = 192.168.0.2
freeswitch_sip_proxy = 192.168.0.2:5060
freeswitch_attempt_stun = false
freeswitch_stun_server = 192.168.0.2
freeswitch_echo_server = 192.168.0.2
freeswitch_echo_port = 50505
freeswitch_well_known_ip = 192.168.0.2
freeswitch_default_timeout = 5000
freeswitch_subscribe_retry = 120

It appears to work better if the IP address you put in for "youropensimexternalIP" also appears in all the subsequent slots in place of 192.168.0.2.

OpenSim Archives

2009-05-04T15:49:14Z

Riebling: /* Usage */

==Introduction==

This function which has existed since r5469 (post 0.5.8). 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 go a step further in that they can save all the necessary asset data to fully restore the terrain, 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

To load an archive, type

load oar [<filename>]

at the console. If no filename is given, then the server looks for a file called region.oar in the current directory.

Currently by default, loading an archive will delete all the objects in the scene 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.

==Examples==

[http://www.secondlifelab.it/downloads/cyberlandia.tar.gz cyberlandia.tar.gz] - cyberlandia landscape designed by the architect Simone Riccardi aka turboy. Contemporary architecture surrounded with a natural/synthetic context [http://www.flickr.com/photos/8905571@N05/3182585775/ image_1] [http://www.flickr.com/photos/8905571@N05/3171070049/ image_2] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]).

[http://www.lordfly.com/nuathens.zip nuathens.zip]- A four region combo called the Nu Athens neighborhood. [http://www.sluniverse.com/php/vb/project-development/16014-nu-athens-interactive-story-opensim-2.html#post501412 Info] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]

===OAR file from "Lusitania Tester" for all===
[http://www.worldsimterra.com/index.php?option=com_content&view=article&id=163&Itemid=100263 OAR-File.tar.gz]- Every week (on Sunday after 21:00 UTC) a OAR file from "Lusitania Tester" of WorldSimTerra-Grid is available for use of building and rezz of different avatars. All the avatars of all the grids are invited to place their free buildings and rezz to share with the OpenSim community. To get the OAR file, the member of the OpenSim community will make the registration on the site, after logging in, the downloads are available on the "Avatar Toolbox" tab (this tab is only available after you login to the site)

Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.

==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==

* Parcel information is not currently saved. This will be addressed in the future.
* Performance is not very good, especially with large archives. This will be addressed in the future

==File Formats==

[[OpenSim Region Archive Format|OAR File Formats]]

==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 [http://www.7-zip.org/ 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.

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.

OpenSim Archives

2009-05-04T15:48:23Z

Riebling: /* Usage */

==Introduction==

This function which has existed since r5469 (post 0.5.8). 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 go a step further in that they can save all the necessary asset data to fully restore the terrain, 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

To load an archive, type

load oar [<filename>]

at the console. If no filename is given, then the server looks for a file called region.oar in the current directory.

Currently by default, loading an archive will delete all the objects in the scene 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 file format of the downloads on this page is '''.tar.gz''' which illustrates that the '''.oar''' format is actually a zipped tar file.

==Examples==

[http://www.secondlifelab.it/downloads/cyberlandia.tar.gz cyberlandia.tar.gz] - cyberlandia landscape designed by the architect Simone Riccardi aka turboy. Contemporary architecture surrounded with a natural/synthetic context [http://www.flickr.com/photos/8905571@N05/3182585775/ image_1] [http://www.flickr.com/photos/8905571@N05/3171070049/ image_2] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]).

[http://www.lordfly.com/nuathens.zip nuathens.zip]- A four region combo called the Nu Athens neighborhood. [http://www.sluniverse.com/php/vb/project-development/16014-nu-athens-interactive-story-opensim-2.html#post501412 Info] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]

===OAR file from "Lusitania Tester" for all===
[http://www.worldsimterra.com/index.php?option=com_content&view=article&id=163&Itemid=100263 OAR-File.tar.gz]- Every week (on Sunday after 21:00 UTC) a OAR file from "Lusitania Tester" of WorldSimTerra-Grid is available for use of building and rezz of different avatars. All the avatars of all the grids are invited to place their free buildings and rezz to share with the OpenSim community. To get the OAR file, the member of the OpenSim community will make the registration on the site, after logging in, the downloads are available on the "Avatar Toolbox" tab (this tab is only available after you login to the site)

Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.

==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==

* Parcel information is not currently saved. This will be addressed in the future.
* Performance is not very good, especially with large archives. This will be addressed in the future

==File Formats==

[[OpenSim Region Archive Format|OAR File Formats]]

==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 [http://www.7-zip.org/ 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.

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.

User talk:Riebling

2009-05-04T15:19:02Z

Riebling:

Removed link to sample (scene_oar.tar.gz - justincc's very basic environment containing a few prims, one script and a big chasm) because the hosting service reports the file has been removed.

Added text explaining the dissonance between ".oar" format and ".tar.gz" files actually linked to the page. When I first downloaded a .tar.gz file and inspected it's contents, I thought "oh crap this must not be a .oar file, it's just a bunch of .xml files" but in fact it was, and they're interchangeable. So I guess the semantics are that ".oar format" refers to the CONTENTS of the zipped tar file, whereas ".tar.gz" refers to the format of the archived and compressed contents. But to tell folks the preferred naming convention is ".oar" and then never use it in the example downloads = dissonance! We prefer harmony. :)

User talk:Riebling

2009-05-04T15:07:12Z

Riebling:

Removed link to sample (scene_oar.tar.gz - justincc's very basic environment containing a few prims, one script and a big chasm) because the hosting service reports the file has been removed.

Added text explaining the dissonance between ".oar" format and ".tar.gz" files actually linked to the page. When I first downloaded a .tar.gz file and inspected it's contents, I thought "oh crap this must not be a .oar file then" but in fact it is, and they're interchangeable. So I guess the semantics are that ".oar format" refers to the CONTENTS of the zipped tar file, whereas ".tar.gz" refers to the format of the archived and compressed contents.

User talk:Riebling

2009-05-04T15:04:40Z

Riebling: Explanation

Removed link to sample (scene_oar.tar.gz - justincc's very basic environment containing a few prims, one script and a big chasm) because the hosting service reports the file has been removed.

OpenSim Archives

2009-05-04T15:01:29Z

Riebling: /* Usage */

==Introduction==

This function which has existed since r5469 (post 0.5.8). 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 go a step further in that they can save all the necessary asset data to fully restore the terrain, 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

To load an archive, type

load oar [<filename>]

at the console. If no filename is given, then the server looks for a file called region.oar in the current directory.

Currently by default, loading an archive will delete all the objects in the scene 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 file format of the downloads on this page is '''.tar.gz''' which illustrates that the '''.oar''' format is actually a zipped tar file.

==Examples==

[http://www.secondlifelab.it/downloads/cyberlandia.tar.gz cyberlandia.tar.gz] - cyberlandia landscape designed by the architect Simone Riccardi aka turboy. Contemporary architecture surrounded with a natural/synthetic context [http://www.flickr.com/photos/8905571@N05/3182585775/ image_1] [http://www.flickr.com/photos/8905571@N05/3171070049/ image_2] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]).

[http://www.lordfly.com/nuathens.zip nuathens.zip]- A four region combo called the Nu Athens neighborhood. [http://www.sluniverse.com/php/vb/project-development/16014-nu-athens-interactive-story-opensim-2.html#post501412 Info] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]

===OAR file from "Lusitania Tester" for all===
[http://www.worldsimterra.com/index.php?option=com_content&view=article&id=163&Itemid=100263 OAR-File.tar.gz]- Every week (on Sunday after 21:00 UTC) a OAR file from "Lusitania Tester" of WorldSimTerra-Grid is available for use of building and rezz of different avatars. All the avatars of all the grids are invited to place their free buildings and rezz to share with the OpenSim community. To get the OAR file, the member of the OpenSim community will make the registration on the site, after logging in, the downloads are available on the "Avatar Toolbox" tab (this tab is only available after you login to the site)

Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.

==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==

* Parcel information is not currently saved. This will be addressed in the future.
* Performance is not very good, especially with large archives. This will be addressed in the future

==File Formats==

[[OpenSim Region Archive Format|OAR File Formats]]

==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 [http://www.7-zip.org/ 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.

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.

OpenSim Archives

2009-05-04T14:59:32Z

Riebling: /* Examples */

==Introduction==

This function which has existed since r5469 (post 0.5.8). 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 go a step further in that they can save all the necessary asset data to fully restore the terrain, 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

To load an archive, type

load oar [<filename>]

at the console. If no filename is given, then the server looks for a file called region.oar in the current directory.

Currently by default, loading an archive will delete all the objects in the scene 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'''

==Examples==

[http://www.secondlifelab.it/downloads/cyberlandia.tar.gz cyberlandia.tar.gz] - cyberlandia landscape designed by the architect Simone Riccardi aka turboy. Contemporary architecture surrounded with a natural/synthetic context [http://www.flickr.com/photos/8905571@N05/3182585775/ image_1] [http://www.flickr.com/photos/8905571@N05/3171070049/ image_2] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]).

[http://www.lordfly.com/nuathens.zip nuathens.zip]- A four region combo called the Nu Athens neighborhood. [http://www.sluniverse.com/php/vb/project-development/16014-nu-athens-interactive-story-opensim-2.html#post501412 Info] (work under [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons by attribution]

===OAR file from "Lusitania Tester" for all===
[http://www.worldsimterra.com/index.php?option=com_content&view=article&id=163&Itemid=100263 OAR-File.tar.gz]- Every week (on Sunday after 21:00 UTC) a OAR file from "Lusitania Tester" of WorldSimTerra-Grid is available for use of building and rezz of different avatars. All the avatars of all the grids are invited to place their free buildings and rezz to share with the OpenSim community. To get the OAR file, the member of the OpenSim community will make the registration on the site, after logging in, the downloads are available on the "Avatar Toolbox" tab (this tab is only available after you login to the site)

Please feel free to place links to other environments here, though unfortunately you'll have to host them on some other site.

==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==

* Parcel information is not currently saved. This will be addressed in the future.
* Performance is not very good, especially with large archives. This will be addressed in the future

==File Formats==

[[OpenSim Region Archive Format|OAR File Formats]]

==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 [http://www.7-zip.org/ 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.

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.

User:Riebling

2009-04-10T14:29:07Z

Riebling: First time greeting

Hello Avatar!