Merge pull request #121 from tqcuong2000/main

Add "cooldown checks" section

Author: Silabear

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 IconHourglass from "~icons/tabler/hourglass-empty";
   import SidebarPlaceholder from "../navigation/SidebarPlaceholder.svelte";
 </script>
 
@@ -71,6 +74,14 @@
     page="/guide/adding-new-features/custom-items/models" />
 </SidebarCategory>
 
+<SidebarCategory name="Cooldowns" icon={IconHourglass}>
+  <SidebarPage label="Summary" icon={IconPennant} page="/guide/cooldown" />
+
+  <SidebarHeading label="Techniques" />
+  <SidebarPage label="Scoreboard" icon={IconScoreboard} page="/guide/cooldown/scoreboard" />
+  <SidebarPage label="Worldclock" icon={IconClock} page="/guide/cooldown/worldclock" />
+</SidebarCategory>
+
 <SidebarCategory name="Right Click Detection" icon={IconMouse}>
   <SidebarPage label="Summary" icon={IconPennant} page="/guide/right-click" />
 

src/routes/guide/cooldown/+page.svx

@@ -0,0 +1,30 @@
+---
+title: Cooldown checks
+description: Learn how to create and check cooldown timers using several common methods.
+version: 26.1
+---
+
+# Cooldown checks
+
+A cooldown restricts how frequently a player triggers a custom action. In most
+datapacks, these actions involve running functions or commands.
+
+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.
+
+## 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.
+
+
+## Implementation methods
+
+There are two main ways to implement a cooldown mechanic in your project:
+
+- [Scoreboard-based cooldown](/guide/cooldown/scoreboard) - Uses a scoreboard objective to store how 
+much time remaining until the cooldown expires. This is the simplest and the easiest to understand version, 
+but if you're creating a larger datapack, or intend on using it with multiple players, you may prefer to use an alternative version to minimise system lag.
+- [Worldclock-based cooldown](/guide/cooldown/worldclock) - Uses the time on a worldclock to measure the elapsed time since an action was last used. This is a non-ticking approach that works well for large datapacks, or any project that uses many cooldown timers.

src/routes/guide/cooldown/scoreboard/+page.svx

@@ -0,0 +1,100 @@
+---
+title: Scoreboard-based cooldown
+description: Learn how to create and check cooldown timers using a scoreboard objective.
+version: 26.1
+---
+
+# 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). This works well 
+for small projects with only a few cooldowns and short durations. If you track many cooldowns or 
+many entities, this negatively affects performance, because the game has to run loads of commands.
+
+In summary, this approach sets a player's score on a scoreboard, and then decreases that score every 
+tick. This means that, when we need to do something which requires a cooldown, we can just check the 
+score to see if the player has an active cooldown or not.
+
+## What you will create
+
+- A `my_cd` scoreboard objective (this tracks the actual cooldown for each plalyer)
+- A `tick` function (this reduces each player's cooldown score)
+- A `check_cooldown` function (this will be used to check and reset the player's cooldown)
+
+:::tip
+
+To learn how to trigger a function when a player uses an item, see the 
+[Right-click menu](/guide/right-click) guide.
+
+:::
+
+### 1. Create the scoreboard objective
+
+In your load function, create a dummy objective named `my_cd`. A dummy 
+objective is just a scoreboard which can only be changed by commands.
+
+```mcfunction:load.mcfunction
+scoreboard objectives add my_cd dummy
+```
+
+### 2. Reduce the score in the `tick` function
+
+In your `tick` function (which runs every tick), reduce the `my_cd`
+score by 1 for any player with `my_cd` ≥ 1.
+
+```mcfunction:tick.mcfunction
+scoreboard players remove @a[scores={my_cd=1..}] my_cd 1
+```
+
+:::note
+
+Alternatively, if optimisation is an concern, you can decrease the commands used, and use a `minecraft:tick` advancement so that 
+it only runs the command when the player has an active cooldown. To do this, you would need a tick advancement which runs a function - 
+in that function, you would decrease the player's score and then revoke the advancement only if their score is 1 or more. This would replace 
+the commands in the tick function, and slightly help to minimise lag.
+
+:::
+
+### 3. Create the `check_cooldown` function
+
+You will run this function whenever you want to do something which is on a cooldown. For example, 
+if you have a special item which you only want the player to be able to use once every 5 seconds, 
+you would run this function to check if the player is on cooldown or not.
+
+In this function, we check the executor's `my_cd` score to tell whether they have an active cooldown. 
+- If the score is 1 or higher (i.e. they haven't reached the end of the cooldown), then the function will return a **failure**..
+- If the score is 0 or doesn't exist yet (i.e. they do not have an active cooldown), then the function will return a **success**.
+
+```mcfunction:check_cooldown.mcfunction
+# If the player is still on cooldown, tell the player and stop here.
+execute if score @s my_cd matches 1.. run tellraw @s {color:"red",text:"This is on cooldown! Wait before you try again."}
+execute if score @s my_cd matches 1.. run return fail
+
+# If the function hasn't yet been stopped, then the player is not on a cooldown
+# so we can set the cooldown and then return a success. 
+
+scoreboard players set @s my_cd 100
+return 1
+```
+
+## 4. Using the `check_cooldown` function
+
+Whenever the player does something that needs a cooldown, you can use `execute if function` with the `check_cooldown` function. If the 
+player still is on a cooldown, then the function will fail and the command will not run. If the player isn't on a cooldown, then 
+the function will set the cooldown and then return a success, so the command WILL run.
+
+In this example, a creeper will only be summoned when the player has no active cooldown (in which case, the cooldown will be set).
+If the player has an active cooldown, then the creeper will not be summoned, and instead the error message in `check_cooldown.mcfunction` 
+will be sent.
+
+```mcfunction
+execute as <player> if function <namespace>:check_cooldown run summon creeper
+```
+
+## Using multiple cooldowns
+
+If you want to have multiple different cooldowns for different items, then you will need a different `cooldown` scoreboard and `check_cooldown`
+function for each cooldown. You will also need to decrease the score for each cooldown in the tick function. 

src/routes/guide/cooldown/worldclock/+page.svx

@@ -0,0 +1,89 @@
+---
+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 works by storing 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.
+
+Although this is more complicated, this function doesn't rely on any ticking commands. This is especially
+good for much larger datapacks because it is the most performance-efficient method.
+
+## What you will create
+- A `cooldown.json` clock in the world clock folder.
+- A `last_used` scoreboard objective (this stores when the action was last used).
+- A `<namespace>:check_cooldown` function (this is used to check the cooldown)
+
+### 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. This 
+basically just registers a new world clock (think of this as a special type of stopwatch). This file needs no data, other than `{}`. 
+
+```json:/world_clock/cooldown.json
+{}
+```
+
+Restart your world/server (`/reload` isn't enough here), then run `/time of <namespace>:cooldown query time` to verify that the clock exists.
+
+### 2. Create the scoreboard objective
+
+You will need a scoreboard objective stores the last time the action was used in the `cooldown` world clock. You can call this scoreboard
+anything - for simplicity, here we will call it `last_used`. You should create this scoreboard objective in your load function.
+
+```mcfunction:load.mcfunction
+scoreboard objectives add last_used dummy
+```
+
+### 3. Create the `check_cooldown` function
+
+You will run this function whenever you want to do something which is on a cooldown. For example, 
+if you have a special item which you only want the player to be able to use once every 5 seconds,
+you would run this function to check if the player is on cooldown or not.
+
+In this function, we check the executor's `last_used` score against the current time on the `cooldown` clock. If the
+difference between the times is less than 100 ticks (5 seconds), then the function will return a **failure**. If not,
+then the function will return a **success** and the `last_used` will be set to the current time. 
+
+```mcfunction:check_cooldown.mcfunction
+# Temporarily store the current time on the cooldown clock
+execute store result score #current_time last_used run time of <namespace>:cooldown query time
+
+# Calculate the difference in times (i.e. the time since the action was last used)
+# basically: "#current_time" = "#current_time" - time of last use
+scoreboard players operation #current_time last_used -= @s last_used
+
+# If the difference is less than 100 ticks, then not enough time has passed, so we tell the player and then return a failure
+execute if score #current_time last_used matches ..100 run tellraw @s {color:"red",text:"This is on cooldown! Wait before you try again."}
+execute if score #current_time last_used matches ..100 run return fail
+
+# If the function hasn't yet been stopped, then the player is not on a cooldown
+# so we can update the last_used time and then return a success. 
+
+execute store result score @s last_used run time of <namespace>:cooldown query time
+return 1
+```
+
+:::warning
+Don't modify the `cooldown` world clock; it will break the cooldown calculations.
+:::
+
+## 4. Using the `check_cooldown` function
+
+Whenever the player does something that needs a cooldown, you can use `execute if function` with the `check_cooldown` function. If the
+player still is on a cooldown, then the function will fail and the command will not run. If the player isn't on a cooldown, then
+the function will set the cooldown and then return a success, so the command WILL run.
+
+In this example, a creeper will only be summoned when the player has no active cooldown (in which case, the cooldown will be set).
+If the player has an active cooldown, then the creeper will not be summoned, and instead the error message in `check_cooldown.mcfunction` 
+will be sent.
+
+```mcfunction
+execute as <player> if function <namespace>:check_cooldown run summon creeper
+```
+
+## Using multiple cooldowns
+
+If you want to have multiple different cooldowns for different items, then you will need a different `last_used` scoreboard and `check_cooldown`
+function for each cooldown. However, you can re-use the `cooldown` world clock for as many cooldowns as you wish.