Skip to content

Tools

Jump to bottom
hp-1e edited this page Oct 31, 2026 · 3 revisions

English | 中文

Tools

A custom tool is written in two places:

Where Contents How to apply
startup_scripts Register the item: type, parts, textures, names, book text Restart the game
ArsenalToolEvents.data in server_scripts Base stats, multipliers, modifier slots, traits, tool actions, area mining, modifiable tags /reload

Registering the item (startup)

StartupEvents.registry('item', event => {
  event.create('kubejs:war_pick', 'tinkers_kubejs_arsenal:tool')
    .part('head', 'tconstruct:pick_head')
    .part('handle', 'tconstruct:tool_handle')
    .part('binding', 'tconstruct:tool_binding')
    .brokenPart('head')
    .displayName('War Pick')
    .name('zh_cn', '战镐')
    .bookText('en_us', 'A heavy pickaxe that can mine and fight.')
    .bookProperty('en_us', 'Mines stone and ores')

  event.create('kubejs:rapier', 'tinkers_kubejs_arsenal:sword')
    .part('blade', 'tconstruct:small_blade')
    .part('guard', 'tconstruct:tool_binding')
    .part('handle', 'tconstruct:tool_handle')
})
Method Description
Type tinkers_kubejs_arsenal:tool A regular tool (Tinkers ModifiableItem)
Type tinkers_kubejs_arsenal:sword A sword (Tinkers ModifiableSwordItem), with sweeping and fast cobweb breaking
.part(layer, partItem) Adds parts in order; the order is the part index. Layer names must be unique within the tool, and the part item must be a Tinkers part
.partTexture(layer, texture) Grey base texture for a layer, default <namespace>:item/tool/<toolPath>/<layer>. Can point at an existing Tinkers texture such as tconstruct:item/tool/broad_axe/head
.brokenPart(layer) The layer has a broken texture <base>_broken, shown when durability runs out
.name(lang, text) Name in other languages; English via .displayName(...)
.bookText(lang, text) A paragraph on the book's tool page, once per call
.bookProperty(lang, text) One entry in the page's property list
.parentModel(...) KubeJS built-in, changes the held pose. Defaults: tconstruct:item/base/axe for tools, forge:item/default-tool for swords

All other KubeJS item builder methods still work. Tools never stack.

Tool stats (server)

ArsenalToolEvents.data(event => {
  event.create('kubejs:war_pick')
    .baseStat('attack_damage', 2)
    .baseStat('attack_speed', 1.0)
    .multiplyStat('durability', 1.2)
    .multiplyStat('mining_speed', 0.8)
    .slot('upgrades', 3)
    .slot('abilities', 1)
    .trait('tconstruct:pierce', 1)
    .toolActions('pickaxe_dig')
    .effective('minecraft:mineable/pickaxe')
    .boxAoeDirection('pitch')
    .boxAoeExpansion(0, 0, 2)
    .boxAoeExpansion(0, 1, 0)
    .modifiable('melee/weapon', 'harvest/primary', 'harvest/stone', 'aoe', 'small', 'interactable/right')
    .materialName(0)
})
Method Description
.baseStat(stat, value) Base stat, repeatable; gets tconstruct: when no namespace is given
.multiplyStat(stat, value) Stat multiplier
.slot(slotType, count) Modifier slots: upgrades abilities defense, etc.
.trait(modifier[, level]) Built-in trait
.toolActions(...) Tool actions such as pickaxe_dig axe_strip shovel_flatten
.effective(blockTag) Blocks this tool is effective on
.boxAoe(width, height, depth) Base box for area mining
.boxAoeExpansion(width, height, depth) One entry per level of Expanded, used in order; repeatable
.boxAoeDirection(direction) pitch height side_hit, default side_hit
.circleAoe(diameter, threeDimensional) Circle area mining
.veinAoe(maxDistance) Vein mining
.treeAoe(widthBonus, depthBonus) Tree felling
.sweepMelee(range) Sweep attack
.circleMelee(diameter) Circle area attack
.module(type, {...}) Any Tinkers tool module, written as is
.primaryPart(index) Primary part, default 0
.materialName(index) Tool name follows the material of this part
.modifiable(...) Adds tconstruct:modifiable/<path> tags, deciding which modifiers apply and which books list the tool
.layoutSlot(index, x, y) Moves a part slot in the station
.sortIndex(n) Station button order, default 100

Generated for you

  • Part stats (part_stats) and default materials (for creative and JEI);
  • The tconstruct:modifiable/multipart and modifiable/durability tags;
  • The station layout: 1 to 4 parts use the Tinkers preset positions. Tools with more than 4 parts need .layoutSlot for the extra parts;
  • The tool building recipe. Tinkers requires tools with more than 3 parts to be built on the Tinker's Anvil, not the Tinker Station.

Books

.modifiable(...) decides whether and where a tool shows up:

Tag Listed in
small Materials and You; Encyclopedia small tools
broad Mighty Smelting; Encyclopedia broad tools
special / ancient Encyclopedia staffs / ancient tools (Tinker's Gadgetry lists them too)

Without any of these tags the tool has no book page. Languages without .bookText show only the name and parts.

Creative tabs, JEI and recycling

  • Each tool appears in every material variant in the Tinkers "Tools" tab. JEI shows them automatically, and the building recipe is on the Tinkers "Tool Building" page.
  • Tinkers' built-in recycling recipe (Part Builder + venom bottle) breaks custom tools back into parts. Add .modifiable('unrecyclable') to prevent it.

Input checks

These cases log an English error and skip the tool:

  • the server definition's ID was not registered in a startup script;
  • a part item is not a Tinkers part;
  • a slot count is below 0, or a trait level is below 1;
  • a part index is out of range;
  • the tool has more than 4 parts but no .layoutSlot.

A tool registered in startup but missing from ArsenalToolEvents.data logs a warning that it has no stats and cannot be built.

English

中文

Clone this wiki locally