Difference between revisions of "Making Tools"

From Forge Community Wiki
(Update to 1.17)
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
  
−
Tools are simply an extension of the <code>Item</code> class. All of the logic is handled directly through one class with the others just being helpers to specify an exact tool type. Their implementations rely mainly on extending a specific class, it's properties, and the use of a tier system.
+
Tools are simply an extension of the <code>Item</code> class. Their implementations mainly rely on extending a specific class, the <code>TierSortingRegistry</code>, and tags.
  
 
== <tt>Tier</tt> ==
 
== <tt>Tier</tt> ==
Line 16: Line 16:
 
|  <code>getAttackDamageBonus</code>  ||  <code>Float</code>  ||  The base attack damage of all items in this tier.  
 
|  <code>getAttackDamageBonus</code>  ||  <code>Float</code>  ||  The base attack damage of all items in this tier.  
 
|-
 
|-
−
|  <code>getLevel</code>  ||  <code>Integer</code>  ||  The harvest level of this tier. Vanilla uses values 0-4.
+
|  <code>getLevel</code>  ||  <code>Integer</code>  ||  The harvest level of this tier. Vanilla uses values 0-4. As of 37.0.31, Forge deprecates this value in favor of the sorting registry system discussed below. This value will be used if the tier is not registered however.
 
|-
 
|-
 
|  <code>getEnchantmentValue</code>  ||  <code>Integer</code>  ||  How enchantable an item of this tier is.  
 
|  <code>getEnchantmentValue</code>  ||  <code>Integer</code>  ||  How enchantable an item of this tier is.  
 
|-
 
|-
 
|  <code>getRepairIngredient</code>  ||  <code>Ingredient</code>  ||  What ingredient can be used to repair this item.  
 
|  <code>getRepairIngredient</code>  ||  <code>Ingredient</code>  ||  What ingredient can be used to repair this item.  
 +
|-
 +
|  <code>getTag</code>  ||  <code>TagKey<Block></code>  ||  What blocks this tier can mine. This should only encompass those blocks which are specific for this tier. Any blocks below this tier will be declared while registering. The naming convention of this tag is <code><modid>:needs_<tier_name>_tool</code>.
 
|-
 
|-
 
|}
 
|}
  
 
{{Tip/Important|An ingredient should be wrapped in a supplier to avoid calling the object directly. Tiers are loaded before registries are populated, so the call to the item needs to be deferred.}}
 
{{Tip/Important|An ingredient should be wrapped in a supplier to avoid calling the object directly. Tiers are loaded before registries are populated, so the call to the item needs to be deferred.}}
 +
 +
{{Tip|Forge has a implementation class called <code>ForgeTier</code> to create a common tier, though this does not have to be used.}}
 +
 +
== <tt>TierSortingRegistry</tt> ==
 +
 +
For a tier to be used in the new system, they need to be registered before items most commonly by static initialization. A tier can be registered via <code>TierSortingRegistry#registerTier</code>. Any tier not defined in the sorting system will be defaulted to vanilla behavior.
 +
 +
This has four parameters:
 +
{| class="wikitable sortable" border=1
 +
!Parameter !!Type !!Description
 +
|-
 +
|  <code>tier</code>  ||  <code>Tier</code>  ||  The tier object being registered.
 +
|-
 +
|  <code>name</code>  ||  <code>ResourceLocation</code>  ||  The name of the tier for dependency resolution.
 +
|-
 +
|  <code>after</code>  ||  <code>List<Object></code>  ||  The list of tiers to place this tier after or the tiers of the same level that are weaker than this one. This can either be a <code>String</code>, <code>ResourceLocation</code>, or <code>Tier</code> where the first two are located by the <code>name</code> parameter above.
 +
|-
 +
|  <code>before</code>  ||  <code>List<Object></code>  ||  The list of tiers to place this tier before or the tiers of the same level that are stronger than this one. This can either be a <code>String</code>, <code>ResourceLocation</code>, or <code>Tier</code> where the first two are located by the <code>name</code> parameter above.
 +
|-
 +
|}
 +
 +
{{Tip|If your tier is equivalent to another tier, then <code>Tier#getTag</code> should return an empty tag reference defined by <code>BlockTags#create</code> and have the equivalent tier be placed in the <code>after</code> list when registering. If the tier is a vanilla tier, you should also specify the next tier above in the <code>before</code> list.}}
  
 
== <tt>DiggerItem</tt> ==
 
== <tt>DiggerItem</tt> ==
Line 32: Line 56:
 
Each tool has four parameters: tier, attack damage, attack speed, and properties. Tiers and properties have already been explained in this and within the [[Making Items|item]] docs. Attack damage specifies how much damage to do above the current base set for that specific tier. Attack speed specifies the speed modifier to apply to your current attack speed (the base attack speed for a player is <code>4.0D</code>).  
 
Each tool has four parameters: tier, attack damage, attack speed, and properties. Tiers and properties have already been explained in this and within the [[Making Items|item]] docs. Attack damage specifies how much damage to do above the current base set for that specific tier. Attack speed specifies the speed modifier to apply to your current attack speed (the base attack speed for a player is <code>4.0D</code>).  
  
−
{{Tip|content=If you decide to extend <code>DiggerItem</code>, there will be a fifth parameter which defines a tag of which blocks this item is effective on.}}
+
{{Tip|content=If you decide to extend <code>DiggerItem</code>, there will be a fifth parameter which defines a tag of which blocks this item is effective on. The naming convention of these tags is <code><modid>:mineable/<tool_name></code>. If this tag should be shared among other mods, the <code>forge</code> namespace should be used instead. }}
 +
 
 +
A tool's compatibility and partial implementation is defined by three methods:
 +
{| class="wikitable sortable" border=1
 +
!Method !!Return Type !!Description
 +
|-
 +
|  <code>getDestroySpeed</code>  ||  <code>Float</code>  ||  Defines whether a block will be mined faster than an empty hand or wrong tool.
 +
|-
 +
|  <code>isCorrectToolForDrops</code>  ||  <code>Boolean</code>  ||  Defines which blocks can drop loot with your tool. If this returns false, then the destroy speed will always slow down mining. This should only be overridden if your item is not a <code>DiggerItem</code> to implement <code>TierSortingRegistry#isCorrectTierForDrops</code> which handles this logic.
 +
|-
 +
|  <code>canPerformAction </code>  ||  <code>Boolean</code>  ||  Queries whether a block can perform the associated action. By default, this will do nothing on its own since a <code>ToolAction</code> is just a string. This can be combined with other logic to get the result of the performed action, usually by doing <code>BlockState#getToolModifiedState</code>. New tool actions can be defined via <code>ToolAction#get</code>.
 +
|-
 +
|}
  
 
== Registering ==
 
== Registering ==
  
−
A tool must be [[Registration|registered]] the same as an item. If using one of the subtypes of <code>DiggerItem</code>, that is all that is required. If not, you will need to chain <code>addToolType</code> onto your properties. This will take in a <code>ToolType</code> and a harvest level. The type is held within <code>ToolType</code> itself. The harvest level will be the value from your tier using <code>Tier#getLevel</code>.
+
A tool must be [[Registration|registered]] the same as an item. Defining the tool type and tier level is done via the mineable tag implemented on your tool and the tier tag on your <code>Tier</code>.
−
 
 
−
{{Tip|content=If you would like to use a custom tool type, you can call <code>ToolType::get</code>. All strings passed in should have their modid appended to them to remove any conflict issues (e.g. <code>examplemod_custom_tool_type</code>). If a standard implementation across mods is used for compatibility, no namespace is needed.}}
 
−
 
 
  
 
[[Category:Items]]
 
[[Category:Items]]

Latest revision as of 14:16, 1 August 2022

Tools are simply an extension of the Item class. Their implementations mainly rely on extending a specific class, the TierSortingRegistry, and tags.

Tier

To create any tool that does not derive from vanilla tiers, you will need your own implementation of Tier. This is the basis of which all tool levels are created. If you would like to use a vanilla tier, then you should specify one of the enums within Tiers.

Here are what each methods defines:

Method Return Type Description
getUses Integer The durability of all items in this tier.
getSpeed Float The efficiency multiplier of all items in this tier.
getAttackDamageBonus Float The base attack damage of all items in this tier.
getLevel Integer The harvest level of this tier. Vanilla uses values 0-4. As of 37.0.31, Forge deprecates this value in favor of the sorting registry system discussed below. This value will be used if the tier is not registered however.
getEnchantmentValue Integer How enchantable an item of this tier is.
getRepairIngredient Ingredient What ingredient can be used to repair this item.
getTag TagKey<Block> What blocks this tier can mine. This should only encompass those blocks which are specific for this tier. Any blocks below this tier will be declared while registering. The naming convention of this tag is <modid>:needs_<tier_name>_tool.

Important

An ingredient should be wrapped in a supplier to avoid calling the object directly. Tiers are loaded before registries are populated, so the call to the item needs to be deferred.
Forge has a implementation class called ForgeTier to create a common tier, though this does not have to be used.

TierSortingRegistry

For a tier to be used in the new system, they need to be registered before items most commonly by static initialization. A tier can be registered via TierSortingRegistry#registerTier. Any tier not defined in the sorting system will be defaulted to vanilla behavior.

This has four parameters:

Parameter Type Description
tier Tier The tier object being registered.
name ResourceLocation The name of the tier for dependency resolution.
after List<Object> The list of tiers to place this tier after or the tiers of the same level that are weaker than this one. This can either be a String, ResourceLocation, or Tier where the first two are located by the name parameter above.
before List<Object> The list of tiers to place this tier before or the tiers of the same level that are stronger than this one. This can either be a String, ResourceLocation, or Tier where the first two are located by the name parameter above.
If your tier is equivalent to another tier, then Tier#getTag should return an empty tag reference defined by BlockTags#create and have the equivalent tier be placed in the after list when registering. If the tier is a vanilla tier, you should also specify the next tier above in the before list.

DiggerItem

DiggerItem is the base of which all tool items extend. You do not necessarily have to use this or any of its supertypes/subtypes. However, it is convenient if you are looking for standard behavior. The subtypes normally referenced are AxeItem, HoeItem, PickaxeItem, ShovelItem.

Each tool has four parameters: tier, attack damage, attack speed, and properties. Tiers and properties have already been explained in this and within the item docs. Attack damage specifies how much damage to do above the current base set for that specific tier. Attack speed specifies the speed modifier to apply to your current attack speed (the base attack speed for a player is 4.0D).

If you decide to extend DiggerItem, there will be a fifth parameter which defines a tag of which blocks this item is effective on. The naming convention of these tags is <modid>:mineable/<tool_name>. If this tag should be shared among other mods, the forge namespace should be used instead.

A tool's compatibility and partial implementation is defined by three methods:

Method Return Type Description
getDestroySpeed Float Defines whether a block will be mined faster than an empty hand or wrong tool.
isCorrectToolForDrops Boolean Defines which blocks can drop loot with your tool. If this returns false, then the destroy speed will always slow down mining. This should only be overridden if your item is not a DiggerItem to implement TierSortingRegistry#isCorrectTierForDrops which handles this logic.
canPerformAction Boolean Queries whether a block can perform the associated action. By default, this will do nothing on its own since a ToolAction is just a string. This can be combined with other logic to get the result of the performed action, usually by doing BlockState#getToolModifiedState. New tool actions can be defined via ToolAction#get.

Registering

A tool must be registered the same as an item. Defining the tool type and tier level is done via the mineable tag implemented on your tool and the tier tag on your Tier.

Retrieved from ‘https://forge.gemwire.uk/index.php?title=Making_Tools&oldid=3297’