View source for Installing and Running Hypergrid On OpenSimulator 0.6.9

= Configuration for OpenSimulator 0.6.x =

== Installing ==

Checkout OpenSim, prebuild and build as normal or Download and install Binary Packages from the [[Main Page|MAIN&nbsp;Page]] <br />If you're running your opensim in '''Grid Mode''' mode with&nbsp;servers on other machines, you&nbsp;only need to modify your OpenSim.ini to enable HyperGrid. 

If you're running in standalone and you want it to be network-able, or if you have your grid on loopback (127.0.0.1) change all the [Network] server addresses to. See below. 

=== EXAMPLE Network Sections ===

==== Default Example, Network Settings for a Stand Alone: ====

<source lang="ini">[Network] = 9000

grid_server_url = "http://example.com:9000"

grid_send_key = null
grid_recv_key = null

user_server_url = "http://example.com:9000"

user_send_key = null
user_recv_key = null

asset_server_url = "http://example.com:9000"

inventory_server_url = "http://example.com:9000"
messaging_server_url = "http://example.com:9000"</source> 

==== Default Example, Network Settings for a Grided Server: ====

<source lang="ini">[Network]
http_listener_port = 9000

grid_server_url = "http://example.com:8001"
grid_send_key = null
grid_recv_key = null

user_server_url = "http://example.com:8002"
user_send_key = null
user_recv_key = null

asset_server_url = "http://example.com:8003"
inventory_server_url = "http://example.com:8003"
messaging_server_url = "http://example.com:8006"</source> 

==== Network Settings&nbsp;for OSGrid Attched Servers: ====

<source lang="ini">[Network]
http_listener_port = 9000
grid_server_url = "http://osgrid.org:8001" ;default 8003
grid_send_key = "1234"
grid_recv_key = "1234"

user_server_url = "http://osgrid.org:8002" 
user_send_key = "1234"
user_recv_key = "1234"

asset_server_url = "http://assets.osgrid.org:8003" 
inventory_server_url = "http://osgrid.org:8004" ;default 8003
messaging_server_url = "http://osgrid.org:8006"</source> 

==== Modifications needed to be applied to OpenSim.ini to enable Hypergrid ====

- Change the following line at the top of the OpenSim.ini 
<pre>hypergrid = false to true</pre>
- NEXT, Add or Modify the ### WORLD MAP Section as shown 

<source lang="ini">; ##
; ## WORLD MAP
; ##

WorldMapModule = "WorldMap"
MapImageModule = "MapImageModule"
WorldMapModule = "HGWorldMapModule" ;NOT INCLUDED IN DEFAULT OpenSim.ini.EXAMPLE</source> 

''Information: HGWorldMapModule will, after teleporting to another grid, clean up tiles in your map left over from the grid on which you were previously.'' 

- NEXT, Modify the [Archictecture] Section at the bottom 

Uncomment the appropriate Include-HG* = line by removing the semi colon and making sure that is the only ONE uncommented. (example shows for a Stand Alone HG enabled installation) 

<source lang="ini">[Architecture]
;Include-Standalone = "config-include/Standalone.ini" ; DEFAULT UNCOMMENTED
Include-HGStandalone = "config-include/StandaloneHypergrid.ini"
;Include-Grid = "config-include/Grid.ini"
;Include-HGGrid = "config-include/GridHypergrid.ini"</source>&nbsp; 

Your OpenSimulator instance should now be ready for inbound &amp; outbound Hypergrid use

== Important Notes ==
Make sure you have a 'home' set. If your home region doesn't exist, the hyperlink TPs may not work. To set your home, go to one of your local regions and "Set Home" from the viewer. 

To Enable scripted Teleporting between regions, standalone, HyperGrid etc, you can use osTeleportAgent function, Example here: [[OsTeleportAgent]]

== Linking regions (Optional) ==

Linking hypergrid regions permits users on your system to easily hypergrid teleport to other grids via the viewer map. For example, if you run Grid A and your friend runs Grid B and both grids are Hypergrid enabled, you can "link" to a region on Grid B from your ROBUST console to create a persistent hypergrid link to your friend's Grid B that appears on the viewer map. 

After creating the link using one of the methods below, your users on Grid A will see a map tile showing the connection to GridB on the viewer map, and can teleport to Grid B by double clicking the map tile to teleport.

You can view all hypergrid linked regions by typing the "show hyperlinks" command on the ROBUST console, and remove linked regions using the unlink-region command described below.

Creating links to hypergrid regions is not limited to grids as it works well for standalones. The hypergrid related console commands are the same for both modes. Use the console for the region server (simulator) instead of the ROBUST console.

=== Method 1 ===

On the console, type for example:
<pre>link-region &lt;Xloc&gt; &lt;Yloc&gt; http://osl2.nac.uci.edu:9006/</pre>
Use Xloc and Yloc that make sense to your world, i.e. close to your regions, but not adjacent. Replace <nowiki>http://osl2.nac.uci.edu:9006/</nowiki> with the URL (i.e. protocol, domain name/ip address, and http_listener_port) of the simulator where the region is running you want to link to.
You can link to a specific region within an instance, by using the name of the region at the end, for example: 
<pre>link-region &lt;Xloc&gt; &lt;Yloc&gt; http://osl2.nac.uci.edu:9006/ UCI Welcome</pre>
The above syntax is the preferred one for this console command starting with revision r/14611 (commit 72748746; this will be in release 0.7.1). The following syntax was used before and is still supported but deprecated in current (development) versions of OpenSimulator:
<pre>link-region &lt;Xloc&gt; &lt;Yloc&gt; osl2.nac.uci.edu:9006</pre> or <pre>link-region 997 997 osl2.nac.uci.edu:9006:UCI Welcome</pre>
Please note that this older syntax uses just the hostname without a protocol specification like <nowiki>http://</nowiki> and a colon instead of a space to append a region name.

=== Method 2 ===

There is also some initial support for reading the links from a xml file. 

Use the console command: link-region &lt;URI&gt; [&lt;excludeList&gt;] 

The uri can be either the path of a local xml file or a xml document on a http server. 

The format of the xml file is: 

<source lang="xml"><Nini>
<Section Name="Region1"> 
<Key Name="xloc" Value="1002"/>
<Key Name="yloc" Value="1006" />
<Key Name="externalPort" Value="9006" />
<Key Name="externalHostName" Value="osl2.nac.uci.edu" />
<Key Name="localName" Value="OSGrid-Gateway" />
<Key Name="real-xloc" Value="10222"/> //optional field that gives the region's real location on its home grid
<Key Name="real-yloc" Value="10265" /> //optional field that gives the region's real location on its home grid
</Section>
<Section Name="Region2"> 
...
</Section>
...
</Nini></source> 

[Note] The section names can be anything you want, but they all should be different and have no spaces in the name. 

==== ExcludeList: ====

The exclude list is a single string paramater with the format: excludeList:&lt;SectionName&gt;[;&lt;SectionName&gt;] 

This means that while reading from the xml file any sections that are listed in the excludeList will be ignored and no HyperGrid link created for them. 

This could allow, link lists to be created on a webserver that everyone could add their own regions to, and then they just make sure they add their own section name(s) to the exclude list on their own region(s). 

So for example, someone might create a editable online list for the up coming OpenSimulator's 2nd birthday. Which might look something like: 

<source lang="xml"><Nini>
<Section Name="OSGrid-Party"> 
<Key Name="xloc" Value="1002"/>
<Key Name="yloc" Value="1006" />
<Key Name="externalPort" Value="9006" />
<Key Name="externalHostName" Value="osl2.nac.uci.edu" />
<Key Name="localName" Value="OSGrid-Gateway" />
</Section>
<Section Name="UCIGrid-Party"> 
...
</Section>
</Nini></source> I could then add my own region to the list with the section name "MW-Party". Then when I startup that region that I want to be part of this hypergrid, I use the command: 
<pre>"link-region &lt;URI of xml file&gt; excludeList:MW-Party"</pre>
This is so that my region doesn't try to create a hyper link to itself. 

=== Method 3 (dynamic) ===

Starting in r8193, if you're in an HG-enabled region, you'll be able to dynamically link sims, and TP there, in any one of these ways (and probably more). All you need to know is the target address, e.g. from the list below. 

1) Type for example secondlife://ucigrid04.nacs.uci.edu:9007/ in the chat box, pull up the chat history and click on that link 

2) Pull up the map and search for things like ucigrid04.nacs.uci.edu:9007 

3) Using the embedded browser visit pages that have links like '''secondlife://ucigrid04.nacs.uci.edu:9007'''/ (there's one up at http://www.ics.uci.edu/~lopes/hypergrid/test.html) 

Again, you can link to a specific region within an instance by adding the name of that region at the end, like this: '''secondlife://ucigrid04.nacs.uci.edu:9007:Gateway 7000/''' 

=== Checking the 4096 Regions Limit ===
Due to the [[#The 4096 Regions Limit|4096 Regions Limit]], there is a check in OpenSimulator since version 0.7.0.1 which verifies that the intended link will be within reach of any of your regions. If none of the regions in your grid or standalone is located within a distance radius of 4096 regions from the region to be linked, then the link will be rejected. You can disable this check in StandaloneCommon.ini (for standalones) or Robust.HG.ini (for grids) with
<source lang="ini">[GridService]
      Check4096 = false</source>

=== Persistent Linked Regions ===
With grid mode, methods 1 and 2 will work on both the Robust console and the region console. On the region console, linked regions will not be stored in the database and will vanish when the region is shut down. Regions that are linked on the Robust console will be persistent over restarts until they are explicitly removed with unlink-region. This is no longer the case. Linked regions are now persistent whether they are linked in grid or standalone mode and must in both cases be explicitly removed with the unlink-region command.

== Listing linked regions ==

To see a list of all linked regions, use the following command on the console (available since 0.7.1 r/13457, also in 0.7-post-fixes):
<pre>show hyperlinks</pre>

== Unlinking regions ==

On the console, use the command: 
<pre>unlink-region &lt;local region name&gt;</pre>

As local region name you should use what command <tt>show hyperlinks</tt> shows for the region that you want to unlink, for example

<pre>unlink-region http://osl2.nac.uci.edu:9006/</pre>

With OpenSimulator revisions before r/14611 (i.e. before release 0.7.1), the syntax is a little different, for example
<pre>unlink-region osl2.nac.uci.edu:9006</pre>

Please note that region names can only have a maximum length of 32 characters when using MySQL as a database. If a linked region has a longer name, it will be truncated. The unlink-region command will only find a region, if the name is also truncated to a maximum length of 32 characters. This limit has been extended to 128 characters for the full local region name in OpenSimulator 0.7.1 (since r/14611).


[[Category:Hypergrid]]