Functions | Inventory

Here is a list of all the functions available in the GodotSteam module. The descriptions are pulled from the official Steamworks SDK documentation with modifications made to fit GodotSteam's implementation of the functions. Naturally, any GodotSteam-specific functions will be noted as such.


addPromoItem( int item ) addPromoItem( uint32 item )

  • 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 app IDs 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.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

addPromoItems( PoolIntArray items )

  • 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 app ID's 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.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

checkResultSteamID( int steam_id_expected, int this_inventory_handle = 0 ) checkResultSteamID( uint64_t steam_id_expected, int32 this_inventory_handle = 0 )

  • Checks whether an inventory result handle belongs to the specified Steam ID.
  • This is important when using deserializeResult, to verify that a remote player is not pretending to have a different user's inventory.
  • Note: If the argument this_inventory_handle is omitted, GodotSteam will use the internally stored ID.
  • Returns a bool.

consumeItem( int item_consume, int quantity ) consumeItem( uint64_t item_consume, uint32 quantity )

  • 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.
  • Note: You must call destroyResult on the provided inventory result when you are done with it.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

deserializeResult( PoolIntArray buffer )

  • Deserializes a result set and verifies the signature bytes.
  • This call has a potential soft-failure mode where the handle status is set to 27. getResultItems 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 getResultTimestamp to 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 checkResultSteamID on the result handle when it completes to verify that a remote player is not pretending to have a different user's inventory.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

destroyResult( int this_inventory_handle = 0 ) destroyResult( int32 this_inventory_handle = 0 )

  • Destroys a result handle and frees all associated memory.
  • Note: If the argument this_inventory_handle is omitted, GodotSteam will use the internally stored ID.
  • Returns nothing; void.

exchangeItems( PoolIntArray output_items, int output_quantity, int input_items, int input_quantity ) exchangeItems( PoolIntArray output_items, uint32 output_quantity, uint64_t input_items, uint32 input_quantity )

  • 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.
  • Will allow the item to be exchanged for either one #101 and one #102, five #103s or three #104s and three #105s. See the Steam Inventory Schema documentation for more details.
  • Note: You must call destroyResult on the provided inventory result when you are done with it.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

generateItems( PoolIntArray items, int quantity ) generateItems( PoolIntArray items, uint32 quantity )

  • 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.
  • You can pass in an array of items, identified by their item defintion int's and optionally a second array of corresponding quantities for each item. The length of these arrays must match!
  • Note: You must call destroyResult on the provided inventory result when you are done with it.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

getAllItems()

  • Start retrieving all items in the current users inventory.
  • Note: 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.
  • Note: You must call destroyResult on the provided inventory result when you are done with it.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

getItemDefinitionProperty( int definition, string name ) getItemDefinitionProperty( uint32 definition, string name )

  • Gets a string property from the specified item definition. 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 getCurrentGameLanguage). Property names are always ASCII alphanumeric and underscores.
  • Pass in NULL for name to get a comma-separated list of available property names.
  • Note: Call loadItemDefinitions first, to ensure that items are ready to be used before calling getItemDefinitionProperty.
  • Returns a string.

getItemsByID( int id_array, int count ) getItemsByID( uint64_t id_array, uint32 count )

  • Gets the state of a subset of the current user's inventory.
  • The subset is specified by an array of item instance IDs.
  • The results from this call can be serialized using serializeResult and passed to other players to "prove" that the current user owns specific items, without exposing the user's entire inventory. For example, you could call this with the IDs of the user's currently equipped items and serialize this to a buffer, and then transmit this buffer to other players upon joining a game.
  • Note: You must call destroyResult on the provided inventory result when you are done with it.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

getItemPrice( int definition ) getItemPrice( uint32 definition )

  • After a successful call to requestPrices, you can call this method to get the pricing for a specific item definition.
  • Returns an int. Returns an uint64_t.

getItemsWithPrices( int length ) getItemsWithPrices( uint32 length )

  • After a successful call to requestPrices, you can call this method to get all the pricing for applicable item definitions. Use the result of getNumItemsWithPrices as the the size of the arrays that you pass in.
  • Returns an array:
    • price_group (dictionary)
      • item (int)
      • price (int)
      • base_prices (int)
      • item (int32)
      • price (uint64_t)
      • base_prices (uint64_t)

getNumItemsWithPrices()

  • After a successful call to requestPrices, this will return the number of item definitions with valid pricing.
  • Returns an int. Returns an uint32.

getResultItemProperty( int index, string name, int this_inventory_handle ) getResultItemProperty( uint32 index, string name, int32 this_inventory_handle )

  • Gets the dynamic properties from an item in an inventory result set.
  • Property names are always composed of ASCII letters, numbers, and/or underscores.
  • If the results do not fit in the given buffer, partial results may be copied.
  • Note: If the argument this_inventory_handle is omitted, GodotSteam will use the internally stored ID.
  • Returns a string.

getResultItems( int this_inventory_handle ) getResultItems( int32 this_inventory_handle )

  • Get the items associated with an inventory result handle.
  • Note: If the argument this_inventory_handle is omitted, GodotSteam will use the internally stored ID.
  • Returns an array containing int item ID's. Returns an array containing uint64_t item ID's.

getResultStatus( int this_inventory_handle ) getResultStatus( int32 this_inventory_handle )

  • Find out the status of an asynchronous inventory result handle.
  • This is a polling equivalent to registering a callback function for inventory_result_ready.
  • Note: If the argument this_inventory_handle is omitted, GodotSteam will use the internally stored ID.
  • Returns a string.

getResultTimestamp( int this_inventory_handle ) getResultTimestamp( int32 this_inventory_handle )

  • Gets the server time at which the result was generated.
  • You can compare this value against getServerRealTime to determine the age of the result.
  • Note: If the argument this_inventory_handle is omitted, GodotSteam will use the internally stored ID.
  • Returns an int. Returns an uint32.

grantPromoItems()

  • 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: addPromoItem and addPromoItems.
  • Any items that can be granted must have a "promo" attribute in their itemdef. That promo item list a set of app ID's 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.
  • Note: You must call destroyResult on the provided inventory result when you are done with it.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

loadItemDefinitions()

  • Triggers an asynchronous load and refresh of item definitions.
  • Item definitions are a mapping of "definition IDs" (integers between 1 and 999999999) to a set of string properties. Some of these properties are required to display items on the Steam community web site. Other properties can be defined by applications. There is no reason to call this function if your game hardcoded the numeric definition IDs (e.g. purple face mask = 20, blue weapon mod = 55) and does not allow for adding new item types without a client patch.
  • Triggers a inventory_definition_update callback.
  • Returns a bool.

requestEligiblePromoItemDefinitionsIDs( int steam_id ) requestEligiblePromoItemDefinitionsIDs( uint64_t steam_id )

  • 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.
  • After calling this function you need to call getEligiblePromoItemDefinitionIDs to get the actual item definition ids.
  • Triggers a inventory_eligible_promo_item callback.
  • Returns nothing; void.

requestPrices()

  • Request prices for all item definitions that can be purchased in the user's local currency. A inventory_request_prices_result 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.
  • Triggers a inventory_request_prices_result callback.
  • Returns nothing; void.

serializeResult( int this_inventory_handle ) serializeResult( int32 this_inventory_handle )

  • Serialized result sets contain a short signature which can't be forged or replayed across different game sessions.
  • A result set can be serialized on the local client, transmitted to other players via your game networking, and deserialized by the remote players. This is a secure way of preventing hackers from lying about posessing rare/high-value items. Serializes a result set with signature bytes to an output buffer. The size of a serialized result depends on the number items which are being serialized. When securely transmitting items to other players, it is recommended to use getItemsByID first to create a minimal result set.
  • Note: If the argument this_inventory_handle is omitted, GodotSteam will use the internally stored ID.
  • Results have a built-in timestamp which will be considered "expired" after an hour has elapsed. See deserializeResult for expiration handling.
  • Returns a bool.

startPurchase( PoolIntArray items, int quantity ) startPurchase( PoolIntArray items, uint32 quantity )

  • 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.
  • If the purchase process was started successfully, then order_id and transaction_id will be valid in the inventory_start_purchase_result call result.
  • If the user authorizes the transaction and completes the purchase, then the callback inventory_result_ready will be triggered and you can then retrieve what new items the user has acquired.
  • Note: You must call destroyResult on the inventory result for when you are done with it.
  • Triggers a inventory_start_purchase_result callback.
  • Returns nothing; void.

transferItemQuantity( int item_id, int quantity, int item_destination, bool split ) transferItemQuantity( uint64_t item_id, uint32 quantity, uint64_t item_destination, bool split )

  • Transfer items between stacks within a user's inventory.
  • This can be used to stack, split, and moving items. The source and destination items must have the same itemdef id. To move items onto a destination stack specify the source, the quantity to move, and the destination item id. To split an existing stack, pass -1 into item_destination. A new item stack will be generated with the requested quantity.
  • Note: Tradability/marketability restrictions are copied along with transferred items. The destination stack receives the latest tradability/marketability date of any item in its composition.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

triggerItemDrop( int definition ) triggerItemDrop( uint32 definition )

  • 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.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

startUpdateProperties()

  • 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 inventory_result_ready callback will be fired with the results of the operation.
  • Returns nothing; void.

submitUpdateProperties()

  • Submits the transaction request to modify dynamic properties on items for the current user. See startUpdateProperties.
  • Note: You must call destroyResult on the provided inventory result for when you are done with it.
  • Returns an int as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle. Returns an int32 as the inventory handle, which is also stored internally. It will overwrite any previously stored inventory handle.

removeProperty( int item_id, string name, int this_inventory_update_handle ) removeProperty( uint64_t item_id, string name, int32 this_inventory_update_handle )

  • Removes a dynamic property for the given item.
  • Note: If the argument this_inventory_update_handle is omitted, GodotSteam will use the internally stored ID. Also note this different from this_inventory_handle and is stored separately.
  • Returns a bool.

setPropertyString( int item_id, string name, string value, int this_inventory_update_handle ) setPropertyString( uint64_t item_id, string name, string value, int32 this_inventory_update_handle )

  • Sets a dynamic property for the given item. Supported value types are strings.
  • Note: If the argument this_inventory_update_handle is omitted, GodotSteam will use the internally stored ID. Also note this different from this_inventory_handle and is stored separately.
  • Returns a bool.

setPropertyBool( int item_id, string name, bool value, int this_inventory_update_handle ) setPropertyBool( uint64_t item_id, string name, bool value, int32 this_inventory_update_handle )

  • Sets a dynamic property for the given item. Supported value types are boolean.
  • Note: If the argument this_inventory_update_handle is omitted, GodotSteam will use the internally stored ID. Also note this different from this_inventory_handle and is stored separately.
  • Returns a bool.

setPropertyInt( int item_id, string name, int value, int this_inventory_update_handle ) setPropertyInt( uint64_t item_id, string name, uint64_t value, int32 this_inventory_update_handle )

  • Sets a dynamic property for the given item. Supported value types are 64 bit integers.
  • Note: If the argument this_inventory_update_handle is omitted, GodotSteam will use the internally stored ID. Also note this different from this_inventory_handle and is stored separately.
  • Returns a bool.

setPropertyFloat( int item_id, string name, float value, int this_inventory_update_handle ) setPropertyFloat( uint64_t item_id, string name, float value, int32 this_inventory_update_handle )

  • Sets a dynamic property for the given item. Supported value types are 32 bit floats.
  • Note: If the argument this_inventory_update_handle is omitted, GodotSteam will use the internally stored ID. Also note this different from this_inventory_handle and is stored separately.
  • Returns a bool.