Comment on page
Inventory.Client
Support us as a GitHub Sponsor 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 GitHub Sponsors ... become a sponsor today!
using InvClient = HeathenEngineering.SteamworksIntegration.API.Inventory.Client;
public static class Inventory.Client
To work with inventory from the point of view of a server you should use the Steam Web API for inventory.
This is a Service interface, methods in this interface should be called with the
input_json parameter.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.
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 Trigger Item Drop. 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, in-game or through a web-based storefront. Check out this presentation from Steam Dev Days 2016 for an implementation overview, details on the specific problems that the Inventory Service solves for developers.
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
private void HandleEvent()
{
}
Then you would register the event such as:
API.Inventory.Client.EventSteamInventoryDefinitionUpdate.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Inventory.Client.EventSteamInventoryDefinitionUpdate.RemoveListener(HandleEvent);
}
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
private void HandleEvent(InventoryResult result)
{
}
Then you would register the event such as:
API.Inventory.Client.EventSteamInventoryResultReady.AddListener(HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Inventory.Client.EventSteamInventoryResultReady.RemoveListener(HandleEvent);
}
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 StartPurchase feature to know when a transaction starts and ends.
You would add a listener on this event such as:
Assuming a handler in the form of
private void HandleEvent(AppId_t appId, ulong orderId, bool authorized)
{
}
Then you would register the event such as:
API.Inventory.Client.EventSteamMicroTransactionAuthorizationResponce.AddListener(
HandleEvent);
When you no longer need this handler you should remove it for example when the behavior using it is destroyed
void OnDestroy()
{
API.Inventory.Client.EventSteamMicroTransactionAuthorizationResponce.RemoveListener(
HandleEvent);
}
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.
public static bool AddPromoItem(SteamItemDef_t itemDef,
Action<InventoryResult> callback)
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.
public static bool AddPromoItems(ItemDefinition item,
Action<InventoryResult> callback)
public static bool AddPromoItems(SteamItemDef_t[] itemDefs,
Action<InventoryResult> callback)
public static bool AddPromoItems(ItemDefinition[] items,
Action<InventoryResult> callback)
public static bool AddPromoItems(IEnumerable<SteamItemDef_t> itemDefs,
Action<InventoryResult> callback)
Checks whether an inventory result handle belongs to the specified Steam ID.
This is important when using Deserialize Results, to verify that a remote player is not pretending to have a different user's inventory.
public static bool CheckResultSteamID(SteamInventoryResult_t resultHandle,
CSteamID steamIDExpected)
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.
public static void ConsumeItem(SteamItemInstanceID_t itemConsume,
uint quantity,
Action<InventoryResult> callback)
Deserializes a result set and verifies the signature bytes.
This call has a potential soft-failure mode where the handle status is set to k_EResultExpired. Get Result Items 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 Get Result Timestamp to ISteamUtils::GetServerRealTime 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 Check Result Steam ID on the result handle when it completes to verify that a remote player is not pretending to have a different user's inventory.
public static void DeserializeResult(byte[] buffer,
Action<InventoryResult> callback)
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.
public static void DestroyResult(SteamInventoryResult_t resultHandle)
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
public static void ExchangeItems(SteamItemDef_t generate,
SteamItemInstanceID_t[] destroy,
uint[] destroyQuantity,
Action<InventoryResult> callback)
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.
public static void GenerateItems(SteamItemDef_t[] itemDefs,
uint[] quantity,
Action<InventoryResult> callback)
Start retrieving all items in the current users inventory.
Calls to this function are subject to rate limits and may return cached results if called too frequently. It is suggested that you call this function only when you are about to display the user's full inventory, or if you expect that the inventory may have changed.
public static void GetAllItems(Action<InventoryResult> callback = null)
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.
public static void GetEligiblePromoItemDefinitionIDs(CSteamID userId,
Action<SteamItemDef_t[], bool> callback)
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 SteamInventoryDefinitionUpdate_t 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.
public static bool GetItemDefinitionIDs(out SteamItemDef_t[] results)
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.
public static string GetItemDefinitionProperty(SteamItemDef_t item,
string propertyName)
Returns a list of the avilable properties on a given item
public static string[] GetItemDefinitionProperties(SteamItemDef_t item)
Gets the state of a subset of the current user's inventory.
public static void GetItemsByID(SteamItemInstanceID_t[] instanceIds,
Action<InventoryResult> callback = null)
After a successful call to RequestPrices, you can call this method to get the pricing for a specific item definition.
public static bool GetItemPrice(SteamItemDef_t item,
out ulong currentPrice,
out ulong basePrice)
After a successful call to RequestPrices, you can call this method to get all the pricing for applicable item definitions.
public static bool GetItemsWithPrices(out SteamItemDef_t[] items,
out ulong[] currentPrices,
out ulong[] basePrices)
Gets the dynamic properties from an item in an inventory result set.
public static bool GetResultItemProperty(SteamInventoryResult_t resultHandle,
uint itemIndex,
string propertyName,
out string valueBuffer,
ref uint bufferSize)
Get the items associated with an inventory result handle.
public static bool GetResultItems(SteamInventoryResult_t resultHandle,
SteamItemDetails_t[] items,
ref uint count)
Gets the server time at which the result was generated.
public static DateTime GetResultTimestamp(SteamInventoryResult_t resultHandle)
Grant all potential one-time promotional items to the current user.
public static bool GrantPromoItems(Action<InventoryResult> callback = null)
Triggers an asynchronous load and refresh of item definitions.
public static bool LoadItemDefinitions()
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.
public static void RequestPrices(
Action<SteamInventoryRequestPricesResult_t, bool> callback)
Gets the state of a subset of the current user's inventory and serializes the data.
public static void SerializeItemResultsByID(SteamItemInstanceID_t[] instanceIds,
Action<byte[]> callback)
Start retrieving all items in the current users inventory and serializes the data.
public static void SerializeAllItemResults(Action<byte[]> callback)
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.
public static void StartPurchase(SteamItemDef_t[] items,
uint[] quantities,
Action<SteamInventoryStartPurchaseResult_t, bool> callback)
Transfer items between stacks within a user's inventory.
public static void TransferItemQuantity(SteamItemInstanceID_t source,
uint quantity,
SteamItemInstanceID_t destination,
Action<InventoryResult> callback)
Trigger an item drop if the user has played a long enough period of time.
public static void TriggerItemDrop(SteamItemDef_t item,
Action<InventoryResult> callback)
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.
public static SteamInventoryUpdateHandle_t StartUpdateProperties()
Submits the transaction request to modify dynamic properties on items for the current user. See StartUpdateProperties.
public static void SubmitUpdateProperties(SteamInventoryUpdateHandle_t handle,
Action<InventoryResult> callback)
Removes a dynamic property for the given item.
public static void RemoveProperty(SteamInventoryUpdateHandle_t handle,
SteamItemInstanceID_t item,
string propertyName)
Sets a dynamic property for the given item. Supported value types are strings, boolean, 64 bit integers, and 32 bit floats.
public static void SetProperty(SteamInventoryUpdateHandle_t handle,
SteamItemInstanceID_t item,
string propertyName,
string data)
public static void SetProperty(SteamInventoryUpdateHandle_t handle,
SteamItemInstanceID_t item,
string propertyName,
bool data)
public static void SetProperty(SteamInventoryUpdateHandle_t handle,
SteamItemInstanceID_t item,
string propertyName,
long data)
public static void SetProperty(SteamInventoryUpdateHandle_t handle,
SteamItemInstanceID_t item,
string propertyName,
float data)
Constructs an ItemDetail object based on a native SteamItemDetails_t object and its source result list
public static ItemDetail GetExtendedItemDetail(SteamInventoryResult_t result,
uint index,
SteamItemDetails_t detail)
Methods that impact a user's inventory will typically have a callback that returns a type of Inventory Result. In addition the Item Definitions stored in the active Steam Settings will be updated with the resulting Item Details which be used as a real time view of the current state of the user's inventory.
The Item Definitions 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 Item Definition 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 Add Promo Items or Grant Prmo Items.
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.
API.Inventory.Client.AddPromoItem(item, callback);
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 Add Promo Item. If you want to grant all possible promo items then use Grant Promo Items.
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.
API.Inventory.Client.AddPromoItems(items, callback);
Checks whether an inventory result handle belongs to the specified Steam ID.
This is important when using Deserialize Results, to verify that a remote player is not pretending to have a different user's inventory.
if(API.Inventory.Client.CheckResultSteamID(resultHandle, expectedId))
Debug.Log("Yes");
else
Debug.Log("No");
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.
API.Inventory.Client.ConsumeItem(item, quantity, callback);
Deserializes a result set and verifies the signature bytes.
This call has a potential soft-failure mode where the handle status is set to k_EResultExpired. Get Result Items 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 Get Result Timestamp to ISteamUtils::GetServerRealTime 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 Check Result Steam ID on the result handle when it completes to verify that a remote player is not pretending to have a different user's inventory.
API.Inventory.Client.DeserializeResult(buffer, callback);
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.
API.Inventory.Client.DestroyResult(resultHandle);
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
API.Inventory.Client.ExchangeItems(itemsToGenerate,
quantitiesToGenerate,
instanceToDestroy,
callback);
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.
API.Inventory.Client.GenerateItems(items, quantity, callback);
Start retrieving all items in the current users inventory.
Calls to this function are subject to rate limits and may return cached results if called too frequently. It is suggested that you call this function only when you are about to display the user's full inventory, or if you expect that the inventory may have changed.
API.Inventory.Client.GetAllItems(callback);
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.
API.Inventory.Client.GetEligiblePromoItemDefinitionIDs(user, callback);
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 SteamInventoryDefinitionUpdate_t 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.
API.Inventory.Client.GetItemDefinitionIDs(out SteamItemDef_t[] results);
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.
API.Inventory.Client.GetResultItems(resultHandle, items, ref count);
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.
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: Add Promo Item and Add Promo Items.
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.
API.Inventory.Client.GrantPromoItems(callback);
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.
API.Inventory.Client.TriggerItemDrop(item, callback);
Last modified 1mo ago