Modding:Tools - Revision history

imported>Sunbeam135 at 22:10, 12 January 2026

2026-01-12T22:10:03Z

← Older revision		Revision as of 22:10, 12 January 2026
Line 189:		Line 189:
	[[Category:Modding]]		[[Category:Modding]]

			[[ru:Модификации:Инструменты]]
	[[zh:模组:工具]]		[[zh:模组:工具]]

imported>Pathoschild: /* Upgrades */ remove ApplyUpgradeLevelToDisplayName field (removed in Stardew Valley 1.6.9)

2025-03-25T17:26:54Z

Upgrades: remove ApplyUpgradeLevelToDisplayName field (removed in Stardew Valley 1.6.9)

@@ Line 69: / Line 69: @@
 | <samp>UpgradeLevel</samp>
 | ''(Optional)'' The tool upgrade level. Default <samp>-1</samp>, which keeps the default value set by the tool class.
 |-
 | <samp>ConventionalUpgradeFrom</samp>

imported>VulpesLucida: zh link

2024-12-28T07:56:34Z

zh link

← Older revision		Revision as of 07:56, 28 December 2024
Line 210:		Line 210:

	[[Category:Modding]]		[[Category:Modding]]

			[[zh:模组:工具]]

imported>Pathoschild: /* Overview */ add item type info

2024-12-16T01:07:16Z

Overview: add item type info

← Older revision		Revision as of 01:07, 16 December 2024
Line 6:		Line 6:
	[[Tools]] are items that can be swung or used by the player to perform some effect (e.g. dig dirt, chop trees, etc).		[[Tools]] are items that can be swung or used by the player to perform some effect (e.g. dig dirt, chop trees, etc).

	They have their data in <samp>Data/Tools</samp>, their in-game sprites in <samp>TileSheets/Tools</samp> and translations in <samp>Strings/Tools</samp> by default, and their code in <samp>StardewValley.Tool</samp> and various subclasses like <samp>StardewValley.Tools.Axe</samp>.		They have [[Modding:Items#Item types\|item type]] <code>(T)</code> (or <code>ItemRegistry.type_tool</code> in C# code), their data in <samp>Data/Tools</samp>, their in-game sprites in <samp>TileSheets/Tools</samp> and translations in <samp>Strings/Tools</samp> by default, and their code in <samp>StardewValley.Tool</samp> and various subclasses like <samp>StardewValley.Tools.Axe</samp>.

	==Data format==		==Data format==

imported>Pathoschild: adjust page post-split, add some high-level info

2024-12-16T00:36:06Z

adjust page post-split, add some high-level info

← Older revision		Revision as of 00:36, 16 December 2024
Line 1:		Line 1:
	← [[Modding:Items\|Items]]		← [[Modding:Items\|Items]]

	==~~Tools~~==		This page explains how the game stores and parses tool-type item data. For items in general, see [[Modding:Items]].

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

	They have their data in <samp>Data/Tools</samp>, their in-game sprites in <samp>TileSheets/Tools</samp>, and their code in <samp>StardewValley.Tool</samp> and various subclasses like <samp>StardewValley.Tools.Axe</samp>.		They have their data in <samp>Data/Tools</samp>, their in-game sprites in <samp>TileSheets/Tools</samp> and translations in <samp>Strings/Tools</samp> by default, and their code in <samp>StardewValley.Tool</samp> and various subclasses like <samp>StardewValley.Tools.Axe</samp>.

	===Data format===		==Data format==
			The tool data in <samp>Data/Tools</samp> consists of a string → model lookup, where...
	~~You can create/edit [[tools]] by editing the~~<samp>Data/Tools</samp> ~~asset. This~~ consists of a string → model lookup, where...		* The key is the [[Modding:Common data field types#Item ID\|unqualified item ID]].
	* The key is the ~~unqualified~~ [[Modding:~~Common_data_field_types~~#~~Item_ID~~\|item ID]].
	* The value is a model with the fields listed below.		* The value is a model with the fields listed below.

	====Basic ~~tool~~ data====		===Basic data===
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 42:		Line 43:
	\|}		\|}

	====Appearance====		===Appearance===
	Note that drawing the tool correctly in the world (ie, while the player is trying to use it) will likely require custom code.		Note that drawing the tool correctly in the world (ie, while the player is trying to use it) will likely require custom code.

Line 60:		Line 61:
	\|}		\|}

	====Upgrades====		===Upgrades===
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 171:		Line 172:
	\|}		\|}

	====Game logic====		===Game logic===
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 181:		Line 182:
	\|}		\|}

	====Extensibility====		===Extensibility===
	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
Line 204:		Line 205:
	</syntaxhighlight>		</syntaxhighlight>
	\|}		\|}

			==See also==
			* [[Modding:Items]] for item data in general

	[[Category:Modding]]		[[Category:Modding]]

imported>Pathoschild: split from Modding:Items; attribution: Pathoschild (main author), BarleyZP (copied info from 1.6 migration guide with main content by Pathoschild and notes by Atravita, followup fixes)

2024-12-15T17:29:22Z

split from Modding:Items; attribution: Pathoschild (main author), BarleyZP (copied info from 1.6 migration guide with main content by Pathoschild and notes by Atravita, followup fixes)

New page

← [[Modding:Items|Items]]

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

They have their data in <samp>Data/Tools</samp>, their in-game sprites in <samp>TileSheets/Tools</samp>, and their code in <samp>StardewValley.Tool</samp> and various subclasses like <samp>StardewValley.Tools.Axe</samp>.

===Data format===

You can create/edit [[tools]] by editing the<samp>Data/Tools</samp> asset. This consists of a string → model lookup, where...
* The key is the unqualified [[Modding:Common_data_field_types#Item_ID|item ID]].
* The value is a model with the fields listed below.

====Basic tool data====
{| class="wikitable"
|-
! field
! purpose
|-
| <samp>ClassName</samp>
| The name of the C# class to construct within the <code>StardewValley.Tools</code> namespace. The class must be a subclass of <samp>StardewValley.Tool</samp>, and have a constructor with no arguments. For example, given a value of <samp>Axe</samp>, the game will create <code>StardewValley.Tools.Axe</code> instances.

The main values are:
* main tools (<samp>Axe</samp>, <samp>FishingRod</samp>, <samp>Hoe</samp>, <samp>MeleeWeapon</samp>, <samp>MilkPail</samp>, <samp>Pan</samp>, <samp>Pickaxe</samp>, <samp>Shears</samp>, <samp>Wand</samp>, and <samp>WateringCan</samp>);
* a special <samp>GenericTool</samp> type which applies the <samp>Data/Tools</samp> data and only has generic logic, so C# mods can patch in their own logic;
* and two tools cut from the game which may not work correctly (<samp>Lantern</samp> and <samp>Raft</samp>).
|-
| <samp>Name</samp>
| The internal name to set for the tool item.
|-
| <samp>DisplayName</samp><br /><samp>Description</samp>
| A [[Modding:Tokenizable strings|tokenizable string]] for the tool's in-game display name and description.
|-
| <samp>AttachmentSlots</samp>
| ''(Optional)'' The number of attachment slots to enable on the tool. Note that only <samp>FishingRod</samp> tools have the code to render and use attachment slots. Default <samp>-1</samp>, which keeps the default value set by the tool class.
|-
| <samp>SalePrice</samp>
| ''(Optional)'' The default price when the item is sold to the player in a shop. Defaults to <samp>-1</samp>, in which case you should set the price manually in shops.
|-
| <samp>CustomFields</samp>
| The [[Modding:Common_data_field_types#Custom_fields|custom fields]] for this entry.
|}

====Appearance====
Note that drawing the tool correctly in the world (ie, while the player is trying to use it) will likely require custom code.

{| class="wikitable"
|-
! field
! purpose
|-
| <samp>Texture</samp>
| The asset name for the texture containing the tool's sprite.
|-
| <samp>SpriteIndex</samp>
| The tool's sprite index within the <samp>Texture</samp>, where 0 is the top row.
|-
| <samp>MenuSpriteIndex</samp>
| ''(Optional)'' The sprite index within the <samp>Texture</samp> for the item icon. Defaults to <samp>SpriteIndex</samp>.
|}

====Upgrades====
{| class="wikitable"
|-
! field
! purpose
|-
| <samp>UpgradeLevel</samp>
| ''(Optional)'' The tool upgrade level. Default <samp>-1</samp>, which keeps the default value set by the tool class.
|-
| <samp>ApplyUpgradeLevelToDisplayName</samp>
| ''(Optional)'' Whether to adjust the <samp>DisplayName</samp> for the usual upgrade levels. For example, the display name for a level one Axe changes to 'Copper Axe'. Default false.

The display name format in English is:
{| class="wikitable"
|-
! upgrade level
! display name format
|-
| 1
| Copper {{t|display name}}
|-
| 2
| Steel {{t|display name}}
|-
| 3
| Gold {{t|display name}}
|-
| 4
| Iridium {{t|display name}}
|}
|-
| <samp>ConventionalUpgradeFrom</samp>
| ''(Optional)'' If set, prepends an upgrade for the given tool ID to the <samp>UpgradeFrom</samp> field. This applies these rules (based on the <samp>UpgradeLevel</samp> field, not the upgrade level of the specified tool ID):

{| class="wikitable"
|-
! upgrade level
! price
! items needed
|-
| 1
| {{price|2000}}
| {{name|Copper Bar|5}}
|-
| 2
| {{price|5000}}
| {{name|Iron Bar|5}}
|-
| 3
| {{price|10000}}
| {{name|Gold Bar|5}}
|-
| 4
| {{price|25000}}
| {{name|Iridium Bar|5}}
|}

For example, Iridium Axe specifies this value:
<syntaxhighlight lang="js">
"ConventionalUpgradeFrom": "(T)GoldAxe"
</syntaxhighlight>
|-
| <samp>UpgradeFrom</samp>
| ''(Optional)'' The requirements to buy this tool from Clint's [[Blacksmith#Upgrade Tools|blacksmith tool upgrade shop]]. If you specify multiple entries, the first one which matches will be applied.

This consists of a list of models with these fields:
{| class="wikitable"
|-
! field
! purpose
|-
| <samp>Price</samp>
| ''(Optional)'' The gold price to buy the upgrade. Defaults to 0.
|-
| <samp>RequireToolId</samp>
| ''(Optional)'' If set, the [[Modding:Common_data_field_types#Item_ID|qualified or unqualified item ID]] for the tool that must be in the player's inventory for the upgrade to appear. The tool will be destroyed when the upgrade is purchased.
|-
| <samp>TradeItemId</samp>
| ''(Optional)'' If set, the [[Modding:Common_data_field_types#Item_ID|qualified or unqualified item ID]] for an extra item that must be traded to upgrade the tool. (For example, many vanilla tools need metal bars.)
|-
| <samp>TradeItemAmount</samp>
| ''(Optional)'' The number of <samp>TradeItemId</samp> required. Defaults to 1.
|-
| <samp>Condition</samp>
| ''(Optional)'' A [[Modding:Game state queries|game state query]] which indicates whether this upgrade is available. Defaults to always true.
|}

For example, these are equivalent to the Steel Axe's upgrade settings:
<syntaxhighlight lang="js">
"UpgradeFrom": [
{
"RequireToolId": "(T)CopperAxe",
"Price": 5000,
"TradeItemId": "(O)335", // Iron Bar
"TradeItemAmount": 5
}
]
</syntaxhighlight>

If you want the tool to always be available, you can just omit the conditions. For example:
<syntaxhighlight lang="js">
"UpgradeFrom": [
{
"Price": 5000
}
]
</syntaxhighlight>

Note that Clint needs a few days to smith the new tool. If you want to sell the tool directly, [[Modding:Shops|add it to a regular shop]] instead.
|}

====Game logic====
{| class="wikitable"
|-
! field
! purpose
|-
| <samp>CanBeLostOnDeath</samp>
| Whether the player can [[Adventurer's Guild#Item Recovery Service|lose this tool when they die]]. Default false.
|}

====Extensibility====
{| class="wikitable"
|-
! field
! purpose
|-
| <samp>ModData</samp>
| ''(Optional)'' The mod data values to set when the tool is created, accessible in C# code via the <samp>tool.modData</samp> dictionary. For example:
<syntaxhighlight lang="js">
"ModData": {
"PowerLevel": 9000
}
</syntaxhighlight>
|-
| <samp>SetProperties</samp>
| ''(Optional)'' Set the value of arbitrary properties on the tool class. For example, this would disable the tool animation and require no stamina:
<syntaxhighlight lang="js">
"SetProperties": {
"InstantUse": true,
"IsEfficient": true
}
</syntaxhighlight>
|}

[[Category:Modding]]