From 48023905e5457cb61bc96c319a6bf5f8ecca9e63 Mon Sep 17 00:00:00 2001
From: tqcuong2000 <81953130+tqcuong2000@users.noreply.github.com>
Date: Mon, 19 Jan 2026 21:49:13 +0700
Subject: [PATCH 1/7] Add "cooldown checks" section
---
src/lib/sidebar/tabs/Guides.svelte | 12 ++
src/routes/guide/cooldown/+page.svx | 41 +++++++
.../guide/cooldown/advancement/+page.svx | 109 ++++++++++++++++++
src/routes/guide/cooldown/gametime/+page.svx | 75 ++++++++++++
.../guide/cooldown/scoreboard/+page.svx | 80 +++++++++++++
5 files changed, 317 insertions(+)
create mode 100644 src/routes/guide/cooldown/+page.svx
create mode 100644 src/routes/guide/cooldown/advancement/+page.svx
create mode 100644 src/routes/guide/cooldown/gametime/+page.svx
create mode 100644 src/routes/guide/cooldown/scoreboard/+page.svx
diff --git a/src/lib/sidebar/tabs/Guides.svelte b/src/lib/sidebar/tabs/Guides.svelte
index 3a5c059..82c4a77 100644
--- a/src/lib/sidebar/tabs/Guides.svelte
+++ b/src/lib/sidebar/tabs/Guides.svelte
@@ -42,6 +42,9 @@
import IconRuler2 from "~icons/tabler/ruler-2";
import IconMathMaxMin from "~icons/tabler/math-max-min";
import IconCat from "~icons/tabler/cat";
+ import IconClock from "~icons/tabler/clock";
+ import IconStar from "~icons/tabler/star";
+ import IconWorld from "~icons/tabler/world";
import SidebarPlaceholder from "../navigation/SidebarPlaceholder.svelte";
@@ -71,6 +74,15 @@
page="/guide/adding-new-features/custom-items/models" />
+
+
+
+
+
+
+
+
+
diff --git a/src/routes/guide/cooldown/+page.svx b/src/routes/guide/cooldown/+page.svx
new file mode 100644
index 0000000..4b72afa
--- /dev/null
+++ b/src/routes/guide/cooldown/+page.svx
@@ -0,0 +1,41 @@
+---
+title: Cooldown System
+description: Learn how to create and check cooldown timers using several common methods.
+version: 1.21.11
+---
+
+# Cooldown checks
+
+A **cooldown** prevents something from running too often. In a datapack,
+the “something” is usually a function or command that you run when a player
+performs an action.
+
+For example, you might detect when a player uses an item (for example, with
+an advancement) and run a `do_things` function. A cooldown ensures `do_things`
+only runs again after a set amount of time has passed.
+
+:::info
+
+In this guide, cooldown values are measured in **ticks** (1 tick = 1/20 second). The value represents how many ticks must pass after the cooldown function runs. For example, a cooldown of `1` means the action becomes available again on the next tick.
+
+:::
+
+Here are some common ways to implement cooldowns:
+
+## [Scoreboard-based cooldowns](/guide/cooldown/scoreboard)
+
+Use a scoreboard objective to store how much time has passed since the player’s last action.
+
+This method works well for small datapacks, or when you only need a few different cooldowns.
+
+## [Advancement-based cooldowns](/guide/cooldown/advancement)
+
+Use advancements as the “cooldown state.”
+
+Advancements can detect player actions and can also be revoked, which makes them useful for “you can use this again” style logic.
+
+## [Gametime-based cooldowns](/guide/cooldown/gametime)
+
+Use the world’s `gametime` (the tick counter since the world was created) to measure elapsed time.
+
+This method is useful when you need many cooldown timers, or when you want to compare timestamps instead of counting up every tick.
diff --git a/src/routes/guide/cooldown/advancement/+page.svx b/src/routes/guide/cooldown/advancement/+page.svx
new file mode 100644
index 0000000..cca42da
--- /dev/null
+++ b/src/routes/guide/cooldown/advancement/+page.svx
@@ -0,0 +1,109 @@
+---
+title: Advancement-based cooldown
+description: Learn how to create and check cooldown timers using an advancement and a scoreboard objective.
+version: 1.21.11
+---
+
+# Advancement-based cooldown
+
+An advancement-based cooldown uses a `minecraft:tick` advancement to run a function while a player is on cooldown. You still use a scoreboard objective to store the remaining time.
+
+Compared to a fully ticking scoreboard approach, this method is **semi-ticking**:
+
+- If a player is **not** on cooldown, nothing runs for them.
+- If a player **is** on cooldown, the tick advancement runs a function each tick until the cooldown ends.
+
+This setup takes a little more work because you need an extra advancement, but it can reduce the amount of work your datapack does when most players are not on cooldown.
+
+## What you will build
+
+- A `my_cd` scoreboard objective to store the cooldown value (in ticks)
+- A tick advancement (`:my_cd`) that runs a function reward
+- A `:my_cd` function that counts the cooldown down
+- A `:do_things` function that checks the cooldown before running your action
+
+## 1) Create the tick advancement
+
+Create an advancement that triggers on `minecraft:tick` and runs `:my_cd` as a reward.
+
+```json:my_cd.json
+{
+ "criteria": {
+ "tick": {
+ "trigger": "minecraft:tick"
+ }
+ },
+ "rewards": {
+ "function": ":my_cd"
+ }
+}
+```
+`minecraft:tick` triggers every tick **until the advancement is granted**.
+That detail is what makes this method work: you keep the advancement
+“not granted” while the player is on cooldown.
+
+### 2) Create the scoreboard objective.
+
+Create a dummy objective named `my_cd` to store the cooldown value.
+
+ ```mcfunction
+ scoreboard objectives add my_cd dummy
+ ```
+### 3) Implement the cooldown countdown function (`:my_cd`)
+
+This function runs once per tick for players who do not have the advancement granted.
+
+- While the cooldown is active (`my_cd` is 1 or higher), revoke the advancement so it stays un-granted and keeps ticking.
+- Reduce the score by 1 each tick.
+
+```mcfunction:my_cd.mcfunction
+# Reduce the cooldown by 1 tick
+scoreboard players remove @s my_cd 1
+
+# Keep the advancement un-granted while the cooldown is active
+execute if score @s my_cd matches 1.. run advancement revoke @s only :my_cd
+```
+
+:::info
+
+If `my_cd` reaches `0`, the `execute if ... matches 1..` check fails,
+so the function stops revoking the advancement. After that, the tick advancement
+can stay granted, and the reward function will stop running.
+
+:::
+
+### 4) Implement the action function (`:do_things`)
+
+This function is what you run when the player performs the action (for example, when they use an item).
+
+It checks the cooldown first. If the player is on cooldown, it stops. Otherwise, it sets a cooldown
+and revokes the advancement to start the per-tick countdown.
+
+```mcfunction:do_things.mcfunction
+# If the player is on cooldown, stop here
+execute if score @s my_cd matches 1.. run return run tellraw @s {"text":"On cooldown!"}
+# Set the cooldown to 5 seconds (100 ticks)
+scoreboard players set @s my_cd 100
+# Start ticking by making the advancement un-granted
+advancement revoke @s only :my_cd
+tellraw @s {"text":"Action performed!"}
+```
+
+:::warning
+
+This function assumes it runs **as** the player (so `@s` is the player).
+If you call it in a different execution context, the scores will be stored on the wrong entity.
+
+:::
+
+## Testing
+
+1. Run `/reload`.
+2. Run `/function :do_things`.
+3. Run it again before 5 second passes to confirm it prints `On cooldown!`.
+
+To add another cooldown, repeat the same pattern with:
+
+- a new scoreboard objective (for example, `dash_cd`)
+- a new tick advancement (for example, `:dash_cd`)
+- a new countdown function (for example, `:dash_cd`)
diff --git a/src/routes/guide/cooldown/gametime/+page.svx b/src/routes/guide/cooldown/gametime/+page.svx
new file mode 100644
index 0000000..d2341a4
--- /dev/null
+++ b/src/routes/guide/cooldown/gametime/+page.svx
@@ -0,0 +1,75 @@
+---
+title: Gametime-based cooldown
+description: Learn how to create and check cooldown timers using the world’s gametime.
+version: 1.21.11
+---
+
+# Gametime-based cooldown
+
+A gametime-based cooldown stores a **timestamp** (the world’s current `gametime`)
+instead of counting down every tick.
+
+This is a **non-ticking** approach: your datapack only does work when the player
+tries to use the action. That makes it a good fit for larger datapacks with many
+different cooldown checks.
+
+## What you will build
+
+- A `last_used` scoreboard objective that stores the last time the player used an action
+- A shared `gametime` scoreboard objective that stores the current world gametime when needed
+- A `:do_things` function that checks whether enough time has passed
+
+### 1) Create the scoreboard objectives
+
+`last_used` stores the last gametime (in ticks) when the player successfully used the action.
+
+```mcfunction
+scoreboard objectives add last_used dummy
+```
+
+You also need an objective to store the current gametime value while you do the calculation.
+You only need to create this once, and you can reuse it for other cooldowns.
+
+```mcfunction
+scoreboard objectives add gametime dummy
+```
+
+### 2) Implement `:do_things`
+
+This function checks the cooldown like this:
+
+- Store the current world `gametime` in the `gametime` score
+- Subtract `last_used` to get “ticks since last use”
+- Subtract the cooldown length (for example, `100` ticks = 5 seconds)
+- If the result is negative, the player is still on cooldown
+- Otherwise, store the current gametime into `last_used` and run the action
+
+```mcfunction:do_things.mcfunction
+# Store the current world gametime (in ticks)
+execute store result score @s gametime run time query gametime
+# gametime = gametime - last_used (ticks since last use)
+scoreboard players operation @s gametime -= @s last_used
+# gametime = gametime - 100 (100 ticks = 5 seconds)
+scoreboard players remove @s gametime 100
+# If the result is negative, the cooldown has not finished
+execute if score @s gametime matches ..-1 run return run tellraw @s {"text":"On cooldown!"}
+# Cooldown finished: save the current gametime as the new last_used timestamp
+execute store result score @s last_used run time query gametime
+tellraw @s {"text":"Action performed!"}
+```
+
+:::warning
+This function assumes it runs **as** the player (so `@s` is the player).
+If you call it in a different execution context, the scores will be stored on the wrong entity.
+:::
+
+:::warning
+Avoid changing the world’s `gametime`, your cooldown math can produce incorrect results and may
+let players bypass cooldowns or get stuck on cooldown.
+
+:::
+
+:::tip
+When players stuck on cooldown (most likely `gametime` being modified),
+you can use the `/scoreboard players reset @a ` command to reset the cooldown for all player.
+:::
diff --git a/src/routes/guide/cooldown/scoreboard/+page.svx b/src/routes/guide/cooldown/scoreboard/+page.svx
new file mode 100644
index 0000000..faf3cbd
--- /dev/null
+++ b/src/routes/guide/cooldown/scoreboard/+page.svx
@@ -0,0 +1,80 @@
+---
+title: Scoreboard-based cooldown
+description: Learn how to create and check cooldown timers using a scoreboard objectives.
+version: 1.21.11
+---
+
+# Scoreboard-based cooldown
+
+A scoreboard-based cooldown stores a number on each player (or entity) and
+changes that number over time.
+
+This guide uses a **ticking** approach, which means the datapack updates the
+cooldown every game tick (20 ticks per second). Ticking cooldowns work well
+for small projects with only a few cooldowns. If you track many cooldowns or
+many entities, ticking can affect performance.
+
+:::tip
+
+To learn how to trigger a function when a player uses an item, see the
+[Right-click menu](/guide/right-click) guide.
+
+:::
+
+## What you will build
+
+- A `cooldown` scoreboard objective
+- A `tick` function that reduces each player’s cooldown over time
+- A `do_things` function that checks the cooldown before doing anything
+
+### 1) Create the scoreboard objective (`load.mcfunction`)
+
+Create a dummy objective named `cooldown`.
+
+A **dummy** objective only changes when commands change it.
+
+```mcfunction:load.mcfunction
+scoreboard objectives add cooldown dummy
+function :tick
+```
+
+### 2) Decrease the cooldown every tick (`tick.mcfunction`)
+
+In your `tick` function, schedule the next run, then reduce the `cooldown`
+score by `1` for any player who has `cooldown` ≥ 1
+
+```mcfunction:tick.mcfunction
+# Run this function again next tick
+schedule function :tick 1t
+# Reduce cooldown for players who are on cooldown
+execute as @a[scores={cooldown=1..}] run scoreboard players remove @s cooldown 1
+```
+
+### 3) Check the cooldown before running the action (`do_things.mcfunction`)
+
+In the function that performs the action, check the executor’s `cooldown` score.
+- If the score is 1 or higher, stop the function and tell the player.
+- If the score is 0 (or not set), set a new cooldown value and continue.
+
+```mcfunction:do_things.mcfunction
+# If the player is still on cooldown, stop here
+execute if score @s cooldown matches 1.. run return run tellraw @s {"text":"On cooldown!"}
+# Set the cooldown to 5 seconds (100 ticks)
+scoreboard players set @s cooldown 100
+tellraw @s {"text":"Action performed!"}
+```
+
+:::warning
+This function assumes it runs **as** the player (so `@s` is the player).
+If you call it in a different execution context, the scores will be stored on the wrong entity.
+:::
+
+## Testing
+- Run `/reload`
+- Run `/function :do_things`
+
+You should see `Used ability!`. If you run the command again before 5 seconds pass,
+you should see `On cooldown!`.
+
+To track more than one cooldown, create additional objectives (for example, `dash_cd`,
+ `teleport_cd`) and use the same logic for each one.
From 3673b286e9dd6a1b87d18be12cb424665c55a9bd Mon Sep 17 00:00:00 2001
From: tqcuong2000 <81953130+tqcuong2000@users.noreply.github.com>
Date: Tue, 20 Jan 2026 07:55:40 +0700
Subject: [PATCH 2/7] add "Cooldown Checks" section
---
src/lib/sidebar/tabs/Guides.svelte | 8 ++++----
src/routes/guide/cooldown/advancement/+page.svx | 14 --------------
src/routes/guide/cooldown/gametime/+page.svx | 11 ++++++-----
src/routes/guide/cooldown/scoreboard/+page.svx | 15 +++------------
4 files changed, 13 insertions(+), 35 deletions(-)
diff --git a/src/lib/sidebar/tabs/Guides.svelte b/src/lib/sidebar/tabs/Guides.svelte
index 82c4a77..b18f029 100644
--- a/src/lib/sidebar/tabs/Guides.svelte
+++ b/src/lib/sidebar/tabs/Guides.svelte
@@ -44,7 +44,7 @@
import IconCat from "~icons/tabler/cat";
import IconClock from "~icons/tabler/clock";
import IconStar from "~icons/tabler/star";
- import IconWorld from "~icons/tabler/world";
+ import IconHourglass from "~icons/tabler/hourglass-empty";
import SidebarPlaceholder from "../navigation/SidebarPlaceholder.svelte";
@@ -74,13 +74,13 @@
page="/guide/adding-new-features/custom-items/models" />
-
-
+
+
-
+
diff --git a/src/routes/guide/cooldown/advancement/+page.svx b/src/routes/guide/cooldown/advancement/+page.svx
index cca42da..b15298a 100644
--- a/src/routes/guide/cooldown/advancement/+page.svx
+++ b/src/routes/guide/cooldown/advancement/+page.svx
@@ -59,7 +59,6 @@ This function runs once per tick for players who do not have the advancement gra
```mcfunction:my_cd.mcfunction
# Reduce the cooldown by 1 tick
scoreboard players remove @s my_cd 1
-
# Keep the advancement un-granted while the cooldown is active
execute if score @s my_cd matches 1.. run advancement revoke @s only :my_cd
```
@@ -89,21 +88,8 @@ advancement revoke @s only :my_cd
tellraw @s {"text":"Action performed!"}
```
-:::warning
-
-This function assumes it runs **as** the player (so `@s` is the player).
-If you call it in a different execution context, the scores will be stored on the wrong entity.
-
-:::
-
## Testing
1. Run `/reload`.
2. Run `/function :do_things`.
3. Run it again before 5 second passes to confirm it prints `On cooldown!`.
-
-To add another cooldown, repeat the same pattern with:
-
-- a new scoreboard objective (for example, `dash_cd`)
-- a new tick advancement (for example, `:dash_cd`)
-- a new countdown function (for example, `:dash_cd`)
diff --git a/src/routes/guide/cooldown/gametime/+page.svx b/src/routes/guide/cooldown/gametime/+page.svx
index d2341a4..3d8cf03 100644
--- a/src/routes/guide/cooldown/gametime/+page.svx
+++ b/src/routes/guide/cooldown/gametime/+page.svx
@@ -58,11 +58,6 @@ execute store result score @s last_used run time query gametime
tellraw @s {"text":"Action performed!"}
```
-:::warning
-This function assumes it runs **as** the player (so `@s` is the player).
-If you call it in a different execution context, the scores will be stored on the wrong entity.
-:::
-
:::warning
Avoid changing the world’s `gametime`, your cooldown math can produce incorrect results and may
let players bypass cooldowns or get stuck on cooldown.
@@ -73,3 +68,9 @@ let players bypass cooldowns or get stuck on cooldown.
When players stuck on cooldown (most likely `gametime` being modified),
you can use the `/scoreboard players reset @a ` command to reset the cooldown for all player.
:::
+
+## Testing
+
+1. Run `/reload`.
+2. Run `/function :do_things`.
+3. Run it again before 5 second passes to confirm it prints `On cooldown!`.
diff --git a/src/routes/guide/cooldown/scoreboard/+page.svx b/src/routes/guide/cooldown/scoreboard/+page.svx
index faf3cbd..08ddf3b 100644
--- a/src/routes/guide/cooldown/scoreboard/+page.svx
+++ b/src/routes/guide/cooldown/scoreboard/+page.svx
@@ -64,17 +64,8 @@ scoreboard players set @s cooldown 100
tellraw @s {"text":"Action performed!"}
```
-:::warning
-This function assumes it runs **as** the player (so `@s` is the player).
-If you call it in a different execution context, the scores will be stored on the wrong entity.
-:::
-
## Testing
-- Run `/reload`
-- Run `/function :do_things`
-
-You should see `Used ability!`. If you run the command again before 5 seconds pass,
-you should see `On cooldown!`.
-To track more than one cooldown, create additional objectives (for example, `dash_cd`,
- `teleport_cd`) and use the same logic for each one.
+1. Run `/reload`.
+2. Run `/function :do_things`.
+3. Run it again before 5 second passes to confirm it prints `On cooldown!`.
From d82211c1f17a59ca7d613a2d0eb09d5ba2373945 Mon Sep 17 00:00:00 2001
From: tqcuong2000 <81953130+tqcuong2000@users.noreply.github.com>
Date: Tue, 20 Jan 2026 07:55:59 +0700
Subject: [PATCH 3/7] add "Cooldown Checks" section
---
src/lib/sidebar/tabs/Guides.svelte | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/lib/sidebar/tabs/Guides.svelte b/src/lib/sidebar/tabs/Guides.svelte
index b18f029..10e57c6 100644
--- a/src/lib/sidebar/tabs/Guides.svelte
+++ b/src/lib/sidebar/tabs/Guides.svelte
@@ -75,7 +75,7 @@
-
+
From 499a0a36da11d3290922e0f1c0aa6f0d81849768 Mon Sep 17 00:00:00 2001
From: tqcuong2000 <81953130+tqcuong2000@users.noreply.github.com>
Date: Tue, 20 Jan 2026 21:17:06 +0700
Subject: [PATCH 4/7] - standardized sentence phrasing and variable names for
consistency across examples - improved readability in several sections -
removed unnecessary lines
---
src/routes/guide/cooldown/+page.svx | 22 +++---
.../guide/cooldown/advancement/+page.svx | 74 ++++++++++---------
src/routes/guide/cooldown/gametime/+page.svx | 35 ++++-----
.../guide/cooldown/scoreboard/+page.svx | 43 +++++------
4 files changed, 90 insertions(+), 84 deletions(-)
diff --git a/src/routes/guide/cooldown/+page.svx b/src/routes/guide/cooldown/+page.svx
index 4b72afa..bc53178 100644
--- a/src/routes/guide/cooldown/+page.svx
+++ b/src/routes/guide/cooldown/+page.svx
@@ -16,26 +16,30 @@ only runs again after a set amount of time has passed.
:::info
-In this guide, cooldown values are measured in **ticks** (1 tick = 1/20 second). The value represents how many ticks must pass after the cooldown function runs. For example, a cooldown of `1` means the action becomes available again on the next tick.
+In this guide, cooldown values are measured in **ticks** (1 tick = 1/20 second).
+The value represents how many ticks must pass after the cooldown function runs.
+For example, a cooldown of `1` means the action becomes available again on the next tick.
:::
Here are some common ways to implement cooldowns:
-## [Scoreboard-based cooldowns](/guide/cooldown/scoreboard)
+## [Scoreboard-based cooldown](/guide/cooldown/scoreboard)
-Use a scoreboard objective to store how much time has passed since the player’s last action.
+Use a scoreboard objective to store how much time remaining until the cooldown expires.
This method works well for small datapacks, or when you only need a few different cooldowns.
-## [Advancement-based cooldowns](/guide/cooldown/advancement)
+## [Advancement-based cooldown](/guide/cooldown/advancement)
-Use advancements as the “cooldown state.”
+Use advancement to tick the cooldown.
-Advancements can detect player actions and can also be revoked, which makes them useful for “you can use this again” style logic.
+This method only ticks the cooldown while the player is on cooldown, making it ideal
+for performance-sensitive projects.
-## [Gametime-based cooldowns](/guide/cooldown/gametime)
+## [Gametime-based cooldown](/guide/cooldown/gametime)
-Use the world’s `gametime` (the tick counter since the world was created) to measure elapsed time.
+Use the world’s gametime to measure elapsed time.
-This method is useful when you need many cooldown timers, or when you want to compare timestamps instead of counting up every tick.
+This is a non-ticking approach that works well for large datapacks or any setup
+that needs many cooldown timers.
diff --git a/src/routes/guide/cooldown/advancement/+page.svx b/src/routes/guide/cooldown/advancement/+page.svx
index b15298a..a8e94cb 100644
--- a/src/routes/guide/cooldown/advancement/+page.svx
+++ b/src/routes/guide/cooldown/advancement/+page.svx
@@ -1,32 +1,43 @@
---
title: Advancement-based cooldown
-description: Learn how to create and check cooldown timers using an advancement and a scoreboard objective.
+description: Learn how to create and check cooldown timer using an advancement and a
+scoreboard objective.
version: 1.21.11
---
# Advancement-based cooldown
-An advancement-based cooldown uses a `minecraft:tick` advancement to run a function while a player is on cooldown. You still use a scoreboard objective to store the remaining time.
+An advancement-based cooldown uses a `minecraft:tick` advancement to run a function while
+a player is on cooldown.
-Compared to a fully ticking scoreboard approach, this method is **semi-ticking**:
+Compared to a fully ticking scoreboard approach, this method is semi-ticking:
-- If a player is **not** on cooldown, nothing runs for them.
-- If a player **is** on cooldown, the tick advancement runs a function each tick until the cooldown ends.
+- If a player is not on cooldown, nothing runs for them.
+- If a player is on cooldown, the tick advancement runs a function each tick until the
+cooldown ends.
-This setup takes a little more work because you need an extra advancement, but it can reduce the amount of work your datapack does when most players are not on cooldown.
+This setup takes a little more work because you need an extra advancement, but it can reduce
+the amount of work your datapack does when most players are not on cooldown.
## What you will build
-- A `my_cd` scoreboard objective to store the cooldown value (in ticks)
-- A tick advancement (`:my_cd`) that runs a function reward
-- A `:my_cd` function that counts the cooldown down
-- A `:do_things` function that checks the cooldown before running your action
+- A `my_cd` scoreboard objective to store the cooldown value (in ticks).
+- A tick advancement (`:my_cd`) that runs a tick function.
+- A `:my_cd` function that counts the cooldown down.
+- A `:do_things` function that checks the cooldown before running your action.
-## 1) Create the tick advancement
+:::tip
-Create an advancement that triggers on `minecraft:tick` and runs `:my_cd` as a reward.
+If you don't know what an advancement is, learn about it ([Advancement](/wiki/files/advancements))
-```json:my_cd.json
+:::
+
+## 1) Create the tick advancement (`my_cd_adv.json`)
+
+Create an advancement that triggers on `minecraft:tick` and runs `:reduce_my_cd`
+as a reward.
+
+```json:my_cd_adv.json
{
"criteria": {
"tick": {
@@ -34,57 +45,50 @@ Create an advancement that triggers on `minecraft:tick` and runs `:my
}
},
"rewards": {
- "function": ":my_cd"
+ "function": ":reduce_my_cd"
}
}
```
-`minecraft:tick` triggers every tick **until the advancement is granted**.
-That detail is what makes this method work: you keep the advancement
-“not granted” while the player is on cooldown.
+Function `:reduce_my_cd` only runs when this advancement is not granted.
### 2) Create the scoreboard objective.
Create a dummy objective named `my_cd` to store the cooldown value.
- ```mcfunction
+ ```mcfunction:load.mcfunction
scoreboard objectives add my_cd dummy
```
-### 3) Implement the cooldown countdown function (`:my_cd`)
+### 3) Create the cooldown countdown function (`reduce_my_cd.mcfunction`)
This function runs once per tick for players who do not have the advancement granted.
-- While the cooldown is active (`my_cd` is 1 or higher), revoke the advancement so it stays un-granted and keeps ticking.
+- While the cooldown is active (`my_cd` ≥ 1), revoke the advancement so it stays
+un-granted and keeps ticking.
- Reduce the score by 1 each tick.
```mcfunction:my_cd.mcfunction
# Reduce the cooldown by 1 tick
scoreboard players remove @s my_cd 1
# Keep the advancement un-granted while the cooldown is active
-execute if score @s my_cd matches 1.. run advancement revoke @s only :my_cd
+execute if score @s my_cd matches 1.. run advancement revoke @s only :my_cd_adv
```
-:::info
-
-If `my_cd` reaches `0`, the `execute if ... matches 1..` check fails,
-so the function stops revoking the advancement. After that, the tick advancement
-can stay granted, and the reward function will stop running.
-
-:::
-
-### 4) Implement the action function (`:do_things`)
+### 4) Create the action function (`do_things.mcfunction`)
-This function is what you run when the player performs the action (for example, when they use an item).
+This function checks the cooldown like this:
-It checks the cooldown first. If the player is on cooldown, it stops. Otherwise, it sets a cooldown
-and revokes the advancement to start the per-tick countdown.
+- If the score `my_cd` ≥ 1, stop and tell the player.
+- Set the cooldown to 5 seconds (100 ticks).
+- Make `:my_cd_adv` advancement un-granted.
```mcfunction:do_things.mcfunction
# If the player is on cooldown, stop here
execute if score @s my_cd matches 1.. run return run tellraw @s {"text":"On cooldown!"}
# Set the cooldown to 5 seconds (100 ticks)
scoreboard players set @s my_cd 100
-# Start ticking by making the advancement un-granted
-advancement revoke @s only :my_cd
+# Make the advancement un-granted
+advancement revoke @s only :my_cd_adv
+# Do your stuff here
tellraw @s {"text":"Action performed!"}
```
diff --git a/src/routes/guide/cooldown/gametime/+page.svx b/src/routes/guide/cooldown/gametime/+page.svx
index 3d8cf03..9ca7a20 100644
--- a/src/routes/guide/cooldown/gametime/+page.svx
+++ b/src/routes/guide/cooldown/gametime/+page.svx
@@ -6,55 +6,56 @@ version: 1.21.11
# Gametime-based cooldown
-A gametime-based cooldown stores a **timestamp** (the world’s current `gametime`)
-instead of counting down every tick.
+A gametime-based cooldown stores a timestamp (the world’s current `gametime`)
+on a scoreboard objective.
-This is a **non-ticking** approach: your datapack only does work when the player
+This is a non-ticking approach: your datapack only does work when the player
tries to use the action. That makes it a good fit for larger datapacks with many
-different cooldown checks.
+different cooldown to check.
## What you will build
-- A `last_used` scoreboard objective that stores the last time the player used an action
-- A shared `gametime` scoreboard objective that stores the current world gametime when needed
-- A `:do_things` function that checks whether enough time has passed
+- A `last_used` scoreboard objective that stores the last timestamp when the player used an action.
+- A `gametime` scoreboard objective that stores the current world gametime.
+- A `:do_things` function that checks whether enough time has passed and runs the action.
### 1) Create the scoreboard objectives
-`last_used` stores the last gametime (in ticks) when the player successfully used the action.
+The `last_used` score stores the last gametime when the player successfully used the action.
```mcfunction
scoreboard objectives add last_used dummy
```
-You also need an objective to store the current gametime value while you do the calculation.
+You also need an score to store the current gametime value while you do the calculation.
You only need to create this once, and you can reuse it for other cooldowns.
```mcfunction
scoreboard objectives add gametime dummy
```
-### 2) Implement `:do_things`
+### 2) Create the action function (`do_things.mcfunction`)
This function checks the cooldown like this:
-- Store the current world `gametime` in the `gametime` score
-- Subtract `last_used` to get “ticks since last use”
-- Subtract the cooldown length (for example, `100` ticks = 5 seconds)
-- If the result is negative, the player is still on cooldown
-- Otherwise, store the current gametime into `last_used` and run the action
+- Store the current gametime in the `gametime` score.
+- Subtract `last_used` to get ticks since last use.
+- Subtract the cooldown length.
+- If the result is negative, the player is still on cooldown, stop the function.
+- Otherwise, store the current gametime into `last_used` and run the action.
```mcfunction:do_things.mcfunction
-# Store the current world gametime (in ticks)
+# Store the current gametime
execute store result score @s gametime run time query gametime
# gametime = gametime - last_used (ticks since last use)
scoreboard players operation @s gametime -= @s last_used
# gametime = gametime - 100 (100 ticks = 5 seconds)
scoreboard players remove @s gametime 100
-# If the result is negative, the cooldown has not finished
+# If the result is negative, the cooldown has not finished and stop the function
execute if score @s gametime matches ..-1 run return run tellraw @s {"text":"On cooldown!"}
# Cooldown finished: save the current gametime as the new last_used timestamp
execute store result score @s last_used run time query gametime
+# Do your stuff here
tellraw @s {"text":"Action performed!"}
```
diff --git a/src/routes/guide/cooldown/scoreboard/+page.svx b/src/routes/guide/cooldown/scoreboard/+page.svx
index 08ddf3b..6ba900f 100644
--- a/src/routes/guide/cooldown/scoreboard/+page.svx
+++ b/src/routes/guide/cooldown/scoreboard/+page.svx
@@ -9,11 +9,17 @@ version: 1.21.11
A scoreboard-based cooldown stores a number on each player (or entity) and
changes that number over time.
-This guide uses a **ticking** approach, which means the datapack updates the
+This guide uses a ticking approach, which means the datapack updates the
cooldown every game tick (20 ticks per second). Ticking cooldowns work well
for small projects with only a few cooldowns. If you track many cooldowns or
many entities, ticking can affect performance.
+## What you will build
+
+- A `my_cd` scoreboard objective
+- A `tick` function that reduces each player’s cooldown over time
+- A `do_things` function that checks the cooldown before doing anything
+
:::tip
To learn how to trigger a function when a player uses an item, see the
@@ -21,46 +27,37 @@ To learn how to trigger a function when a player uses an item, see the
:::
-## What you will build
-
-- A `cooldown` scoreboard objective
-- A `tick` function that reduces each player’s cooldown over time
-- A `do_things` function that checks the cooldown before doing anything
-
-### 1) Create the scoreboard objective (`load.mcfunction`)
+### 1) Create the scoreboard objective.
-Create a dummy objective named `cooldown`.
+Create a dummy objective named `my_cd`.
-A **dummy** objective only changes when commands change it.
+A dummy objective only changes when commands change it.
```mcfunction:load.mcfunction
-scoreboard objectives add cooldown dummy
-function :tick
+scoreboard objectives add my_cd dummy
```
-### 2) Decrease the cooldown every tick (`tick.mcfunction`)
+### 2) Create the `tick` function.
-In your `tick` function, schedule the next run, then reduce the `cooldown`
-score by `1` for any player who has `cooldown` ≥ 1
+In your `tick` function which runs every tick, reduce the `my_cd`
+score by 1 for any player who has `my_cd` ≥ 1
```mcfunction:tick.mcfunction
-# Run this function again next tick
-schedule function :tick 1t
-# Reduce cooldown for players who are on cooldown
-execute as @a[scores={cooldown=1..}] run scoreboard players remove @s cooldown 1
+execute as @a[scores={my_cd=1..}] run scoreboard players remove @s my_cd 1
```
-### 3) Check the cooldown before running the action (`do_things.mcfunction`)
+### 3) Create the action function (`do_things.mcfunction`)
-In the function that performs the action, check the executor’s `cooldown` score.
+In this function, check the executor’s `my_cd` score.
- If the score is 1 or higher, stop the function and tell the player.
- If the score is 0 (or not set), set a new cooldown value and continue.
```mcfunction:do_things.mcfunction
# If the player is still on cooldown, stop here
-execute if score @s cooldown matches 1.. run return run tellraw @s {"text":"On cooldown!"}
+execute if score @s my_cd matches 1.. run return run tellraw @s {"text":"On cooldown!"}
# Set the cooldown to 5 seconds (100 ticks)
-scoreboard players set @s cooldown 100
+scoreboard players set @s my_cd 100
+# Do your stuff here
tellraw @s {"text":"Action performed!"}
```
From f6e86e8693793a725df008db097181d5f5c68539 Mon Sep 17 00:00:00 2001
From: tqcuong2000 <81953130+tqcuong2000@users.noreply.github.com>
Date: Tue, 20 Jan 2026 21:27:39 +0700
Subject: [PATCH 5/7] update variables name
---
src/routes/guide/cooldown/advancement/+page.svx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/routes/guide/cooldown/advancement/+page.svx b/src/routes/guide/cooldown/advancement/+page.svx
index a8e94cb..20e5724 100644
--- a/src/routes/guide/cooldown/advancement/+page.svx
+++ b/src/routes/guide/cooldown/advancement/+page.svx
@@ -22,8 +22,8 @@ the amount of work your datapack does when most players are not on cooldown.
## What you will build
- A `my_cd` scoreboard objective to store the cooldown value (in ticks).
-- A tick advancement (`:my_cd`) that runs a tick function.
-- A `:my_cd` function that counts the cooldown down.
+- A tick advancement (`:my_cd_adv`) that runs a tick function.
+- A `:reduce_my_cd` function that counts the cooldown down.
- A `:do_things` function that checks the cooldown before running your action.
:::tip
From 3577d7514bcd73c6415049b6a56e4c4f375e3873 Mon Sep 17 00:00:00 2001
From: InfinityI
Date: Sat, 28 Mar 2026 14:45:35 +0700
Subject: [PATCH 6/7] - update version from 1.21.11 to 26.1 - update `gametime`
to `worldclock` - fix typos and improve readability.
---
src/lib/sidebar/tabs/Guides.svelte | 2 +-
src/routes/guide/cooldown/+page.svx | 43 ++++++-----
.../guide/cooldown/advancement/+page.svx | 49 ++++++------
src/routes/guide/cooldown/gametime/+page.svx | 77 -------------------
.../guide/cooldown/scoreboard/+page.svx | 41 +++++-----
.../guide/cooldown/worldclock/+page.svx | 74 ++++++++++++++++++
6 files changed, 145 insertions(+), 141 deletions(-)
delete mode 100644 src/routes/guide/cooldown/gametime/+page.svx
create mode 100644 src/routes/guide/cooldown/worldclock/+page.svx
diff --git a/src/lib/sidebar/tabs/Guides.svelte b/src/lib/sidebar/tabs/Guides.svelte
index 10e57c6..ce9149b 100644
--- a/src/lib/sidebar/tabs/Guides.svelte
+++ b/src/lib/sidebar/tabs/Guides.svelte
@@ -80,7 +80,7 @@
-
+
diff --git a/src/routes/guide/cooldown/+page.svx b/src/routes/guide/cooldown/+page.svx
index bc53178..f4b863f 100644
--- a/src/routes/guide/cooldown/+page.svx
+++ b/src/routes/guide/cooldown/+page.svx
@@ -1,45 +1,48 @@
---
-title: Cooldown System
+title: Cooldown checks
description: Learn how to create and check cooldown timers using several common methods.
-version: 1.21.11
+version: 26.1
---
# Cooldown checks
-A **cooldown** prevents something from running too often. In a datapack,
-the “something” is usually a function or command that you run when a player
-performs an action.
+A cooldown restricts how frequently a player triggers a custom action. In most
+datapacks, these actions involve running functions or commands.
-For example, you might detect when a player uses an item (for example, with
-an advancement) and run a `do_things` function. A cooldown ensures `do_things`
-only runs again after a set amount of time has passed.
+For example, consider a custom wand that shoots fireballs when a player
+right clicks. Without a cooldown, players could spam the wand, resulting
+in lag or unbalanced gameplay. Adding a cooldown ensures the player waits a few
+seconds before shooting another fireball.
-:::info
+## Core concepts
+- **Cooldown**: A timer that prevents an action from running again until a specified
+amount of time has elapsed since the last execution.
+- **Action**: The command or function the cooldown restricts.
+- **Namespace**: A unique identifier for your datapack that prevents conflicts with other
+datapacks. Use it as a prefix for all functions and resources (for example, `mypack:my_function`).
-In this guide, cooldown values are measured in **ticks** (1 tick = 1/20 second).
-The value represents how many ticks must pass after the cooldown function runs.
-For example, a cooldown of `1` means the action becomes available again on the next tick.
-:::
+## Implementation methods
-Here are some common ways to implement cooldowns:
+This guide covers three common methods for implementing cooldowns in Minecraft datapacks:
+scoreboard-based, advancement-based, and worldclock-based.
-## [Scoreboard-based cooldown](/guide/cooldown/scoreboard)
+### [Scoreboard-based cooldown](/guide/cooldown/scoreboard)
Use a scoreboard objective to store how much time remaining until the cooldown expires.
This method works well for small datapacks, or when you only need a few different cooldowns.
-## [Advancement-based cooldown](/guide/cooldown/advancement)
+### [Advancement-based cooldown](/guide/cooldown/advancement)
-Use advancement to tick the cooldown.
+Use an advancement to tick the cooldown.
-This method only ticks the cooldown while the player is on cooldown, making it ideal
+This method only ticks the cooldown when the player is using the action, making it ideal
for performance-sensitive projects.
-## [Gametime-based cooldown](/guide/cooldown/gametime)
+### [Worldclock-based cooldown](/guide/cooldown/worldclock)
-Use the world’s gametime to measure elapsed time.
+Use a timespan on a worldclock to measure elapsed time.
This is a non-ticking approach that works well for large datapacks or any setup
that needs many cooldown timers.
diff --git a/src/routes/guide/cooldown/advancement/+page.svx b/src/routes/guide/cooldown/advancement/+page.svx
index 20e5724..75afb82 100644
--- a/src/routes/guide/cooldown/advancement/+page.svx
+++ b/src/routes/guide/cooldown/advancement/+page.svx
@@ -1,8 +1,8 @@
---
title: Advancement-based cooldown
-description: Learn how to create and check cooldown timer using an advancement and a
+description: Learn how to create and check a cooldown timer using an advancement and a
scoreboard objective.
-version: 1.21.11
+version: 26.1
---
# Advancement-based cooldown
@@ -24,17 +24,17 @@ the amount of work your datapack does when most players are not on cooldown.
- A `my_cd` scoreboard objective to store the cooldown value (in ticks).
- A tick advancement (`:my_cd_adv`) that runs a tick function.
- A `:reduce_my_cd` function that counts the cooldown down.
-- A `:do_things` function that checks the cooldown before running your action.
+- A `:cooldown` function that checks the cooldown before running your action.
:::tip
-If you don't know what an advancement is, learn about it ([Advancement](/wiki/files/advancements))
+To learn about advancements, see the [Advancement guide](/wiki/files/advancements).
:::
-## 1) Create the tick advancement (`my_cd_adv.json`)
+### 1) Create the tick advancement (`my_cd_adv.json`)
-Create an advancement that triggers on `minecraft:tick` and runs `:reduce_my_cd`
+Create an advancement that triggers every tick and runs `:reduce_my_cd`
as a reward.
```json:my_cd_adv.json
@@ -49,7 +49,9 @@ as a reward.
}
}
```
-Function `:reduce_my_cd` only runs when this advancement is not granted.
+The function `:reduce_my_cd` only runs when the advancement
+is not granted. This happens because advancements only grant their
+rewards to players who don't already have them.
### 2) Create the scoreboard objective.
@@ -62,38 +64,39 @@ Create a dummy objective named `my_cd` to store the cooldown value.
This function runs once per tick for players who do not have the advancement granted.
-- While the cooldown is active (`my_cd` ≥ 1), revoke the advancement so it stays
-un-granted and keeps ticking.
+- While the cooldown is active (`my_cd` ≥ 1), revoke the advancement
+ to keep it un-granted so the tick function continues to run.
- Reduce the score by 1 each tick.
-```mcfunction:my_cd.mcfunction
+```mcfunction:reduce_my_cd.mcfunction
# Reduce the cooldown by 1 tick
scoreboard players remove @s my_cd 1
# Keep the advancement un-granted while the cooldown is active
execute if score @s my_cd matches 1.. run advancement revoke @s only :my_cd_adv
```
-### 4) Create the action function (`do_things.mcfunction`)
+### 4) Create the `cooldown` function
-This function checks the cooldown like this:
+This function checks the cooldown as follows:
-- If the score `my_cd` ≥ 1, stop and tell the player.
-- Set the cooldown to 5 seconds (100 ticks).
+- If the player's `my_cd` score ≥ 1, the cooldown has not ended, return fail.
+- Set the player's cooldown to 5 seconds (100 ticks).
- Make `:my_cd_adv` advancement un-granted.
-```mcfunction:do_things.mcfunction
-# If the player is on cooldown, stop here
-execute if score @s my_cd matches 1.. run return run tellraw @s {"text":"On cooldown!"}
-# Set the cooldown to 5 seconds (100 ticks)
+```mcfunction:cooldown.mcfunction
+# If the player is on cooldown, return fail
+execute if score @s my_cd matches 1.. run return fail
+# Reset the cooldown (change "100" to your cooldown length in ticks)
scoreboard players set @s my_cd 100
# Make the advancement un-granted
advancement revoke @s only :my_cd_adv
-# Do your stuff here
-tellraw @s {"text":"Action performed!"}
+# Return success
+return 1
```
## Testing
-1. Run `/reload`.
-2. Run `/function :do_things`.
-3. Run it again before 5 second passes to confirm it prints `On cooldown!`.
+Check the cooldown in your function:
+```mcfunction:my_function
+execute if function :cooldown run tellraw @a {"text": "Cooldown Ready!"}
+```
diff --git a/src/routes/guide/cooldown/gametime/+page.svx b/src/routes/guide/cooldown/gametime/+page.svx
deleted file mode 100644
index 9ca7a20..0000000
--- a/src/routes/guide/cooldown/gametime/+page.svx
+++ /dev/null
@@ -1,77 +0,0 @@
----
-title: Gametime-based cooldown
-description: Learn how to create and check cooldown timers using the world’s gametime.
-version: 1.21.11
----
-
-# Gametime-based cooldown
-
-A gametime-based cooldown stores a timestamp (the world’s current `gametime`)
-on a scoreboard objective.
-
-This is a non-ticking approach: your datapack only does work when the player
-tries to use the action. That makes it a good fit for larger datapacks with many
-different cooldown to check.
-
-## What you will build
-
-- A `last_used` scoreboard objective that stores the last timestamp when the player used an action.
-- A `gametime` scoreboard objective that stores the current world gametime.
-- A `:do_things` function that checks whether enough time has passed and runs the action.
-
-### 1) Create the scoreboard objectives
-
-The `last_used` score stores the last gametime when the player successfully used the action.
-
-```mcfunction
-scoreboard objectives add last_used dummy
-```
-
-You also need an score to store the current gametime value while you do the calculation.
-You only need to create this once, and you can reuse it for other cooldowns.
-
-```mcfunction
-scoreboard objectives add gametime dummy
-```
-
-### 2) Create the action function (`do_things.mcfunction`)
-
-This function checks the cooldown like this:
-
-- Store the current gametime in the `gametime` score.
-- Subtract `last_used` to get ticks since last use.
-- Subtract the cooldown length.
-- If the result is negative, the player is still on cooldown, stop the function.
-- Otherwise, store the current gametime into `last_used` and run the action.
-
-```mcfunction:do_things.mcfunction
-# Store the current gametime
-execute store result score @s gametime run time query gametime
-# gametime = gametime - last_used (ticks since last use)
-scoreboard players operation @s gametime -= @s last_used
-# gametime = gametime - 100 (100 ticks = 5 seconds)
-scoreboard players remove @s gametime 100
-# If the result is negative, the cooldown has not finished and stop the function
-execute if score @s gametime matches ..-1 run return run tellraw @s {"text":"On cooldown!"}
-# Cooldown finished: save the current gametime as the new last_used timestamp
-execute store result score @s last_used run time query gametime
-# Do your stuff here
-tellraw @s {"text":"Action performed!"}
-```
-
-:::warning
-Avoid changing the world’s `gametime`, your cooldown math can produce incorrect results and may
-let players bypass cooldowns or get stuck on cooldown.
-
-:::
-
-:::tip
-When players stuck on cooldown (most likely `gametime` being modified),
-you can use the `/scoreboard players reset @a ` command to reset the cooldown for all player.
-:::
-
-## Testing
-
-1. Run `/reload`.
-2. Run `/function :do_things`.
-3. Run it again before 5 second passes to confirm it prints `On cooldown!`.
diff --git a/src/routes/guide/cooldown/scoreboard/+page.svx b/src/routes/guide/cooldown/scoreboard/+page.svx
index 6ba900f..6d0821a 100644
--- a/src/routes/guide/cooldown/scoreboard/+page.svx
+++ b/src/routes/guide/cooldown/scoreboard/+page.svx
@@ -1,7 +1,7 @@
---
title: Scoreboard-based cooldown
-description: Learn how to create and check cooldown timers using a scoreboard objectives.
-version: 1.21.11
+description: Learn how to create and check cooldown timers using a scoreboard objective.
+version: 26.1
---
# Scoreboard-based cooldown
@@ -11,14 +11,14 @@ changes that number over time.
This guide uses a ticking approach, which means the datapack updates the
cooldown every game tick (20 ticks per second). Ticking cooldowns work well
-for small projects with only a few cooldowns. If you track many cooldowns or
-many entities, ticking can affect performance.
+for small projects with only a few cooldowns and short durations. If you track many cooldowns or
+many entities, ticking affects performance.
## What you will build
- A `my_cd` scoreboard objective
-- A `tick` function that reduces each player’s cooldown over time
-- A `do_things` function that checks the cooldown before doing anything
+- A `tick` function that reduces each player's cooldown over time
+- A `cooldown` function that checks the cooldown before doing anything
:::tip
@@ -27,42 +27,43 @@ To learn how to trigger a function when a player uses an item, see the
:::
-### 1) Create the scoreboard objective.
+### 1) Create the scoreboard objective
Create a dummy objective named `my_cd`.
-A dummy objective only changes when commands change it.
+A dummy objective stores a value that only changes when commands modify it.
```mcfunction:load.mcfunction
scoreboard objectives add my_cd dummy
```
-### 2) Create the `tick` function.
+### 2) Create the `tick` function
In your `tick` function which runs every tick, reduce the `my_cd`
-score by 1 for any player who has `my_cd` ≥ 1
+score by 1 for any player with `my_cd` ≥ 1
```mcfunction:tick.mcfunction
execute as @a[scores={my_cd=1..}] run scoreboard players remove @s my_cd 1
```
-### 3) Create the action function (`do_things.mcfunction`)
+### 3) Create the `cooldown` function
In this function, check the executor’s `my_cd` score.
- If the score is 1 or higher, stop the function and tell the player.
-- If the score is 0 (or not set), set a new cooldown value and continue.
+- If the score is 0 or doesn't exist yet, set a new cooldown value and continue.
-```mcfunction:do_things.mcfunction
+```mcfunction:cooldown.mcfunction
# If the player is still on cooldown, stop here
-execute if score @s my_cd matches 1.. run return run tellraw @s {"text":"On cooldown!"}
-# Set the cooldown to 5 seconds (100 ticks)
+execute if score @s my_cd matches 1.. run return fail
+# Reset the cooldown (change "100" to your cooldown length in ticks)
scoreboard players set @s my_cd 100
-# Do your stuff here
-tellraw @s {"text":"Action performed!"}
+# Return success
+return 1
```
## Testing
-1. Run `/reload`.
-2. Run `/function :do_things`.
-3. Run it again before 5 second passes to confirm it prints `On cooldown!`.
+Check the cooldown in your function:
+```mcfunction:my_function
+execute if function :cooldown run tellraw @a {"text": "Cooldown Ready!"}
+```
diff --git a/src/routes/guide/cooldown/worldclock/+page.svx b/src/routes/guide/cooldown/worldclock/+page.svx
new file mode 100644
index 0000000..0d3c418
--- /dev/null
+++ b/src/routes/guide/cooldown/worldclock/+page.svx
@@ -0,0 +1,74 @@
+---
+title: Worldclock-based cooldown
+description: Learn how to create and check cooldown timers using the world clock.
+version: 26.1
+---
+
+# Worldclock-based cooldown
+
+A worldclock cooldown stores a timestamp of when an action was last used in a scoreboard objective.
+Your datapack compares this stored time with the current time to determine if the cooldown has ended.
+
+This is a non-ticking approach: your datapack only does work when the player
+tries to use the action. This makes it a good fit for larger datapacks with many
+different cooldowns to check.
+
+## What you will build
+- A `cooldown.json` clock in the world clock folder.
+- A `timespan` scoreboard objective that stores when the action was last used.
+- A `:check_cooldown` function that checks whether enough time has passed.
+
+### 1) Setup the world clock
+In your datapack namespace, create a folder named `world_clock`. Then, create a file named
+`cooldown.json` inside the folder.
+```json:cooldown.json
+{}
+```
+Restart your world/server, then run `/time of :cooldown query time` to verify.
+(`/reload` won't work).
+
+### 2) Create the scoreboard objectives
+
+The `timespan` scoreboard objective stores the last time the action was used in the `cooldown` world clock.
+
+```mcfunction
+scoreboard objectives add timespan dummy
+```
+
+### 3) Create the action function (`do_things.mcfunction`)
+
+When you trigger this function, this is what happens:
+
+- Store the current time in the `#current` score.
+- Subtract `timespan` from `#current` to get ticks since last use.
+- Subtract the cooldown length from the result.
+- If the result is negative, the player is still on cooldown, return fail.
+- Otherwise, store the current time into `timespan` and return 1 (success).
+
+```mcfunction:cooldown.mcfunction
+# Store the current timespan
+execute store result score #current timespan run time of :cooldown query time
+# ticks since last use = #current - timespan
+scoreboard players operation #current timespan -= @s timespan
+# cooldown = ticks since last use - cooldown duration (change 100 to your cooldown length in ticks)
+scoreboard players remove #current timespan 100
+# If the result is negative, the cooldown is still active, return fail.
+execute if score #current timespan matches ..-1 run return fail
+# Cooldown finished: save the current gametime as the new last_used timestamp
+execute store result score @s timespan run time of :cooldown query time
+# Return success
+return 1
+```
+
+:::warning
+
+Do not modify the `cooldown` world clock; it will break the cooldown calculations.
+
+:::
+
+## Testing
+
+Check the cooldown in your function:
+```mcfunction:my_function
+execute if function :cooldown run tellraw @a {"text": "Cooldown Ready!"}
+```
From dfc0c48c887eb01d69d1f0b4fe680a6568d3c46d Mon Sep 17 00:00:00 2001
From: InfinityI
Date: Sat, 28 Mar 2026 14:53:56 +0700
Subject: [PATCH 7/7] - fix inconsistency naming
---
src/routes/guide/cooldown/worldclock/+page.svx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/routes/guide/cooldown/worldclock/+page.svx b/src/routes/guide/cooldown/worldclock/+page.svx
index 0d3c418..20c952c 100644
--- a/src/routes/guide/cooldown/worldclock/+page.svx
+++ b/src/routes/guide/cooldown/worldclock/+page.svx
@@ -16,7 +16,7 @@ different cooldowns to check.
## What you will build
- A `cooldown.json` clock in the world clock folder.
- A `timespan` scoreboard objective that stores when the action was last used.
-- A `:check_cooldown` function that checks whether enough time has passed.
+- A `:cooldown` function that checks whether enough time has passed.
### 1) Setup the world clock
In your datapack namespace, create a folder named `world_clock`. Then, create a file named