Editing OpenSimulator Internals/Databases (section)

== Grid Database (osimdev_robust) ==

=== Table List ===

{| class="wikitable"
! Table !! Purpose
|-
| regions || Region registration -- one row per online or recently-seen region
|-
| UserAccounts || User accounts including the internal GRID SERVICES account
|-
| Avatars || Avatar appearance: worn items, attachment points, visual params (key-value store)
|-
| GridUser || Home region, last region, last position, login/logout timestamps
|-
| Presence || Active sessions -- who is online right now and in which region
|-
| auth || Password hashes and authentication tokens
|-
| tokens || Session tokens for region-to-region and HyperGrid authentication
|-
| inventoryfolders || Inventory folder hierarchy
|-
| inventoryitems || Inventory item records
|-
| assets || Asset metadata and binary data
|-
| Friends || Friend relationships and permissions, including HyperGrid friends
|-
| AgentPrefs || Per-user preferences (hover height, language, default permissions)
|-
| hg_traveling_data || HyperGrid travel state for avatars currently visiting foreign grids
|-
| MuteList || Per-user mute lists
|-
| im_offline || Stored offline instant messages
|-
| migrations || Schema version tracking for each service
|}

----

=== regions ===

One row per registered region. Written on simulator startup (RegisterRegion), updated on shutdown (DeregisterRegion).

{| class="wikitable"
! Field !! Type !! Notes
|-
| uuid || varchar(36) || Primary key -- region UUID
|-
| regionHandle || bigint unsigned || Encoded X,Y handle: (locX << 32) | locY
|-
| regionName || varchar(128) || Display name, max 128 chars
|-
| serverURI || varchar(255) || HTTP endpoint of the simulator e.g. http://osimdev.org:9000/
|-
| locX || int unsigned || Region origin X in metres (region coord * 256)
|-
| locY || int unsigned || Region origin Y in metres (region coord * 256)
|-
| sizeX || int || Region width in metres (512 for a 2x2 varregion)
|-
| sizeY || int || Region height in metres
|-
| flags || int || Bitmask of RegionFlags (4 = RegionOnline)
|-
| last_seen || int || Unix timestamp of last registration or deregistration
|-
| owner_uuid || varchar(36) || Estate owner UUID
|-
| ScopeID || char(36) || Grid scope -- zero UUID for default scope
|-
| access || int unsigned || Parcel access level (1 = PG)
|-
| regionMapTexture || varchar(36) || UUID of map tile image asset
|-
| PrincipalID || char(36) || Used for reservation authentication
|-
| Token || varchar(255) || Authentication token for reserved regions
|}

Legacy fields present but unused in current code: regionRecvKey, regionSendKey, regionSecret, regionDataURI, regionAssetURI, regionAssetRecvKey, regionAssetSendKey, regionUserURI, regionUserRecvKey, regionUserSendKey, serverRemotingPort, eastOverrideHandle, westOverrideHandle, southOverrideHandle, northOverrideHandle.

Sample row (T1 on osimdev):

{| class="wikitable"
! Field !! Value
|-
| uuid || 6f0a42d1-3053-422d-9c26-13205c9c7723
|-
| regionName || T1
|-
| locX / locY || 256000 (= region coordinate 1000)
|-
| sizeX / sizeY || 512
|-
| flags || 4 (RegionOnline)
|-
| serverURI || http://osimdev.org:9000/
|}

----

=== UserAccounts ===

{| class="wikitable"
! Field !! Type !! Notes
|-
| PrincipalID || char(36) || UUID primary key
|-
| FirstName || varchar(64) ||
|-
| LastName || varchar(64) ||
|-
| Email || varchar(64) || Login email
|-
| UserLevel || int || 0 = normal user, 240 = god-level
|-
| UserFlags || int || Reserved
|-
| Created || int || Unix timestamp
|}

Two rows on a fresh grid: the admin avatar (UserLevel 0) and the internal GRID SERVICES account (UserLevel 240). The GRID SERVICES account has no auth record and never logs in -- it is used internally by OpenSim services.

----

=== Avatars ===

Key-value store. One row per attribute per avatar. PrincipalID + Name form the composite key.

{| class="wikitable"
! Name pattern !! Value format !! Notes
|-
| _ap_N || UUID or comma-separated UUIDs || Attachment point N -- asset UUID of worn item. Comma-separated for multi-attach points.
|-
| Wearable N:0 || inventoryUUID:assetUUID || Worn wearable layer N. 0=shape, 1=skin, 2=shirt, 3=pants, 13=physics, etc.
|-
| AvatarHeight || float || Avatar height in metres
|-
| AvatarType || int || 0 = classic system avatar, 1 = mesh avatar
|-
| VisualParams || comma-separated bytes || 253-element appearance slider array -- body shape, skin tone, hair color etc.
|-
| Serial || int || Appearance version serial number
|}

Attachment point numbers follow the SL/OpenSim standard: 2=chest, 5=left hand, 12=hair, 40=left foot, etc. Multi-attach points store comma-separated UUIDs.

Sample data (Jagga Meredith, 13 rows): AvatarType=1 (mesh), AvatarHeight=1.6885326, 4 attachment points, 5 wearable layers (shape, skin, shirt, pants, physics).

----

=== GridUser ===

One row per user. Written on first login, updated on every login, logout, and teleport.

{| class="wikitable"
! Field !! Type !! Notes
|-
| UserID || varchar(255) || UUID or HyperGrid URI -- primary key
|-
| HomeRegionID || char(36) || UUID of home region
|-
| HomePosition || varchar(64) || Vector3 in region-local metres
|-
| HomeLookAt || varchar(64) || Vector3 look direction
|-
| LastRegionID || char(36) || UUID of last visited region
|-
| LastPosition || varchar(64) || Vector3 in region-local metres
|-
| LastLookAt || varchar(64) || Vector3 look direction
|-
| Online || tinyint || 1 only while session is active
|-
| Login || int || Unix timestamp of last login
|-
| Logout || int || Unix timestamp of last logout
|}

UserID is varchar(255) not char(36) -- accommodates HyperGrid user URIs from foreign grids.

----

=== Presence ===

One row per active session. Empty when no users are logged in. Rows are created on login and deleted on logout.

{| class="wikitable"
! Field !! Type !! Notes
|-
| SessionID || char(36) || Primary key -- unique per login session
|-
| UserID || varchar(255) || UUID or HyperGrid URI
|-
| RegionID || char(36) || Current region UUID -- zero UUID if not yet in a region
|-
| SecureSessionID || char(36) || Secondary session token for viewer authentication
|-
| LastSeen || timestamp || Auto-updated on change -- used to detect stale sessions
|}

----

=== auth ===

One row per user account. Stores password credentials.

{| class="wikitable"
! Field !! Type !! Notes
|-
| UUID || char(36) || Primary key -- matches UserAccounts.PrincipalID
|-
| passwordHash || char(32) || MD5 hash of password
|-
| passwordSalt || char(32) || MD5 salt
|-
| webLoginKey || varchar(255) || UUID for web-based login -- zero UUID if not configured
|-
| accountType || varchar(32) || Default: UserAccount
|}

GRID SERVICES account has no auth row -- it cannot log in.

----

=== tokens ===

Short-lived session tokens used for region-to-region and HyperGrid authentication.

{| class="wikitable"
! Field !! Type !! Notes
|-
| UUID || char(36) || User UUID -- composite primary key with token
|-
| token || varchar(255) || UUID-format token
|-
| validity || datetime || Expiry datetime -- expired tokens remain until cleaned up
|}

Multiple tokens per user are normal -- one per teleport attempt. Expired tokens are not automatically deleted; they accumulate until a cleanup job runs.

----

=== assets ===

{| class="wikitable"
! Field !! Type !! Notes
|-
| id || char(36) || Primary key -- asset UUID
|-
| name || varchar(64) || Display name
|-
| description || varchar(64) || Description -- HG landmarks store grid URI here
|-
| assetType || tinyint || Asset type number (see below)
|-
| data || longblob || Raw binary asset data
|-
| local || tinyint(1) || 1 = local-only, not transferred to other grids
|-
| temporary || tinyint(1) || 1 = temporary, may be discarded
|-
| asset_flags || int || Bitmask of asset flags
|-
| CreatorID || varchar(128) || Creator UUID or HyperGrid URI
|-
| create_time || int || Unix timestamp of creation
|-
| access_time || int || Unix timestamp of last access
|}

Asset types observed on osimdev:

{| class="wikitable"
! assetType !! Name
|-
| 0 || Texture
|-
| 3 || Landmark -- HG landmarks store grid URI in description field
|-
| 6 || Object -- serialized prim/linkset XML
|-
| 7 || Notecard
|-
| 10 || Script
|-
| 20 || Animation
|}

Library/system assets use non-random UUID patterns and CreatorID 11111111-1111-0000-0000-000100bba000. On osimdev after initial setup and one user session: 2602 total assets, 85 user-created (1 texture, 4 landmarks, 79 objects, 1 notecard).

----

=== inventoryfolders ===

{| class="wikitable"
! Field !! Type !! Notes
|-
| folderID || char(36) || Primary key
|-
| folderName || varchar(64) || Display name
|-
| type || smallint || Folder type (see below)
|-
| version || int || Incremented on folder contents change
|-
| agentID || char(36) || Owner UUID
|-
| parentFolderID || char(36) || Parent folder UUID -- zero UUID for root
|}

System folder types:

{| class="wikitable"
! type !! Name
|-
| -1 || User-created folder
|-
| 0 || Textures
|-
| 1 || Sounds
|-
| 2 || Calling Cards
|-
| 3 || Landmarks
|-
| 5 || Clothing
|-
| 6 || Objects
|-
| 7 || Notecards
|-
| 8 || My Inventory (root)
|-
| 10 || Scripts
|-
| 13 || Body Parts
|-
| 14 || Trash
|-
| 15 || Photo Album
|-
| 16 || Lost And Found
|-
| 20 || Animations
|-
| 21 || Gestures
|-
| 23 || Favorites
|-
| 46 || Current Outfit
|-
| 47 || Outfit
|-
| 48 || My Outfits
|-
| 50 || Received Items
|-
| 56 || Settings
|-
| 57 || Materials
|-
| 100 || My Suitcase (HyperGrid)
|}

My Suitcase (type 100) is the HyperGrid suitcase -- items here travel with the avatar to foreign grids. Firestorm creates system folders: #Firestorm (containing #AO, #LSL Bridge, #Wearable Favorites).

----

=== inventoryitems ===

{| class="wikitable"
! Field !! Type !! Notes
|-
| inventoryID || char(36) || Primary key
|-
| assetID || varchar(36) || Foreign key to assets.id
|-
| assetType || int || Asset type
|-
| invType || int || Inventory type (can differ from assetType)
|-
| inventoryName || varchar(64) || Display name
|-
| inventoryDescription || varchar(128) ||
|-
| avatarID || char(36) || Owner UUID
|-
| parentFolderID || char(36) || Containing folder UUID
|-
| creatorID || varchar(255) || Creator UUID or HyperGrid URI
|-
| inventoryBasePermissions || int unsigned || Base permission bitmask
|-
| inventoryCurrentPermissions || int unsigned || Current permission bitmask
|-
| inventoryNextPermissions || int unsigned || Next owner permission bitmask
|-
| inventoryEveryOnePermissions || int unsigned || Everyone permission bitmask
|-
| inventoryGroupPermissions || int unsigned || Group permission bitmask
|-
| groupID || varchar(36) || Associated group UUID
|-
| groupOwned || tinyint || 1 if group-owned
|-
| salePrice || int || Sale price in grid currency
|-
| saleType || tinyint || 0=not for sale, 1=original, 2=copy, 3=contents
|-
| creationDate || int || Unix timestamp
|-
| flags || int unsigned || Item flags
|}

creatorID is varchar(255) to accommodate HyperGrid creator URIs. Item count on osimdev after initial session and AviWorlds visit: 380 items (171 objects, 75 animations, 34 links, 28 textures, 24 body parts, 21 clothing, 15 landmarks, 6 notecards, 3 scripts, 2 sounds, 1 mesh).

----

=== Friends ===

One row per directional friendship. Friendships are stored as two rows (A->B and B->A).

{| class="wikitable"
! Field !! Type !! Notes
|-
| PrincipalID || varchar(255) || Owner UUID or HyperGrid URI -- composite primary key
|-
| Friend || varchar(255) || Friend UUID or HyperGrid compound string
|-
| Flags || varchar(16) || Permission flags (1 = accepted)
|-
| Offered || varchar(32) || Pending offer token
|}

For HyperGrid friends, Friend field format is: UUID;GridURI;DisplayName;token

Example: 5a365446-ad4f-4f7f-a843-563494b0e78b;http://login.aviworlds.com:8002/;Jagga Meredith;23cba5bc

----

=== AgentPrefs ===

One row per user. Written when user explicitly sets preferences in-world. Defaults apply if no row exists.

{| class="wikitable"
! Field !! Type !! Default !! Notes
|-
| PrincipalID || char(36) || -- || Primary key
|-
| AccessPrefs || char(2) || M || Content rating: G, M, or A
|-
| HoverHeight || double || 0.0 || Avatar hover offset in metres
|-
| Language || char(5) || en-us || Viewer language preference
|-
| LanguageIsPublic || tinyint || 1 || Whether language preference is visible to others
|-
| PermEveryone || int || 0 || Default everyone permissions for new objects
|-
| PermGroup || int || 0 || Default group permissions for new objects
|-
| PermNextOwner || int || 532480 || Default next owner permissions for new objects
|}

----

=== hg_traveling_data ===

Tracks avatars currently traveling between grids via HyperGrid. One row per active HG session. Rows are deleted when the avatar returns home or logs out. Empty when no avatars are traveling.

{| class="wikitable"
! Field !! Type !! Notes
|-
| SessionID || varchar(36) || Primary key
|-
| UserID || varchar(36) || Avatar UUID
|-
| GridExternalName || varchar(255) || URI of the grid being visited
|-
| ServiceToken || varchar(255) || Auth token for the foreign grid session
|-
| ClientIPAddress || varchar(16) || Avatar's client IP on the foreign grid
|-
| MyIPAddress || varchar(16) || This grid's external IP as seen by the foreign grid
|-
| TMStamp || timestamp || Auto-updated -- used to detect stale travel records
|}

----