Modding:Items: Difference between revisions

Latest revision as of 16:15, 4 August 2026

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

Overview

Item IDs

Every item is identified in the game data using a unique item ID. This has two forms:

The unqualified item ID (item.ItemId) is a unique string ID for the item, like 128 (vanilla item) or Example.ModId_Watermelon (custom item). For legacy reasons, the unqualified ID for vanilla items may not be globally unique; for example, Pufferfish (object 128) and Mushroom Box (bigcraftable 128) both have item ID 128.
The qualified item ID (item.QualifiedItemId) is a globally unique identifier which combines the item's type ID and unqualified item ID, like (O)128 for object ID 128.

With SMAPI installed, you can run the list_items console command in-game to search item IDs.

Note: mods created before Stardew Valley 1.6 may use the item.ParentSheetIndex field as an item identifier. This is not a valid identifier; multiple items of the same type may have the same sprite index for different textures.

Item types

Items are defined by item type data definitions, which handle parsing data of a certain type. For example, the game's ObjectDataDefinition class handles producing object-type items by parsing the Data/Objects asset.

Each definition has a unique ID like (O), which is used to form globally unique qualified item IDs. In C# code, this is tracked by the item.TypeDefinitionId field, which matches ItemRegistry.type_* constants for vanilla item types.

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

item type	type identifier	data asset	brief summary
Objects	`(O)`	`Data/Objects`	The most common item type. Depending on their data, they can be placed in the world, picked up, eaten, sold to shops, etc.
Big craftables	`(BC)`	`Data/BigCraftables`	Items which can be placed in the world and are two tiles tall (instead of one like objects).
Boots	`(B)`	`Data/Boots`	Items which can be equipped in the player's boots slot. These change the player sprite and may provide buffs.
Furniture	`(F)`	`Data/Furniture`	Decorative items which can be placed in the world. In some cases players can sit on them or place items on them.
Hats	`(H)`	`Data/Hats`	Items which can be equipped in the player's hat slot. These change the player sprite.
Mannequins	`(M)`	`Data/Mannequins`	Decorative items which can be placed in the world, and used to store and display clothing.
Pants	`(P)`	`Data/Pants`	Items which can be equipped in the player's pants slot. These change the player sprite.
Shirts	`(S)`	`Data/Shirts`	Items which can be equipped in the player's shirt slot. These change the player sprite.
Tools	`(T)`	`Data/Tools`	Items that can be swung or used by the player to perform some effect (e.g. dig dirt, chop trees, milk or shear animals, etc).
Trinkets	`(TR)`	`Data/Trinkets`	Items that can be equipped in the player's trinket slot to enable special effects.
Wallpaper & flooring	`(WP)` and `(FL)`	`Data/AdditionalWallpaperFlooring`	Items which can be applied to a decoratable location (e.g. a farmhouse or shed) to visually change its floor or wall design. (These are separate from placeable items like brick floor.)
Weapons	`(W)`	`Data/Weapons`	Items which can be swung or used by the player to damage monsters.

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, mannequin, pants, shirt, tool, trinket, wallpaper, and floorpaper.

Item sprites

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.

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

When an item is broken (e.g. due to deleting the mod which adds it), it's represented in-game as a default Error Item with a 🛇 sprite. This keeps the previous item data in case the item data is re-added.

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(). 0 can be used as a blank value. Here are the valid categories:

value	internal constant	context tag	English translation	Color	Properties
-2	`Object.GemCategory`	`category_gem`	Mineral	`#6E005A`	Affected by Gemologist profession
-4	`Object.FishCategory`	`category_fish`	Fish	`#00008B` (DarkBlue)	Affected by Fisher and Angler professions
-5	`Object.EggCategory`	`category_egg`	Animal Product	`#FF0064`	Affected by Rancher profession, can be used in a slingshot
-6	`Object.MilkCategory`	`category_milk`	Animal Product	`#FF0064`	Affected by Rancher profession
-7	`Object.CookingCategory`	`category_cooking`	Cooking	`#DC3C00`
-8	`Object.CraftingCategory`	`category_crafting`	Crafting	`#943D28`	Is Placeable
-9	`Object.BigCraftableCategory`	`category_big_craftable`			Is Placeable
-12	`Object.mineralsCategory`	`category_minerals`	Mineral	`#6E005A`	Affected by Gemologist profession
-14	`Object.meatCategory`	`category_meat`	Animal Product	`#FF0064`
-15	`Object.metalResources`	`category_metal_resources`	Resource	`#406672`
-16	`Object.buildingResources`	`category_building_resources`	Resource	`#406672`
-17	`Object.sellAtPierres`	`category_sell_at_pierres`
-18	`Object.sellAtPierresAndMarnies`	`category_sell_at_pierres_and_marnies`	Animal Product	`#FF0064`	Affected by Rancher profession
-19	`Object.fertilizerCategory`	`category_fertilizer`	Fertilizer	`#708090` (SlateGray)	Is Placeable, is always passable
-20	`Object.junkCategory`	`category_junk`	Trash	`#696969` (DimGray)
-21	`Object.baitCategory`	`category_bait`	Bait	`#8B0000` (DarkRed)	Can be attached to a fishing rod
-22	`Object.tackleCategory`	`category_tackle`	Fishing Tackle	`#008B8B` (DarkCyan)	Can be attached to a fishing rod, cannot stack
-23	`Object.sellAtFishShopCategory`	`category_sell_at_fish_shop`
-24	`Object.furnitureCategory`	`category_furniture`	Decor	`#9650BE`
-25	`Object.ingredientsCategory`	`category_ingredients`	Cooking
-26	`Object.artisanGoodsCategory`	`category_artisan_goods`	Artisan Goods	`#009B6F`	Affected by Artisan profession
-27	`Object.syrupCategory`	`category_syrup`	Artisan Goods	`#009B6F`	Affected by Tapper profession
-28	`Object.monsterLootCategory`	`category_monster_loot`	Monster Loot	`#320A46`
-29	`Object.equipmentCategory`	`category_equipment`
-74	`Object.SeedsCategory`	`category_seeds`	Seed	`#A52A2A` (Brown)	Is Placeable, is always passable
-75	`Object.VegetableCategory`	`category_vegetable`	Vegetable	`#008000` (Green)	Affected by Tiller profession, can be used in a slingshot
-79	`Object.FruitsCategory`	`category_fruits`	Fruit	`#FF1493` (DeepPink)	Affected by Tiller profession (if not foraged), can be used in a slingshot
-80	`Object.flowersCategory`	`category_flowers`	Flower	`#DB36D3`	Affected by Tiller profession
-81	`Object.GreensCategory`	`category_greens`	Forage	`#0A8232`
-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`			`#552F1B`
-103	`Object.skillBooksCategory`			`#7A5d27`
-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.

Specific item types

For docs about each item type (e.g. objects or weapons), see the item types table above.

For C# mods

Identify items

You can uniquely identify items by checking their item ID fields. For example:

bool isPufferfish = item.QualifiedItemId == "(O)128";

The ItemRegistry class also provides methods to work with items. For example:

// check if item would be matched by a qualified or unqualified item ID
bool isPufferfish = ItemRegistry.HasItemId(item, "128");

// qualify an item ID if needed
string pufferfishQualifiedId = ItemRegistry.QualifyItemId("128"); // returns "(O)128"

Note that flavored items like jellies and wine don't have their own ID. For example, Blueberry Wine and Wine are both (O)348. You can get the flavor item ID from the preservedParentSheetIndex field; for example, Blueberry Wine will have the item ID for blueberry. (Despite the name, it contains the item's ID rather than its ParentSheetIndex).

Create item instances

The ItemRegistry.Create method is the main way to construct items. For example:

Item pufferfish = ItemRegistry.Create("(O)128"); // can optionally specify count and quality

If the ID doesn't match a real item, the ItemRegistry will return an Error Item by default. You can override that by setting allowNull: true when calling the method.

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 boots = ItemRegistry.Create<Boots>("(B)505"); // Rubber Boots

When creating an item manually instead, make sure to pass its ItemId (not QualifiedItemId) to the constructor. For example:

Item pufferfish = new Object("128", 1);

Work with item metadata

The ItemRegistry class provides several methods for working with item metadata. Some useful methods include:

method	effect
`ItemRegistry.Create`	Create an item instance.
`ItemRegistry.Exists`	Get whether a qualified or unqualified item ID matches an existing item. For example: bool pufferfishExists = 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`	Get high-level info about an item: // get info about Rubber Boots ItemMetadata metadata = ItemRegistry.GetMetadata("(B)505"); // get item ID info $"The item has unqualified ID {metadata.LocalId}, qualified ID {metadata.QualifiedId}, and is defined by the {metadata.TypeIdentifier} item data definition."; // does the item exist in the data files? bool exists = metadata.Exists(); And get common parsed item data: // get parsed info ParsedItemData data = metadata.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.

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.