Inventory

Steam Inventory lets you define items that will be held in the user's Steam Inventory. These items can be made tradable between players, marketable on the community marketplace, made available for sale in the Steam store or in your game and can be defined with probability tables and exchange recipes enabling crafting, loot boxes and more.

Steam Inventory is by and far the largest, most capable and most complex feature of Steamworks. This article will introduce the general concepts of the system, as the system can be used in many ways for many purposes quick start and how to guides will be separated out.

Required Reading - Please dont just skip this, it is important

Items

https://partner.steamgames.com/doc/features/inventory/schema

This is the most basic unit/object in Steam's Inventory system. An item is a defined concept with a unique ID, name, description and a range of additional metadata depending on the type of item it is and how it can be used. For example, an item can have a "price" which makes it available on the Steam Store, it can also have an "exchange" defined allowing it to be crafted by consuming a given set of other items.

Bundles

https://partner.steamgames.com/doc/features/inventory/schema#SpecifyBundles

This represents a set of items and quantities and when instantiated, unpacks into the collection of items.

Item Generators

https://partner.steamgames.com/doc/features/inventory/schema

This is a set of rules that will result in the production of an item. There are various types of generators; the most commonly used would be the PlayTimeGenerator which can be invoked to generate items for a player based on the amount of time the player has played the game.

Tags

https://partner.steamgames.com/doc/features/inventory/itemtags

A somewhat advanced feature, tags allow you to mark up an item instance with additional data. For example, your Iron Sword item could have a "Quality" tag with values such as "Quality:Common" or "Quality:Rare"

Tools

https://partner.steamgames.com/doc/features/inventory/tools

Tools are related to tags and allow you to create items that can modify other items, such as changing the tags on an item

Item Store

https://partner.steamgames.com/doc/features/inventory/itemstore

Your items can be sold to your players via the item store. This requires the items to have a price or price category and is an optional feature.

Steam Community Market

https://partner.steamgames.com/doc/features/inventory/schema

Items can be made marketable by players, which allows players to buy and sell items amongst themselves and results in a small cut of proceeds being relayed to you as the developer. See the marketable field on the Schema definition page.

Steam Trading

https://partner.steamgames.com/doc/features/inventory/schema

Items can be made tradeable by players, which allows players to trade with each other over the Steam Inventory screen (outside your game). See the tradable field on the Schema definition page.

What Can It Do?

Crafting The Steam Inventory system supports an exchange concept where you define a recipe—a collection of items and their quantities—that can be traded for a specific item. While this feature can be used for loot boxes and similar systems, its most user-friendly application is as a crafting system. Players collect reagents (items) and exchange them for gear such as a shield or sword made from iron and leather.

Microtransactions (MTX) Steam Inventory serves as the framework for defining items available for purchase through the Steam store or your storefront, with management handled by Steam.

Player Economy Create items that players can securely trade both in and out of the game; these items can also be optionally listed on the Community Marketplace for player-to-player sales.

In-App Purchase (IAP) Define items that can be purchased in-game, and set up exchange recipes that allow players to buy items using in-game currency through your shop.

Item Collection and Progression Securely define items, reagents, crafting recipes, drop rates, and probability tables that drive item collection and progression within your game.

In-Game Economy Manage items, reagents, recipes, drop rates, and loot tables that power your in-game economy. Items managed by Steam Inventory do not have to be available for sale, trade, or community marketing; you can keep them hidden and control every aspect of their distribution, consumption, and use. This system offers a secure method for managing client interactions with items, including generators, drops, and exchanges.


Use

Regardless of how you use the Steam Inventory system, follow these simple guidelines when managing items in your game.

What Is an Item

An item is simply an integer representing the unique ID of an item type. Each ID is linked to an Item Definition that describes the item's name, price, and other properties. Typically, you only need to know the quantity of each item type a user owns (for example, how many of item type 42 does the user have) and, in a store context, the local price of that item.

Inventory Snapshot

Items exist outside your game logic and can be affected by various systems, including Steam. Therefore, your game must query the inventory state to determine what items the user owns at any given moment. This snapshot represents the current state, which may change without your game’s knowledge. Valve and Heathen recommend refreshing your view of the inventory just before any critical operation, such as opening an inventory screen or entering a game session where items will be used. Heathen provides tools for easily requesting and inspecting item quantities, tags, and overall state.

Using Items

User items are presented as a collection of "item details"; each detail represents a stack of a single item type. For example, a user might have 10 stacks of gold, each with a different quantity. Although rare, a stack can have a quantity of 0. Most operations—such as exchanging or consuming items—work with specific item details, each having a unique identifier. Heathen's tools simplify handling these details and building lists for exchanges and consumption, so you usually do not need to sort items manually.

Exchanging

Exchanging, also known as crafting, involves trading one or more items for a different item. The result is always a single item, which can be a bundle, generator, or any nested type. Examples include: • Exchanging 1 chest for a bundle (which might contain multiple items, a generator, or other bundles); • Crafting a sword by trading 2 iron and 10 gold for an iron sword; • Buying a chest by exchanging 100 gold for 1 chest, which can later be opened to yield a bundle.

Consuming

Consuming items means deleting them, which applies to consumables like food, boosts, or potions, but can be used to remove any item. Use with caution.


Examples

Item Definitions

To create your item definitions, you do this in JSON and upload it to your Steamworks developer portal In the above sections, we outlined the various things you can do and the Schema link at the top guides you to Valve's documentation on creating that JSON.

Code Free

Once you have created your Steam Inventory Items in the Steam Developer Portal you can access them in your project via code, through the Item Data struct or the Inventory API. You can also access your item definitions via Scriptable Objects using the Steam Settings object.

In all cases, using your Item Definition, you will be able to

  • Determine if the user owns this item and how many they own

  • Be able to start a purchase of this item

  • Be able to combine this item

  • Be able to use this item in an exchange recipe

  • Be able to exchange other items (recipes) for this item

  • Be able to read the item's price, name and other attributes if set

Heathen's system will attempt to track changes to the items that Steam notifies the game of, and in many cases, this can keep the item state up to date through gameplay. However: It's important to remember that changes can occur to the items from outside your game's view. As such, anytime you need to "know" with a level of certainty how many or what items the player owns, you should perform a Get All Items

Scriptable Objects

To import your Steam Inventory Item Definition into your project as a Scriptable Object, you need to start your game in the Editor so that the Steam API can initialize. Then, open your Steam Settings in the inspector and click the Import option under the Inventory section

This may take a few seconds to complete, but it will import all item definitions and create a Scriptable Object representation for each one stored under the Steam Settings object, similar to Stas, Achievements and other Steam artifacts.

Once complete you now have a scriptable object that you can use with other "code-free" tools to interact with your items.

C#

We have created simple structs in C# that let you do everything you might want to do with an item and all you need is that item's ID.

// Assuming you have an item whose ID is 100, this is now that item
ItemData myItem = 100;

Get All Items

For efficiency, Steamworks Inventory uses a local cache. The SDK keeps the player's inventory data locally, so actions like reading an item's quantity are effectively instant. Get All Items asks Steam.exe to refresh this cache; it's recommended to call this just before any in-game action where you need an accurate view, and values may have changed from outside the game, such as opening the inventory UI.

Code Free

Not Applicable

C#

This can be done using the static Update function on ItemData.

// Using ItemData
ItemData.Update(HandleInventoryUpdate);

Or by using the Inventory.Client static class

// Using API Extensions
Inventory.Client.GetAllItems(HandleInventoryUpdate);

In either case, the handler will look like such

void HandleInventoryUpdate(InventoryResult response)
{
    // response.result is the EResult indicating if this is good or not
    // response.items is an array of ItemDetail describing all details found
    // response.timestamp is when this was returned originally
}

Once the handler has returned, you can then use ItemData for specific items to check quantities and perform similar actions.

ItemData myItem = 100;
Debug.Log($"The player has {myItem.GetTotalQuantity()} of item ID 100");

You can do something similar using the Inventory.Client

long quantity = Inventory.Client.ItemTotalQuantity(100);
Debug.Log($"The player has {quantity} of item ID 100");

Check Quantity

How do you know if the user owns any of a given item, and if so, how many?

Code Free

Not Applicable

C#

Using the Item Data structure

//Assuming your item
ItemData myItem = 100;

//Then you can read the quantity
Debug.Log($"The player has {myItem.GetTotalQuantity()} of item ID 100");

Or you can use the API

long quantity = Inventory.Client.ItemTotalQuantity(100);
Debug.Log($"The player has {quantity} of item ID 100");

Add Promo Item

This lets you "give" users an item; in general, Steam Inventory doesn't allow you to just give users items when you want, but promotional items can be. If you read the above documentation, you can learn more about creating items that can be given to users, just once or multiple times.

Code Free

Not Applicable

C#

// Assuming 
ItemData myItem = 100;
// or
ItemDefinitionObject myItem; // Drag and drop in the inspector

//Then you can request the item to be added, note that it will only be added
//If the rules you defined on the item in the Steamworks Developer Portal
//Resolve for this user
myItem.AddPromoItem(HandleResult);

Or you can use the API

Inventory.Client.AddPromoItem(100, HandleResult);

The callback delegate takes the form of

void HandleResult(InventoryResult response)
{
    // response.result is the EResult indicating if this is good or not
    // response.items is an array of ItemDetail describing all details found
    // response.timestamp is when this was returned originally
}

Get Price

If your item has a valid price or price category set, you can request the current price and get the data for the local user. This is useful when creating in-game cash shops.

Code Free

Not Applicable

C#

// Assuming 
ItemData myItem = 100;
// or
ItemDefinitionObject myItem; // Drag and drop in the inspector

// Before you work with prices, be sure to request the prices
// This is normally done for you on initialisation
// but be sure
ItemData.RequestPrices((result, ioError) =>
{
    // if result.m_result is okay and ioError is false all is well
});

// get the current and base price (base price is before sales/promos)
myItem.GetPrice(out ulong currentPrice, out ulong basePrice);

// get the current price as a human-friendly string ... this assumes
// the currency is base 100 (USD, GBP, Euro, etc.)
string price = myItem.CurrentPriceString();
// and the same for base price
string basePrice = myItem.BasePriceString();

// Do you just need the currency symbol? .. e.g. $, €, £, etc
string symbol = ItemData.CurrencySymbol;

Start Purchase

You can add one or more items to a user's Steam shopping cart directly from your game by calling Start Purchase. If the provided inputs are valid, such as a valid item, price, and availability for the user, the Steam overlay will open and display the item in the shopping cart.

Starting the purchase does not initiate the payment process; it simply adds the item to the cart. The user can then modify or complete the purchase at their discretion. If they choose to proceed, MTX Txn Authorisation Response events will be triggered within the game.

Code Free

Not Applicable

C#

// Assuming 
ItemData myItem = 100;
// or
ItemDefinitionObject myItem; // Drag and drop in the inspector

// Assuming myItem is valid for purchase (has a price, is not blocked or hidden)
// How many to buy?
uint count = 1;
myItem.StartPurcahse(count, (result, ioError) =>
{
    if(!ioError && result.m_result == EResult.k_EResultOK)
    {
        ulong OrderId = result.m_ulOrderID;
        ulong TransactionId = result.m_ulTransID;
    }
});

Exchange

Exchange allows you to securely exchange 1 or more items for another item. This can be used for several in-game features such as

In-Game Store

Allow your players to earn in-game currency and securely exchange it for items. You can also implement premium currency, where players "purchase" the currency. However, be cautious with this form of monetisation, as it often leads to negative outcomes.

Lootbox

This is where you have a single item that gets "opened" to reveal 1 or more items. This is effectively simply exchanging the "lootbox" for an item generator or bundle.

Crafting

This is where your player finds, earns, or purchases reagents that can then be "forged", aka "exchanged", for something else

Serialize Inventory

Serialise Inventory is used when an authenticated user needs to prove ownership of specific inventory items. This feature allows a user to generate a serialised representation of their inventory—either the full inventory or a selected subset—which can be shared as proof of ownership.

For example, in a card collection game, a player may need to prove to their opponent that they own all the cards in their deck. By serialising the relevant cards, the player can present a verifiable snapshot of those items, authenticated by the Steam backend.

Consume / Delete Items

You should rarely, if ever, need to do this; this cannot be reversed once done.

Code Free

Not Applicable

C#

// Assuming 
ItemData myItem = 100;
// or
ItemDefinitionObject myItem; // Drag and drop in the inspector

// Then to consume 1 
myItem.Consume(result =>
{
    // result is an InventoryResult and can be used to see what was done
});

// To consume a defined number ...
// Note this may construct multiple consume orders if the requested number is 
// split across various stacks of items
myItem.Cosnume(42, result =>
{
    // result is an InventoryResult and can be used to see what was done
});

Last updated