Player inventory#

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

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

GetInventoryAsync#

Retrieves the current inventory item instances associated with the currently signed in player.

This method optionally takes a GetInventoryOptions 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.

The following sample code retrieves the first five items for the current user, and then retrieves the next five.

C#

// Optional, defaults to 20
GetInventoryOptions options = new GetInventoryOptions
{
    ItemsPerFetch = 5
};

GetInventoryResult inventoryResult = await EconomyService.Instance.PlayerInventory.GetInventoryAsync(options);
List<PlayersInventoryItem> firstFiveItems = inventoryResult.PlayersInventoryItems;
// do something with your items

if (inventoryResult.HasNext) {
    inventoryResult = await inventoryResult.GetNextAsync(5);
    List<PlayersInventoryItem> nextFiveItems = inventoryResult.PlayersInventoryItems;
    // do something with your items
}

This next sample code retrieves only the player's SWORD items.

C#

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

GetInventoryResult inventoryResult = await EconomyService.Instance.PlayerInventory.GetInventoryAsync(options);

List<PlayersInventoryItem> listOfItems = inventoryResult.PlayersInventoryItems;

// ... etc

These methods return a GetInventoryResult.

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 player's 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 player's inventory items retrieved. It has the following field:

• 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 its 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 an AddInventoryItemOptions object. This is used to set a custom PlayersInventoryItemId — if null, one is autogenerated. Can also be used to set a dictionary of instance data.

Returns a PlayersInventoryItem representing the inventory item added to the player's inventory.

C#

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

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

PlayersInventoryItem createdInventoryItem = await EconomyService.Instance.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 is generated.
• InstanceData: A Dictionary<string, object>. Used to set a dictionary of instance data.

DeletePlayersInventoryItemAsync#

Deletes an item from a player's inventory.

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

C#

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

DeletePlayersInventoryItemOptions#

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

• WriteLock: A string. Defaults to null. Use this to set a write lock for optimistic concurrency. See Write Lock.

UpdatePlayersInventoryItemAsync#

Updates an item with new instance data.

Returns the updated players inventory item.

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

C#

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

UpdatePlayersInventoryItemOptions options = new UpdatePlayersInventoryItemOptions
{
    WriteLock = writeLock 
};

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

UpdatePlayersInventoryItemOptions#

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

• WriteLock: A string. Defaults to null. Use this to set a write lock for optimistic concurrency. See 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 resource ID of the inventory item configuration associated with this instance.
• InstanceData: Any instance data associated with this players inventory item.
• InstanceDataDeserializable: Any instance data associated with this players’ inventory item, as an IDeserializable. See Using InstanceDataDeserializable.
• WriteLock: The current writelock string for this player's inventory item.
• Created: The date this player's inventory item was created. It is an EconomyDate object.
• Modified: The date this player's inventory item was modified. It is an EconomyDate object.

It also has the following helper method:

GetItemDefinitionAsync#

This method fetches the configuration of this player's inventory item, type of InventoryItemDefinition.

C#

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 is passed the playersInventoryItem ID of the item that was updated.

C#

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

Using InstanceDataDeserializable#

Use InstanceDataDeserializable to add custom data for specific items in a player's inventory. It is passed in as type object and fetched as type IDeserializable. This allows you to pass in your own custom classes as instance data.

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

C#

class MyInstanceData
    {
        public int Durability;
        public string Rarity;
    }

MyInstanceData myInstanceData = new MyInstanceData() { Durability = 100, Rarity = "purple"};
PlayersInventoryItem updatedItem = await EconomyService.Instance.PlayerInventory.UpdatePlayersInventoryItemAsync("playersInventoryItemId", myInstanceData);

You can deserialize the instance data by doing the following:

C#

MyInstanceData fetchedInstanceData = updatedItem.InstanceData.GetAs<MyInstanceData>();
int durability = fetchedInstanceData.Durability;
string rarity = fetchedInstanceData.Rarity;