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

• Valve's Documentation https://partner.steamgames.com/doc/features/inventory

• Schema Documentation https://partner.steamgames.com/doc/features/inventory/schema

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.

Toolkit for Unity

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;

Toolkit for Unreal

This is optional; you do not have to pre-register your item definitions, but if you prefer to work with references, this can be a handy approach, allowing our system to manage inventory query results and load them into your predefined references.

Game Instance & Data Assets

You can define your Inventory Items as Inventory Item Data Assets

Once created, you can set the Item Definition ID ... this is the ID you created when you uploaded your Item Definition JSON to the Steamworks Developer Portal

With the inventory, Item is defined as a Data Asset you can then reference the item in you Steam Game Settings blueprint.

Doing so allows our systems to update the Inventory Item Details of this data asset for you any time you use the "Simple" versions of inventory requests, such as Get All Items - Task

It also allows you to work with this item type in a context-sensitive manner ... for example, you could create a variable Inventory Item Data Asset in a Blueprint and set your item as its default value.

You can now use the Iron Ingot variable to work with this item type however you choose.

Global Events

Steamworks has a number of global events that we have exposed to you as Blueprint bindable events from the Steam Game Instance along with giving you a simple "Get Steam Game Instance" node to easily access your instance.

The following are just a few of the most common use cases or needs regarding Steam Inventory. If you check the articles below this article, you will find more specific cases such as Crafing Systems, Microtransactions and Promo Items

Steamworks.NET

Not Applicable

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.

Toolkit for Unity

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");

Toolkit for Unreal

This is how you "refresh" your view of the player's inventory. We provide 3 variations of this feature in Blueprints, with the Task variant being the most commonly used.

As you can see, the Get All Items - Task is an asynchronous node that will run the Completed pin when Steam responds with the results. The Result point is the EResult enumerator describing the status of the call, and Items will be the items found, if any.

If you prefer to work with the callbacks yourself self you can use our Get All Items - Simple node, which will invoke an event when the result is ready and works more similarly to the native Steamworks SDK, but does package the results for you, saving you from manually managing the result handle.

When you're working with Inventory Item Data Assets, you should either always use the Simple variation or you need to manually clear and update details on the Steam Game Instance

You optionally pass in an array of strings representing the custom properties you would like the system to read from the resulting items. When the callback is executed it will define its result state and if not a failed condition it will include an array of the Item Details with Properties it found. You can think of each of these as a "stack" of 0 to many of a given item type.

The Definition ID of the item detail tells you what type of item it is, and the instance ID can be used with other functions, such as consume or exchange.

Native Style

In the above example, we used the "Simple" version of the Get All Items, which takes in a delegate that will be called when the process completes, letting our internal systems manage the callback for you. You can optionally bind to a global event listening for all "Inventory Result Ready" calls and compare the result ready "handle" with the handle provided by the native "Get All Items"

Here we request Steam to fetch all items, Steam will give us a result handle identifying this particular request

Here we are listening on the global event for Inventory Result Ready when we get that we compare it to our handle to see if its from our request.

Assuming it is from our request we can ask Steam to read us back the results based on that result handle

As you can see, our "Simple" variant greatly simplifies the process and handles the internals for you.

C++

Coming Soon

Steamworks.NET

First, you will need to register a callback to handle the response from Steam

m_ResultReady_t = Callback<SteamInventoryResultReady_t>.Create(HandleInventoryResults);

The handler for this will take the form of

void HandleInventoryResults(SteamInventoryResultReady_t results)
{
}

The actual call to Get All Items is simpler

SteamInventory.GetAllItems(out SteamInventoryResult_t resultHandle);

The result handle can then be used in your callback handler to match the response to the request.

void HandleInventoryResults(SteamInventoryResultReady_t results)
{
    //Compare the result ready handle to the anticipated handle
    if(results.m_handle == resultHandle)
    {
        //Assuming it is an expected result, you can read data from it
    }
}

Note that this same callback is used for all requests, so this is invoked anytime an inventory query result is ready. It is up to you to track the result, handle and then handle each result ready response accordingly.

Check Quantity

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

Toolkit for Unity

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");

Toolkit for Unreal

Blueprint

If you are using SteamInventoryData assets and letting our system manage that for you, then you can read the quantity from your reference easily at any time after Getting All Items or a similar query.

If you choose not to use Inventory Item Data Asset, then you will have to sum the total of the details returned in the SteamInventoryResults, which can be cumbersome

C++

Coming Soon

Steamworks.NET

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.

Toolkit for Unity

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
}

Toolkit for Unreal

Blueprint

The most commonly used approach is to use the Add Promo Item - Task node.

This is an asynchronous node whose completed pin will be run when the process is complete and will provide you with the results, if any.

If you are using Inventory Item Data Assets, you can do this from the data asset as well.

C++

Coming Soon

Steamwork.NET

Coming Soon

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.

Toolkit for Unity

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;

Toolkit for Unreal

Blueprint

Before you do anything with prices, you will want to request prices. This will update the cash with the items' prices, and it will report the currency code and symbol used by this user, which will be important for displaying prices later.

If you are using Inventory Item Data Assets, you can read this from the asset itself

You will notice that the values are whole numbers; for currencies that use decimal values, simply divide by 100. For example, a value of 99 where the user's currency is Euro would be €0.99

You can also request an array of all the items that have prices. This can simplify building out a store page.

Get all item definitions that have a defined price valid for this user

You can then read the current and base price for this user; note that the current and base price are int64 (long) values. It is the base 100 value. e.g. $1.99 would be returned as 199.

C++

Coming Soon

Steamworks.NET

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.

Toolkit for Unity

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;
    }
});

Toolkit for Unreal

Blueprint

For items that have a valid price and are enabled for purchase in their item definition, you can form the gate "start purchase" ... what this does is simply load the items into the Steam shopping cart and give you an Order and Transaction ID that represents that as of yet incomplete transaction.

As noted, this "starts" the process, but does not mean the transaction is completed. You can listen to the Micro Transaction Authorization Response event to know when a transaction is completed and check it against the Order ID provided in the Start Purchase process.

Note that a transaction can fail or be cancelled... so it's the "Authorized = True" that indicates this order is complete. Also, be aware that the user may have changed the state of the shopping cart before completing the transaction, so items may have been added or removed. It would be advisable to check the state of the inventory again or to listen to the Inventory Results Ready event and listen for changes to the player's inventory

C++

Coming Soon

Steamworks.NET

Comming Soon

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

Toolkit for Unity

Toolkit for Unreal

Steamwroks.NET

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.

Toolkit for Unity

Toolkit for Unreal

Steamwroks.NET

Consume / Delete Items

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

Toolkit for Unity

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
});

Toolikit for Unreal

Steamworks.NET