Modding:Items

← Index

This page explains how the game stores and parses item data. This is an advanced guide for mod developers.

Introduction

Overview

As of Stardew Valley 1.6, there are a few important features of Items in the game.

1. Each item as a string ID (ItemId) and a globally-unique string ID (QualifiedItemId). The QualifiedItemId is auto-generated by prefixing the ItemId with the item type identifier.

   For legacy reasons, the ItemId for vanilla items may not be globally unique. For example, Pufferfish (object 128) and Mushroom Box (bigcraftable 128) both have ItemId: 128. They can be distinguished by their QualifiedItemId, which are (O)128 and (BC)128 respectively.

2. Each item type has an item data definition in the game code which tells the game how to handle it. C# mods can add or edit definitions. Each definition has a unique prefix which is used in the qualified item IDs. The vanilla types are bigcraftables ((BC)), boots ((B)), farmhouse flooring ((FL)), furniture ((F)), hats ((H)), objects ((O)), pants ((P)), shirts ((S)), tools ((T)), wallpaper ((WP)), and weapons ((W)).
3. Custom items can now provide their own item texture, specified in a new field in the item data assets (see below). The item's ParentSheetIndex field is the index within that texture.

In other words, the four important fields for items are:

name	type	description
ItemId	string	A unique string ID for this item which should be globally unique (but may not be for existing vanilla items for backwards compatibility). For example, 128 (vanilla item) or Example.ModId_Watermelon (custom item).
QualifiedItemId	string	A globally unique item key, like (O)128 for a vanilla item or (O)Example.ModId_Watermelon for a custom one. This is auto-generated from the TypeDefinitionId and ItemId fields.
ParentSheetIndex	int	The item's sprite index within its spritesheet.
TypeDefinitionId	string	The ID for the data definition which defines the item, like (O) for an object. You can use ItemRegistry.type_* constants with this field: if (item.TypeDefinitionId == ItemRegistry.type_object) ...

Item references

Item references throughout the game code now use the ItemId instead of the ParentSheetIndex. Since the ItemId is identical to the index for existing vanilla items, most data assets are unaffected by this change. For example, here's from Data/NPCGiftTastes with one custom item:

"Universal_Like": "-2 -7 -26 -75 -80 72 395 613 634 635 636 637 638 724 459 Example.ModID_watermelon"

Unless otherwise noted, unqualified item IDs will produce objects. Some assets let you override that by specifying a QualifiedItemId value instead. For example, you can add (O)128 to the gift taste list to explicitly add for an object. Here's a partial list of data assets and their supported item ID formats:

data asset	item ID format
Data/CraftingRecipes Data/CookingRecipes	Ingredients: both supported. Output: set field 2 to the unqualified item ID, and field 3 to one of true (bigcraftable) or false (object).
Data/FruitTrees	Fruit: both supported. Sapling: unqualified only.
Data/NPCGiftTastes	Both supported, but only (O) items can be gifted.

Item types

These are the item types for which custom items can added/edited:

item type	type identifier	data asset
Big craftables	(BC)	Data/BigCraftables Each item can set a custom texture name in the Texture field, and sprite index in the SpriteIndex field. The default texture is TileSheets/Craftables.
Boots	(B)	Data/Boots Each item can set a custom texture name in fields 9 (item) and 7 (shoe color), and sprite index in fields 8 (item) and 5 (shoe color). The default textures are Maps/springobjects (item) and Characters/Farmer/shoeColors (shoe color).
Crops	not technically an item type	Data/Crops Each crop can set a custom texture name and sprite index. The default texture is TileSheets/crops.
Fish (in fish tanks)	not technically an item type	Data/AquariumFish Each fish can set a custom aquarium texture name in field 6, and sprite index in field 0. The default texture is LooseSprites/AquariumFish.
Furniture	(F)	Data/Furniture Each item can set a custom texture name in field 9, and sprite index in field 8. The default texture is TileSheets/furniture.
Fruit Trees	not technically an item type	Data/FruitTrees Each fruit tree can set a custom texture name and sprite index. The default texture is TileSheets/fruitTrees.
Hats	(H)	Data/Hats Each item can set a custom texture name in field 7, and sprite index in field 6. The default texture is Characters/Farmer/hats.
Objects	(O)	Data/Objects Each item can set a custom texture name in the Texture field, and sprite index in the SpriteIndex field. The default texture is Maps/springobjects.
Pants	(P)	Data/pantsData Each item can set a custom texture name in the Texture field, and sprite index in the SpriteIndex field. The default texture is Characters/Farmer/pants.
Shirts	(S)	Data/shirtData Each item can set a custom texture name in the Texture field, and sprite index in the SpriteIndex field. The default texture is Characters/Farmer/shirts. Shirt textures must be exactly 256 pixels wide, divided into two halves: the left half for the shirt sprites, and the right half for any dye masks. The remaining space can be left blank if needed. sprites dye masks /-----------\ /-----------\ ┌────────────────────────────────┐ │ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │ │ │ 0 ││ 1 ││ 2 ││ a ││ b ││ c │ │ │ └───┘└───┘└───┘└───┘└───┘└───┘ │ │ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │ │ │ 3 ││ 4 ││ 5 ││ d ││ e ││ f │ │ │ └───┘└───┘└───┘└───┘└───┘└───┘ │ └────────────────────────────────┘
Tools	(T)	Data/Tools Each item can set a custom texture name in the Texture field, and sprite index in the SpriteIndex field. The vanilla tools use the TileSheets/Tools texture.
Wallpaper & flooring	(WP) and (FL)	Data/AdditionalWallpaperFlooring See format docs.
Weapons	(W)	Data/Weapons

When resolving an unqualified item ID like 128, the game will get the first item type for which it exists in this order: object, big craftable, furniture, weapon, boots, hat, pants, shirt, tool, wallpaper, and floorpaper.

For each item type, the game has two files in its Content folder (which can be unpacked for editing):

• a data asset for the text data for its items (names, descriptions, prices, etc);
• and a spritesheet for the in-game item icons.

Each item has a ParentSheetIndex field which is its position in the item type's spritesheet, starting at 0 in the top-left and incrementing by one as you move across and then down. For example, hat #0 is the first sprite in Characters/Farmer/hats. The ParentSheetIndex is also used to identify the item itself; since spritesheet indexes aren't unique (e.g., there's both a hat #10 and object #10), code needs to check the type too like item is Weapon weapon && weapon.ParentSheetIndex == 4.

Get a list of items

With SMAPI installed, you can run the list_items console command in-game to view/search items and their IDs.

Define a custom item

You can define custom items for most vanilla item types using only Content Patcher or SMAPI's content API.

For example, this content pack adds a new Pufferchick item with a custom image, custom gift tastes, and a custom crop that produces it. Note that item references in other data assets like Data/Crops and Data/NPCGiftTastes use the item ID.

{
    "Format": "2.8.0",
    "Changes": [
        // add item
        {
            "Action": "EditData",
            "Target": "Data/Objects",
            "Entries": {
                "{{ModId}}_Pufferchick": {
                    "Name": "{{ModId}}_Pufferchick", // best practice to match the ID, since it's sometimes used as an alternate ID (e.g. in Data/CraftingRecipes)
                    "Displayname": "Pufferchick",
                    "Description": "An example object.",
                    "Type": "Seeds",
                    "Category": -74,
                    "Price": 1200,

                    "Texture": "Mods/{{ModId}}/Objects",
                    "SpriteIndex": 0
                }
            }
        },

        // add gift tastes
        {
            "Action": "EditData",
            "Target": "Data/NPCGiftTastes",
            "TextOperations": [
                {
                    "Operation": "Append",
                    "Target": ["Entries", "Universal_Love"],
                    "Value": "{{ModId}}_Pufferchick",
                    "Delimiter": " " // if there are already values, add a space between them and the new one
                }
            ]
        },

        // add crop (Pufferchick is both seed and produce, like coffee beans)
        {
            "Action": "EditData",
            "Target": "Data/Crops",
            "Entries": {
                "{{ModId}}_Pufferchick": {
                    "Seasons": [ "spring", "summer", "fall" ],
                    "DaysInPhase": [ 1, 1, 1, 1, 1 ],
                    "HarvestItemId": "{{ModId}}_Pufferchick",

                    "Texture": "Mods/{{ModId}}/Crops",
                    "SpriteIndex": 0
                }
            }
        },

        // add item + crop images
        {
            "Action": "Load",
            "Target": "Mods/{{ModId}}/Crops, Mods/{{ModId}}/Objects",
            "FromFile": "assets/{{TargetWithoutPath}}.png" // assets/Crops.png, assets/Objects.png
        }
    ]
}

Most item data assets work just like Data/Objects. See also specific info for custom fruit trees, custom tools, and melee weapons.

Error items

Prior to 1.6, in-game items with no underlying data (e.g. because you removed the mod which adds them) would previously cause issues like invisible items, errors, and crashes. This was partly mitigated by the bundled Error Handler mod.

Stardew Valley 1.6 added comprehensive handling for such items. They'll be shown with a 🛇 sprite in inventory UIs and in-game, the name Error Item, and a description which indicates the missing item ID for troubleshooting.

For C# mods

Compare items

Since Item.QualifiedItemId is globally unique, it can be used to simplify comparing items. For example:

old code	new code
item.ParentSheetIndex == 128	item.QualifiedItemId == "(O)128"
IsNormalObjectAtParentSheetIndex(item, 128)	item.QualifiedItemId == "(O)128"
!item.bigCraftable && item.ParentSheetIndex == 128	item.QualifiedItemId == "(O)128"
item is Boots && item.ParentSheetIndex == 505	item.QualifiedItemId == "(B)505"

You can also use ItemRegistry.QualifyItemId to convert any item ID into a qualified one (if it's valid), and ItemRegistry.HasItemId to check if an item has a qualified or unqualified item ID.

Note that flavored item don't have their own ID. For example, Blueberry Wine and Wine are both (O)348. This affects flavored jellies, juices, pickles, and wines. In those cases you should still compare their separate fields like preservedParentSheetIndex (which actually contains the preserved item's ItemId, not its ParentSheetIndex).

Construct items

When constructing items, specify the item's ItemId (not QualifiedItemId). For example:

new Object("128", 1);                      // vanilla item
new Object("Example.ModId_Watermelon", 1); // custom item

You can use a utility method to construct items from their QualifiedItemId:

Item item = ItemRegistry.Create("(B)505"); // Rubber Boots

Define custom item types

You can implement IItemDataDefinition for your own item type, and call ItemRegistry.AddTypeDefinition to register it. This provides all the logic needed by the game to handle the item type: where to get item data, how to draw them, etc. This is extremely specialized, and multiplayer compatibility is unknown. Most mods should add custom items within the existing types instead.

New Is* methods

1.6 added some StardewValley.Object methods to handle custom items in a generic way (and to let mods patch the logic):

method	effect
object.IsBar()	Whether the item is a copper bar, iron bar, gold bar, iridium bar, or radioactive bar.
object.IsBreakableStone()	Whether the item is a stone debris item which can be broken by a pickaxe.
object.IsFence()	Whether the item is a fence.
object.IsFruitTreeSapling()	Whether the item is a fruit tree sapling. This checks the Data\fruitTrees keys, so it works with custom fruit trees too.
object.IsHeldOverHead()	Whether the player is shown holding up the item when it's selected in their toolbar. Default true (except for furniture).
object.IsIncubator()	Whether the item can incubate farm animal eggs when placed in a building.
object.IsTapper()	Whether the item is a tapper or heavy tapper.
object.IsTeaSapling()	Whether the item is a tea sapling.
object.IsTwig()	Whethere the item is a twig debris item.
object.IsWeeds()	Whether the item is a weed debris item.

Work with item metadata

1.6 added an ItemRegistry API for working with the new item system. Some of the provided methods are:

method	effect
ItemRegistry.Create	Create an item from its item ID (qualified or unqualified). If the ID doesn't match a real item, the optional allowNull parameter indicates whether to return null or an Error Item. For example: Item item = ItemRegistry.Create("(B)505"); // Rubber Boots You can also get a specific value type instead of Item if needed. This will throw a descriptive exception if the type isn't compatible (e.g. you try to convert furniture to boots). Boots item = ItemRegistry.Create<Boots>("(B)505"); // Rubber Boots
ItemRegistry.Exists	Get whether a qualified or unqualified item ID matches an existing item. For example: bool pufferfishExist = ItemRegistry.Exists("(O)128");
ItemRegistry.IsQualifiedId	Get whether the given item ID is qualified with the type prefix (like (O)128 instead of 128).
ItemRegistry.QualifyItemId	Get the unique qualified item ID given an unqualified or qualified one. For example: string qualifiedId = ItemRegistry.QualifyItemId("128"); // returns (O)128
ItemRegistry.GetMetadata	This lets you get high-level info about an item: // get info about Rubber Boots ItemMetadata info = ItemRegistry.GetMetadata("(B)505"); // get item ID info $"The item has unqualified ID {info.LocalId}, qualified ID {info.QualifiedId}, and is defined by the {info.TypeIdentifier} item data definition."; // does the item exist in the data files? bool exists = info.Exists(); And get common parsed item data: // get parsed info ParsedItemData data = info.GetParsedData(); $"The internal name is {data.InternalName}, translated name {data.DisplayName}, description {data.Description}, etc."; // draw an item sprite Texture2D texture = data.GetTexture(); Rectangle sourceRect = data.GetSourceRect(); spriteBatch.Draw(texture, Vector2.Zero, sourceRect, Color.White); And create an item: Item item = metadata.CreateItem(); And get the type definition (note that this is very specialized, and you should usually use ItemRegistry instead to benefit from its caching and optimizations): IItemDataDefinition typeDefinition = info.GetTypeDefinition();
ItemRegistry.ResolveMetadata	Equivalent to ItemRegistry.GetMetadata, except that it'll return null if the item doesn't exist.
ItemRegistry.GetData	Get the parsed data about an item, or null if the item doesn't exist. This is a shortcut for ItemRegistry.ResolveMetadata(id)?.GetParsedData(); see the previous method for info on the parsed data.
ItemRegistry.GetDataOrErrorItem	Equivalent to ItemRegistry.GetData, except that it'll return info for an Error Item if the item doesn't exist (e.g. for drawing in inventory).
ItemRegistry.GetErrorItemName	Get a translated Error Item label.

Common data

Quality

Each item has a quality level which (depending on the item type) may affect its price, health boost, etc. The valid qualities are:

quality	value	constant
normal	0	Object.lowQuality
silver	1	Object.medQuality
gold	2	Object.highQuality
iridium	4	Object.bestQuality

Categories

Each item also has a category (represented by a negative integer). In code, you can get an item's category value from item.Category, and its translated name from item.getCategoryName(). Here are the valid categories:

value	internal constant	context tag	English translation	Properties
-2	Object.GemCategory	category_gem	Mineral	Affected by Gemologist profession
-4	Object.FishCategory	category_fish	Fish	Affected by Fisher and Angler professions
-5	Object.EggCategory	category_egg	Animal Product	Affected by Rancher profession, can be used in a slingshot
-6	Object.MilkCategory	category_milk	Animal Product	Affected by Rancher profession
-7	Object.CookingCategory	category_cooking	Cooking
-8	Object.CraftingCategory	category_crafting	Crafting	Is Placeable
-9	Object.BigCraftableCategory	category_big_craftable		Is Placeable
-12	Object.mineralsCategory	category_minerals	Mineral	Affected by Gemologist profession
-14	Object.meatCategory	category_meat	Animal Product
-15	Object.metalResources	category_metal_resources	Resource
-16	Object.buildingResources	category_building_resources	Resource
-17	Object.sellAtPierres	category_sell_at_pierres
-18	Object.sellAtPierresAndMarnies	category_sell_at_pierres_and_marnies	Animal Product	Affected by Rancher profession
-19	Object.fertilizerCategory	category_fertilizer	Fertilizer	Is Placeable, is always passable
-20	Object.junkCategory	category_junk	Trash
-21	Object.baitCategory	category_bait	Bait	Can be attached to a fishing rod
-22	Object.tackleCategory	category_tackle	Fishing Tackle	Can be attached to a fishing rod, cannot stack
-23	Object.sellAtFishShopCategory	category_sell_at_fish_shop
-24	Object.furnitureCategory	category_furniture	Decor
-25	Object.ingredientsCategory	category_ingredients	Cooking
-26	Object.artisanGoodsCategory	category_artisan_goods	Artisan Goods	Affected by Artisan profession
-27	Object.syrupCategory	category_syrup	Artisan Goods	Affected by Tapper profession
-28	Object.monsterLootCategory	category_monster_loot	Monster Loot
-29	Object.equipmentCategory	category_equipment
-74	Object.SeedsCategory	category_seeds	Seed	Is Placeable, is always passable
-75	Object.VegetableCategory	category_vegetable	Vegetable	Affected by Tiller profession, can be used in a slingshot
-79	Object.FruitsCategory	category_fruits	Fruit	Affected by Tiller profession (if not foraged), can be used in a slingshot
-80	Object.flowersCategory	category_flowers	Flower	Affected by Tiller profession
-81	Object.GreensCategory	category_greens	Forage
-95	Object.hatCategory	category_hat
-96	Object.ringCategory	category_ring
-97	Object.bootsCategory	category_boots
-98	Object.weaponCategory	category_weapon
-99	Object.toolCategory	category_tool
-100	Object.clothingCategory	category_clothing
-101	Object.trinketCategory	category_trinket
-102	Object.booksCategory
-103	Object.skillBooksCategory
-999	Object.litterCategory	category_litter

Console commands

With the Console Code mod installed, you can run this command in the SMAPI console to see a list of objects by category: cs return string.Join(`\n`, Game1.objectData.Keys.Select(key => new StardewValley.Object(key, 1)).GroupBy(item => item.Category, item => item.Name).OrderByDescending(p => p.Key).Select(p => $`{p.Key}: {string.Join(`, `, p.OrderBy(name => name))}`));

Context tags

A context tag is an arbitrary data label like category_gem or item_apple attached to items. These provide metadata about items (e.g. their color, quality, category, general groupings like alcohol or fish, etc), and may affect game logic (e.g. machine processing).

See Modding:Context tags for more info.

Objects

See Modding:Objects for more info.

Big craftables

Big craftables are objects which can be placed in the world and are two tiles tall (instead of one like objects). See Modding:Big craftables for more info.

Boots

See Modding:Boots for more info.

Pants

See Modding:Pants for more info.

Shirts

See Modding:Shirts for more info.

Furniture

Furniture are decorative items which can be placed in the world, including chairs which the player can sit on.

See Modding:Furniture for more info.

Hats

Hats are items that can be equipped in the player's hat slot.

See Modding:Hats for more info.

Tools

Tools are items that can be swung or used by the player to perform some effect (e.g. dig dirt, chop trees, etc).

See Modding:Tools for more info.

Weapons

Weapons are tools that can be used by the player to damage monsters.

See Modding:Weapons for more info.

See also

• Modding:Index for related content like crops, fish, gift tastes, and recipes