Timers and Cooldowns

Timers and cooldowns are both built on a scoreboard objective that changes by one every tick, and both are reusable for several entities without hand-writing the tick logic.

  • A timer counts up from 0 to its duration and fires its onComplete handlers when it gets there. Pick it for round timers, capture phases, delayed rewards, warmups, or any mechanic that should complete after a predictable amount of ticks.
  • A cooldown counts down from its duration to 0 and answers "ready or not" for each entity. Pick it for abilities, interactions, item usage limits, or any mechanic that should be reusable once the delay has passed.

Durations are expressed as TimeNumber values - 5.seconds, 200.ticks, 2.seconds, 40.ticks, etc.

Timers

Timers use a scoreboard objective that increments every tick. When the score reaches the configured duration, completion handlers fire.

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

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

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

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

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

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

Using a timer

function("round") {
	with(timer) {
		start(player)
		onComplete(player) {
			say("Time's up!")
		}
		stop(player)
	}
}
Kotlin
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:

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)
	}
}
Kotlin

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. The bar fills from empty to full over the duration. Its max is the duration in ticks, and every tick copies the timer score into the bar:

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
Mcfunction

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.

Here is a complete pack, the timer boss bar example of the playground, with a round timer shown on a boss bar, and the files Kore generates for it:

Timer with boss barA round timer whose progress shows in a boss bar.Open in the playground
fun playground() = dataPack("boss_round") {
	pack { description = textComponent("A 10 second round shown in a boss bar") }

	val player = player("Steve")
	val round = registerTimerWithBossBar("round", 10.seconds) {
		color = BossBarColor.GREEN
		style = BossBarStyle.NOTCHED_20
	}

	function("start_round") {
		round.start(player)
		round.onComplete(player) { say("Round over!") }
	}
}
Kotlin

Cooldowns

Cooldowns use a scoreboard objective that decrements every tick. When the score reaches 0 the cooldown is ready.

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

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

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

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

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

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

Here is a complete pack, the cooldowns example of the playground, with a dash ability on a cooldown, and the files Kore generates for it:

CooldownsAn ability usable once every few seconds.Open in the playground
fun playground() = dataPack("dash") {
	pack { description = textComponent("A dash usable every 3 seconds") }

	val player = player("Steve")
	val dash = registerCooldown("dash_cd", 3.seconds)

	function("use_dash") {
		dash.ifReady(player) { say("Dash!") }
	}
}
Kotlin

Using a cooldown

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
	}
}
Kotlin

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

  • Time Units - The TimeNumber values used for durations.
  • Events - Start or reset cooldowns and timers from gameplay triggers such as clicks, kills, or item use.
  • State Delegates - Reduce scoreboard boilerplate in adjacent stateful systems.