Editing OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory (section)

= OpenSimulator Internals/Walkthroughs/Avatar Acquires Inventory =

== Overview ==

Traces what happens in code, connectors, and database when an avatar acquires an object into inventory. Covers three cases:

# Taking a copyable object from the world (Take Copy).
# Taking a no-copy object from the world (Take / derez).
# Buying an object from another avatar or vendor (buy object).

Avatar-to-avatar direct inventory transfer (Give Inventory) is a separate flow not covered here.

----

== Case 1: Take Copy (copyable object) ==

Avatar right-clicks an object they have copy permission on and selects Take Copy.

=== 1. Client Sends DeRezObject ===

 OpenSim/Region/Framework/Scenes/Scene.cs -- DeRezObjects()

# Viewer sends DeRezObject packet with action = TakeCopy.
# Scene.DeRezObjects() fires.
# Permission check: CanTakeObject() for the SOG.
# If passing: calls IInventoryAccessModule.CopyToInventory(DeRezAction.TakeCopy, folderID, objlist, remoteClient, false).
# Object remains in scene -- Take Copy does not delete it.

=== 2. Object Serialised to Asset ===

 BasicInventoryAccessModule -- CopyBundleToInventory()

# Suspends keyframe motion.
# Records current world position/rotation.
# Serialises SOG to XML via SceneObjectSerializer.ToOriginalXmlFormat() (single object) or CoalescedSceneObjectsSerializer (multiple selected).
# Restores position.
# Calls CreateItemForObject(TakeCopy):
#* Destination folder: Object folder (FolderType.Object).
#* Owner: remoteClient.AgentId.
# Calls AddPermissions() -- same-owner path: copies current perms, preserves folded bits, applies NextOwnerMask to NextPermissions.
# Creates asset: UUID.Random(), AssetType.Object, stores via AssetService.Store().
# Calls Scene.AddInventoryItem() → InventoryService.AddItem().
# Sends SendInventoryItemCreateUpdate() to client.

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: new item in Object folder

=== 3. HG Asset Post (HG users only) ===

 HGInventoryAccessModule -- ExportAsset()

If avatar is a foreign HG user and OutboundPermission=true:
* m_assMapper.Post(assetID, agentID, foreignAssetServer) -- HTTP POST to push asset to foreign grid.

----

== Case 2: Take (no-copy object, or owner taking back own object) ==

Avatar takes a no-copy object, or picks up their own placed object.

=== 1. Client Sends DeRezObject ===

# Viewer sends DeRezObject packet with action = Take.
# Same permission check path.
# Calls IInventoryAccessModule.CopyToInventory(DeRezAction.Take, folderID, objlist, remoteClient, false).

=== 2. Object Serialised (same as Take Copy) ===

CopyBundleToInventory() with Take:
* Destination folder: original FromFolderID if owner taking back own item and folder still valid; otherwise Object folder.
* Asset created and stored, inventory item inserted.

=== 3. Object Removed from Scene ===

DoPostRezWhenFromItem():
* If item is no-copy (CurrentPermissions & Copy == 0): InventoryService.DeleteItems() removes item from inventory first (item was previously there for the no-copy object).

Scene.DeRezObjects() also:
* Calls DeleteSceneObject() -- removes SOG from scene graph, removes from SimulationDataService (prims table).

; DB writes:
* assets -- INSERT: serialised object XML
* inventoryitems -- INSERT: new item (or UPDATE if SaveToExisting)
* inventoryitems -- DELETE: original no-copy item if applicable
* prims/primshapes -- DELETE: object removed from region storage

----

== Case 3: Buy Object ==

Avatar buys an object set for sale (right-click → Buy).

=== 1. Client Sends ObjectBuy ===

 OpenSim/Region/Framework/Scenes/Scene.cs -- ProcessObjectBuy() (via IBuySellModule)

# Viewer sends ObjectBuy packet with price.
# IBuySellModule.BuyObject() called.
# Checks sale type and price.
# If sale type is Copy: calls IInventoryAccessModule.CopyToInventory(DeRezAction.TakeCopy) -- same as Take Copy path above. Object stays in scene.
# If sale type is Original: calls IInventoryAccessModule.CopyToInventory(DeRezAction.Take). Object leaves scene.
# If sale type is Contents: copies contents of the object's inventory to buyer's inventory, not the object itself (separate path via task inventory).

Money transfer (if price > 0):
* IBuySellModule calls IMoneyModule.ObjectBuy() -- money transfer between accounts. This is grid-specific; base OpenSim has no money module by default.

; DB writes (object sale):
* Same as Take or Take Copy depending on sale type.

----

== Permissions Applied on Acquire ==

AddPermissions() is the key method. Two paths:

New owner (buyer or taker who is not the original owner) and PropagatePermissions=true:
* effectivePerms = intersection of all parts' CurrentAndFoldedNextPermissions().
* Applies PermissionsUtil.ApplyNoModFoldedPermissions().
* basePerms = effectivePerms & RootPart.NextOwnerMask.
* Fixes and folds: PermissionsUtil.FixAndFoldPermissions().
* Sets ObjectSlamPerm flag -- permissions applied again on rez.

Same owner (taking back own object):
* effectivePerms = intersection of current perms.
* NextPermissions = RootPart.NextOwnerMask & effectivePerms.
* No slam flag.

----

== Summary: DB Tables Touched ==

{| class="wikitable"
! Table !! Operation !! Case
|-
| assets || INSERT || All cases: new serialised object asset
|-
| inventoryitems || INSERT || All cases: new inventory item
|-
| inventoryitems || DELETE || No-copy Take: removes existing item
|-
| prims/primshapes/primitems || DELETE || Take (no-copy) or Take (own object): removes from region
|}

----

== HG Suitcase Note ==

When a local user is abroad (HG), ProcessInventoryForHypergriding() has renamed their non-suitcase folders to "(Unavailable)". Items they acquire while abroad go into My Suitcase (the only accessible folder). On return home, ProcessInventoryForComingHome() restores the full inventory view.

Foreign users acquiring objects: ExportAsset() posts the asset to their home grid's asset server if OutboundPermission=true.

----

== See Also ==

* [[OpenSimulator Internals/Walkthroughs]]
* [[OpenSimulator Internals/Code Map/InventoryAccessModule]]
* [[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]]