138
edits
Changes
Jump to navigation
Jump to search
Line 4:
Line 4: + − Items are divided into several types:+ + + + + + + + − + − + − | The default type for items in inventories or placed in the world.+ + − + − + + − + − + + − + − + + + + + + + + + + + + + + + + + − | [[#Furniture|furniture]]+ − | Decorative items which can be placed in the world, including chairs which the player can sit on.+ − + − + + + − + − + + + − + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Line 42:
Line 151: − − Flooring and wallpaper are not in any of these types and are not currently documented in this wiki. Line 51:
Line 158: − Every item must be assigned a unique <samp>ParentSheetIndex</samp> 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 {{nexus mod|1720|Json Assets}}, which coordinates dynamic item ID assignment so multiple custom item mods can work together.+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
→Introduction: add info from Modding:Migrate to Stardew Valley 1.6 (main author Pathoschild, with various notes and fixes by Atravita, Margotbean, DeLiXxn)
==Introduction==
==Introduction==
===Overview===
===Overview===
Stardew Valley 1.6 makes three major changes to how items work in the game:
# Each item now has a string ID (<samp>ItemId</samp>) and a globally unique string ID (<samp>QualifiedItemId</samp>). The <samp>QualifiedItemId</samp> is auto-generated by prefixing the <samp>ItemId</samp> with the item type identifier.<p>For legacy reasons, the <samp>ItemId</samp> for vanilla items may not be globally unique. For example, Pufferfish (object 128) and Mushroom Box (bigcraftable 128) both have <samp>ItemId: 128</samp>. They can be distinguished by their <samp>QualifiedItemId</samp>, which are <samp>(O)128</samp> and <samp>(BC)128</samp> respectively.
# Each item type now has an ''item data definition'' in the game code which tells the game how to handle it. [[#For C# mods|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 (<samp>(BC)</samp>), boots (<samp>(B)</samp>), farmhouse flooring (<samp>(FL)</samp>), furniture (<samp>(F)</samp>), hats (<samp>(H)</samp>), objects (<samp>(O)</samp>), pants (<samp>(P)</samp>), shirts (<samp>(S)</samp>), tools (<samp>(T)</samp>), wallpaper (<samp>(WP)</samp>), and weapons (<samp>(W)</samp>).</li>
# Custom items can now provide their own item texture, specified in a new field in the item data assets (see below). The item's <samp>ParentSheetIndex</samp> field is the index within that texture.
In other words, the four important fields for items are:
{| class="wikitable"
{| class="wikitable"
|-
|-
! name
! type
! type
! summary
! description
|-
|-
| [[#Objects|objects]]
| <samp>ItemId</samp>
| <samp>string</samp>
| A [[Modding:Common data field types#Unique string ID|unique string ID]] for this item which should be globally unique (but may not be for existing vanilla items for backwards compatibility). For example, <samp>128</samp> (vanilla item) or <samp>Example.ModId_Watermelon</samp> (custom item).
|-
|-
| [[#Big craftables|big craftables]]
| <samp>QualifiedItemId</samp>
| Craftable items which can be placed in the world and are two tiles tall.
| <samp>string</samp>
| A globally unique item key, like <samp>(O)128</samp> for a vanilla item or <samp>(O)Example.ModId_Watermelon</samp> for a custom one. This is auto-generated from the <samp>TypeDefinitionId</samp> and <samp>ItemId</samp> fields.
|-
|-
| [[#Boots|boots]]
| <samp>ParentSheetIndex</samp>
| Items that can be equipped in the player's [[footwear]] slot.
| <samp>int</samp>
| The item's sprite index within its spritesheet.
|-
|-
| [[#Clothing|clothing]]
| <samp>TypeDefinitionId</samp>
| Cosmetic items that can be equipped in the player's [[Tailoring|pants and shirt]] slots.
| <samp>string</samp>
| The ID for the data definition which defines the item, like <samp>(O)</samp> for an object. You can use <samp>ItemRegistry.type_*</samp> constants with this field:
<syntaxhighlight lang="c#">
if (item.TypeDefinitionId == ItemRegistry.type_object)
...
</syntaxhighlight>
|}
===Item references===
Item references throughout the game code now use the <samp>ItemId</samp> instead of the <samp>ParentSheetIndex</samp>. Since the <samp>ItemId</samp> is identical to the index for existing vanilla items, most data assets are unaffected by this change. For example, here's from <samp>Data/NPCGiftTastes</samp> with one custom item:
<syntaxhighlight lang="json">
"Universal_Like": "-2 -7 -26 -75 -80 72 395 613 634 635 636 637 638 724 459 Example.ModID_watermelon"
</syntaxhighlight>
Unless otherwise noted, unqualified item IDs will produce [[Modding:Items|objects]]. Some assets let you override that by specifying a <samp>QualifiedItemId</samp> value instead. For example, you can add <code>(O)128</code> 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:
{| class="wikitable"
|-
|-
! data asset
! item ID format
|-
|-
| [[#Hats|hats]]
| [[Modding:Recipe data|<samp>Data/CraftingRecipes</samp><br /><samp>Data/CookingRecipes</samp>]]
| Items that can be equipped in the player's [[hats|hat]] slot.
|  
* Ingredients: both supported.
* Output: set field 2 to the unqualified item ID, and field 3 to one of <samp>true</samp> (bigcraftable) or <samp>false</samp> (object).
|-
|-
| [[#Tools|tools]]
| [[#Custom fruit trees|<samp>Data/fruitTrees</samp>]]
| Items that can be swung or used by the player to perform some effect.
|  
* Fruit: both supported.
* Sapling: unqualified only.
|-
|-
| [[#Weapons|weapons]]
| [[Modding:Gift taste data|<samp>Data/NPCGiftTastes</samp>]]
| Tools that can be used by the player to damage monsters.
| Both supported, but only <samp>(O)</samp> items can be gifted.
|}
|}
===Item types===
These are the item types for which custom items can added/edited:
{| class="wikitable"
|-
! item type
! type identifier
! data asset
|-
| [[Modding:Items|big craftables]]
| <samp>(BC)</samp>
| <samp>Data/BigCraftables</samp><br /><small>Each item can set a custom texture name in the <samp>Texture</samp> field, and sprite index in the <samp>SpriteIndex</samp> field. The default texture is <samp>TileSheets/Craftables</samp>.</small>
|-
| boots
| <samp>(B)</samp>
| <samp>Data/Boots</samp><br /><small>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 <samp>Maps/springobjects</samp> (item) and <samp>Characters/Farmer/shoeColors</samp> (shoe color).</small>
|-
| [[Modding:Crop data|crops]]
| <small>''not technically an item type''</small>
| <samp>Data/Crops</samp><br /><small>Each crop can set a custom texture name and sprite index. The default texture is <samp>TileSheets/crops</samp>.</small>
|-
| [[Modding:Fish data|fish (in fish tanks)]]
| <small>''not technically an item type''</small>
| <samp>Data/AquariumFish</samp><br /><small>Each fish can set a custom aquarium texture name in field 6, and sprite index in field 0. The default texture is <samp>LooseSprites/AquariumFish</samp>.</small>
|-
| [[Modding:Items|furniture]]
| <samp>(F)</samp>
| <samp>Data/Furniture</samp><br /><small>Each item can set a custom texture name in field 9, and sprite index in field 8. The default texture is <samp>TileSheets/furniture</samp>.</small>
|-
| fruit trees
| <small>''not technically an item type''</small>
| <samp>Data/FruitTrees</samp><br /><small>Each fruit tree can set a custom texture name and sprite index. The default texture is <samp>TileSheets/fruitTrees</samp>.</small>
|-
| [[Modding:Items|hats]]
| <samp>(H)</samp>
| <samp>Data/Hats</samp><br /><small>Each item can set a custom texture name in field 7, and sprite index in field 6. The default texture is <samp>Characters/Farmer/hats</samp>.</small>
|-
| [[Modding:Items|objects]]
| <samp>(O)</samp>
| <samp>Data/Objects</samp><br /><small>Each item can set a custom texture name in the <samp>Texture</samp> field, and sprite index in the <samp>SpriteIndex</samp> field. The default texture is <samp>Maps/springobjects</samp>.</small>
|-
| [[#Custom pants|pants]]
| <samp>(P)</samp>
| <samp>Data/pantsData</samp><br /><small>Each item can set a custom texture name in the <samp>Texture</samp> field, and sprite index in the <samp>SpriteIndex</samp> field. The default texture is <samp>Characters/Farmer/pants</samp>.</small>
|-
| [[#Custom shirts|shirts]]
| <samp>(S)</samp>
| <samp>Data/shirtData</samp><br /><small>Each item can set a custom texture name in the <samp>Texture</samp> field, and sprite index in the <samp>SpriteIndex</samp> field. The default texture is <samp>Characters/Farmer/shirts</samp>.</small>
<small>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.</small>
<pre>
sprites dye masks
/-----------\ /-----------\
┌────────────────────────────────┐
│ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │
│ │ 0 ││ 1 ││ 2 ││ a ││ b ││ c │ │
│ └───┘└───┘└───┘└───┘└───┘└───┘ │
│ ┌───┐┌───┐┌───┐┌───┐┌───┐┌───┐ │
│ │ 3 ││ 4 ││ 5 ││ d ││ e ││ f │ │
│ └───┘└───┘└───┘└───┘└───┘└───┘ │
└────────────────────────────────┘
</pre>
|-
| [[#Custom tools|tools]]
| <samp>(T)</samp>
| <samp>Data/Tools</samp><br /><small>Each item can set a custom texture name in the <samp>Texture</samp> field, and sprite index in the <samp>SpriteIndex</samp> field. The vanilla tools use the <samp>TileSheets/Tools</samp> texture.</small>
|-
| Wallpaper & floorpaper
| <samp>(WP)</samp> and <samp>(FL)</samp>
| <samp>Data/AdditionalWallpaperFlooring</samp><br /><small>See [[Modding:Migrate to Stardew Valley 1.5.5#In the furniture catalogue|format docs]].</small>
|-
| [[Modding:Items|weapons]]
| <samp>(W)</samp>
| <samp>Data/Weapons</samp><br /><small>[[#Custom melee weapons|Completely overhauled]] into a data model.</small>
|}
When resolving an unqualified item ID like <samp>128</samp>, 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 <samp>Content</samp> folder (which can be [[Modding:Editing XNB files#unpacking|unpacked for editing]]):
For each item type, the game has two files in its <samp>Content</samp> folder (which can be [[Modding:Editing XNB files#unpacking|unpacked for editing]]):
Each item has a <samp>ParentSheetIndex</samp> 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 <samp>Characters/Farmer/hats</samp>. The <samp>ParentSheetIndex</samp> 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 <code>item is Weapon weapon && weapon.ParentSheetIndex == 4</code>.
Each item has a <samp>ParentSheetIndex</samp> 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 <samp>Characters/Farmer/hats</samp>. The <samp>ParentSheetIndex</samp> 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 <code>item is Weapon weapon && weapon.ParentSheetIndex == 4</code>.
See the sections below for details on each item type.
See the sections below for details on each item type.
===Define a custom item===
===Define a custom item===
You can define custom items for most vanilla item types using only [[Modding:Content Patcher|Content Patcher]] or [[Modding:Modder Guide/APIs/Content|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 <samp>Data/Crops</samp> and <samp>Data/NPCGiftTastes</samp> use the item ID.
{{#tag:syntaxhighlight|<nowiki>
{
"Format": "</nowiki>{{Content Patcher version}}<nowiki>",
"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
}
]
}</nowiki>|lang=javascript}}
Most item data assets work just like <samp>Data/Objects</samp>. See also specific info for [[#Custom fruit trees|custom fruit trees]], [[#Custom tools|custom tools]], and [[#Custom melee weapon data|melee weapons]].
===Error items===
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 adds comprehensive handling for such items. They'll be shown with a <samp>🛇</samp> 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===
<dl style="margin-left: 2em;">
<dt>Compare items</dt>
<dd>
Since <samp>Item.QualifiedItemId</samp> is globally unique, it can be used to simplify comparing items. For example:
{| class="wikitable"
|-
! old code
! new code
|-
|-
| <samp>item.ParentSheetIndex == 128</samp>
| <samp>item.QualifiedItemId == "(O)128"</samp>
|-
| <samp>IsNormalObjectAtParentSheetIndex(item, 128)</samp>
| <samp>item.QualifiedItemId == "(O)128"</samp>
|-
| <samp>!item.bigCraftable && item.ParentSheetIndex == 128</samp>
| <samp>item.QualifiedItemId == "(O)128"</samp>
|-
| <samp>item is Boots && item.ParentSheetIndex == 505</samp>
| <samp>item.QualifiedItemId == "(B)505"</samp>
|}
You can also use <samp>ItemRegistry.QualifyItemId</samp> to convert any item ID into a qualified one (if it's valid), and <samp>ItemRegistry.HasItemId</samp> 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 <samp>(O)348</samp>. This affects flavored jellies, juices, pickles, and wines. In those cases you should still compare their separate fields like <samp>preservedParentSheetIndex</samp> (which actually contains the preserved item's <samp>ItemId</samp>, not its <samp>ParentSheetIndex</samp>).
</dd>
<dt>Construct items</dt>
<dd>Creating items works just like before, except that you now specify the item's <samp>ItemId</samp> (''not'' <samp>QualifiedItemId</samp>) instead of its <samp>ParentSheetIndex</samp>. For example:
<syntaxhighlight lang="c#">
new Object("128", 1); // vanilla item
new Object("Example.ModId_Watermelon", 1); // custom item
</syntaxhighlight>
You can use a new utility method to construct items from their <samp>QualifiedItemId</samp>:
<syntaxhighlight lang="c#">
Item item = ItemRegistry.Create("(B)505"); // Rubber Boots
</syntaxhighlight>
</dd>
<dt>Define custom item types</dt>
<dd>You can implement <samp>IItemDataDefinition</samp> for your own item type, and call <samp>ItemRegistry.AddTypeDefinition</samp> 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.</dd>
<dt>New <samp>Is*</samp> methods</dt>
<dd>1.6 adds some <samp>StardewValley.Object</samp> methods to handle custom items in a generic way (and to let mods patch the logic):
{| class="wikitable"
|-
! method
! effect
|-
| <samp>object.IsBar()</samp>
| Whether the item is a [[Copper Bar|copper bar]], [[Iron Bar|iron bar]], [[Gold Bar|gold bar]], [[Iridium Bar|iridium bar]], or [[Radioactive Bar|radioactive bar]].
|-
| <samp>object.IsBreakableStone()</samp>
| Whether the item is a stone debris item which can be broken by a pickaxe.
|-
| <samp>object.IsFence()</samp>
| Whether the item is a [[Crafting#Fences|fence]].
|-
| <samp>object.IsFruitTreeSapling()</samp>
| Whether the item is a [[Fruit Trees|fruit tree]] sapling. This checks the <samp>Data\fruitTrees</samp> keys, so it works with custom fruit trees too.
|-
| <samp>object.IsHeldOverHead()</samp>
| Whether the player is shown holding up the item when it's selected in their toolbar. Default true (except for furniture).
|-
| <samp>object.IsIncubator()</samp>
| Whether the item can incubate [[Animals|farm animal]] eggs when placed in a building.
|-
| <samp>object.IsTapper()</samp>
| Whether the item is a [[Tapper|tapper]] or [[Heavy Tapper|heavy tapper]].
|-
| <samp>object.IsTeaSapling()</samp>
| Whether the item is a [[Tea Sapling|tea sapling]].
|-
| <samp>object.IsTwig()</samp>
| Whethere the item is a twig debris item.
|-
| <samp>object.IsWeeds()</samp>
| Whether the item is a weed debris item.
|}
</dd>
<dt>Work with item metadata</dt>
<dd>
1.6 adds an <samp>ItemRegistry</samp> API for working with the new item system. Some of the provided methods are:
{| class="wikitable"
|-
! method
! effect
|-
| <samp>ItemRegistry.Create</samp>
| Create an item from its item ID (qualified or unqualified). If the ID doesn't match a real item, the optional <samp>allowNull</samp> parameter indicates whether to return null or an Error Item. For example:
<syntaxhighlight lang="c#">
Item item = ItemRegistry.Create("(B)505"); // Rubber Boots
</syntaxhighlight>
You can also get a specific value type instead of <samp>Item</samp> if needed. This will throw a descriptive exception if the type isn't compatible (e.g. you try to convert furniture to boots).
<syntaxhighlight lang="c#">
Boots item = ItemRegistry.Create<Boots>("(B)505"); // Rubber Boots
</syntaxhighlight>
|-
| <samp>ItemRegistry.Exists</samp>
| Get whether a qualified or unqualified item ID matches an existing item. For example:
<syntaxhighlight lang="c#">
bool pufferfishExist = ItemRegistry.Exists("(O)128");
</syntaxhighlight>
|-
| <samp>ItemRegistry.IsQualifiedId</samp>
| Get whether the given item ID is qualified with the type prefix (like <samp>(O)128</samp> instead of <samp>128</samp>).
|-
| <samp>ItemRegistry.QualifyItemId</samp>
| Get the unique qualified item ID given an unqualified or qualified one. For example:
<syntaxhighlight lang="c#">
string qualifiedId = ItemRegistry.QualifyItemId("128"); // returns (O)128
</syntaxhighlight>
|-
| <samp>ItemRegistry.GetMetadata</samp>
| This lets you get high-level info about an item:
<syntaxhighlight lang="c#">
// 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();
</syntaxhighlight>
And get common parsed item data:
<syntaxhighlight lang="c#">
// 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);
</syntaxhighlight>
And create an item:
<syntaxhighlight lang="c#">
Item item = metadata.CreateItem();
</syntaxhighlight>
And get the type definition (note that this is very specialized, and you should usually use <samp>ItemRegistry</samp> instead to benefit from its caching and optimizations):
<syntaxhighlight lang="c#">
IItemDataDefinition typeDefinition = info.GetTypeDefinition();
</syntaxhighlight>
|-
| <samp>ItemRegistry.ResolveMetadata</samp>
| Equivalent to <samp>ItemRegistry.GetMetadata</samp>, except that it'll return null if the item doesn't exist.
|-
| <samp>ItemRegistry.GetData</samp>
| Get the parsed data about an item, or <samp>null</samp> if the item doesn't exist. This is a shortcut for <code>ItemRegistry.ResolveMetadata(id)?.GetParsedData()</code>; see the previous method for info on the parsed data.
|-
| <samp>ItemRegistry.GetDataOrErrorItem</samp>
| Equivalent to <samp>ItemRegistry.GetData</samp>, except that it'll return info for an Error Item if the item doesn't exist (e.g. for drawing in inventory).
|-
| <samp>ItemRegistry.GetErrorItemName</samp>
| Get a translated ''Error Item'' label.
|}
</dd>
</dl>
==Common data==
==Common data==