Jwbshaw: first

2026-07-07T13:18:13Z

first

New page

= OpenSimulator Internals/Code Map/AvatarFactoryModule =

== Overview ==

OpenSim/Region/CoreModules/Avatar/AvatarFactory/AvatarFactoryModule.cs

INonSharedRegionModule. Manages avatar appearance: receives baked texture updates from the viewer, validates the baked texture cache on login, queues appearance saves to AvatarService, and sends appearance to other clients. One instance per region.

Registered as IAvatarFactoryModule. Accessed by other modules via m_scene.AvatarFactory.

----

== Configuration ==

[Appearance] section in OpenSim.ini

{| class="wikitable"
! Key !! Default !! Purpose
|-
| DelayBeforeAppearanceSave || 5s || How long to wait after a change before saving to AvatarService
|-
| DelayBeforeAppearanceSend || 2s || How long to wait after a change before sending to other clients
|}

Timer fires every 500ms (m_checkTime) to drain the send and save queues.

----

== Event Wiring ==

SubscribeToClientEvents() hooks per client:

{| class="wikitable"
! Event !! Handler
|-
| OnRequestWearables || Client_OnRequestWearables()
|-
| OnSetAppearance || Client_OnSetAppearance()
|-
| OnAvatarNowWearing || Client_OnAvatarNowWearing()
|}

OnCachedTextureRequest is commented out.

----

== SetAppearance() ==

Main entry point for appearance changes. Called from Client_OnSetAppearance() and from other modules.

# Acquires m_setAppearanceLock (serialises concurrent updates).
# Calls sp.Appearance.SetVisualParams() if visualParams provided -- updates slider values, may change height.
# Calls sp.Appearance.SetTextureEntries() if textureEntry provided -- updates baked texture UUIDs.
# Calls UpdateBakedTextureCache() -- validates and stores baked textures in local asset cache and IBakedTextureModule.
# For NPCs: calls SendAppearance() immediately and returns.
# If appearance changed: calls QueueAppearanceSave().
# Always calls QueueAppearanceSend().

----

== UpdateBakedTextureCache() ==

Called on each texture update from viewer.

# Iterates cacheItems from viewer -- each maps a BakeType index to a CacheId and TextureID.
# For each entry: checks local IAssetCache for the baked texture asset.
# If found: updates WearableCacheItems[idx] with new TextureID and CacheId. Counts as a hit.
# If not found: sends SendRebakeAvatarTextures() to viewer for the missing texture. Throttled via ExpiringKey -- one rebake request per texture per 30 seconds.
# Clears PBR bake indices (>= BAKES_COUNT_PV7) that were not in the update set.
# If all items hit and validDirtyBakes > 0: stores full set to IBakedTextureModule (bake server).

----

== ValidateBakedTextureCache() ==

Called from CompleteMovement() on new root agent arrival (non-HG). Returns true if cache is valid.

# NPCs always return true.
# Checks each bake index: if WearableCacheItems matches face texture and asset is in local cache: hit.
# If local cache invalid and IBakedTextureModule available: fetches from bake server, populates local cache and WearableCacheItems.
# Returns true if hits >= BAKE_INDICES.Length (skirt index 19 is optional).

If ValidateBakedTextureCache returns false: CompleteMovement() calls QueueAppearanceSave() to trigger a rebake cycle.

----

== Queue / Timer Mechanism ==

QueueAppearanceSend(agentId):
* Adds agentId to m_sendqueue with timestamp = now + m_sendtime.
* Starts m_updateTimer.

QueueAppearanceSave(agentId):
* Adds agentId to m_savequeue with timestamp = now + m_savetime.
* Starts m_updateTimer.

HandleAppearanceUpdateTimer() (fires every 500ms):
* Drains m_sendqueue: for each expired entry calls SendAppearance(agentId) -- sp.SendAppearanceToAllOtherAgents() + Animator.SendAnimPack().
* Drains m_savequeue: batches expired entries, runs SaveAppearance() on thread pool.
* Stops timer when both queues empty.

SaveAppearance():
* Calls SetAppearanceAssets() -- resolves each wearable ItemID to AssetID via InventoryService.GetItem().
* Calls m_scene.AvatarService.SetAppearance() -- writes to ROBUST AvatarService → avatarappearance table.

; DB writes (async, via SaveAppearance):
* avatarappearance -- UPDATE: full appearance for avatar UUID

----

== Client_OnAvatarNowWearing() ==

Triggered when viewer sends AvatarIsWearing packet (outfit change initiated).

# Makes a copy of current AvatarAppearance (no lock needed on copy).
# Updates Wearables array from the wearing list -- sets ItemID, AssetID initially UUID.Zero.
# Calls avatAppearance.GetAssetsFrom(sp.Appearance) -- copies known asset IDs from current appearance.
# Under m_setAppearanceLock: updates sp.Appearance.Wearables only (does not overwrite textures or visual params).
# Calls QueueAppearanceSave() -- schedules async inventory lookup and save.

Note: Does NOT call QueueAppearanceSend(). The viewer will follow with OnSetAppearance once baking is done; that triggers the send.

----

== Client_OnRequestWearables() ==

Viewer requests wearable list (e.g. on login or reconnect). Fires async with a 4-second sleep before sending. Calls client.SendWearables(sp.Appearance.Wearables, sp.Appearance.Serial).

----

== SaveBakedTextures() ==

Saves baked textures from local asset cache to permanent AssetService storage. Used for NPCs. Marks assets as non-local, non-temporary, stores via m_scene.AssetService.Store().

----

== See Also ==

* [[OpenSimulator Internals/Code Map/ScenePresence]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Code Map/ROBUST/AvatarService]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rez In Region]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Change Outfit]]

OpenSimulator Internals/Code Map/AvatarFactoryModule - Revision history

Jwbshaw: first