OpenSimulator Internals/Code Map/ROBUST/GridUserService

OpenSimulator Internals/Code Map/ROBUST/GridUserService

Overview

GridUserService tracks per-user grid state: online/offline status, login/logout timestamps, home location, and last known position. It is used by LoginService on login and logout, and by simulators to update position as the avatar moves.

Source files:

OpenSim/Services/UserAccountService/GridUserService.cs
OpenSim/Services/UserAccountService/GridUserServiceBase.cs

Note: despite the name, these files live in the UserAccountService directory, not a GridUserService directory.

---

Constructor and Config Loading

GridUserServiceBase(IConfigSource config)

Config is read in two layers; [GridUserService] overrides [DatabaseService]:

Section	Key	Default	Notes
[DatabaseService]	StorageProvider	(none)	DLL name -- fallback
[DatabaseService]	ConnectionString	(none)	DB connection string -- fallback
[GridUserService]	StorageProvider	(inherited)	Overrides [DatabaseService]
[GridUserService]	ConnectionString	(inherited)	Overrides [DatabaseService]
[GridUserService]	Realm	GridUser	Table name

Note: the comment in GridUserServiceBase.cs misspells the section name as [GridUsetService]. The actual section key read is "GridUserService".

Throws if StorageProvider is empty or if the plugin cannot be loaded.

The loaded plugin is stored as m_Database (IGridUserData).

Console commands are registered once only (m_Initialized static flag prevents re-registration on multiple instantiations):

• show grid user <ID> -- displays all fields for a user ID (prefix match via GetAll)
• show grid users online -- counts users marked Online whose last login is less than 5 days ago

---

Data Model

GridUserData stores one row per user. Fields stored in the Data dictionary:

Field	Type	Notes
Online	bool string	"True" or "False"
Login	int string	Unix timestamp of last login
Logout	int string	Unix timestamp of last logout
HomeRegionID	UUID string	Region UUID of home location
HomePosition	Vector3 string	Position within home region
HomeLookAt	Vector3 string	Look-at direction at home
LastRegionID	UUID string	Region UUID of last known position
LastPosition	Vector3 string	Last known position within region
LastLookAt	Vector3 string	Last known look-at direction

UserID is stored directly on GridUserData, not in the Data dictionary.

UserID may be longer than 36 characters (HyperGrid user IDs include a URI suffix). All cache and lookup operations truncate to the first 36 characters for the cache key.

---

Cache

private static ExpiringCacheOS<string, GridUserData> cache

Static cache shared across all instances. TTL is 300000ms (5 minutes). Cache key is the first 36 characters of userID.

GetGridUserData() checks the cache first. On cache miss, calls m_Database.GetAll(userID). All write operations (LoggedIn, LoggedOut, SetHome, SetLastPosition) update the cache after a successful Store().

If GetAll() returns multiple records for the same userID (should not happen in a healthy database), GetGridUserData() selects the record with the most recent Login or Logout timestamp. Parse failures during this selection are silently swallowed via empty catch.

Null results are cached for 300000ms to avoid repeated database hits for unknown users.

---

GetGridUserInfo

public virtual GridUserInfo GetGridUserInfo(string userID)
public virtual GridUserInfo[] GetGridUserInfo(string[] userIDs)

Single-user: calls GetGridUserData(), returns null if not found, otherwise converts via ToInfo().

Batch: iterates the array and calls the single-user method for each. No batch database query -- each ID hits the cache or database individually.

ToInfo() maps GridUserData fields to GridUserInfo:

• Missing or unparseable fields are left as default values (zero UUID, zero Vector3, UnixEpoch for timestamps)
• Login and Logout are converted from Unix int to DateTime via Util.ToDateTime()

---

LoggedIn

public GridUserInfo LoggedIn(string userID)

1. Fetches existing record or creates a new GridUserData if none exists
2. Sets Online = "True"
3. Sets Login = current Unix timestamp
4. Stores to database
5. Updates cache
6. Returns GridUserInfo via ToInfo()

---

LoggedOut

public bool LoggedOut(string userID, UUID sessionID, UUID regionID, Vector3 lastPosition, Vector3 lastLookAt)

sessionID parameter is accepted but not used.

1. Fetches existing record or creates a new GridUserData if none exists
2. Sets Online = "False"
3. Sets Logout = current Unix timestamp
4. Sets LastRegionID, LastPosition, LastLookAt from parameters
5. Stores to database -- returns false on Store() failure
6. Updates cache on success
7. Returns true on success, false on Store() failure

---

SetHome

public bool SetHome(string userID, UUID homeID, Vector3 homePosition, Vector3 homeLookAt)

1. Fetches existing record or creates a new GridUserData if none exists
2. Sets HomeRegionID, HomePosition, HomeLookAt from parameters
3. Stores to database -- returns false on Store() failure
4. Updates cache on success

---

SetLastPosition

public bool SetLastPosition(string userID, UUID sessionID, UUID regionID, Vector3 lastPosition, Vector3 lastLookAt)

sessionID parameter is accepted but not used.

1. Fetches existing record or creates a new GridUserData if none exists
2. Sets LastRegionID, LastPosition, LastLookAt from parameters
3. Stores to database -- returns false on Store() failure
4. Updates cache on success

The debug log line for this method is commented out in the source.

---

Console Commands

show grid user <ID>:

• Calls m_Database.GetAll(ID) -- prefix match
• Displays all fields for each matching record via ConsoleDisplayList
• Prints count of matching entries

show grid users online:

• Iterates all records via m_Database.GetAll("")
• Counts records where Online == "True" AND login timestamp is less than 5 days ago
• The 5-day cutoff exists because crashed or unclean-shutdown simulators may leave users marked online indefinitely
• The commented-out code shows a total online count was originally planned alongside the recent count

---

Notes

• The comment in GridUserServiceBase.cs misspells [GridUserService] as [GridUsetService] -- the code reads the correct key name regardless.
• sessionID is accepted by LoggedOut() and SetLastPosition() but never used.
• The batch GetGridUserInfo(string[]) does not batch database queries -- it calls the single-user path per ID.
• Multiple records per userID are handled defensively but should not occur in a healthy database.

---

See Also

• OpenSimulator Internals/Code Map/ROBUST
• OpenSimulator Internals/Code Map/Shared
• OpenSimulator Internals/Databases