← All articles

How to make a custom weapon: damage, attack speed and a look players recognise

A custom weapon is a vanilla item with attribute modifiers for damage and speed, a name, and usually its own model. The numbers are easier than they look once you know what the player starts with, and the command differs between versions mostly in how the modifiers are written.

Checked for versions: Java Edition 1.20 to 26.3.

The numbers behind every melee weapon

A player starts with 1 attack damage and an attack speed of 4. A weapon adds modifiers on top: a vanilla iron sword adds +5 damage and −2.4 speed, which is where its 6 damage and 1.6 speed come from. So to hit for 7, add 6; to swing 1.6 times a second, add −2.4.

RoleFeels likeDamage / speedModifiersDamage per second
DaggerFast, light, pressure4 / 2.0+3 / −2.08
LongswordBalanced and readable7 / 1.6+6 / −2.411.2
War hammerSlow, heavy, punishing11 / 0.8+10 / −3.28.8
Ritual staffMostly a prop3 / 1.2+2 / −2.83.6

Damage per second is damage times speed at full charge. It shows why a hammer that hits hardest is not the strongest weapon in a long fight, and why its big single hits feel different in a duel.

Setting modifiers replaces the defaults

Once you give an item attribute modifiers, its built-in ones are gone. A diamond sword given only +2 luck hits like an empty hand. Always set both damage and speed, even when you only meant to change one.

Use the IDs minecraft:base_attack_damage and minecraft:base_attack_speed for those two modifiers and the tooltip shows totals, "7 Attack Damage", the way a vanilla sword does; with any other ID it shows "+6 Attack Damage".

The same longsword in each version

1.21.5 – 26.x: modifiers are a plain list and attribute IDs have no prefix.

/give @p minecraft:iron_sword[minecraft:custom_name={text:"Guild longsword",italic:false},minecraft:attribute_modifiers=[{type:"minecraft:attack_damage",id:"minecraft:base_attack_damage",amount:6,operation:"add_value",slot:"mainhand"},{type:"minecraft:attack_speed",id:"minecraft:base_attack_speed",amount:-2.4,operation:"add_value",slot:"mainhand"}]] 1

1.21.2 – 1.21.4: the list sits inside {modifiers:[…]} and the name is a JSON string. On 1.21 – 1.21.1, also write the attribute types as minecraft:generic.attack_damage and minecraft:generic.attack_speed.

/give @p minecraft:iron_sword[minecraft:custom_name='{"text":"Guild longsword","italic":false}',minecraft:attribute_modifiers={modifiers:[{type:"minecraft:attack_damage",id:"minecraft:base_attack_damage",amount:6,operation:"add_value",slot:"mainhand"},{type:"minecraft:attack_speed",id:"minecraft:base_attack_speed",amount:-2.4,operation:"add_value",slot:"mainhand"}]}] 1

Before 1.20.5: NBT with a name and a UUID per modifier.

/give @p minecraft:iron_sword{display:{Name:'{"text":"Guild longsword","italic":false}'},AttributeModifiers:[{AttributeName:"generic.attack_damage",Name:"guild_damage",Amount:6,Operation:0,UUID:[I;1,1,1,1],Slot:"mainhand"},{AttributeName:"generic.attack_speed",Name:"guild_speed",Amount:-2.4,Operation:0,UUID:[I;1,1,1,2],Slot:"mainhand"}]} 1

1.20.5 – 1.20.6 sit in between: components like 1.21, but each modifier needs a uuid and a name instead of an id.

Choosing the base item

/give @p minecraft:stick[minecraft:max_stack_size=1,minecraft:max_damage=250,minecraft:weapon={item_damage_per_attack:1},minecraft:custom_name={text:"Ritual staff",italic:false},minecraft:attribute_modifiers=[{type:"minecraft:attack_damage",id:"minecraft:base_attack_damage",amount:2,operation:"add_value",slot:"mainhand"},{type:"minecraft:attack_speed",id:"minecraft:base_attack_speed",amount:-2.8,operation:"add_value",slot:"mainhand"}]] 1

A weapon players can recognise

If two weapons share the same texture, players will mix them up whatever their stats are. Give each one its own model: from 1.21.4 the item points to an item definition with item_model (the item model builder writes that file), before that a CustomModelData number picks a model through the pack's overrides. A short name and one lore line about what the weapon is for do the rest.

Hiding the stat lines

For a mystery relic you may not want the numbers in the tooltip. From 1.21.5 add tooltip_display={hidden_components:["minecraft:attribute_modifiers"]}; on 1.20.5 – 1.21.4 put show_in_tooltip:false inside attribute_modifiers; before 1.20.5 use HideFlags:2.

FAQ

Can a weapon be unbreakable?

Yes, add unbreakable={}. On a server economy that removes a reason to replace it, so keep it for rare rewards.

Do enchantments still work on top?

Yes. Sharpness and the rest add to the modified damage; the conflicts article lists which ones cannot go together.

How do I balance several custom weapons?

Put them in one table with damage, speed and damage per second, then test each in the same fight. The spreadsheet version and the in-game feel are rarely the same on the first try.