Inventory.Client
Last updated
Old Knowledge Base
Last updated
Support us as a and get instant access to all our assets, exclusive tools and assets, escalated support and issue tracking and our gratitude. These articles are made possible by our ... become a sponsor today!
To work with inventory from the point of view of a server you should use the Steam Web API for inventory.
The Steam Inventory Service is a set of features that allow a game to enable persistent player inventories without having to run special servers to manage users or items.
The following is from the Steam Documentation for the Inventory feature.
A callback is a delegate similar to a UnityEvent, that is its a pointer to a method that will be called at some later point ... in the case of Steam methods it gets called when the process completes.
Triggered whenever item definitions have been updated, which could be in response to LoadItemDefinitions or any time new item definitions are available (eg, from the dynamic addition of new item types while players are still in-game).
You would add a listener on this event such as:
Assuming a handler in the form of
Then you would register the event such as:
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
This is fired whenever an inventory result transitions from k_EResultPending to any other completed state, see GetResultStatus for the complete list of states. There will always be exactly one callback per handle.
You would add a listener on this event such as:
Assuming a handler in the form of
Then you would register the event such as:
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
You would add a listener on this event such as:
Assuming a handler in the form of
Then you would register the event such as:
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
Grant a specific one-time promotional item to the current user.
This can be safely called from the client because the items it can grant can be locked down via policies in the itemdefs. One of the primary scenarios for this call is to grant an item to users who also own a specific other game. This can be useful if your game has custom UI for showing a specific promo item to the user otherwise if you want to grant multiple promotional items then use AddPromoItems or GrantPromoItems.
Any items that can be granted MUST have a "promo" attribute in their itemdef. That promo item list a set of APPIDs that the user must own to be granted this given item. This version will grant all items that have promo attributes specified for them in the configured item definitions. This allows adding additional promotional items without having to update the game client. For example the following will allow the item to be granted if the user owns either TF2 or SpaceWar.
Grant a specific one-time promotional item to the current user.
This can be safely called from the client because the items it can grant can be locked down via policies in the itemdefs. One of the primary scenarios for this call is to grant an item to users who also own a specific other game. If you want to grant a single promotional item then use AddPromoItem. If you want to grant all possible promo items then use GrantPromoItems.
Any items that can be granted MUST have a "promo" attribute in their itemdef. That promo item list a set of APPIDs that the user must own to be granted this given item. This version will grant all items that have promo attributes specified for them in the configured item definitions. This allows adding additional promotional items without having to update the game client. For example the following will allow the item to be granted if the user owns either TF2 or SpaceWar.
Checks whether an inventory result handle belongs to the specified Steam ID.
Consumes items from a user's inventory. If the quantity of the given item goes to zero, it is permanently removed.
Once an item is removed it cannot be recovered.
This is not for the faint of heart - if your game implements item removal at all, a high-friction UI confirmation process is highly recommended.
Destroys a result handle and frees all associated memory.
This only needs to be called if you are manually handling results ... which should not be happening if your using Heathen's Steamworks.
This is only provided for completness of the API to enable deep customization for those who wish to do so.
Grant one item in exchange for a set of other items.
This can be used to implement crafting recipes or transmutations, or items which unpack themselves into other items (e.g., a chest).
The caller of this API passes in the requested item and an array of existing items and quantities to exchange for it. The API currently takes an array of items to generate but at this time the size of that array must be 1 and the quantity of the new item must be 1.
Any items that can be granted MUST have an exchange attribute in their itemdef. The exchange attribute specifies a set of recipes that are valid exchanges for this item. Exchange recipes are evaluated atomically by the Inventory Service; if the supplied components do not match the recipe, or do not contain sufficient quantity, the exchange will fail.
It is much simpler to handle this feature through the Item Defenition object.
This is included in the API for completness sake
For developer use only, this will only work if the authenticated Steam user is a member of the development team for this app.
Grants specific items to the current user, for developers only.
This API is only intended for prototyping - it is only usable by Steam accounts that belong to the publisher group for your game.
Start retrieving all items in the current users inventory.
Request the list of "eligible" promo items that can be manually granted to the given user.
These are promo items of type "manual" that won't be granted automatically. An example usage of this is an item that becomes available every week.
Gets a property value for a specific item definition.
Note that some properties (for example, "name") may be localized and will depend on the current Steam language settings (see ISteamApps::GetCurrentGameLanguage). Property names are always ASCII alphanumeric and underscores.
Returns a list of the avilable properties on a given item
Gets the state of a subset of the current user's inventory.
After a successful call to RequestPrices, you can call this method to get the pricing for a specific item definition.
After a successful call to RequestPrices, you can call this method to get all the pricing for applicable item definitions.
Gets the dynamic properties from an item in an inventory result set.
Get the items associated with an inventory result handle.
Gets the server time at which the result was generated.
Grant all potential one-time promotional items to the current user.
Triggers an asynchronous load and refresh of item definitions.
Request prices for all item definitions that can be purchased in the user's local currency. A SteamInventoryRequestPricesResult_t call result will be returned with the user's local currency code. After that, you can call GetNumItemsWithPrices and GetItemsWithPrices to get prices for all the known item definitions, or GetItemPrice for a specific item definition.
Gets the state of a subset of the current user's inventory and serializes the data.
Start retrieving all items in the current users inventory and serializes the data.
Starts the purchase process for the user, given a "shopping cart" of item definitions that the user would like to buy. The user will be prompted in the Steam Overlay to complete the purchase in their local currency, funding their Steam Wallet if necessary, etc.
Transfer items between stacks within a user's inventory.
Trigger an item drop if the user has played a long enough period of time.
Starts a transaction request to update dynamic properties on items for the current user. This call is rate-limited by user, so property modifications should be batched as much as possible (e.g. at the end of a map or game session). After calling SetProperty or RemoveProperty for all the items that you want to modify, you will need to call SubmitUpdateProperties to send the request to the Steam servers. A SteamInventoryResultReady_t callback will be fired with the results of the operation.
Submits the transaction request to modify dynamic properties on items for the current user. See StartUpdateProperties.
Removes a dynamic property for the given item.
Sets a dynamic property for the given item. Supported value types are strings, boolean, 64 bit integers, and 32 bit floats.
Checks whether an inventory result handle belongs to the specified Steam ID.
Consumes items from a user's inventory. If the quantity of the given item goes to zero, it is permanently removed.
Once an item is removed it cannot be recovered.
This is not for the faint of heart - if your game implements item removal at all, a high-friction UI confirmation process is highly recommended.
Destroys a result handle and frees all associated memory.
This only needs to be called if you are manually handling results ... which should not be happening if your using Heathen's Steamworks.
This is only provided for completeness of the API to enable deep customization for those who wish to do so.
Grant one item in exchange for a set of other items.
This can be used to implement crafting recipes or transmutations, or items which unpack themselves into other items (e.g., a chest).
The caller of this API passes in the requested item and an array of existing items and quantities to exchange for it. The API currently takes an array of items to generate but at this time the size of that array must be 1 and the quantity of the new item must be 1.
Any items that can be granted MUST have an exchange attribute in their itemdef. The exchange attribute specifies a set of recipes that are valid exchanges for this item. Exchange recipes are evaluated atomically by the Inventory Service; if the supplied components do not match the recipe, or do not contain sufficient quantity, the exchange will fail.
It is much simpler to handle this feature through the Item Definition object.
This is included in the API for completeness sake
For developer use only, this will only work if the authenticated Steam user is a member of the development team for this app.
Grants specific items to the current user, for developers only.
This API is only intended for prototyping - it is only usable by Steam accounts that belong to the publisher group for your game.
Start retrieving all items in the current users inventory.
Request the list of "eligible" promo items that can be manually granted to the given user.
These are promo items of type "manual" that won't be granted automatically. An example usage of this is an item that becomes available every week.
Get the items associated with an inventory result handle.
You should never need to call this method if your using Heathen's Steamworks
This method is included for completeness of the interface.
Gets the server time at which the result was generated.
This should never need to be called if your Heathen's Steamworks.
This method is included for completeness of the interface.
Trigger an item drop if the user has played a long enough period of time. This period can be customized in two places:
At the application level within Inventory Service: Playtime Item Grants. This will automatically apply to all "playtimegenerator" items that do not specify any overrides.
In an individual "playtimegenerator" item definition. The settings would take precedence over any application-level settings.
Only item definitions which are marked as "playtime item generators" can be spawned. Typically this function should be called at the end of a game or level or match or any point of significance in the game in which an item drop could occur. The granularity of the playtime generator settings is in minutes, so calling it more frequently than minutes is not useful and will be rate limited in the Steam client. The Steam servers will perform playtime accounting to prevent too-frequent drops. The servers will also manage adding the item to the players inventory.
For more info on how to use the Steamworks Web API please see the .
The Inventory Service can be used in two ways - either server-less or with the addition of a trusted server that knows game state. Without a game server, the game client can communicate directly to the steam service to retrieve users inventory contents, consume and exchange items, and receive new items granted as an effect of playtime. Users can also purchase items directly from the Item Store, or trade and exchange markets in the Steam community. However because the client can't be trusted (and the keys in a client can always be captured by an attacker) you can't give users specific items in this scheme. Rather you select certain items that can be dropped, and configure a drop frequency. At appropriate times, the game client invokes . Steam servers manage the playtime and drop frequency per-player. These APIs are called using an internal "Client API Key" that is assumed to be untrusted. If you have a participating trusted server then you can use a privileged Steam API key on the server and grant explicit items for appropriate situations. It is still important to keep in mind that you can't trust your own clients so you can only do this when the server is the master of the state of the game. Finally in conjunction with the Inventory Service you can sell an individual item or a cart of items, or through a web-based . Check out this presentation from for an implementation overview, details on the specific problems that the Inventory Service solves for developers.
See for more information.
To learn more please read the article on and on .
This is fired whenever Steam client notifies your game of a MTX transaction completing and includes details about that transaction. You can use this along side the feature to know when a transaction starts and ends.
This is important when using , to verify that a remote player is not pretending to have a different user's inventory.
Deserializes a result set and verifies the signature bytes. This call has a potential soft-failure mode where the handle status is set to . will still succeed in this mode. The "expired" result could indicate that the data may be out of date - not just due to timed expiration (one hour), but also because one of the items in the result set may have been traded or consumed since the result set was generated. You could compare the timestamp from to to determine how old the data is. You could simply ignore the "expired" result code and continue as normal, or you could request the player with expired data to send an updated result set. You should call on the result handle when it completes to verify that a remote player is not pretending to have a different user's inventory.
Returns the set of all item definition IDs which are defined in the App Admin panel of the Steamworks website. These item definitions may not necessarily be contiguous integers. This should be called in response to a callback. There is no reason to call this function if your game hardcodes the numeric definition IDs (eg, purple face mask = 20, blue weapon mod = 55) and does not allow for adding new item types without a client patch.
Constructs an object based on a native SteamItemDetails_t object and its source result list
Methods that impact a user's inventory will typically have a that returns a type of . In addition the stored in the active Steam Settings will be updated with the resulting which be used as a real time view of the current state of the user's inventory.
The object contains shortcut methods to many of the features found in the API.Inventory interface.
For example it is possible to consume quantity, add promo items and exchange items directly from the item its self. Please review the object closely to understand all the options available to you.
Grant a specific one-time promotional item to the current user. This can be safely called from the client because the items it can grant can be locked down via policies in the itemdefs. One of the primary scenarios for this call is to grant an item to users who also own a specific other game. This can be useful if your game has custom UI for showing a specific promo item to the user otherwise if you want to grant multiple promotional items then use or . Any items that can be granted MUST have a "promo" attribute in their itemdef. That promo item list a set of APPIDs that the user must own to be granted this given item. This version will grant all items that have promo attributes specified for them in the configured item definitions. This allows adding additional promotional items without having to update the game client. For example the following will allow the item to be granted if the user owns either TF2 or SpaceWar.
Grant a specific one-time promotional item to the current user. This can be safely called from the client because the items it can grant can be locked down via policies in the itemdefs. One of the primary scenarios for this call is to grant an item to users who also own a specific other game. If you want to grant a single promotional item then use . If you want to grant all possible promo items then use . Any items that can be granted MUST have a "promo" attribute in their itemdef. That promo item list a set of APPIDs that the user must own to be granted this given item. This version will grant all items that have promo attributes specified for them in the configured item definitions. This allows adding additional promotional items without having to update the game client. For example the following will allow the item to be granted if the user owns either TF2 or SpaceWar.
This is important when using , to verify that a remote player is not pretending to have a different user's inventory.
Deserializes a result set and verifies the signature bytes. This call has a potential soft-failure mode where the handle status is set to . will still succeed in this mode. The "expired" result could indicate that the data may be out of date - not just due to timed expiration (one hour), but also because one of the items in the result set may have been traded or consumed since the result set was generated. You could compare the timestamp from to to determine how old the data is. You could simply ignore the "expired" result code and continue as normal, or you could request the player with expired data to send an updated result set. You should call on the result handle when it completes to verify that a remote player is not pretending to have a different user's inventory.
Returns the set of all item definition IDs which are defined in the App Admin panel of the Steamworks website. These item definitions may not necessarily be contiguous integers. This should be called in response to a callback. There is no reason to call this function if your game hardcodes the numeric definition IDs (eg, purple face mask = 20, blue weapon mod = 55) and does not allow for adding new item types without a client patch.
Grant all potential one-time promotional items to the current user. This can be safely called from the client because the items it can grant can be locked down via policies in the itemdefs. One of the primary scenarios for this call is to grant an item to users who also own a specific other game. If you want to grant specific promotional items rather than all of them see: and . Any items that can be granted MUST have a "promo" attribute in their itemdef. That promo item list a set of APPIDs that the user must own to be granted this given item. This version will grant all items that have promo attributes specified for them in the configured item definitions. This allows adding additional promotional items without having to update the game client. For example the following will allow the item to be granted if the user owns either TF2 or SpaceWar.
