Jwbshaw: first

2026-07-07T12:00:45Z

first

New page

= OpenSimulator Internals/Code Map/ROBUST/AvatarService =

== Overview ==

AvatarService stores and retrieves avatar appearance data. It is a thin layer over a key-value database table -- all appearance state is stored as named string pairs keyed by PrincipalID.

Source files:

OpenSim/Services/AvatarService/AvatarService.cs
OpenSim/Services/AvatarService/AvatarServiceBase.cs

----

=== Constructor and Config Loading ===

AvatarServiceBase(IConfigSource config)

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

{| class="wikitable"
! Section !! Key !! Default !! Notes
|-
| [DatabaseService] || StorageProvider || (none) || DLL name -- fallback
|-
| [DatabaseService] || ConnectionString || (none) || DB connection string -- fallback
|-
| [AvatarService] || StorageProvider || (inherited) || Overrides [DatabaseService]
|-
| [AvatarService] || ConnectionString || (inherited) || Overrides [DatabaseService]
|-
| [AvatarService] || Realm || Avatars || Table name
|}

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

The loaded plugin is stored as m_Database (IAvatarData).

----

=== Data Model ===

Avatar data is stored as a flat key-value table. Each row has:

* PrincipalID -- avatar UUID
* Name -- attribute name (e.g. "AvatarType", "AvatarHeight", attachment slot names)
* Value -- string value

AvatarType is stored as a separate named row, not in the Data dictionary. Value 1 = SL-style avatar.

Attachment slots are stored with names prefixed by underscore ("_").

AvatarData.ToAvatarAppearance() and AvatarData(AvatarAppearance) handle conversion between the flat key-value representation and the structured AvatarAppearance object. Those conversions are in OpenSim/Framework/, not in this service.

----

=== GetAvatar ===

public AvatarData GetAvatar(UUID principalID)

# Queries m_Database.Get("PrincipalID", principalID.ToString()) -- returns all rows for this avatar
# If no rows found: returns AvatarData with AvatarType = 1 (SL avatar), empty Data dictionary
# Iterates rows:
#* Row with Name == "AvatarType" sets ret.AvatarType
#* All other rows go into ret.Data[Name] = Value
# Returns populated AvatarData

GetAppearance() calls GetAvatar() then calls avatar.ToAvatarAppearance() on the result.

----

=== SetAvatar ===

public bool SetAvatar(UUID principalID, AvatarData avatar)

Write is delete-then-reinsert -- no partial update:

# Deletes all existing rows for principalID
# Stores the AvatarType row first
# Iterates avatar.Data:
#* Special case: AvatarHeight -- validates as float in range [0, 10]
#** Attempts locale-insensitive parse (replaces comma with period)
#** If unparseable or out of range: silently substitutes 1.771488f
#** Comment in source notes this was a hack added 2011-07-30 to cope with bad values injected by buggy simulators on OSGrid. Comment suggests removal after six months -- it is still present.
#* All other keys stored as-is
#* On any Store() failure: deletes all rows for principalID and returns false
# Returns true if all rows stored successfully

SetAppearance() constructs AvatarData from an AvatarAppearance object, then calls SetAvatar().

----

=== ResetAvatar ===

public bool ResetAvatar(UUID principalID)

Deletes all rows for principalID. Returns the result of m_Database.Delete().

----

=== SetItems ===

public bool SetItems(UUID principalID, string[] names, string[] values)

Stores a parallel array of name/value pairs for principalID. Returns false if arrays are different lengths. Stores each pair individually; stops and returns false on first Store() failure. Does not delete existing rows first -- this is a partial update, unlike SetAvatar().

----

=== RemoveItems ===

public bool RemoveItems(UUID principalID, string[] names)

Deletes individual named rows for principalID. Iterates names and calls m_Database.Delete(principalID, name) for each. Always returns true regardless of individual delete results.

----

=== Notes ===

* The AvatarHeight sanitization hack (justified 2011-07-30) is still present and active. The original comment estimated it could be removed after six months.
* SetAvatar() and SetItems() have different write semantics: SetAvatar() is a full replace (delete-all, reinsert); SetItems() is upsert (no prior delete).
* RemoveItems() always returns true -- individual delete failures are silently ignored.
* There are no console commands registered by this service.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ROBUST]]
* [[OpenSimulator Internals/Code Map/Shared]]
* [[OpenSimulator Internals/Databases]]

OpenSimulator Internals/Code Map/ROBUST/AvatarService - Revision history

Jwbshaw: first