Item Definition
Defines a Steam Inventory Item
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!
public class ItemDefinition : ScriptableObject
Represents a Steam Inventory Item of any type. This object contains all the schema data for any possible item. The specifics of each field are defined in Steam's Inventory Schema documentaiton.
When importing items from Steam API note that Valve omits the bundle node from Items of type 'Generator' thus anytime you import items from Valve the "Items" field on generator type items will be empty and must be set manually before you can export them again.
This is a deliberate decision from Valve and has been confirmed it is not a bug it is by design. If you (like us) would like it changed then please submit a support ticket to Valve letting them know that this decision adversly impacts you.
public SteamItemDef_t Id => get;
Returns the item defintion ID.
public List<ItemDetail> Details => get;
public long TotalQuantity => get;
Returns the quantity of this item the user owns, this is the sum of all quanity in each detail.
public string DisplayName => get;
This can only be used if you have called LoadItemDefintions from the Inventory API. It returns the localized name of the item if any.
public bool HasPrice => get;
Indicates rather or not this item has a price ... this will always return false until after the system has fully initalized. Initalization occures on initalization of the API and can take a few seconds.
public Currency.Code CurrencyCode => get;
public string CurrencySymbol => get;
Returns the sting symbol used by the local user's currency.
public ulong CurrentPrice => get;
The price of the item as a whole number e.g. 1 represents the smallest denominator in the user's currency so 100 would represent 100 cents or 1 dolar in USD ... this will always return false until after the system has fully initalized. Initalization occures on initalization of the API and can take a few seconds.
No price found if this returns 0.
public ulong BasePrice => get;
The base price of the item as a whole number e.g. 1 represents the smallest denominator in the user's currency so 100 would represent 100 cents or 1 dolar in USD ... this will always return false until after the system has fully initalized. Initalization occures on initalization of the API and can take a few seconds.
No price found if this returns 0.
public InventoryItemType Type => get;
public string Name => get;
Gets the simple name of the item as defined in your schema. If you need the language based name see DisplayName.
public string Description => get;
Gets the simple description as defined in your schema. If you need the langauge based name you will need to fetch item defintions and get the description property.
public string DisplayType => get;
Gets the simple display type as defined in your schema. If you need the langauge based name you will need to fetch item defintions and get the description property.
public Bundle.Entry[] Bundle => get;
Gets the array of Bundle.Entry objects defining the contents of this bundle if any
public AppId_t[] PromoRuleOwns => get;
Returns the list of app ids that the user must own for this item to be droped as a promo item.
public string[] PromoRuleAchievemets => get;
Returns the list of achievment IDs that the user must have achieved for this item to be droped as a promo item.
public PromoRule.PlayedEntry[] PromoRulePlayed => get;
Returns the list of player entries ... indicates the app ID and length of time in min that the player must have played before this item can be droped as a promo.
public string DropStartTime => get;
The item drop start time if this is a promo item.
public ExchangeRecipe[] Recipies => get;
Returns the array of exchange recipies for this item if any
public Color BackgroundColor => get;
The background color used in the Steam Store and marketplace entries if any
public Color NameColor => get;
The name color used in the Steam Store and marketplace entries if any
public string IconUrl => get;
The icon URL for this item if any, this is used by the Steam Store and marketplace entries.
public string IconUrlLarge => get;
The icon URL for this item if any, this is used by the Steam Store and marketplace entries.
public bool Marketable => get;
Can this item be sold by players on the Steam marketplace.
public bool Tradable => get;
Can this item be traded between players via the Steam Inventory system.
public ItemTag[] Tags;=> get
The set of tags related to this item.
public ItemDefinition[] TagGenerators => get;
The array of items used as tag generators related to this item
public TagGeneratorValue[] TagGeneratorvalueArray => get;
The array of values that can be generated for this item
public string[] StoreTags => get;
Returns the array of store tags assigned to this item
public string[] StoreImages => get;
Returns the array of store images assigned to this item
public bool Hidden => get;
Is this item hidden from the user's inventory
public bool StoreHidden => get;
Is this item hidden from the store
public bool AddPromoItem(callback);
Grants the item in a one-time promotional to the local user
public ConsumeOrder[] GetConsumeOrders(quantity);
Creates ConsumeOrders which can be used with the Consume method to consume instances of this item if available. This is only needed when consuming more than 1 instance at a time.
public bool Consume(callback);
public bool Consume(order, callback);
Consume 1 or many instances of this item if the player owns them
This method checks if a user can exchange for this item using a specific recipie. You can get the list of available recipies from the ItemDefinition.item_exchange or you can create the recipie manually if you know the items needed.
This will always return false if the recipie uses tags in any of the required items
public bool CanExchange(ExchangeRecipe, out List<ExchangeEntry>);
public bool GetExchangeEntry(quantity, out entries);
Gets a set of ExchangeEntry objects that match the quantity provided if the player's owns them. This can be used with Exchange to "craft" 1 item by exchanging a set of other items.
Exchanges a collection of ExchangeEntry for this item. The Valve backend will validate and insure that this set of ExchangeEntries satisifies one of the configured excahnge recipies for this item.
public void Exchange(IEnumerable<ExchangeEntry>, callback);
Exchanges a set of ExchangeEntry objects to create a new instance of this item.
Can only be used by developers for development testing
public void GenerateItem(callback);
Only available to developers, this simply creates a new instance of this item
public void StartPurchase(callback);
If the item is confugred correctly for store purchases this will open the store loading the cart with the indicated number of items to be purcahsed.
public string CurrentPriceString();
This reurnts the culture formated string for the currency assuming it is base 100. This works well for curencies such as USD, EUR, GBP or anything with a "cent" concept but will not work well for currencies that always use whole numbers such as the Yen.
public string BasePriceString();
This reurnts the culture formated string for the currency assuming it is base 100. This works well for curencies such as USD, EUR, GBP or anything with a "cent" concept but will not work well for currencies that always use whole numbers such as the Yen.
public void TriggerDrop(callback);
Triggers a play time drop assuming the player has played long enough and the item is a playtime generator item.
First you need to make sure you have loaded the user's inventory. This is probably already done for you in that the Heathen Steamworks Behaviour will call GetAllItems when it first initalizes however its important to understand that Steam Inventory can change from many different points of view both in and out of game so to be sure you have the latest we do sugest you refresh your local view of the user's inventory jsut before you preform any sinsative tasks.
Once your happy that the local state is fresh enough for your purposes you can check for ownership of an item by simply checking its TotalQuantity
if(item.TotalQuantity > 0)
Debug.Log("The user owns " + item.TotalQuanity + " of this item.");
else
Debug.Log("The user does not own any of this item.");
You can refresh the local state of items at any time, keep in mind Valve may rate limit this and simply return the most recent cashe value.
To refresh the full inventory
API.Inventory.Client.GetAllItems(callback);
The callback is optional and can be used to know when the results comeback. The Heathen SteamSettings object will update the state of all known ItemDefinition objects so its not nessisary to process the resulting InventoryResults object unless you want to check for something specific.
You can also choose to refresh a specific set of item instances
API.Inventory.Client.GetItemsByID(instances, callback);
As with GetAllItems the callback is optional and can be used to check the specifics of the resullting data or simply to know when the request has been completed.
Short cut to the Add Promo Item of the API.Inventory interface.
item.AddPromoItem(callback);
You can use the Item Definition to consume 1 or more instances of the item with simple method calls.
This is the simplest and most common approch, it assumes you are consuming a single instance of the item.
item.Consume(callback);
When consuming multiple instnaces we need to first get a set of orders.
Steam Inventory Items may have zero (0) or many item details which will consist of zero (0) or many instances each. its simplest to think of an Item Detail as a stack of that type of item. Each stack may have 0 or many items of that type in it. When consuming we need to indicate the stack to consume from and how many to consume from that stack. That is what the GetConsumeOrders method does, it provides a refernce to which stacks should consume how many to result in the total you indicated.
Example:
- instance A = 4 quantity
- instance B = 0 quantity
- instance C = 2 quantity
- instance D = 3 quantity
In this case the user has a total of 9 of this item spread across 4 insances. If you requested to consume 5 of this item you would get 2 orders back.
- 1.Order 1 would contain 4 from instance A
- 2.Order 2 would contain 1 from instance C
Once you had the orders its up to you to call the Consume method on the order.
var orders = item.GetConsumeOrders(quantity);
foreach(var order in orders)
{
item.Consume(order, callback);
}
To exchange some items for another item, the item you wish to exchange for must define the recipie of items in its Item Definition as upoloaded to Steam's portal.
The item recipie is how this is able to run client side, since the item definition defines what exchanges are valid, and the Steam backend controls what items the player owns then Steam can assuradly confirm that a recipie is valid.
An exchange, exchanges some set of items for some other item. Its most simple to think of this as crafting, you provide some set of ingrediants and the result is some single item. When you call Exchange on an item you provide a set of items and if the process is succesfult you will recieve evidence of a new instnace of this item in the player's inventory.
To start the proces you must first identify the specifc item instnaces to be consumed. How you generate ExchangeEntry objects for an item depends on the specific needs of the recipie. In most cases a recipie will require a number of a specific item type, in this case you can simply call
GetExchangeEntry on the specific item.if(itemToExchange.GetExchangeEntry(quantity, out entries))
{
// Enough where found
}
else
{
// Not enough of this item available
}
Once you have the collection of ExchangeEntries you can pass them into the item you wish to exchange them for.
item.Exchange(exchangeEntries, callback);
Exchange chest for bundle
if(chest.GetExchangeEntry(1, out EchangeEntry[] entries))
{
bundle.Exchange(entries, (result, error) => {
Debug.Log("result contains the items we gave the player");
});
}
else
{
Debug.Log("The player didn't have any chests");
}
Exchange for a particular recipie;
In this use case we pick a particular recipie for the item we want to exchange ... lets say we want to exchange 10 gold and 1 gem for a random item. Lets assue our random item is defined as an item generator named randomLoot;
Lets allso assume that the recipie to do this is the first recipie in our randomLoot item.
var recipie = randomLoot.item_exchange.recipie[0];
if(randomLoot.CanExchange(recipie, out List<ExchangeEntry> entries))
{
//This returns true if the local user owns the required items
//We can use the output entries to execute the exchange
randomLoot.Exchange(entries, (responce) =>
{
if(responce.result == EResult.k_EResultOK)
Debug.Log("Complete");
else
Debug.LogWarning("Something went wrong ... check the result");
});
}
Exchange 10 iron and 50 gold for 1 ironSword;
In this example we will manually build out the exchange entries checking each one as we go.
if(iron.GetExchangeEntry(10, out EchangeEntry[] ironEntries))
{
if(gold.GetExcahngeEntry(50, out ExchangeEntry[] goldEntries))
{
var recipie = new List<ExchangeEntry>();
recipie.Add(ironEntries);
recipie.Add(goldEntries);
ironSword.Exchange(recipie, (result, error) => {
Debug.Log("results contains the sword if any");
});
}
else
{
Debug.Log("Not enough gold");
}
}
else
{
Debug.Log("Not enough iron");
}
From the Client API this is only avialable to developers of this app for development testing. If you need to do this in production for a non-developer then you need to use the Web API.
Grants the player this item, this is used only by developers and is meant for testing only.
item.GenerateItem(callback);
To generate multiple instances of this item you can use
item.GenerateItem(count, callback);
Only items that have a valid price or price category and are not set to store hidden or hidden in general can be called to start purchase.
You can use API.Inventory.Client.StartPurchase to start a purchase on a complex cart of items. This example on the Item Defintion is for starting a purchase of a single item or some quantity of a signle item.
item.StartPurchase(callback);
or
item.StartPurchse(count, callback);
or
API.Inventory.Client.StartPurchase(items, itemQuantities, callback);
Last modified 4mo ago