Player inventory

Use the SDK to manage player inventory items including adding, updating, and deleting items.

Read time 4 minutes

Last updated 7 months ago

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.

Note

All the methods in this namespace can throw an EconomyException.

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.


// Optional, defaults to 20GetInventoryOptions options = new GetInventoryOptions{    ItemsPerFetch = 5};GetInventoryResult inventoryResult = await EconomyService.Instance.PlayerInventory.GetInventoryAsync(options);List<PlayersInventoryItem> firstFiveItems = inventoryResult.PlayersInventoryItems;// do something with your itemsif (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.


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

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.


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.


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.


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

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


PlayersInventoryItem playersInventoryItem = // ... fetch the players inventory itemInventoryItemDefinition 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.

Note

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


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


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:


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

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Player inventory

GetInventoryAsync

GetInventoryOptions

GetInventoryResult

AddInventoryItemAsync

AddInventoryItemOptions

DeletePlayersInventoryItemAsync

DeletePlayersInventoryItemOptions

UpdatePlayersInventoryItemAsync

UpdatePlayersInventoryItemOptions

PlayersInventoryItem

GetItemDefinitionAsync

PlayersInventoryItemUpdated

Using InstanceDataDeserializable