Item Durability

Item durability makes a tool or weapon wear down with use until it breaks. The last hit still lands and the item stops at exactly zero. A broken item does nothing until it is repaired, and every repair lowers the most it can hold, down to a floor, so mending is never free and never endless.

Also called: Weapon wear, Breakable items, Condition, Item repair.

A walrus blacksmith holds a sword across an anvil as its blade snaps in two and the tip spins through the air in a burst of sparks, while a gull apprentice watches with a whetstone. — Saltbrine Smithy, an invented seaside crafting game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Item Durability" to my game.

What it should do: Durability gives items a life. The player has to decide when to use a favourite tool, when to save it, and when to pay for a repair.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> sound
  sound: Sound
  worn: Worn
  broken: Broken
  sound --> worn: wears below the warning
  sound --> broken: one big hit
  worn --> broken: last bit used up
  worn --> sound: repaired above warning
  broken --> worn: small repair
  broken --> sound: big repair
```

Use these starting values:
- maxDurability: 100 units
- wornBelow: 25 units
- repairLoss: 8 units
- lowestMax: 30 units

Watch out for these common mistakes:
- The last hit is refused: Tell your AI: let the hit that finishes the item go through, stop at exactly zero, and only then call it broken.
- Durability goes below zero: Tell your AI: never let durability go below zero.
- A broken item still works: Tell your AI: check for broken in the one place every use goes through, not in each attack.
- Repairs make the item immortal: Tell your AI: lower the ceiling with each repair, down to a floor, so repairs always cost something.
- A repair of a sound item costs wear: Tell your AI: if there is nothing to mend, do nothing and take nothing.
- A repair makes a nearly new item worse: Tell your AI: work out the new ceiling first, and skip the repair if the item already has that much or more.
- A sliver keeps an item alive: Tell your AI: treat anything below a tiny level as zero, or count durability in whole units.
- The warning never shows: Tell your AI: show a warning below a set level, and never above the item's own ceiling.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

Durability gives items a life. The player has to decide when to use a favourite tool, when to save it, and when to pay for a repair.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Sound → Worn: wears below the warning
Sound → Broken: one big hit
Worn → Broken: last bit used up
Worn → Sound: repaired above warning
Broken → Worn: small repair
Broken → Sound: big repair

Good starting values

Value	Start with	What it changes
maxDurability	100 units	How much a new item holds. A bigger number makes the item last longer between repairs.
wornBelow	25 units	The warning level, a quarter of a new item by default. Below it the game shows that the item is nearly spent, so a break never comes as a surprise. It is held back to the item's own ceiling, so a fresh item is never marked as worn.
repairLoss	8 units	How much the ceiling drops with each repair. It gives every repair a price beyond coins. Zero means repairs are free of wear.
lowestMax	30 units	The floor for the ceiling. The item always stays usable for a short while after many repairs. It is held back to the full value, so the floor cannot sit above where the item starts.

What usually goes wrong

The last hit is refused

The item has 5 left and the hit costs 12. The game says the item is too worn and refuses, so the player is stuck with an item that has a little left but cannot be used.

Fix: Tell your AI: let the hit that finishes the item go through, stop at exactly zero, and only then call it broken.

Durability goes below zero

The hit takes more than what is left and the item ends at minus 7. A later repair of 10 then leaves it at 3, which is less than the player paid for.

Fix: Tell your AI: never let durability go below zero.

A broken item still works

A check for broken is missing on one of the ways to use the item, such as a charged attack or a thrown item. The player keeps using a broken sword through the side door.

Fix: Tell your AI: check for broken in the one place every use goes through, not in each attack.

Repairs make the item immortal

Every repair brings the item back to full, so a single sword can be used for ever for a few coins, and wear stops mattering.

Fix: Tell your AI: lower the ceiling with each repair, down to a floor, so repairs always cost something.

A repair of a sound item costs wear

The player clicks repair on a full item by mistake, or repairs one with a tiny scratch, and the ceiling drops for nothing.

Fix: Tell your AI: if there is nothing to mend, do nothing and take nothing.

A repair makes a nearly new item worse

The ceiling drops by 8 with each repair. An item with 95 of 100 left is repaired, the ceiling falls to 92, and the item is cut down to 92. The player paid for a repair and lost 3.

Fix: Tell your AI: work out the new ceiling first, and skip the repair if the item already has that much or more.

A sliver keeps an item alive

Many small uses leave a tiny rest like 0.0000000000000001. The item looks broken but still counts as working, or the other way round.

Fix: Tell your AI: treat anything below a tiny level as zero, or count durability in whole units.

The warning never shows

The item goes from fine to broken in one hit with no warning, or the warning level is above the full value and the new item shows as worn.

Fix: Tell your AI: show a warning below a set level, and never above the item's own ceiling.

How to check it works

A new item with 100 durability. you use it for 10: it has 90 left and the game reports a change of minus 10.
An item with 5 left. you use it for 12: the use goes through, the item ends at exactly 0, and it counts as broken.
A broken item. you try to use it: the use is refused and nothing changes.
An item with 30 left and a warning level of 25. you use it for 5, then for 1 more: at 25 it is still fine, and at 24 it is shown as worn.
An item with 40 of 100 left, and a repair that loses 8 from the ceiling. you repair it by 30: the ceiling is 92 and the item has 70.
An item with 85 of 100 left. you repair it by 50, and an item with 10 left by a full repair: both end at the new ceiling of 92 and no higher.
A new item. you wear it down and fully repair it three times: the ceiling is 92, then 84, then 76.
An item that is worn down and fully repaired again and again, with a floor of 30. you keep going for thirty rounds: the ceiling stops at 30 and a further repair costs no more.
An item that is at its ceiling. you try to repair it: nothing happens and the ceiling stays where it is.
An item with 95 of 100 left, and a repair that loses 8 from the ceiling. you try to repair it, and then try again with an item that has 91 left: the first is skipped and nothing changes, and the second ends at 92 with a ceiling of 92.
A broken item. you repair it by 20: it has 20, shows as worn, and can be used again.
An item with 50 left. you try to use it or repair it by 0, minus 5, a number that is not a number, or without end: nothing happens.
An item with 1 left. you use it ten times for a tenth each: it has exactly 0 and is broken.

Works well with

Currency Wallet: A repair that is paid for but not done, or done but not paid for, is a bug players find fast. Check the repair price against the wallet first, then pay and repair in one step.
Item Upgrades: If an upgrade fully repairs the item, players will upgrade only to get a free repair. Decide whether an upgrade also restores durability, and say so on the screen.
Inventory System: Merging a worn sword into a new one would either lose wear or create it. Keep durability with each single item, not with the stack, and do not merge items with different durability.

Common questions

how does item durability work in games

Each item holds a number that goes down with use. At zero it breaks and does nothing until it is repaired. A warning level below the full value shows the player that it is nearly spent.

what do i tell my ai to add durability to a weapon

Paste this: Add durability to weapons. Each use lowers it, the hit that takes it to zero still counts, and a broken weapon cannot be used until repaired. Each repair lowers the weapon's maximum a little, down to a floor, and a repair on an undamaged weapon does nothing.

should repairs restore an item completely

A repair that restores everything makes wear a small cost. Many games lower the maximum a little with every repair, so an item slowly ages and the player eventually replaces it.

why do some players hate durability

Items that break at a bad moment, with no warning, feel unfair. Show a warning level, let the last use still work, and make repairs easy to reach.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

17 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it