Tool Definitions 1.16-1.18

This page is about the JSON defining a tool properties from 1.16 to 1.18.2. For the format since 1.19, see Tool Definitions. 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. Stat Providers
  3. Harvest Logic
     1. Effective Tag
     2. Modified Tag
     3. Fixed Tier
  4. AOE Iterators
     1. Box AOE Iterator
     2. Circle AOE Iterator
     3. Tree AOE Iterator
     4. Veining AOE Iterator
     5. Fallback AOE Iterator
  5. Weapon Attacks
     1. Particle Weapon Attack
     2. Circle Weapon Attack
     3. Sweep Weapon Attack
  6. Tool Hooks
  7. Tool Modules
     1. Dual Interaction
     2. Preference Set Interaction

Format

A tool definition has the following format:

• (Object): The root tool definition object.
  • parts (Array): List of tool parts for each material index. Order determines the order of materials in all relevant contexts. If unset, tool will have no parts (which is either required or disallowed based on the tool’s stat provider).
    • (Object): A part requirement.
      • item (item ID): Tool part item for the index, must implement IToolPart and have a valid stat type for the tool’s stat provider. May not be set alongside stat.
      • stat (Stat Type): Stat type for the index, must be valid for the tool’s stat provider. May not be set alongside part.
      • weight (Integer): Weight of the part, used when there are multiple parts of the same type for a weighted average. If unset, defaults to 1.
  • stats (Object): Sets the base stats and multipliers for the tool. If unset, tool uses default values for all base stats and 1.0 multipliers.
    • base (Object): Mapping from tool stat IDs to the value to set for that stat. If unset, tool uses default values for all base stats.
      • <tool_stat> (Any): Sets the value for <tool_stat> to the given value. JSON type is determined by the stat.
    • 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.
  • slots (Slot Count): Starting modifier slots for this tool. If unset, the tool has no starting slots.
    • <slot> (Integer): Number of slots added of the slot type <slot>.
  • traits (Array): List of starting tool traits. If unset, defaults to an empty list.
    • (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.
  • tool_actions (Array): Since 1.18, set of tool actions which may be performed by this tool. If unset, defaults to an empty list.
    • (Tool Action): A tool action which may be performed by this tool.
  • harvest (Object): Since 1.18, sets various properties related to using the tool has a harvest tool. If unset, the tool uses default harvest logic and no AOE iterator.
    • logic (Harvest Logic): Determines the effective blocks for the tool along with additional mining speed bonuses. If unset, uses default harvest logic.
      • type (Resource Location): The harvest logic type.
      • Any other fields defined by the harvest logic type.
    • aoe (Object): Determines the shape of AOE mining on the tool. If unset, the tool has no AOE mining.
      • type (Resource Location): The AOE iterator type.
      • Any other fields defined by the AOE iterator type.
  • attack (Weapon Attack): Since 1.18, determines the shape of AOE mining on the tool. If unset, the tool has no AOE mining.
    • type (Resource Location): The weapon attack type.
    • Any other fields defined by the weapon attack type.
  • modules (Object): Since 1.18.2, map of additional tool hook ID to a tool module implementing that hook. If unset, tool implements no additional hooks.
    • <tool_hook> (Object): Module implementing the tool hook <tool_hook>.
      • type (Resource Location): The tool module type.
      • Any other fields defined by the tool module type.

Stat Providers

All tools must have a stat provider, which determines which tool parts are allowed and required, and how those parts are used to compute stats. Stat providers are defined in Java, meaning they cannot be configured for a given tool. The following stat providers are valid for tools requesting a stat provider:

• tconstruct:no_parts: Stat provider for a tool with no tool parts. Will cause the tool definition to error if the parts array has any values.
• tconstruct:melee_harvest: Stat provider for melee weapons and harvest tools. Requires one or more parts of stat type tconstruct:head, and also supports stat types tconstruct:handle and tconstruct:extra. See Melee/Harvest Stat Type for more info.
• tconstruct:ranged: Since 1.18.2, stat provider for ranged weapons such as bows. Requires one or more parts of stat type tconstruct:limb, and also supports stat types tconstruct:grip and tconstruct:bowstring. See Ranged Stat Type for more info.

In addition, the following stat providers are used but not registered (meaning they are not available to JSON Things):

• Skull Stats: Stat provider for slime skulls. Requires one or more parts of stat type tconstruct:skull. See Skull Stat Type for more info.

Harvest Logic

Since 1.18

Harvest logic determines which blocks a tool is effective on, additional modifiers to tool mining speed, and the maximum tier a tool may harvest. Tool harvest logic has the following format:

• (Object): A harvest logic object.
  • type (Resource Location): The harvest logic type.
  • Any other fields defined by the harvest logic type.

The following subsections describe the formats for specific harvest logic types.

Effective Tag

Tag harvest logic defines the most common form of harvest logic using a tag to describe effective blocks. It has the following format:

• (Object): A harvest logic object.
  • type (Resource Location): Always tconstruct:effective_tag.
  • tag (Block tag): Block tag containing the blocks this tool is effective on.

Modified Tag

The modified tag harvest logic defines harvest logic that is effective on a given tag, but also has additional mining speed modifiers to specific blocks. It is notably used by the mattock to allow mining some blocks that are not marked as effective a bit faster. It has the following format:

• (Object): A harvest logic object.
  • type (Resource Location): Always tconstruct:modified_tag.
  • tag (Block tag): Block tag containing the blocks this tool is effective on.
  • modifiers (Array): List of mining speed modifiers to apply.
    • modifier (Number): Multiplier to mining speed for any blocks matching the block predicate.
    • predicate (Block Predicate): Block predicate determining the blocks affected by this modifier. Uses the legacy Tinkers’ Construct block predicate.

Fixed Tier

The fixed tier harvest logic defines harvest logic that is effective on a given tag, but cannot mine above the listed mining tier. It is notably used by the pickadze to limit the mining tier to gold. It has the following format:

• (Object): A harvest logic object.
  • type (Resource Location): Always tconstruct:fixed_tier.
  • tag (Block tag): Block tag containing the blocks this tool is effective on.
  • tier (Mining Tier): Maximum mining tier for this tool.

AOE Iterators

Since 1.18

AOE iterators implement different shapes of multi-block harvest on tools, including with how they expand when the expander modifier is applied. They have the following base format:

• (Object): A AOE iterator object.
  • type (Resource Location): The AOE iterator type.
  • Any other fields defined by the AOE iterator type.

The following subsections describe the formats for specific AOE iterator types.

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.
  • 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.
  • 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.
  • 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.
  • max_distance (Integer): Maximum distance from the targeted block through matching blocks to include, defaults to 0. Summed with the expander level.

Fallback AOE Iterator

The fallback 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:fallback.
  • tag (Block Tag): Block tag to check.
  • if_matches (AOE Iterator): Iterator to run if tag matches the targeted block.
  • fallback (AOE Iterator): Iterator to run if tag does not match the targeted block.

Weapon Attacks

Since 1.18

Weapon attacks implement additional behavior that runs after attacking with the tool. They have the following base format:

• (Object): A weapon attack object.
  • type (Resource Location): The weapon attack type.
  • Any other fields defined by the weapon attack type.

The following subsections describe the formats for specific weapon attack types.

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: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.
  • 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.
  • range (Number): Range from the attacker to perform the sweep attack, defaults to 0. The expander level will be added to this range.

Tool Hooks

Since 1.18.2

Tool hooks are used to define additional behaviors on a tool beyond those covered in the default serializer. The following tool hooks exist:

• tconstruct:tool_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.

The reason there is only a single tool hook is because the system was implemented to allow flexability in addons, with the intention of eventually migrating tool type specific behaviors such as attack or harvest to tool hooks. This migration was ultimately completed in 1.19.

Tool Modules

Since 1.18.2

Tool modules are used to implement tool hooks. Unlike the system that would eventually come to 1.19, tool modules in 1.18 may only implement a single hook. They have the following base format:

• (Object): A tool module object.
  • type (Resource Location): The tool module type.
  • Any other fields defined by the tool module type.

The following subsections describe the format for specific tool modules.

Dual Interaction

The dual interaction module implements the tconstruct:tool_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).