Jwbshaw: first

2026-06-22T10:03:03Z

first

New page

= OpenSimulator Internals/GridService =

== Overview ==

GridService is the region map. It handles region registration on simulator startup, deregistration on shutdown, and answers queries for region location and coordinates. It also maintains HyperGrid links to remote grids via HypergridLinker.

GridService can be load-balanced -- it is stateless with respect to runtime state. All persistent data lives in the database.

See [[OpenSimulator Internals/ROBUST Services]] for placement in the overall architecture.

----

== Source Files ==

{| class="wikitable"
! File !! Location
|-
| GridService.cs || OpenSim/Services/GridService/
|-
| HypergridLinker.cs || OpenSim/Services/GridService/
|-
| MySqlRegionData.cs || OpenSim/Data/MySQL/
|-
| GridServiceConnector.cs || OpenSim/Server/Handlers/Grid/
|-
| GridServerPostHandler.cs || OpenSim/Server/Handlers/Grid/
|}

----

== Configuration ==

=== Robust.ini ===

[GridService]
LocalServiceModule = "OpenSim.Services.GridService.dll:GridService"
StorageProvider = "OpenSim.Data.MySQL.dll:MySqlRegionData"
ConnectionString = "Data Source=localhost;Database=osimdev_robust;User ID=opensim;Password=xxx;"

; Region name uniqueness
AllowDuplicateNames = false

; Delete region record on clean shutdown, or just mark offline
DeleteOnUnregister = true

; Optional: require token authentication for region registration
; AuthenticationService = "OpenSim.Services.AuthenticationService.dll:PasswordAuthenticationService"

; HyperGrid
HypergridLinker = true
AllowHypergridMapSearch = false
AssetService = "OpenSim.Services.AssetService.dll:AssetService"
MapTileDirectory = "maptiles"

; Per-region flag overrides
; DefaultRegionFlags = DefaultRegion
; Region_RegionName = +DefaultRegion,-FallbackRegion
; Region_<UUID> = +DefaultRegion

DeleteOnUnregister defaults true. If false, or if the region has the Persistent flag set, deregistration clears RegionOnline but keeps the record.

----

== Initialisation Sequence ==

# Loads storage provider from StorageProvider config -- runs MySQL migration "GridStore" on startup
# Reads DeleteOnUnregister, AllowDuplicateNames, AllowHypergridMapSearch from [GridService]
# Optionally loads AuthenticationService plugin if configured
# Registers console commands (suppressed if SuppressConsoleCommands = true)
# Calls SetExtraServiceURLs() -- reads SearchURL, MapTileURL, DestinationGuide, GatekeeperURI, GridName, GridNick, GridStatus, GridStatusRSS, ExportSupported, GatekeeperURIAlias into m_ExtraFeatures dictionary
# Creates HypergridLinker if HypergridLinker = true in config -- throws if HyperGrid config is missing

Only the first GridService instance registers console commands and initialises HypergridLinker. Subsequent instances (e.g. local connector in simulator) skip this via m_RootInstance guard.

----

== HTTP Endpoint ==

Single endpoint: POST /grid

All operations use METHOD dispatch in the POST body. GridServiceConnector registers one handler -- GridServerPostHandler -- with auth.

{| class="wikitable"
! METHOD value !! Parameters !! Returns
|-
| register || SCOPEID, VERSIONMIN, VERSIONMAX, region key-value pairs || Success/Failure XML
|-
| deregister || REGIONID || Success/Failure XML
|-
| get_neighbours || SCOPEID, REGIONID || XML list of GridRegion key-value pairs
|-
| get_region_by_uuid || SCOPEID, REGIONID || XML GridRegion or null
|-
| get_region_by_position || SCOPEID, X, Y || XML GridRegion or null
|-
| get_region_by_name || SCOPEID, NAME || XML GridRegion or null
|-
| get_localregion_by_name || SCOPEID, NAME || XML GridRegion or null (no HG lookup)
|-
| get_regions_by_name || SCOPEID, NAME, MAX || XML list of GridRegion key-value pairs
|-
| get_region_range || SCOPEID, XMIN, XMAX, YMIN, YMAX || XML list of GridRegion key-value pairs
|-
| get_default_regions || SCOPEID || XML list of GridRegion key-value pairs
|-
| get_default_hypergrid_regions || SCOPEID || XML list of GridRegion key-value pairs
|-
| get_fallback_regions || SCOPEID, X, Y || XML list sorted by distance
|-
| get_online_regions || SCOPEID, X, Y, MC || XML list sorted by distance, capped at MC
|-
| get_hyperlinks || SCOPEID || XML list of HyperGrid link entries
|-
| get_region_flags || SCOPEID, REGIONID || integer flags value
|-
| get_grid_extra_features || (none) || XML key-value pairs from m_ExtraFeatures
|}

Protocol version negotiation on register: client sends VERSIONMIN/VERSIONMAX, server checks overlap with ProtocolVersions.ServerProtocolVersionMin/Max. No overlap = failure.

----

== RegisterRegion ==

Validation sequence:

# RegionID must not be zero UUID
# RegionLocY must be above Constants.MaximumRegionSize (coordinates below this are reserved for HG links)
# Overlap check: queries database for any region occupying the bounding box -- fails if more than one overlap, or if one overlap with a different RegionID
# Reservation check: if existing record has Reservation flag set, rejects if PrincipalID is zero UUID; otherwise treats as authentication request
# Authentication check: if Authenticate flag set, verifies token via AuthenticationService (30 second window)
# Duplicate name check: if AllowDuplicateNames = false, rejects if another region with same name and different RegionID exists
# Move check: if region previously registered at different coordinates, checks NoMove and LockedOut flags before deleting old record
# Applies DefaultRegionFlags from config, then per-region overrides by name or UUID
# Sets RegionOnline flag, stores record with last_seen timestamp

----

== DeregisterRegion ==

If DeleteOnUnregister = false OR region has Persistent flag:
- Clears RegionOnline flag, updates last_seen, stores record

Otherwise:
- Deletes record from database

----

== GetNeighbours ==

Queries database for all regions within a bounding box of (posX-1, posY-1) to (posX+sizeX+1, posY+sizeY+1). Excludes the requesting region itself. Excludes any region with the Hyperlink flag set -- HG links are never returned as neighbours.

----

== Region Lookup Methods ==

{| class="wikitable"
! Method !! Behaviour
|-
| GetRegionByUUID || Direct UUID lookup
|-
| GetRegionByHandle || Extracts X/Y from 64-bit handle, delegates to GetRegionByPosition
|-
| GetRegionByPosition || Snaps coordinates to region grid, queries database
|-
| GetRegionByName || Parses RegionURI; local grid: exact name match or default region; foreign grid: HG link attempt if AllowHypergridMapSearch = true
|-
| GetLocalRegionByName || Same as GetRegionByName but returns null for foreign grid URIs -- no HG lookup
|-
| GetRegionsByName || Partial name match; local grid returns sorted list; foreign grid attempts HG link if AllowHypergridMapSearch = true
|-
| GetRegionRange || Bounding box query, snapped to region grid
|-
| GetDefaultRegions || Regions with DefaultRegion flag set and RegionOnline
|-
| GetDefaultHypergridRegions || Regions with DefaultHGRegion flag, then appends normal defaults
|-
| GetFallbackRegions || Regions with FallbackRegion flag, sorted by distance to given coordinates, excludes Hyperlink and offline regions
|-
| GetOnlineRegions || All online regions sorted by distance, capped at maxCount, excludes Hyperlink regions
|-
| GetHyperlinks || Regions with Hyperlink flag and RegionOnline
|}

----

== Region Flags ==

Flags are stored as an integer bitmask in the regions table. Key flags used by GridService:

{| class="wikitable"
! Flag !! Notes
|-
| RegionOnline || Set on register, cleared on deregister (if not deleted)
|-
| Persistent || Prevents deletion on deregister -- record kept with RegionOnline cleared
|-
| DefaultRegion || Returned by GetDefaultRegions -- login destination if no other target
|-
| DefaultHGRegion || Returned by GetDefaultHypergridRegions -- HyperGrid entry point
|-
| FallbackRegion || Returned by GetFallbackRegions -- used when teleport target is unavailable
|-
| Hyperlink || Marks a HyperGrid link entry -- excluded from neighbours, returned by GetHyperlinks
|-
| NoDirectLogin || Set on HyperGrid link entries -- prevents direct login to linked region
|-
| Reservation || Holds a coordinate for a specific PrincipalID -- blocks other registrations
|-
| Authenticate || Requires token authentication on registration
|-
| NoMove || Prevents region from re-registering at different coordinates
|-
| LockedOut || Prevents registration entirely
|}

Per-region flags can be set in Robust.ini:

Region_RegionName = +DefaultRegion,-FallbackRegion
Region_<UUID> = +DefaultRegion

Flags are applied after DefaultRegionFlags on every registration.

----

== HypergridLinker ==

HypergridLinker handles linking to remote grids. It is created by GridService if HypergridLinker = true in config.

Key behaviours:

* LinkRegion() contacts the remote grid's Gatekeeper via GatekeeperServiceConnector to obtain the remote region's UUID, handle, size, and map image
* Linked regions are stored in the regions table with Hyperlink + NoDirectLogin + RegionOnline flags
* IsLocalGrid() checks whether a URI belongs to this grid -- prevents hyperlinking to local regions
* TryUnlinkRegion() removes the hyperlink record from the database
* Map tiles for linked regions are stored in the MapTileDirectory (default: maptiles/)
* The 4096-region distance check is disabled in current code -- distance enforcement moved to EntityTransferModule

HypergridLinker is disabled if HyperGrid config section is missing -- throws on construction.

----

== Database Layer ==

MySqlRegionData uses realm "regions" by default. Key behaviours:

* Get(posX, posY) queries within a bounding box of posX-MaximumRegionSize to posX -- handles varregions by finding which region contains the point
* Get(startX, startY, endX, endY) expands the query by MaximumRegionSize on the lower bounds to catch varregions that start outside the box but overlap it
* Store() does UPDATE first, INSERT on failure (upsert pattern)
* GetDefaultRegions, GetFallbackRegions, GetHyperlinks, GetOnlineRegions all use bitwise flag queries: (flags & value) <> 0
* Region name is truncated to 128 characters on store

----

== Extra Features ==

GetExtraFeatures() returns m_ExtraFeatures, a static dictionary populated at startup from config. Used by SimulatorFeaturesModule to push grid URLs to viewers via OpenSimExtras. Keys include:

* search-server-url
* map-server-url
* destination-guide-url
* GridURL (GatekeeperURI)
* GridName
* GridNick
* GridStatus
* GridStatusRSS
* ExportSupported
* GridURLAlias

----

== Console Commands ==

{| class="wikitable"
! Command !! Usage !! Notes
|-
| show regions || show regions || Lists all regions with name, UUID, position, size, flags
|-
| show region name || show region name <name> || Full detail for named region
|-
| show region at || show region at <x> <y> || Full detail for region at grid coordinates
|-
| show grid size || show grid size || Approximate grid area in km², excludes HG links
|-
| deregister region id || deregister region id <uuid>+ || Manual deregister, accepts multiple UUIDs
|-
| set region flags || set region flags <name> <flags> || Modify flags, e.g. +DefaultRegion,-FallbackRegion
|-
| link-region || link-region <x> <y> <ServerURI> [name] || Create HG link (HypergridLinker)
|-
| unlink-region || unlink-region <name> || Remove HG link (HypergridLinker)
|-
| link-mapping || link-mapping [<x> <y>] || Set auto-mapping origin for HG links
|-
| show hyperlinks || show hyperlinks || List all HG link entries
|}

----

== See Also ==

* [[OpenSimulator Internals/ROBUST Services]]
* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Data Dictionaries]]

OpenSimulator Internals/GridService - Revision history

Jwbshaw: first