# Inventory

**URL:** https://heroiclabs.com/docs/hiro/unity/inventory/
**Keywords:** inventory, hiro
**Categories:** hiro, unity, inventory

---


# Inventory

Read more about the Inventory system in Hiro [here](../../concepts/inventory/).

## Initializing the inventory system

The inventory system relies on the [Nakama System](../getting-started/nakama-system) and an `ILogger`, both must be passed in as dependencies via the constructor.

```csharp
var inventorySystem = new InventorySystem(logger, nakamaSystem);
systems.Add(inventorySystem);
```

## Subscribing to changes in the inventory system

You can listen for changes in the inventory system so that you can respond appropriately, such as updating the UI, by implementing the `IObserver` pattern, or use the `SystemObserver<T>` type which handles it for you.

```csharp
var disposer = SystemObserver<InventorySystem>.Create(inventorySystem, system => {
    Instance.Logger.Info($"System updated.");

    // Update UI elements etc as necessary here...
});
```

## Refreshing the inventory system

To ensure the inventory system has the latest information from Nakama you can refresh it.

```csharp
await inventorySystem.RefreshAsync();
```

## Listing the available items

You can list the available items in the inventory system.

```csharp
var items = await inventorySystem.GetItemCodexAsync();

foreach (var item in items)
{
    Debug.Log($"Item {item.Id}: {item.Name} - {item.Description}");
}
```

You can optionally retrieve a filtered list of items by category.

```csharp
var category = "<category1>";
var items = await inventorySystem.GetItemCodexAsync(category)
```

## Listing the user's inventory

You can list a user's inventory.

```csharp
foreach (var item in inventorySystem.Items)
{
    Debug.Log($"Item {item.Id}: {item.Name} - {item.Description}");
}
```

## Granting inventory items

Grant one or more inventory items to the player.

```csharp
var items = new Dictionary<string, long>
{
    { "<itemId1>", 1 },
    { "<itemId2>", 10 }
};

await inventorySystem.GrantItemsAsync(items);
```

### Removing inventory items

To remove items from a user's inventory, without consuming them, use a negative grant value.

```csharp
var items = new Dictionary<string, long>
{
    { "<itemId1>", -1 },
    { "<itemId2>", -10 }
};

await inventorySystem.GrantItemsAsync(items);
```

## Consuming items

You can consume `items` or `item instances` for a user that have the `consumable` flag. You can specify whether or not the user is allowed to overconsume (use more than they have). 

{{< note "important">}}
Setting `overconsume` to `true` can be useful when handling multiple device scenarios. This allows consumption of the item, even if the local device's resource data is out of sync. However, once the item reaches zero, further consumption is prevented, irrespective of the overconsume setting. This provides developers flexibility in managing inventory inconsistencies across devices.
{{< / note >}}

```csharp
var itemsToConsume = new Dictionary<string, long>
{
    {"<consumableId1>", 2},
    {"<consumableId2>", 1}
};
var instancesToConsume = new Dictionary<string, long>
{
    {"<instanceId1>", 1},
    {"<instanceId2>", 1}
};

var overconsume = false;

await inventorySystem.ConsumeItemsAsync(itemsToConsume, instancesToConsume, overconsume);
```

## Updating item properties

You can update the properties on an item instance.

```csharp
var updates = new Dictionary<string, UpdateInventoryItemProperties>
{
    {
        "itemId1",
        new UpdateInventoryItemProperties
        (
            // String Properties
            new Dictionary<string, string>
            {
                { "crafted_by", "username" }
            },
            // Numeric Properties
            new Dictionary<string, double>
            {
                { "rank",  5 }
            }
        )
    }
};

await inventorySystem.UpdateItemsAsync(updates);
```

## Additional information

- [Hiro Inventory sample project](../../../../sample-projects/unity/hiro-inventory)
- [Mage Mayhem sample project](../../../../sample-projects/games/mage-mayhem)