Hypergrid Implementation

From OpenSimulator

Jump to: navigation, search



See Hypergrid Glossary for a very incomplete glossary of Hypergrid terms.

Class Summary


Class Name Interfaces Description
Friends.HGFriendsModule IFriendsModule, IFriendsSimConnector, ISharedRegionModule Extends and replaces FriendsModule. Accessed via Scene.RequestModuleInterface<IFriendsModule>() and Scene.RequestModuleInterface<IFriendsSimConnector>(). Performs HG specific friend functions such as forwarding friendship requests and caching.
Friends.HGStatusNotifier None Helps manage HG friend status notifications.
InstantMessage.HGMessageTransferModule IInstantMessageSimConnector, IMessageTransferModule, ISharedRegionModule Handles sending of instant messages to foreign agents. Replaces MessageTransferModule.
Lure.HGLureModule ISharedRegionModule Handles sending of teleport requests to foreign agents. Replaces LureModule.


Class Name Interfaces Description
EntityTransfer.HGEntityTransferModule IEntityTransferModule, IUserAgentVerificationModule, INonSharedRegionModule Extends and replaces EntityTransferModule. Fetched by Scene.RequestModuleInterface<IEntityTransferModule>() and Scene.RequestModuleInterface<IUserAgentVerificationModule>(). Performs Hypergrid specific operations such as transferring assets from foreign to local asset service for avatar attachments.
InventoryAccess.HGInventoryAccessModule IInventoryAcessmodule, INonSharedRegionModule Child class of InventoryAccessModule that replaces this in the Hypergrid configuration. Registered with scene for other modules to obtain when they call scene.RequestModuleInterface<IInventoryAccessModule>().
InventoryAccess.HGAssetMapper None Performs asset operations related to inventory operations, such as fetching and inserting all the assets necessary to render an object from a foreign asset service and inserting them into the local asset service.
UserManagement.HGUserManagementModule IUserManagement, ISharedRegionModule Extends and replaces UserManagementModule. Registered with scene as IUserManagement. Does HG specific operations to manage known user identifiers.


Class Name Interfaces Description
Asset.HGAssetBroker IAssetService, ISharedRegionModule Registered as the interface returned by Scene.RequestModuleInterface<IAssetService>(). Decides whether to dispatch asset requests to cache, local storage or foreign asset services depending on asset ID. Foreign asset service requests are handled by HGAssetServiceConnector. Also enforces security checks such as whether certain assets can be imported or exported to foreign grids. Assets fetch from remote asset services will be copied to the local asset service.
Inventory.HGInventoryBroker IInvenotryService, ISharedRegionModule Registered as the interface returned by Scene.RequestModuleInterface<IInventoryService>(). Decides whether an inventory request needs to be handled locally (n the case of a local user) or forwarded to a foreign grid's inventory service.


These classes are glue code that receive external messages to invoke Hypergrid services.

Class Name Interfaces/Base classes Description
GatekeeperAgentHandler AgentPostHandler Redirects incoming agent creation calls to the GatekeeperService.
GatekeeperServiceConnector ServiceConnector Receives incoming calls for the GatekeeperService.
HeloServerConnector ServiceConnector TODO
HGFriendsServerConnector ServiceConnector Instantiates HGFriendsServerPostHandler.
HGFriendsServerPostHandler BaseStreamHandler Receives incoming HG Friends calls and triggers the appropriate HGFriendsService method.
HomeAgentHandler AgentPostHandler TODO
HypergridHandlers - Providers handlers to GatekeeperServiceConnector.
InstantMessageServerConnector ServiceConnector Receives incoming IM messages over the Hypergrid and forwards on to the IM service
UserAgentServerConnector ServiceConnector Forwards incoming user agent requests to the UserAgent service.


Class Name Interfaces Description
Asset.HGAssetServiceConnector IAssetService Internally instantiated by HGAssetBroker to handle requests that need to be forwarded to foreign asset services.
Hypergrid.GatekeeperServiceConnector ISimulationService Connector to a foreign Gatekeeper service.
Hypergrid.HeloServicesConnector None Connector to a foreign Helo service.
Hypergrid.HGFriendsServicesConnector None Connector to a foreign Friends service.
Hypergrid.UserAgentServiceConnector ISimulationService, IUserAgentService Connector to a foreign User Agent service.


Class Name Interfaces Description
GatekeeperService IGatekeeperService Perform gatekeeper operations for the grid. See Hypergrid Protocol for more details.
HGAssetService IAssetService Provides the asset service accessed by foreign grids.
HGFriendsService IHGFriendsService Provides the friends service accessed by foreign grids.
HGInstantMessageService IInstantMessage Provides the instant messages service accessed by foreign grids.
HGInventoryService IInventoryService, XInventoryService Provides the inventory service accessed by foreign grids. Probably for older versions of Hypergrid and superseded by HGSuitcaseInventoryService.
HGSuitcaseInventoryService IInventoryService, XInventoryService Provides the inventory service accessed by foreign grids. Uses the 'suitcase' concept (with matching user inventory folder) to control access.
UserAccountCache IUserAccountService Appears currently unused.
UserAgentService IUserAgentService Provides the user agent service accessed by foreign grids. See Hypergrid Protocol for more details.

Hyperlinks and Agent Transfers

When you establish a link between your opensim and another, a message is sent out to that other opensim requesting information about it; the required information includes the network information of that opensim host, and the coordinates of its first region on its local grid in the form of a region handle. For example, suppose you are linking node X.com:9000, placing it in your local map at 900, 900. That opensim runs one or more regions that likely are not in 900, 900 on their own map; suppose the first region of that opensim is at 1100, 1100. From your point of view, it doesn't matter what those other coordinates are, and you don't need to know -- that's the key to being able to decentralize the "world" as given by a 2D map; you want to place it in your map at 900, 900. The "true" position of that simulator only matters for the LL viewer, when there are teleports between your world and that other opensim. This mapping between coordinate systems is the essence of hyperlinks for opensim; it's one simple but critical thing that the hypergrid implementation does. The mapping happens on the TeleportFinish event; instead of sending the local coordinates to the viewer, the hypergrid teleport wrapper sends the remote coordinates.

When an agent teleports through that hyperlink the following happens. First, before InformRegionOfChildAgent, the local opensim notifies the remote opensim of this foreign user via the "expect_hg_user" method. That message sends along the addresses of all the servers that this user uses, i.e. user, inventory and asset servers. The remote opensim places an entry for that user in its local user profile cache but not in its user database; the foreign user information is non-persistent. After that, the teleport process is exactly the same as the normal teleport process; the only difference is that the region handles are switched between the remote region's hyperlink position on the local grid and its actual position on its grid.

In summary, the two new concepts introduced by the hypergrid are the concept of an hyperlink and the concept of a "local user" vs. "foreign user".

Inventory Access

Inventory access from a foreign grid is done by wrapping the existing scene-inventory interactions with additional code that gets or posts inventory assets from/to the user's asset server. When inventory is accessed, the hypergrid wrapper checks if the user is foreign and, if she is, the wrapper requests the necessary assets from the user's asset server. As with any fetched asset, these may be cached by the foreign simulator. From then on, the wrapper passes the control to the existing inventory access functions.

When something is added to inventory, the hypergrid wrapper is notified via an event, and posts the assets to the user's asset server. A cache of the exchanged item identifiers is maintained so that they aren't continually refetched.

The result is that hypergrided opensim instances end up interacting with several asset servers, instead of just one. That interaction is implemented in a by instantiating a GridAssetClient object for each foreign grid, instead of just the one used in non-Hypergrid OpenSimulator installations.

Asset Access

In a normal non-Hypergrid OpenSimulator installation, either

  • the LocalAssetServiceConnector (for standalone) by specification in the [Modules] section of bin/config-include/Standalone.ini
  • or the RemoteAssetServiceConnector (for grid) by specification in the [Modules] section of bin/config-include/Grid.ini

get registered to the scene (via Scene.RegisterModuleInterface()). Both these interfaces implement IAssetService. Other modules then retrieve this via the Scene.RequestModuleInterface<IAssetService>() call.

Under a Hypergrid configuration, HGAssetBroker is registered to the scene instead. This IAssetService implementation contains logic to work out if a requested asset can be served from cache, is a locally hosted asset or needs to be fetched from a remote grid, etc. Similar logic is present for other IAssetService methods (e.g. store).

Requests that need to be forwarded to foreign asset services are then passed on to an internal instance of HGAssetServiceConnector.

HGAssetBroker also contains code to work out if any security configuration should prevent certain assets from being imported or exported.


Please see Hypergrid Friends.

Personal tools
About This Wiki