# Timers

> Scoreboard-based timers with Kore's OOP module. Countdown timers, boss bar timers, tick-based schedules, and reusable handles. Build cooldowns and game timers without raw command blocks.

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

Timers use a [scoreboard objective](https://minecraft.wiki/w/Scoreboard) that increments
every [tick](https://kore.ayfri.com/docs/concepts/time.md).
When the score reaches the configured duration, completion handlers fire.

This is a strong fit for round timers, capture phases, delayed rewards, warmups, or any mechanic that should complete
after a predictable amount of [ticks](https://kore.ayfri.com/docs/concepts/time.md). Durations are expressed as [
`TimeNumber`](https://kore.ayfri.com/docs/concepts/time.md) values - `5.seconds`, `200.ticks`, etc.

> [!FOOTPRINT]
> - **Objectives:** one per timer, named after it.
> - **Storage:** none.
> - **Entities:** none.
> - **Forceloaded chunks:** none.
> - **Every tick:** `timer_<name>_tick` adds 1 to every entity at 0 or more, and `registerTimerWithBossBar` adds `timer_<name>_bar_tick`, which copies the timer into the boss bar.
> - **Load and files:** `timer_<name>_init` creates the objective, `onComplete` blocks become functions listed in `#kore:timer_complete_handlers`, and `registerTimerWithBossBar` adds the boss bar `<pack>:<name>_bar`.

## Registering a timer

```kotlin
val timer = registerTimer("round_timer", 5.seconds)
```

This generates:

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

## Typical lifecycle

```kotlin
function("round_start") {
	timer.start(player)
}

function("round_cancel") {
	timer.stop(player)
}
```

Using dedicated start and stop points keeps it clear which gameplay events begin or cancel the countdown.

## Using a timer

```kotlin
function("round") {
	with(timer) {
		start(player)
		onComplete(player) {
			say("Time's up!")
		}
		stop(player)
	}
}
```

| Function     | Description                                            |
|--------------|--------------------------------------------------------|
| `start`      | Set the score to 0, beginning the countdown            |
| `stop`       | Set the score to −1, halting the timer                 |
| `onComplete` | Register a handler that fires when duration is reached |

## Timer with Boss Bar

Combines a timer with an auto-managed boss bar:

```kotlin
val timedBar = registerTimerWithBossBar("boss_timer", 10.seconds) {
	color = BossBarColor.GREEN
	style = BossBarStyle.NOTCHED_20
}

function("boss_round") {
	with(timedBar) {
		start(player)
		onComplete(player) { say("Boss round over!") }
		stop(player)
	}
}
```

The boss-bar variant is useful when you want a countdown that is both mechanical and visible to players without having
to manually synchronize a separate UI layer. Its max is the duration in ticks, and every tick copies the timer score
into the bar:

```mcfunction
execute as @e[limit=1,scores={boss_timer=0..}] store result bossbar my_pack:boss_timer_bar value run scoreboard players get @s boss_timer
```

One bar shows one timer: when several entities run the same timer at once, the bar follows one of them. Register a
timer per entity, or per team, to show each its own bar.