Regions: Difference between revisions

From Open Metaverse Wiki
(Adding a little bit more info about region sizes and a backlink to the Opensimulator main page)
 
(5 intermediate revisions by one other user not shown)
Line 1: Line 1:
=Introduction=
''[[Opensimulator]]: Documentation: Regions''
 
Subjects related to regions.
Subjects related to regions.


=Types of regions=
=Region sizes=


==Standard sized regions==
==Standard sized regions==
Line 8: Line 9:


==Varregions==
==Varregions==
Open Simulator supports variable sized regions. These are usually (always?) multiples of 256 meters on a side.
The varregion is based on the old megaregion concept but with completely rewritten code allowing for much more integration of the 256x256 m "blocks". The dimension limits (quadratic and multiples of 256 m) are the same as for a megaregion but for nearly all other practical purposes a varregion is treated by the simulator as a single unit.
 
==Megaregions==
The megaregion was introduced by [Aurora] and later adopted by other opensimulator forks.
 
A megaregion is essentially made from several standard regions merged into a single simulator with all region "blocks" sharing the same server resources and several other features and with no region borders between them. Since it's based on the standard 256x256 m region, the size of a megaregion has to be a product of 256 m and the region has to be quadratic with the same numebr of "blocks" along the x (west-to-east) and the y (south-to-north) axis.
 
The megaregion is an outdated concept, replaced by the varregion, but there may still be used by a few grids running on old versions of Opensimulator.


=Initial connection to a region=
=Initial connection to a region=
TBD
The process by which a viewer connects to a region is rather complicated. It's necessary to accumulate information sent via multiple routes before the viewer can start up a new region.
 
For the initial region, the reply from the login server provides enough information to get the process started, but not enough to start up the region. Additional data needed include:
 
* The major capabilities, which are obtained by making an HTTP request of the seed capability, which is a URL answered by the region server.
* The region handshake reply, which is sent by the server to the viewer over the UDP connection, in response to a region handshake request.
 
Both of those requests must be answered before the region can be created in the viewer.


==Login to the first region==
==Login to the first region==
The login process starts with an XMLRPC request to the login server. On a successful login, an XML set of key-value pairs is returned, which includes, at least:
The login process starts with an XMLRPC request to the login server. On a successful login, an XML set of key-value pairs is returned, which includes, at least:


* seed_capability -- the URL for the initial region used to query for more capability URLs.
; seed_capability : the URL for the initial region used to query for more capability URLs.
* secure_session_id -- a unique UUID for the current session. Unclear what this is for.
; secure_session_id : a unique UUID for the current session. Unclear what this is for.
* circuit_code: Self::get_key_i64(&login_reply, "circuit_code")?.try_into()?,
; circuit_code: a unique ID which identifies the UDP connection
* sim_ip -- the IP address of the initial region server. This is currently IPv4 only.
; sim_ip : the IP address of the initial region server. This is currently IPv4 only.
* sim_port -- UDP port, to be used with sim_ip, for receiving and sending UDP messages.
; sim_port : UDP port, to be used with sim_ip, for receiving and sending UDP messages.
* session_id -- UUID of the current session.
; session_id : UUID of the current session.
* agent_id -- UUID of the avatar logging in. This is the avatar's permanent identity.
; agent_id : UUID of the avatar logging in. This is the avatar's permanent identity.
* message -- Message to display to the user at login. Usually a message of the day or some such.
; message : Message to display to the user at login. Usually a message of the day or some such.
* first_name -- First name of user/avatar.
; first_name : First name of user/avatar.
* last_name -- Last name of user/avatar.
; last_name : Last name of user/avatar.
* start_region [x, y] -- world coordinates of the southwest (0,0) corner of the initial region.
; start_region [x, y] : world coordinates of the southwest (0,0) corner of the initial region.
* look_at [x,y,z] -- unit vector indicating the initial direction of view.
; look_at [x,y,z] : unit vector indicating the initial direction of view.


Note that this information does not contain the initial location of the avatar. That reaches the viewer via an object update to an object with the same UUID as the agent_id. An implication of this is that the viewer doesn't know where the avatar is at startup, yet it will have to send an agent update before it knows that. This causes a race condition in interest list updates.
Note that this information does not contain the initial location of the avatar. That reaches the viewer via an object update to an object with the same UUID as the agent_id. An implication of this is that the viewer doesn't know where the avatar is at startup, yet it will have to send an agent update before it knows that. This causes a race condition in interest list updates.
Line 33: Line 48:
Open Simulator logins for grids with varregions provide some additional info:
Open Simulator logins for grids with varregions provide some additional info:


* "region_size_x"
; region_size_x : Region size, meters.
* "region_size_y"
; region_size_y : Region size, meters.


If these are absent, 256 is the default value.
If these are absent, 256 is the default value.
Line 49: Line 64:
The data sent in an EnableSimulator message is a subset of that in a login reply:
The data sent in an EnableSimulator message is a subset of that in a login reply:


* "Handle" -- region origin in world coordinates, sent as a 64-bit region handle value, big-endian.  
; Handle : region origin in world coordinates, sent as a 64-bit region handle value, big-endian.  
* "IP": -- IP address of simulator  
; IP : IP address of simulator  
* "Port" UDP port for simulator, sent as a 32-bit integer.
; Port : UDP port for simulator, sent as a 32-bit integer.
* "RegionSizeX" -- optional, Open Simulator only, region size in meters, sent as a 4-byte binary string, big-endian.
; RegionSizeX : optional, Open Simulator only, region size in meters, sent as a 4-byte binary string, big-endian.
* "RegionSizeY" -- optional, Open Simulator only, region size in meters, sent as a 4-byte binary string, big-endian.
; RegionSizeY : optional, Open Simulator only, region size in meters, sent as a 4-byte binary string, big-endian.


There is also an EstablishAgentCommunication message:
There is also an EstablishAgentCommunication message:


* "sim-ip-and-port": -- IP address and UDP port, in string format: "87.101.7.128:15272"  
; sim-ip-and-port : IP address and UDP port, in string format: "87.101.7.128:15272"  
* "seed-capability" -- URL of the simulator's capability request server.
; seed-capability : URL of the simulator's capability request server.
* "agent-id" - UUID of agent involved
; agent-id : UUID of agent involved


These fields all have the same meanings as in a login reply.
These fields all have the same meanings as in a login reply.

Latest revision as of 22:51, 26 August 2023

Opensimulator: Documentation: Regions

Subjects related to regions.

Region sizes

Standard sized regions

The standard region size is a 256 meter square. This is the only size supported by Second Life.

Varregions

The varregion is based on the old megaregion concept but with completely rewritten code allowing for much more integration of the 256x256 m "blocks". The dimension limits (quadratic and multiples of 256 m) are the same as for a megaregion but for nearly all other practical purposes a varregion is treated by the simulator as a single unit.

Megaregions

The megaregion was introduced by [Aurora] and later adopted by other opensimulator forks.

A megaregion is essentially made from several standard regions merged into a single simulator with all region "blocks" sharing the same server resources and several other features and with no region borders between them. Since it's based on the standard 256x256 m region, the size of a megaregion has to be a product of 256 m and the region has to be quadratic with the same numebr of "blocks" along the x (west-to-east) and the y (south-to-north) axis.

The megaregion is an outdated concept, replaced by the varregion, but there may still be used by a few grids running on old versions of Opensimulator.

Initial connection to a region

The process by which a viewer connects to a region is rather complicated. It's necessary to accumulate information sent via multiple routes before the viewer can start up a new region.

For the initial region, the reply from the login server provides enough information to get the process started, but not enough to start up the region. Additional data needed include:

  • The major capabilities, which are obtained by making an HTTP request of the seed capability, which is a URL answered by the region server.
  • The region handshake reply, which is sent by the server to the viewer over the UDP connection, in response to a region handshake request.

Both of those requests must be answered before the region can be created in the viewer.

Login to the first region

The login process starts with an XMLRPC request to the login server. On a successful login, an XML set of key-value pairs is returned, which includes, at least:

seed_capability
the URL for the initial region used to query for more capability URLs.
secure_session_id
a unique UUID for the current session. Unclear what this is for.
circuit_code
a unique ID which identifies the UDP connection
sim_ip
the IP address of the initial region server. This is currently IPv4 only.
sim_port
UDP port, to be used with sim_ip, for receiving and sending UDP messages.
session_id
UUID of the current session.
agent_id
UUID of the avatar logging in. This is the avatar's permanent identity.
message
Message to display to the user at login. Usually a message of the day or some such.
first_name
First name of user/avatar.
last_name
Last name of user/avatar.
start_region [x, y]
world coordinates of the southwest (0,0) corner of the initial region.
look_at [x,y,z]
unit vector indicating the initial direction of view.

Note that this information does not contain the initial location of the avatar. That reaches the viewer via an object update to an object with the same UUID as the agent_id. An implication of this is that the viewer doesn't know where the avatar is at startup, yet it will have to send an agent update before it knows that. This causes a race condition in interest list updates.

Open Simulator logins for grids with varregions provide some additional info:

region_size_x
Region size, meters.
region_size_y
Region size, meters.

If these are absent, 256 is the default value.

Teleports

TBD

Adjacent regions

TBD

How viewers find out about adjacent regions

In both Second Life and Open Simulator, viewers are told about the regions adjacent to regions to which they are already connected. This information is sent over the event poller channel in LLSD format. At some time in the past it was sent as a UDP message (Enable Simulator, Low/151), but that message is now "blacklisted" in the Second Life UDP message_template.msg file.

The data sent in an EnableSimulator message is a subset of that in a login reply:

Handle
region origin in world coordinates, sent as a 64-bit region handle value, big-endian.
IP
IP address of simulator
Port
UDP port for simulator, sent as a 32-bit integer.
RegionSizeX
optional, Open Simulator only, region size in meters, sent as a 4-byte binary string, big-endian.
RegionSizeY
optional, Open Simulator only, region size in meters, sent as a 4-byte binary string, big-endian.

There is also an EstablishAgentCommunication message:

sim-ip-and-port
IP address and UDP port, in string format: "87.101.7.128:15272"
seed-capability
URL of the simulator's capability request server.
agent-id
UUID of agent involved

These fields all have the same meanings as in a login reply.

Once both of these messages have arrived, it is possible to begin talking to an adjacent region's simulator.

Region crossings

TBD