Tool Definitions

This page is about the JSON defining a tool properties since 1.19.2. For the format from 1.16 to 1.18.2, see Tool Definitions 1.16-1.18. For the recipes defining tool crafting, see Tool Recipes.

Tool definitions are used to assign behaviors to a tool. Tool definitions are located under data/<domain>/tinkering/tool_definitions/<name>.json for the tool definition ID <domain>:<name>.

• Table of Contents
  1. Format
  2. Tool Hooks
     1. Behavior Hooks
     2. Material Hooks
     3. Mining Hooks
     4. Weapon Hooks
     5. Interaction Hooks
  3. Tool Modules
     1. Behavior Modules
        1. Set Stats
        2. Multiply Stats
        3. Modifier Slots
        4. Tool Actions
        5. Tool Traits
     2. Material Modules
        1. Part Stats
        2. Material Stats
        3. Tool Parts
        4. Material Traits
        5. Material Repair
        6. Default Materials
     3. Mining Modules
        1. Is Effective
        2. Mining Speed Modifier
        3. One Click Break
        4. Max Harvest Tier
     4. Weapon Modules
        1. Particle Weapon Attack
        2. Circle Weapon Attack
        3. Sweep Weapon Attack
     5. Interaction Modules
        1. Dual Interaction
        2. Preference Set Interaction
     6. AOE Modules
        1. Box AOE Iterator
        2. Circle AOE Iterator
        3. Tree AOE Iterator
        4. Veining AOE Iterator
        5. Conditional AOE Iterator

Format

A tool definition has the following format:

• (Object): The root tool definition object.
  • modules (Array): List of tool modules on the tool.
    • (Object): A single tool module.
      • type (Resource Location): The tool module type.
      • hooks (Array): List of tool hook IDs defining when this module is used. If unset, will use the default list of hooks defined by the tool module type.
        • (Resource Location): A tool hook ID. The tool module type must support the given hook.
      • Any other fields defined by the tool module type.

Tool Hooks

Tools hooks are entry points in code that call various behaviors defined as part of the tool. For most tool hooks, its possible for multiple tool modules to define that hook, in which case the behavior of those modules will be merged. All tool modules define a default list of tool hooks, so its typically not necessary to consider hooks when writing a tool definition. However, as mentioned in format, it is possible to override the default list of hooks for a module.

The following tool hooks are available by default:

Behavior Hooks

• tconstruct:tool_stats: Hook defining the stats for a tool. Used for base tool stats, tool stat multipliers, and material stats. If this hook is implemented by multiple tool modules, they are all applied in order.
• tconstruct:volatile_data: Hook allowing a module to add data to the tool’s volatile data. Used notably for starting modifier slots, along with select behaviors defined as a boolean in volatile data. If this hook is implemented by multiple tool modules, they are all applied in order.
• tconstruct:tool_actions: Hook defining Forge tool actions that can be performed by this tool. If this hook is implemented by multiple tool modules, any tool module stating an action is supported will mean its supported.
• tconstruct:tool_traits: Hook defining the traits on a tool based on it’s construction. Handles both default tool traits and material traits. If this hook is implemented by multiple tool modules, they are all applied in order.
• tconstruct:rebalanced_trait: Hook defining additional traits added the rebalanced modifier applies its trait variant. Supports any modules that support tconstruct:tool_traits. If this hook is implemented by multiple tool modules, they are all applied in order.

Material Hooks

• tconstruct:tool_materials: Hook for getting the list of material stat type requirements for the given tool. Used primarily for display and building example tools, along with as part of the tool casting recipe. This hook cannot be merged.
• tconstruct:tool_parts: Hook for getting the list of tool parts used for creating the given tool. Notably used for tool building recipes and part swapping alongside display. This hook cannot be merged.
• tconstruct:missing_materials: Hook called when a tool is missing material NBT to generate a list of materials; typically called when taking a tool from the creative menu or the /give command. This hook cannot be merged.
• tconstruct:material_repair: Hook defining repairing the tool using a tool material. Used both in the tinker station or tinker’s anvil for material item repair, and in the crafting table with repair kits. If this hook is implemented by multiple tool modules, the one that repairs the largest amount for the given material is used.

Mining Hooks

• tconstruct:is_effective: Hook defining the list of blocks a tool can effectively mine. Used by all harvest tools to select their primary tag. This hook cannot be merged.
• tconstruct:mining_tier: Hook allowing modifying the mining tier of a tool after stats apply. Used notably to limit the maximum harvest tier of a tool. If this hook is implemented by multiple modules, they are all applied in order.
• tconstruct:mining_speed: Hook allowing modifying the mining speed against a particular block beyond the default behavior of using the mining speed stat when effective. Used mainly to boost mining speed against blocks that are “ineffective”, such as in the mattock. If this hook is implemented by multiple tool modules, they are all applied in order.
• tconstruct:aoe_iterator: Hook defining the additional blocks that may be mined when mining an effective block. Used by AOE tools such as sledge hammers or excavators to define different shapes for their range. This hook cannot be merged.

Weapon Hooks

• tconstruct:after_melee_hit: Hook defining additional behaviors to run after successfully damaging an entity. Used notably by AOE weapons to damage additional targets. If this hook is implemented by multiple tool modules,they all are applied in order.

Interaction Hooks

• tconstruct:interaction: Hook defining whether a given interaction modifier is allowed to run on the tool. Used to control whether interaction modifiers run on “attack” or “interact” for tools that support multiple methods of interaction, or to ensure only blocking runs on “interact” on shields. This hook cannot be merged.

Tool Modules

The following subsections describe the JSON format for all tool modules that exist by default in Tinkers’ Construct.

Behavior Modules

Behaivor modules define core tool behaviors.

Set Stats

The set stats module is used to set the base stats for a tool. In addition, its used by tools with no tool materials to set the general stats. This module by default implements the hook tconstruct:tool_stats, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:base_stats.
  • stats (Object): Mapping from tool stat IDs to the value to set for that stat.
    • <tool_stat> (Any): Sets the value for <tool_stat> to the given value. JSON type is determined by the stat.

Stats from this module are applied using the “update” method, meaning for numeric stats they are summed with the default value of the stat ignored.

Multiply Stats

The multiply stats module is used to set the stat multipliers for a tool, which multiply stats from all sources including both modifiers and conditional stats. This module by default implements the hook tconstruct:tool_stats, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:multiply_stats.
  • multipliers (Object): Mapping from numeric tool stat IDs to the multiplier value.
    • <tool_stat> (Number): Sets the multiplier for <tool_stat> to the given value.

Modifier Slots

The modifier slots module is used to set the tool’s starting modifier slots. This module by default implements the hook tconstruct:volatile_data, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:modifier_slots.
  • slots (Slot Count): Starting modifier slots for this tool.
    • <slot> (Integer): Number of slots added of the slot type <slot>.

Tool Actions

The tool actions module is used to add tool actions which can be performed by this tool. This is typically used to define actions related to a tool’s core behaviors such as blocks it can mine, as behaviors such as tilling are handled by modifiers. This module by default implements the hook tconstruct:tool_actions, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:tool_actions.
  • tool_actions (Array): Set of tool actions which may be performed by this tool.
    • (Tool Action): A tool action which may be performed by this tool.

Tool Traits

The tool traits module is used to define unconditional traits on a tool, such as cleavers starting with severing. This module by default implements the hook tconstruct:tool_traits, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:traits.
  • traits (Array): List of starting tool traits.
    • (Object): A tool trait.
      • name (Modifier ID): Modifier to apply as a trait.
      • level (Integer): Level of the modifier to apply. If unset, defaults to 1.

Material Modules

Material modules define behavior related to tool materials.

Part Stats

The parts stats module defines all behavior related to tool materials for a tool.

This module by default implements the tconstruct:tool_stats, tconstruct:tool_traits, tconstruct:tool_materials, tconstruct:tool_parts, and tconstruct:material_repair hooks. It has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:part_stats.
  • parts (Array): List of tool parts for each material index. Order determines the order of materials in all relevant contexts.
    • (item ID): Compact format to specify a tool part item for the index. Item must implement IToolPart.
    • (Object): Object format to specify a tool part item.
      • item (item ID): Tool part item for the index, must implement IToolPart.
      • scale (Number): Scaling value for the material stat type from this part. If unset, defaults to 1.
  • primary_part (Integer): Index of the tool part to use for traits for the tconstruct:rebalanced_trait hook. Defaults to 0, setting to -1 will provide no rebalanced trait.

Material Stats

The material stats module defines all behavior related to tool materials for a tool except tool parts, used for unconventional tools that are crafted by other means. For conventional tools, its typically better to use part stats.

This module by default implements the tconstruct:tool_stats, tconstruct:tool_traits, tconstruct:tool_materials, and tconstruct:material_repair hooks. It has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:material_stats.
  • stat_types (Array): List of stat types for each material index. Order determines the order of materials in all relevant contexts.
    • (Stat Type): Compact format to specify a stat type for the index.
    • (Object): Object format to specify a stat type.
      • stat (Stat Type): Stat type for the index.
      • scale (Number): Scaling value for the stat type. If unset, defaults to 1.
  • primary_part (Integer): Index of the stat type to use for traits for the tconstruct:rebalanced_trait hook. Defaults to 0, setting to -1 will provide no rebalanced trait.

Tool Parts

The tool parts module is used to specify the list of tool parts for a tool separately from the part stats module. It is designed to be used alongside the material stats module to allow part swapping on some but not all materials in a tool.

This module by default implements the tconstruct:tool_parts hook, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:tool_parts.
  • parts (Array): List of tool parts for each material index. May be shorter than the list of stats defined by the material stats module, but should not be longer.
    • (item ID): Tool part item for the given index. Item must implement IToolPart.

Material Traits

The material traits module is a module used internally by the part stats and material stats modules to implement the tconstruct:rebalanced_trait hook. IT is provided separately in case an addon wishes to create something similar to rebalanced traits; in most cases its better to use one of the above modules to handle material traits.

When used directly, the material traits module implements the tconstruct:tool_traits hook by default, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:material_traits.
  • material_index (Integer): Index of the material to use for the traits list.
  • stat_type (Stat Type): Stat type determining which trait list is fetched for the relevant material.

Material Repair

The material repair module defines repairing a tool using a material that is not part of it’s material list. It is primarily used for tools with no materials such as traveler’s gear, but may be used on a tool with materials to define a material that always can repair the tool.

The material repair module implements the tconstruct:material_repair hook by default, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:material_repair.
  • material (Material ID): Material used to repair this tool.
  • durability (Integer): Amount of durability restored when repairing with this material. May not be set alongside stat_type.
  • stat_type (Stat Type): Stat type used to lookup the repair durability when repairing with this material. May not be set alongside durability.

Default Materials

The default materials module defines a list of materials to use by default if a tool has no materials. This module implements the tconstruct:missing_materials hook, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:material_repair.
  • materials (Array): List of material providers. Should be the same length as the material list in the above modules.
    • (Material Provider): Material provider for the given index. Uses the stat type from the relevant index.

Mining Modules

Mining modules implement behaviors related to using the tool to break blocks.

Is Effective

The is effective module makes a tool effective against the listed block types. It by default implements the tconstruct:is_effective hook, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:is_effective.
  • ignore_tier (Boolean): If true, ignores the required mining tier to mine the block in deciding whether the tool is effective. If false (default), the tool is only effective if the mining tier is high enough to break the block.
  • predicate_type (Resource Location): Block predicate serializer ID determining the list of blocks this tool is effective on.
  • Any other fields defined by the block predicate serializer.

Mining Speed Modifier

The mining speed modifier module multiplies the mining speed on matching blocks. It is used for special interactions between certain tool types and blocks, either making the tool faster on certain effective blocks, or mine ineffective blocks at a speed above not using a tool.

The mining speed modifier implements the tconstruct:mining_speed hook by default, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:mining_speed_modifier.
  • modifier (Number): Multiplier to mining speed for any blocks matching the block predicate.
  • predicate_type (Resource Location): Block predicate serializer ID determining the list of blocks to modify.
  • Any other fields defined by the block predicate serializer.

One Click Break

The one click break module makes the tool fast enough to break blocks matching the predicate in one click, without being fast enough to instantly break the block. It is used by a potentially upcoming tool which is designed for carefully deconstructing smeltery blocks.

The one click break implements the tconstruct:mining_speed hook by default, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:one_click_break.
  • predicate_type (Resource Location): Block predicate serializer ID determining the list of blocks to modify.
  • Any other fields defined by the block predicate serializer.

Max Harvest Tier

The max harvest tier module limits the maximum harvest tier for a tool to the given tier. It is used by the pickadze to restrict the list of blocks it can harvest compared to a pickaxe or a mattock.

The max harvest tier module implements the tconstruct:mining_tier hook by default, and has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:max_tier.
  • tier (harvest tier): Maximum harvest tier allowed on this tool. Uses the Forge tier sorting registry to decide which tier is smaller.

Weapon Modules

Weapon modules implement behaviors related to using the tool as a weapon. All current weapon modules by default implement the tconstruct:after_melee_hit hook.

Particle Weapon Attack

The particle weapon attack module defines a particle to display whenever attacking with this weapon while fully charged. It has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:melee_particle.
  • particle (particle ID): Particle to display on fully charged attacks. Must be a SimpleParticleType.

Circle Weapon Attack

The circle weapon attack defines an AOE attack centered on the target when the weapon is fully charged. All targets will be targeted by a full attack, meaning modifiers will apply to each target separately but more durability is consumed.

The circle weapon attack has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:circle_melee.
  • diameter (Number): Range from the original target to also hit with the attack, defaults to 0. The expander level will add to this range.

Sweep Weapon Attack

The sweep weapon attack grants a tool a sweeping attack, similar to the vanilla sword’s sweep attack. The attack AOE is centered on the attacker, and all targets are dealt damage based damage dealt to the main target scaled by the level of sweeping edge. Modifiers are not applied to additional target, and conditional damage such a smite only considers the primary target.

The sweep weapon attack has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:sweep_melee.
  • range (Number): Range from the attacker to perform the sweep attack, defaults to 0. The expander level will be added to this range.

Interaction Modules

Interaction modules implement behaviors related to interaction modifiers using the tool. All interaction modules by default implement the tconstruct:interaction hook.

Dual Interaction

The dual interaction module implements the tconstruct:interaction hook for a tool that can interact on both “attack” (left click) and “interact” (right click). By default, all interaction modifiers will run on “interact” with this hook, but any modifiers defined in the tool’s persistent data set tconstruct:attack_modifiers will trigger on attack instead. Modifiers are added to that set using the modifier set recipe.

The dual interaction module has a type of tconstruct:dual_option_interaction, and no additional fields.

Preference Set Interaction

The preference set interaction module implements the tconstruct:interaction hook for a tool that can interact on both “attack” (left click) and “interact” (right click). This module defines a set of modifiers which interact on one source, and all modifiers outside that set interact on the other source. It is notably used on shields, which set “interact” to the blocking modifier, and run all other interaction modifiers on left click.

The preference set interaction module has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:preference_set_interaction.
  • preferred_modifiers (Modifier Predicate): Predicate matching modifiers to put on preferred_source. Any modifiers that don’t match the predicate will interact on the other source.
  • preferred_source (String): Interaction source to use for preferred_modifiers. May be right_click (for interact) or left_click (for attack).

AOE Modules

AOE modules implement different shapes of AOE iterators on tools and how they expand when the expander modifier is applied. All AOE modules by default implement tconstruct:aoe_iterator.

In addition to being defined as tool modules, all AOE modules are registered to a separate registry of AOE iterators, used in the conditional AOE iterator module.

Box AOE Iterator

The box AOE iterator defines tool AOE in a cube, with the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:box_aoe.
  • bonus (Object): Box size expansion applied when the tool has no expanders.
    • width (Integer): Base box width radius, defaults to 0.
    • height (Integer): Base box height radius, defaults to 0.
    • depth (Integer): Base box depth, defaults to 0.
  • expansions (Array): List of expansions to apply at each level. If the level exceeds the list size, will cycle through the list again. For example, if the list size is 2 and the level is 3, the first expansion is applied twice and the second once.
    • (Object): Box size expansion for a level.
      • width (Integer): Level box width radius, defaults to 0.
      • height (Integer): Level box height radius, defaults to 0.
      • depth (Integer): Level box depth, defaults to 0.
  • expansion_direction (Resource Location): Determines how width, height, and depth are oriented with respect to the player’s position and targeted block. By default, the following options exist:
    • tconstruct:side_hit: Orients based on the targeted block face. width is to the left/right of the target, height is above/below the target, and depth back behind the target.
    • tconstruct:pitch: Orients based on the direction the player is facing. width is to the left/right of the player view, height is above/below the player view, and depth back behind the player view.
    • tconstruct:height: Orients height to the Y axis, width to the left/right of the side hit, and depth behind the target. When targeting the top or bottom of a block, width orients to the left/right of the player view, and depth behind the player view.

Circle AOE Iterator

The circle AOE iterator defines tool AOE in a radius around the targeted block, with the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:circle_aoe.
  • diameter (String): Base diameter, summed with the expander value for the total size.
  • 3D (Boolean): If true, AOE area will be a 3D half sphere. If false (default), will be a circle.

Tree AOE Iterator

The tree AOE iterator defines tool AOE that targets all matching logs in a tree. It has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:tree_aoe.
  • width_bonus (Integer): Bonus width radius applied at level 0, defaults to 0. Every other level starting with the first increases width by 1.
  • depth_bonus (Integer): Bonus depth applied at level 0, defaults to 0. Every other level starting with the second increases depth by 1.

Veining AOE Iterator

The veining AOE iterator defines tool AOE that targets all matching connected blocks up to a given recursion depth.

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:vein_aoe.
  • max_distance (Integer): Maximum distance from the targeted block through matching blocks to include, defaults to 0. Summed with the expander level.

Conditional AOE Iterator

The conditional AOE iterator nests two AOE iterators, using the first if the targeted block matches the given predicate, or the fallback if it does not match the predicate. It has the following format:

• (Object): A tool module object.
  • type (Resource Location): Always tconstruct:conditional_aoe.
  • condition (Block Predicate): Block condition to check.
  • if_true (AOE Iterator): Iterator to run if condition matches the targeted block.
  • if_false (AOE Iterator): Iterator to run if condition does not match the targeted block.