Adding a Tool to Tinkers' Construct

See also: Creating a Low Code Mod

This page covers all related elements for adding a new tool to Tinkers’ Construct.

Adding a tool requires registering a new item. This requires either a Java mod, or Json Things to register the appropriate items. Details on each will be provided in the appropriate subsections. If you are creating a Java addon, all resources listed below can be generated using our datagen setup; the best examples of this are in Tinkers’ Construct itself.

Often, when creating new tools it is desirable to also create a new tool part. Details on how to do that is covered on Adding a Tool Part.

• Table of Contents
  1. Items
     1. Java
     2. Thing Packs
  2. Data packs
     1. Tool Definitions
     2. Item Tags
     3. Recipes
  3. Resource packs
     1. Models
        1. Armor Models
        2. Material textures
     2. Localization
     3. Book
        1. Tools
        2. Armor
        3. Examples

Items

Tool items must be registered either in Java or using Json Things.

Java

Items registered using Java have a lot of flexibility, as you are free to implement the IModifiable interface on any item class. For most addons however, one of the standard item classes should be sufficient:

• ModifiableItem: handles most tool types, including melee weapons, harvest tools, staffs, and shields.
• ModifiableBowItem: Implements a standard bow that draws back and releases arrows.
• ModifiableCrossbowItem: Implements a bow which holds the arrow after charging and fires on an additional click.
• ModifiableArmorItem: Implements a standard armor piece using a single layered texture. Ideal for simple armor sets without any materials or modifiers that altar their appearance.
• MultilayerArmorItem: Implements an armor piece using our armor model system. Allows adding material textures and extra modifier based textures, such as golden or dyed.

Outside of custom implementations, the item class has minimal code as the majority of behavior is added through data packs.

Thing Packs

See also: Json Things Items

Items registered using Json Things are located in things/<domain>/item/<name>.json for the item <domain>:<name> in a Thing Pack. The following item types are available for adding new tools:

• Standard Tool: handles most tool types, including melee weapons, harvest tools, staffs, and shields. For an example, see the halberd from Tinkers’ Things.
• Bow: The bow type is used for implementing a standard bow that draws back and releases arrows. For an example, see the shortbow from Tinkers’ Things.
• Crossbow: the crossbow type is for implementing a bow which holds the arrow after charging and fires on an additional click. For an example, see the blowpipe from Tinkers’ Things.
• Armor: Armor has two different types based on whether you wish to use armor models or a single texture with no materials or modifiers. The same type will be used for all 4 armor pieces, just specifying the slot in the definition. For an example, see makeshift helmet from Tinkers’ Things.

Tools tend to be pretty simple in Thing Packs as the majority of the behavior is added through data packs.

Data packs

Data packs are used to define behavior, recipes, and in game documentation.

Tool Definitions

The majority of behavior for a tool is defined by its tool definition. This includes starting stats, starting modifier slots, tool traits, whether it uses tool parts, and more. The tool definition page has a full list of behaviors you can apply to your tool.

Tinkers’ Things has many examples of different tool definitions, with some highlights including:

• Chisel: Simple mining tool with no materials. Demonstrates repairing non-material tools, tool stats, tool traits, starting modifier slots, and harvest modules.
• Halberd: Melee weapon with multiple tool parts. Demonstrates a tool part based tool with additional base stats and stat multipliers.
• Shortbow: Additional tool part example as a ranged weapon. The primary difference from the halverd is the choice of tool parts, which applies ranged stats instead of melee stats.
• Laminar Shield: Example shield, with the blocking ability and left click interaction.
• Amethyst Staff: Example staff item with dual left and right click interaction, this one reusing some ranged material stats to improve the staff.
• Knapsack: Non-standard tool item which simply uses the inventory modifiers and no other stats to create a bag.

Item Tags

While the majority of tool behavior is added though tool definitions, item tags add important functionality to a tool, including support for different tool stats and their recipes. For a list of relevant item tags, check out tool tags. For some examples of item tags, check out Tinkers’ Things.

Recipes

See also: Recipe Format

In order to make tools craftable, its necessary to give it a recipe. For tools with no materials, you can simply use any existing recipe type, including crafting table. As an example, the chisel from Tinkers’ Things uses a shaped crafting table recipe.

For tools with materials, you have three options for crafting:

• Tool Building: Defines crafting the tool in the tinker station or tinker’s anvil. The availability of the recipe in the tinker station is based on the number of inputs. For an example, see the amethyst staff from Tinkers’ Things.
• Tool Casting: Defines crafting the tool in the casting table from a single tool part and castable materials. Limits material options, but can add variety to tool crafting. For an example, see the laminar shield from Tinkers’ Things.
• For tools with just 1 material, you could manually set the NBT and use another recipe type. For instance, slimeskulls use the casting table by manually setting the NBT on the output. This approach does not scale well to multiple materials on the item.

For tools crafted in the tinker station or tinker’s anvil, it is advised to also add a station slot layout to add a button for players to craft your tool. This button is purely documentation, it has no impact on the recipes. Note you can use a single layout for multiple tool recipes, such as is done for plate armor in the base mod. See the amethyst staff and laminar armor from Tinkers’ Things for example slot layouts.

Resource packs

Resource packs are used to define tool visuals, including textures and translations.

Models

For the tool item to display properly, it is necessary to create a tool model under assets/<domain>/models/item. This model handles both tools with and without materials, and notably handles modifier textures. The textures required will vary based on the model definition.

For some example tool models from Tinkers’ Things, see:

• Chisel: Example tool model with no materials.
• Halberd: Example tool model with materials.

Note for most tool models, it is necessary to create multiple model JSONs for different item overrides. At minimum you typically want a broken model, though held tools also tend to want at minimum a blocking variant.

Armor Models

When defining an armor item using the multilayer armor item, it is necessary to define an armor model. For examples of armor models from Tinkers’ Things, see:

• Makeshift: Armor model with no materials, but supports embellishments and the golden modifier.
• Laminar: Armor model with 3 materials.

Material textures

The textures for a tool parts are not typically created by hand. Rather, we create a gray scale version of the texture, then take advantage of texture generators to generate the variants. For information on using texture generators in a Java mod, see Texture Generators.

For information on using texture generators in a low code mod, see the Generate Part Textures Command. For an example part texture JSON file, see Tinkers’ Things.

Localization

The tool item with ID <domain>:<name> uses the following translation keys in assets/<domain>/lang/en_us.json and other languages:

• item.<domain>.<name>: display name of the tool.
• item.<domain>.<name>.description: Conventional translation key of the tool in the tinker station and tinker’s anvil. Unneeded if the tool has no slot layout.

Book

In order for your tool to show in the book, it is first necessary to verify you added it to the proper book tool tags. Based on the tag you choose, you will need to create a JSON in the appropriate location under assets/tconstruct/book/.

We currently do not have documentation on the book format, so your best reference is copying and modifying an example page.

Tools

Based on the item tag you choose for your tool, it will have a page in the encyclopedia, plus one of materials and you, mighty smelting, and tinker’s gadgetry:

• tconstruct:modifiable/small: Tool will have a page under assets/tconstruct/book/materials_and_you/en_us/tools/<domain>_<name>.json and assets/tconstruct/book/encyclopedia/en_us/tools/small/<domain>_<name>.json
• tconstruct:modifiable/broad: Tool will have a page under assets/tconstruct/book/mighty_smelting/en_us/tools/<domain>_<name>.json and assets/tconstruct/book/encyclopedia/en_us/tools/broad/<domain>_<name>.json
• tconstruct:modifiable/special: Tool will have a page under assets/tconstruct/book/tinkers_gadgetry/en_us/staffs/<domain>_<name>.json and assets/tconstruct/book/encyclopedia/en_us/tools/staff/<domain>_<name>.json
• tconstruct:modifiable/ancient: Tool will have a page under assets/tconstruct/book/tinkers_gadgetry/en_us/ancient/<domain>_<name>.json and assets/tconstruct/book/encyclopedia/en_us/tools/ancient/<domain>_<name>.json

Armor

The armor item <domain>:<name> in any armor tag will have a JSON under assets/tconstruct/book/encyclopedia/en_us/armor/<domain>_<name>.json. In addition, you will need a non-encyclopedia page under assets/tconstruct/book/<book>/en_us/armor/<domain>_<name>.json for armor items in the tag tconstruct:modifiable/book_armor/<book>.

For example pages from Tinkers’ Things, see:

• Encyclopedia: all armor from the addon.
• Materials and You: makeshift armor in the Materials and You tag.
• Mighty Smelting: laminar armor in the Mighty Smelting tag.

Examples

For examples from Tinkers’ Things, see:

• Encyclopedia: All tools and armor.
• Materials and You: Small tools and makeshift armor.
• Mighty Smelting: Broad tools and laminar armor.
• Tinker’s Gadgetry: Special tools.

Tinkers’ Things does not currently have an ancient tool example.