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.
| Role | Feels like | Damage / speed | Modifiers | Damage per second |
|---|---|---|---|---|
| Dagger | Fast, light, pressure | 4 / 2.0 | +3 / −2.0 | 8 |
| Longsword | Balanced and readable | 7 / 1.6 | +6 / −2.4 | 11.2 |
| War hammer | Slow, heavy, punishing | 11 / 0.8 | +10 / −3.2 | 8.8 |
| Ritual staff | Mostly a prop | 3 / 1.2 | +2 / −2.8 | 3.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
- A sword or an axe already behaves like a weapon: it has durability, takes weapon enchantments in an anvil, and an axe knocks a raised shield out of use.
- A stick, a bone or a blaze rod works for props and staffs, but has no durability and stacks. Add
max_stack_size=1andmax_damage; a command that makes an item both stackable and damageable is refused. From 1.21.5 theweaponcomponent sets how much durability each hit costs.
/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.