Modifiers

English | 中文

Modifiers

Defining a modifier (server, /reload)

ArsenalModifierEvents.data(event => {
  event.create('kubejs:vampire')
    .color('B02030')
    .name('Vampire').name('zh_cn', '吸血')
    .flavor('Blood for blood')
    .description('Deals more melee damage and heals on hit')
    .statBoost('tconstruct:attack_damage', 'add', 0.5)
    .icon('minecraft:item/redstone')
    .levelDisplay('default')
    .tooltipDisplay('always')
    .priority(100)
})

Method	Description
.color('RRGGBB')	Modifier color
.name/.flavor/.description([lang,] text)	Name, flavor line and description
.statBoost(toolStat, operation, perLevel)	Native Tinkers stat boost; operation is add percent multiply_base multiply_conditional multiply_all
.module(moduleType, {...})	Any Tinkers modifier module, written as is
.icon(sprites...)	Icon in the book and JEI; multiple sprites are layered in order. Sprites must be on the block atlas, such as minecraft:item/* or tconstruct:gui/modifiers/*; your own go in kubejs/assets/kubejs/textures/item/<name>.png as kubejs:item/<name>
.levelDisplay(value)	default single_level no_levels pluses
.tooltipDisplay(value)	always tinker_station never
.priority(n)	Modifier priority

Names, descriptions, colors and icons are synced to clients. To put the modifier on a tool you still need a modifier recipe (see Recipes), or test with /tconstruct modifiers @s add <id> <level>.

Modifier events (server)

Script-defined modifiers automatically carry an event module. Listen by modifier ID; handlers fire only for tools or armor with that modifier, and only on the server. After changing handler logic, /kubejs reload server_scripts is enough.

// While computing melee damage; damage can be changed
ArsenalModifierEvents.meleeDamage('kubejs:vampire', event => {
  event.damage = event.damage * (1 + 0.1 * event.level)
})
// After the hit; event.damage is the damage actually dealt
ArsenalModifierEvents.afterMeleeHit('kubejs:vampire', event => {
  event.attacker.heal(event.damage * 0.05 * event.level)
})
// Before armor reduction; fires once per armor piece with the modifier
ArsenalModifierEvents.hurt('kubejs:guard', event => {
  event.damage = Math.max(0, event.damage - event.level)
})

Event	When	Main fields
meleeDamage	Computing melee damage	Writable damage; baseDamage
afterMeleeHit	After a melee hit	damage is the damage dealt
projectileHit	Projectile hits an entity	projectile hitEntity attacker target blocked modifiers
blockBreak	After breaking a block	pos state world player entity isAOE() canHarvest() isEffective()
hurt	Before armor reduction	Writable damage; entity slot source directDamage
damage	After armor reduction	Same as hurt
toolStats	When the tool is rebuilt	add/percent/multiply/multiplyAll(stat, value), get(stat), hasTag(tag), modifierLevel(id), itemId
attributes	When the tool is rebuilt	add(attribute, amount, 'addition'|'multiply_base'|'multiply_total'), slot

• Every event has level, effectiveLevel and modifier; tool events also have tool.
• Attack events (meleeDamage, afterMeleeHit) have attacker player target livingTarget hand slot projectile critical fullyCharged extraAttack baseDamage damage.

Global tool stats

Applies to every Tinkers tool, with or without a modifier:

ArsenalToolEvents.stats(event => {
  if (event.hasTag('tconstruct:modifiable/harvest')) event.percent('tconstruct:mining_speed', 0.1)
  if (String(event.itemId) == 'kubejs:war_pick') event.add('tconstruct:attack_damage', 1)
})

ArsenalTool queries

Usable in any KubeJS event:

ArsenalTool.isTool(item)
ArsenalTool.modifierLevel(item, 'kubejs:vampire')
ArsenalTool.hasModifier(item, 'kubejs:vampire')
ArsenalTool.armorModifierLevel(entity, 'kubejs:guard')        // sum over all four armor pieces
ArsenalTool.projectileModifierLevel(arrow, 'kubejs:vampire')
ArsenalTool.getInt(item, 'kubejs:kills')                     // persistent tool data
ArsenalTool.setInt(item, 'kubejs:kills', 10)
ArsenalTool.getFloat(item, key) / ArsenalTool.setFloat(item, key, value)
ArsenalTool.rebuild(item)                                     // recompute stats with the current scripts

Notes

• Modifier events fire only for modifiers defined by this mod. For built-in Tinkers modifiers, combine ArsenalTool with KubeJS's own events.
• toolStats, attributes and ArsenalToolEvents.stats are computed and stored when the tool is rebuilt, so they can only depend on the tool's own data. Put conditions that change all the time into events like meleeDamage. After you change a script, existing tools update on their next rebuild (adding a modifier, repairing, ...) or when you call ArsenalTool.rebuild(item).
• The Tinker Station preview rebuilds tools on the client thread, so stat event handlers must not depend on world state or do expensive work.