Player Inventory

The methods in the PlayerInventory namespace allow you to retrieve and update the player's inventory items.

These methods will return inventory data for the currently signed in player from the Authentication SDK.

All the methods in this namespace can throw an EconomyException as described here

GetInventoryAsync

Retrieves the current inventory items associated with the currently signed in player.

This method optionally takes a AddInventoryItemOptions object. This can be used to set the number of items per fetch and for filtering.

You can filter the inventory items using a list of configuration item IDs and/or PlayersInventoryItem IDs. If you use these filter options then only players items that have the specified configuration item IDs and PlayersInventoryItem IDs will be returned.

// Will retrieve the default maximum of 20 items
GetInventoryResult inventoryResult = await Economy.PlayerInventory.GetInventoryAsync();

List<PlayersInventoryItem> listOfItems = inventoryResult.PlayersInventoryItems;

if (inventoryResult.HasNext) {
    inventoryResult.GetNext();
}
List<PlayersInventoryItem> updatedList = inventoryResult.PlayersInventoryItems;

// ... etc

Retrieve the first 5 balances for the current user, and then retrieve the next 5.

PlayerInventory.GetInventoryOptions options = new PlayerInventory.GetInventoryOptions
{
    ItemsPerFetch = 5
};
GetInventoryResult inventoryResult = await Economy.PlayerInventory.GetInventoryAsync(options);

List<PlayersInventoryItem> listOfItems = inventoryResult.PlayersInventoryItems;

if (inventoryResult.HasNext) {
    GetInventoryResult nextinventoryResult = await inventoryResult.GetNext(5);
}

// ... etc

Retrieve only the player's SWORD items.

PlayerInventory.GetInventoryOptions options = new PlayerInventory.GetInventoryOptions
{
    InventoryItemIds = new List<string>() { "SWORD" }
};

GetInventoryResult inventoryResult = await Economy.PlayerInventory.GetInventoryAsync(options);

List<PlayersInventoryItem> listOfItems = inventoryResult.PlayersInventoryItems;

// ... etc

These methods return a GetInventoryResult. This object handles the pagination for you.

GetInventoryOptions

The options object for a GetInventoryAsync call. It has the following fields:

  • PlayersInventoryItemIds: A list of strings. Defaults to null. The PlayersInventoryItem IDs of the items in the players inventory that you want to retrieve.
  • InventoryItemIds: A list of strings. Defaults to null. The configuration IDs of the items you want to retrieve.
  • ItemsPerFetch: An int. Defaults to 20. Use this to set the maximum number of items to fetch per call between 1 and 100 inclusive.

GetInventoryResult

A GetInventoryResult provides paginated access to the list of players inventory items retrieved. It has the following fields:

  • PlayersInventoryItems: A List<PlayersInventoryItem> with the currently fetched items

It has the following methods:

  • GetNextAsync(int itemsToFetch = 20): This method asynchronously fetches more results. It has one optional parameter to limit the amount of results fetched (this can be between 1 and 100 inclusive, default is 20). It will return a new result, which contains both the original items and the newly fetched items in it's PlayersInventoryItems list. The result will be null if there are no more results to fetch.

AddInventoryItemAsync

Adds an item to the player's inventory.

This method optionally takes a AddInventoryItemOptions object. This is used to set a custom PlayersInventoryItemId - if null one will be autogenerated. Can also be used to set a dictionary of instance data.

Returns a PlayersInventoryItem representing the inventory item added to the players inventory.

Dictionary<string, object> instanceData = new Dictionary<string, object>
{
    { "rarity", "purple" }
};

PlayerInventory.AddInventoryItemOptions options = new PlayerInventory.AddInventoryItemOptions
{
    PlayersInventoryItemId = "customID",
    InstanceData = instanceData 
};

PlayersInventoryItem createdInventoryItem = await Economy.PlayerInventory.AddInventoryItemAsync("SWORD", options);

AddInventoryItemOptions

The options object for a AddInventoryItemAsync call. It has the following fields:

  • PlayersInventoryItemId: A string. Defaults to null. Sets the ID of the created PlayersInventoryItem. If not supplied, one will be generated.
  • InstanceData: A Dictionary<string, object>. Used to set a dictionary of instance data. See [here](./player_inventory.md#Using InstanceData).

DeletePlayersInventoryItemAsync

Deletes an item from a player's inventory.

This method optionally takes a DeletePlayersInventoryItemOptions object used to set the write lock. If a writeLock is provided, it will only delete the item if the writeLock is accepted by the Economy service. If no writelock is provided then the operation will be forced through.

PlayerInventory.DeletePlayersInventoryItemOptions options = new PlayerInventory.DeletePlayersInventoryItemOptions
{
    WriteLock = "writeLock"
};
Economy.PlayerInventory.DeletePlayersInventoryItemAsync("playersInventoryItemID", options);

DeletePlayersInventoryItemOptions

The options object for a DeletePlayersInventoryItemAsync call. It has the following fields:

  • WriteLock: A string. Defaults to null. Use this to set a write lock for optimistic concurrency. More details [here](./common_objects.md#Write Lock).

UpdatePlayersInventoryItemAsync

Updates an item with new instance data.

Returns the updated players inventory item.

This method optionally takes a UpdatePlayersInventoryItemOptions object used to set the write lock. If a writeLock is provided, it will only update the item if the writeLock is accepted by the Economy service. If no writelock is provided then the operation will be forced through.

Dictionary<string, object> instanceData = new Dictionary<string, object>
{
    { "rarity", "purple" }
};

PlayerInventory.UpdatePlayersInventoryItemOptions options = new PlayerInventory.UpdatePlayersInventoryItemOptions
{
    WriteLock = writeLock 
};

PlayersInventoryItem playersInventoryItem = await Economy.PlayerInventory.UpdatePlayersInventoryItemAsync("playersInventoryItemID", instanceData, options);

UpdatePlayersInventoryItemOptions

The options object for a UpdatePlayersInventoryItemAsync call. It has the following fields:

  • WriteLock: A string. Defaults to null. Use this to set a write lock for optimistic concurrency. More details [here](./common_objects.md#Write Lock).

PlayersInventoryItem

A PlayersInventoryItem represents a single unique item in a player's inventory. It contains the following fields:

  • PlayersInventoryItemId: The ID of this unique inventory item in the players inventory
  • InventoryItemId: The configuration ID of this inventory item
  • InstanceData: Any instance data associated with this players inventory item. See below for more details.
  • WriteLock: The current writelock string for this players inventory item
  • Created: The date this players inventory item was created. It is an EconomyDate object (see here).
  • Modified: The date this players inventory item was modified. It is an EconomyDate object (see here).

It also has the following helper method:

GetItemDefinition

This method fetches the configuration of this players inventory item, type of InventoryItemDefinition.

PlayersInventoryItem playersInventoryItem = // ... fetch the players inventory item
InventoryItemDefinition itemDefinition = playersInventoryItem.GetItemDefinitionAsync();

PlayersInventoryItemUpdated

This event can be subscribed to in order to be notified when the SDK updates a specific item in the player's inventory. The subscriber will be passed the playersInventoryItem ID of the item that was updated.

Note: This event will only be called for SDK initiated actions (e.g. updating player's inventory, making purchases etc). It will not be called for any updates from other devices / service side changes.

Economy.PlayerInventory.PlayersInventoryItemUpdated += playersInventoryItemID => {
    Debug.Log($"The players inventory item that was updated was {playersInventoryItemID}");
};

Using InstanceData

InstanceData is used to add custom data for specific items in a player's inventory. It is of type Dictionary<string, object>.

For example, a player's shield may have a durability rating. This could be set and updated using InstanceData:

Dictionary<string, object> instanceData = new Dictionary<string, object>();
instanceData.Add("durability", 100);        

PlayersInventoryItem updatedItem = await Economy.PlayerInventory.UpdatePlayersInventoryItemAsync("playersInventoryItemId", instanceData);