Jump to content

OpenSimulator Internals/GridService

From Open Simulator Technical Help

OpenSimulator Internals/GridService

[edit]

Overview

[edit]

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

[edit]
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

[edit]

Robust.ini

[edit]
[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

[edit]
  1. Loads storage provider from StorageProvider config -- runs MySQL migration "GridStore" on startup
  2. Reads DeleteOnUnregister, AllowDuplicateNames, AllowHypergridMapSearch from [GridService]
  3. Optionally loads AuthenticationService plugin if configured
  4. Registers console commands (suppressed if SuppressConsoleCommands = true)
  5. Calls SetExtraServiceURLs() -- reads SearchURL, MapTileURL, DestinationGuide, GatekeeperURI, GridName, GridNick, GridStatus, GridStatusRSS, ExportSupported, GatekeeperURIAlias into m_ExtraFeatures dictionary
  6. 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

[edit]

Single endpoint: POST /grid

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

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

[edit]

Validation sequence:

  1. RegionID must not be zero UUID
  2. RegionLocY must be above Constants.MaximumRegionSize (coordinates below this are reserved for HG links)
  3. 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
  4. Reservation check: if existing record has Reservation flag set, rejects if PrincipalID is zero UUID; otherwise treats as authentication request
  5. Authentication check: if Authenticate flag set, verifies token via AuthenticationService (30 second window)
  6. Duplicate name check: if AllowDuplicateNames = false, rejects if another region with same name and different RegionID exists
  7. Move check: if region previously registered at different coordinates, checks NoMove and LockedOut flags before deleting old record
  8. Applies DefaultRegionFlags from config, then per-region overrides by name or UUID
  9. Sets RegionOnline flag, stores record with last_seen timestamp

DeregisterRegion

[edit]

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

Otherwise: - Deletes record from database

GetNeighbours

[edit]

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

[edit]
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

[edit]

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

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

[edit]

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

[edit]

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

[edit]

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

[edit]
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

[edit]
Retrieved from "http://osimdev.org/wiki/index.php?title=OpenSimulator_Internals/GridService&oldid=30"