> For the complete documentation index, see [llms.txt](https://obey.gitbook.io/wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://obey.gitbook.io/wiki/tools/features/usage-and-durability.md).

# Usage & Durability

Documentation for CrownTools usage modes, dynamic durability synchronization, and broken states.

CrownTools features a custom durability system stored in Persistent Data Containers (PDC), completely replacing standard Vanilla Minecraft tool damage.

***

## Usage Modes

Custom tools can be created in one of two durability modes when given via `/tools give`:

### 1. Count-Based Mode (`USES`)

* The tool has a specific maximum usage limit (e.g. `500` uses).
* Each action (mining blocks, boosting flight, soaking/placing liquid) increments the internal uses counter by `1`.
* Setting value to `-1` creates a tool with **Unlimited** uses.

### 2. Time-Based Mode (`TIME`)

* The tool is valid for a specific duration after creation (e.g. `7d` for 7 days, `1h` for 1 hour).
* Expiration timestamp is stored on creation (`ct_valid_until`).
* Once the current system time exceeds the expiration timestamp, the tool becomes expired/broken.
* Setting value to `-1` creates a tool with **Unlimited** duration.

***

## Durability Bar Synchronization

* Vanilla item damage is intercepted and blocked by `BlockingListener` (`PlayerItemDamageEvent`).
* CrownTools dynamically syncs the visual item durability bar (damage indicator) based on remaining uses or remaining time ratio: $$\text{Damage} = \text{MaxDurability} \times \left(1 - \frac{\text{Remaining}}{\text{Max}}\right)$$
* As the tool is used or time elapses, the durability bar drains smoothly in real-time.

***

## Broken State & Destruction

When a tool reaches `0` remaining uses or its time expires:

### Mode A: Remove on Destruction (`remove-on-destruction: true`)

* The tool is permanently removed from the player's inventory.
* Broadcasts/plays the `tool-removed` sound effect and sends the `tool-removed` chat message.

### Mode B: Broken State (`remove-on-destruction: false`)

* The tool enters a **Broken** state and remains in the inventory.
* Display name updates to `<tool>-display-name-broken` (e.g. `DRILL [Broken]`).
* Lore switches to broken lore displaying the repair cost and repair instructions (`Shift Rightclick to Repair`).
* The item durability bar shows empty.
* Attempting to use a broken tool cancels the action, sends the `tool-broken` message, and plays the `tool-broken` sound effect.
* If `repairable: true` is configured, the player can repair the tool to restore full functionality.