# Cooldowns

> Scoreboard-based cooldown system with the Kore OOP module - register, start, check, and reset cooldowns.

Updated 2026-10-07. Canonical: https://kore.ayfri.com/docs/oop/cooldowns

Cooldowns use a [scoreboard objective](https://minecraft.wiki/w/Scoreboard) that decrements
every [tick](https://kore.ayfri.com/docs/concepts/time.md).
When the score reaches 0 the cooldown is ready. Durations are expressed as [`TimeNumber`](https://kore.ayfri.com/docs/concepts/time.md) values -
`2.seconds`, `40.ticks`, etc.

They are a good fit for abilities, interactions, item usage limits, or any mechanic that should be reusable for several
players without hand-writing the decrement logic every time.

> [!FOOTPRINT]
> - **Objectives:** one per cooldown, named after it.
> - **Storage:** none.
> - **Entities:** none.
> - **Forceloaded chunks:** none.
> - **Every tick:** `cooldown_<name>_tick` removes 1 from every entity above 0.
> - **Load and files:** `cooldown_<name>_init` creates the objective. Each `ifReady` block becomes a `cooldown_<name>_ready_<hash>` function, listed in `#kore:cooldown_ready_handlers`.

## Registering a cooldown

```kotlin
val cd = registerCooldown("attack_cd", 2.seconds)
```

This generates:

- A **load function** that creates the scoreboard objective.
- A **tick function** that decrements the score of every entity with a score ≥ 1, players or not.

## Typical usage pattern

```kotlin
function("dash_skill") {
	with(cd) {
		ifReady(player) {
			say("Dash!")
		}
	}
}

function("dash_hit") {
	cd.start(player)
}
```

This split keeps the "can I use it?" check separate from the event or action that actually starts the cooldown.

## Using a cooldown

```kotlin
function("combat") {
	with(cd) {
		start(player)               // sets the score to the duration
		ifReady(player) {           // runs only when score == 0, then restarts
			say("Attack ready!")
		}
		reset(player)               // forces score to 0
	}
}
```

## Function reference

| Function  | Description                                                    |
|-----------|----------------------------------------------------------------|
| `start`   | Set the entity score to the configured duration                |
| `ifReady` | Run a block only when the cooldown is ready                    |
| `reset`   | Force the cooldown back to `0`                                 |
| tick hook | Auto-generated function that decrements active cooldown scores |

## See also

- [Timers](https://kore.ayfri.com/docs/oop/timers.md) - Use timers when you need scheduled callbacks rather than per-player readiness checks.
- [Events](https://kore.ayfri.com/docs/oop/events.md) - Start or reset cooldowns from gameplay triggers such as clicks, kills, or item use.
- [State Delegates](https://kore.ayfri.com/docs/helpers/state-delegates.md) - Reduce scoreboard boilerplate in adjacent stateful systems.