Modding:Items
← Index
This page explains how the game stores and parses item data. This is an advanced guide for mod developers.
Introduction
Overview
Items are divided into several types:
| type | summary |
|---|---|
| objects | The default type for items in inventories or placed in the world. |
| big craftables | Craftable items which can be placed in the world and are two tiles tall. |
| boots | Items that can be equipped in the player's footwear slot. |
| clothing | Cosmetic items that can be equipped in the player's pants and shirt slots. |
| furniture | Decorative items which can be placed in the world, including chairs which the player can sit on. |
| hats | Items that can be equipped in the player's hat slot. |
| tools | Items that can be swung or used by the player to perform some effect. |
| weapons | Tools that can be used by the player to damage monsters. |
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.
Flooring and wallpaper are not in any of these types and are not currently documented in this wiki.
See the sections below for details on each item type.
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
Every item must be assigned a unique ParentSheetIndex within its type, and that index must fit within the item type's spritesheet.
Adding custom items to the data assets and spritesheets directly is not recommended, since it's very easy to conflict with other mods or cause game errors. Instead you should create a content pack for Json Assets, which coordinates dynamic item ID assignment so multiple custom item mods can work together.
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 | 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 | ||
| -98 | Object.weaponCategory | category_weapon | ||
| -99 | Object.toolCategory | category_tool |
| 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.objectInformation.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 attached to items. These can produce various effects in-game, or may be informational only.
The game generates some tags based on the game data (like the item quality), and others are defined in the Data/ObjectContextTags data asset (which consists of a string→string dictionary, where the key is the item's internal name or the alternative ID matching the id_<type>_<identifier> tag, and the value is a comma-delimited list of tags to add).
Here's an incomplete list of context tags added or used in the base game. Mods can add custom context tags, which aren't listed here.
- Added automatically for all items:
-
context tag effect category_ <category>Added automatically based on the item category. See the 'context tag' column in the item category list for possible values. fish_ <metadata>Added automatically for a fish item based on its metadata in Data/Fish. For crab pot fish (i.e. those with type trap):
context tag notes fish_trap_location_ <water type>Based on field 2 ('darting randomness'). For example, fish_trap_location_ocean. For fishing rod fish (i.e. those whose type is not trap):
context tag notes fish_difficulty_ <difficulty>Based on field 1 ('chance to dart'), where <difficulty>is one of easy (0–33), medium (34–66), hard (67–100), or extremely_hard (101+). For example, fish_difficulty_hard.fish_motion_ <motion>Based on field 4 ('location'). For example, fish_motion_floater. fish_favor_weather_ <weather>Based on field 7 ('weather'). For example, fish_favor_weather_sunny. id_ <type>_<identifier>Added automatically as an alternative ID. The <type>is one of B (boots), BBL (big craftable recipe), BL (object recipe), BO (big craftable), C (clothing), F (furniture), H (hat), O (object), R (ring), W (melee weapon), else blank. The<identifier>is the item's parent sheet index. For example, pufferfish has value id_o_128 (object #128).item_ <name>Added automatically based on the item name. The name is trimmed, lowercase, with spaces replaced with underscores, and with single quotes removed. For example, '1000 Years From Now' has context tag item_1000_years_from_now. - Added automatically for object-type items:
-
context tag effect jelly_item
juice_item
pickle_item
wine_itemFor items produced by the keg or preserves jar, the preserved item type. preserve_sheet_index_ <id>For items produced by the keg or preserves jar, the parent sheet index for the original item that was produced. For example, blueberry wine has preserve_sheet_index_258, where 258 is the blueberry item's index. quality_none
quality_silver
quality_gold
quality_iridiumAdded automatically based on the item quality. quality_qi Added automatically for items cooked while the Qi's Cuisine special order is active. - Context tags from Data/ObjectContextTags:
-
context tag effect color_* The color produced by this item when the player dyes clothing at Emily's house. The context tag only affects which of the six color dye pots it can be placed in; for example, color_red and color_dark_red are both placed in the red pot, but they don't produce different colors. dye pot context tags red color_red, color_salmon, color_dark_red, color_pink orange color_orange, color_dark_orange, color_dark_brown, color_brown, color_copper yellow color_yellow, color_dark_yellow, color_gold, color_sand green color_green, color_dark_green, color_lime, color_yellow_green, color_jade blue color_blue, color_dark_blue, color_dark_cyan, color_light_cyan, color_cyan, color_aquamarine purple color_purple, color_dark_purple, color_dark_pink, color_pale_violet_red, color_poppyseed, color_iridium
Some game data also references context tags in a generic way. For example, you can add custom tags for an item to Data/ObjectContextTags, then reference them in the fish pond data. Specifically:
| game data | effects |
|---|---|
| fish ponds | In Data/FishPondData, used to match fish that can be placed in the pond (see RequiredTags in the fish pond data). |
| special orders | In Data/SpecialOrders, used to match items that meet the quest objectives (see AcceptedContextTags in the special order data). |
| tailoring | In Data/TailoringRecipes, used to match items that are needed for a recipe. |
| gift tastes | In Data/NPCGiftTastes, used to set character likes and dislike for every item using the context tag. |
The debug listtags console command lists all the tags of the item being held.
| raw tag dump |
|---|
| Here's a list of context tags extracted from Data/ObjectContextTags that aren't listed above yet: alcohol_item, algae_item, ancient_item, beach_item, bomb_item, bone_item, book_item, ceramic_item, chicken_item, color_black, color_dark_gray, color_gray, color_iron, color_prismatic, color_white, cooking_item, cow_milk_item, cowboy_item, crop_year_2, dinosaur_item, doll_item, drink_item, dwarvish_item, dye_medium, dye_strong, egg_item, elvish_item, fertilizer_item, fish_bug_lair, fish_carnivorous, fish_crab_pot, fish_desert, fish_freshwater, fish_lake, fish_legendary, fish_mines, fish_night_market, fish_nonfish, fish_ocean, fish_pond, fish_river, fish_secret_pond, fish_semi_rare, fish_sewers, fish_swamp, fish_talk_demanding, fish_talk_rude, fish_talk_stiff, fish_upright, flower_item, food_bakery, food_breakfast, food_cake, food_party, food_pasta, food_salad, food_sauce, food_seafood, food_soup, food_spicy, food_sushi, food_sweet, forage_item, forage_item_beach, forage_item_cave, forage_item_desert, forage_item_mines, forage_item_secret, fossil_item, fruit_item, fruit_tree_item, furnace_item, ginger_item, goat_milk_item, golden_relic_item, honey_item, hunting_item, instrument_item, jelly_item, juice_item, large_egg_item, large_milk_item, light_source, machine_item, marine_item, mayo_item, medicine_item, milk_item, noble_item, ore_item, pickle_item, potion_item, prehistoric_item, quality_fertilizer_item, scroll_item, season_all, season_fall, season_spring, season_summer, season_winter, slime_egg_item, slime_item, statue_item, strange_doll_1, strange_doll_2, syrup_item, totem_item, toy_item, trash_item, tree_seed_item, wood_item. |
Objects
Objects are the default type for items in inventories or placed in the world.
They have their data in Data/Objects, their icon sprites in Maps/springobjects, and their code in StardewValley.Object. See a table of sprites and their corresponding indexes.
Data format
The object data in Data/Objects consists of a string→ObjectData dictionary (where ObjectData is defined in the game code in StardewValley.GameData.Objects.ObjectData). It has entries like this[1]:
"201": {
"Name": "Complete Breakfast",
"DisplayName": "[LocalizedText Strings\\Objects:CompleteBreakfast_Name]",
"Description": "[LocalizedText Strings\\Objects:CompleteBreakfast_Description]",
"Type": "Cooking",
"Category": -7,
"Price": 350,
"Texture": null,
"SpriteIndex": 201,
"Edibility": 80,
"IsDrink": false,
"Buffs": [
{
"Id": "Food",
"BuffId": null,
"IconTexture": null,
"IconSpriteIndex": 0,
"Duration": 600,
"IsDebuff": false,
"GlowColor": null,
"CustomAttributes": {
"FarmingLevel": 2.0,
"FishingLevel": 0.0,
"MiningLevel": 0.0,
"LuckLevel": 0.0,
"ForagingLevel": 0.0,
"MaxStamina": 50.0,
"MagneticRadius": 0.0,
"Speed": 0.0,
"Defense": 0.0,
"Attack": 0.0
},
"CustomFields": null
}
],
"GeodeDropsDefaultItems": false,
"GeodeDrops": null,
"ArtifactSpotChances": null,
"ExcludeFromFishingCollection": false,
"ExcludeFromShippingCollection": false,
"ExcludeFromRandomSale": false,
"ContextTags": [
"color_yellow",
"food_breakfast"
],
"CustomFields": null
}
For each entry in the data asset:
- The key (before the colon) is the item ID and its sprite index within the object spritesheet (saved as ParentSheetIndex in-code).
- The value (after the colon) is the data pertaining to that object, with the fields listed below. The objects with keys 516–534 (Ring.ringLowerIndexRange through Ring.ringUpperIndexRange) and 801 (wedding ring) are hardcoded as rings.
Field values are described below:
| Field | Data Type | EffectCite error: Closing </ref> missing for <ref> tag:
See also
References
|
|---|