Editing OpenSimulator Internals/Code Map/InventoryAccessModule (section)

= OpenSimulator Internals/Code Map/InventoryAccessModule =

== Overview ==

 OpenSim/Region/CoreModules/Framework/InventoryAccess/BasicInventoryAccessModule.cs
 OpenSim/Region/CoreModules/Framework/InventoryAccess/HGInventoryAccessModule.cs

Two modules, one extends the other. BasicInventoryAccessModule handles all local inventory operations. HGInventoryAccessModule extends it for HyperGrid asset mirroring and suitcase management.

Registered as IInventoryAccessModule. Selected via [Modules] InventoryAccessModule = BasicInventoryAccessModule or HGInventoryAccessModule.

----

== BasicInventoryAccessModule ==

=== Configuration ===

 [Inventory] section

{| class="wikitable"
! Key !! Default !! Purpose
|-
| CoalesceMultipleObjectsToInventory || true || Group multiple selected objects into one coalesced inventory item
|}

=== Event Wiring ===

OnNewClient() hooks per client:
* OnCreateNewInventoryItem → CreateNewInventoryItem()

=== CreateNewInventoryItem() ===

Called when avatar creates a new item directly in inventory (new script, notecard, landmark, etc.).

# Checks CanCreateUserInventory permission.
# Resolves target folder by ID, or by type if folder not found.
# If transactionID set (asset upload in progress): delegates to IAgentAssetTransactions.HandleItemCreationFromTransaction().
# Otherwise creates inline based on asset type:
#* Landmark: generates landmark asset data (region_id, local_pos, region_handle), stores asset, creates inventory item.
#* LSLText: uses Constants.DefaultScriptID as asset.
#* Notecard: uses Constants.EmptyNotecardID.
#* Settings/Material: uses environment/material defaults.
#* Clothing/Bodypart: sets flags = subType.
# Calls Scene.CreateNewInventoryItem() -- writes to inventoryitems table via InventoryService.

; DB writes:
* assets -- INSERT: new asset (landmark, notecard, etc.)
* inventoryitems -- INSERT: new inventory item

=== CopyToInventory() ===

Main path for taking objects from world to inventory (Take, TakeCopy, Delete, Return).

# Groups SOGs by owner (for coalesced objects, only same-owner SOGs merge).
# For each bundle: calls CopyBundleToInventory().

CopyBundleToInventory():
# Suspends keyframe motion on all SOGs.
# Records and stores positions/rotations (attachment stored pos used for attachments).
# Applies NextOwnerMask cleanup.
# Serialises: single SOG → SceneObjectSerializer.ToOriginalXmlFormat(); multiple → CoalescedSceneObjectsSerializer.ToXml().
# Restores positions.
# Calls CreateItemForObject() -- determines destination folder and creates InventoryItemBase shell.
# Calls AddPermissions() -- computes effective permissions from SOG current+folded perms; applies NextOwner if ownership changes.
# Creates asset: CreateAsset() → UUID.Random(), stores via AssetService.Store().
# If SaveToExistingUserInventoryItem: InventoryService.UpdateItem().
# Otherwise: Scene.AddInventoryItem() → InventoryService.AddItem(). Sends SendInventoryItemCreateUpdate() to client or owner's client.

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT or UPDATE

=== CreateItemForObject() ===

Determines destination folder and owner:

* Take / TakeCopy: remoteClient's agent ID, Object folder (or original folder if owner taking back own item).
* Delete (own item): Trash folder.
* Delete (other's item) / Return: Lost and Found folder of object owner.
* Group-owned: Last owner's inventory.

=== AddPermissions() ===

* If new owner (remoteClient != object owner) and PropagatePermissions: applies NextOwnerMask, sets ObjectSlamPerm flag.
* If same owner: copies current perms preserving folded bits.

=== RezObject() ===

Rezzes an inventory item into the scene.

# Gets InventoryItemBase from InventoryService.
# Gets asset from AssetService.
# Calls Scene.GetObjectsToRez() -- deserialises XML into List<SceneObjectGroup>.
# Calls Scene.GetNewRezLocation() -- raycasts to find rez position.
# Calls DoPreRezWhenFromItem():
#* Checks CanRezObject permission for each SOG.
#* Sets name/description from inventory item.
#* Applies ownership change and permission slam if new owner or Slam flag set.
#* Calls ApplyNextOwnerPermissions() if ownership changed.
#* Sets FromUserInventoryItemID if item is copyable.
# For each SOG: Scene.AddNewSceneObject(), CreateScriptInstances(), ResumeScripts().
# Calls DoPostRezWhenFromItem():
#* If item is no-copy: InventoryService.DeleteItems() -- removes item from inventory.

; DB reads:
* inventoryitems -- SELECT by item UUID
* assets -- SELECT by asset UUID

; DB writes (conditional):
* inventoryitems -- DELETE: if no-copy item consumed on rez

=== CapsUpdateInventoryItemAsset() ===

Called via capability when avatar edits a notecard, script, gesture, etc. in-world.

# Gets item, checks ownership and permissions.
# Creates new asset from uploaded data.
# Calls AssetService.Store() + InventoryService.UpdateItem().
# Returns new asset UUID.

; DB writes:
* assets -- INSERT: updated asset
* inventoryitems -- UPDATE: new assetID

----

== HGInventoryAccessModule ==

Extends BasicInventoryAccessModule. Active when HyperGrid is enabled.

=== Additional Configuration ===

 [HGInventoryAccessModule] section

{| class="wikitable"
! Key !! Default !! Purpose
|-
| OutboundPermission || true || Allow assets to be posted to foreign user's asset server
|-
| RestrictInventoryAccessAbroad || true || Hide non-suitcase inventory when going HG
|-
| CheckSeparateAssets || false || Support grids where world and inventory use different asset servers
|-
| RegionHGAssetServerURI || (empty) || Local asset server URL when CheckSeparateAssets=true
|}

=== HGAssetMapper ===

Static singleton. Handles Get() and Post() -- HTTP calls to foreign asset servers to fetch or push assets.

* Get(assetID, agentID, foreignAssetServerURL): fetches asset from foreign server if not in local cache.
* Post(assetID, agentID, foreignAssetServerURL): pushes local asset to foreign server (subject to OutboundPermission).

=== IsForeignUser() ===

Returns true if the user's asset server differs from local. Gets AssetServerURI from AgentCircuitData.ServiceURLs or UserManagementModule. If CheckSeparateAssets=true, compares against m_LocalAssetsURL.

=== RezObject() Override ===

Before calling base.RezObject():
* If IsForeignUser: calls m_assMapper.Get(item.AssetID, agentID, foreignAssetServer) -- fetches object asset from foreign grid if not cached locally.

=== ExportAsset() Override ===

Called from CopyBundleToInventory() after asset is stored:
* If IsForeignUser and OutboundPermission: calls m_assMapper.Post() -- pushes newly created asset to foreign user's asset server.

=== Suitcase Management ===

On TeleportStart (HG departure, local user):
* ProcessInventoryForHypergriding(): fetches root folder content, renames all non-Suitcase folders to "FolderName (Unavailable)", sends BulkUpdateInventory to client. Avatar sees only My Suitcase contents while abroad.

On TeleportFail (HG departure failed, local user):
* ProcessInventoryForComingHome(): fetches root folder, sends full inventory back without "(Unavailable)" suffix.

On CompleteMovement (HG arrival, local user returning home):
* ProcessInventoryForComingHome(): same as TeleportFail -- restores full inventory view.

ProcessInventoryForArriving() and ProcessInventoryForLeaving() are currently no-ops.

=== GenerateLandmark() Override ===

Appends "gatekeeper {URL}" line to landmark data so HG landmarks carry grid identity.

=== Permissions ===

CanTakeObject(): if OutboundPermission=false and user is foreign, only allow taking own objects.
OnTransferUserInventory(): if OutboundPermission=false, block inventory transfer to foreign users.

=== PostInventoryAsset() ===

Hooked to OnNewInventoryItemUploadComplete event. After any inventory asset upload:
* If IsForeignUser and OutboundPermission (or asset is a landmark): posts asset to foreign user's asset server.

----

== See Also ==

* [[OpenSimulator Internals/Code Map/Scene]]
* [[OpenSimulator Internals/Code Map/AttachmentsModule]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Removes From Inventory]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Rezzes Box]]
* [[OpenSimulator Internals/Walkthroughs/Avatar Derezzes Object]]