Skip to content

Cooldown category update #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NervN merged 3 commits into from
Sep 1, 2025
Merged

Cooldown category update #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ddebeed
Cooldown category update
zerofoil Apr 25, 2025
c19f33e
Request category update
zerofoil Apr 26, 2025
d0cb41a
Merge branch 'raspdevpy:main' into main
zerofoil Sep 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 43 additions & 37 deletions guide/Cooldown/channelCooldown_ai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +1,61 @@
# $channelCooldown

Sets a cooldown for a command, *per channel*! This means the command can only be used again in the specific channel after the specified cooldown has expired.
Sets a cooldown for a command in channel.

#### Usage:
## Usage

`$channelCooldown[time (default is 5s);Error message]`
```bash
$channelCooldown[time;error message]
```
1. **time** - (Optional) default value: `5s`. The cooldown duration. Example times: `10s`, `1m`, `2h`, `1d`
2. **error message** - (Optional) default value: (none). The message to send if a cooldown is still in progress.

* **time:** The cooldown duration. Defaults to 5 seconds if not provided. Examples: `10s`, `1m`, `2h`, `1d`.
* **Error message:** The message to send when a user tries to use the command before the cooldown expires.
## Example

### Example:
#### Using $channelCooldown

As you can see, first time it will set the cooldown and execute code below, second time, it won't allow execution

<discord-messages>
<discord-message :bot="false" role-color="#ffcc9a" author="Member">
!!exec $channelCooldown[2h;You can get points again after %time%]<br>
$sendMessage[You received 100x points.]
</discord-message>
<discord-message :bot="true" role-color="#0099ff" author="Custom Command" avatar="https://media.discordapp.net/avatars/725721249652670555/781224f90c3b841ba5b40678e032f74a.webp">
You can get points again after 1 hour 54 minutes and 56 seconds
</discord-message>
<discord-message :bot="false" role-color="#d6e0ff" author="User" avatar="https://cdn.discordapp.com/embed/avatars/0.png">
!!exec $channelCooldown[5m;You're on cooldown!]<br>
You're not on cooldown!
</discord-message>
<discord-message :bot="true" role-color="#5fb0fa" author="Custom Command" avatar="https://doc.ccommandbot.com/bot-profile.png">
You're not on cooldown!
</discord-message>
<discord-message :bot="false" role-color="#d6e0ff" author="User" avatar="https://cdn.discordapp.com/embed/avatars/0.png">
!!exec $channelCooldown[5m;You're on cooldown! Still %mins%m remaining!]<br>
You're not on cooldown!
</discord-message>
<discord-message :bot="true" role-color="#5fb0fa" author="Custom Command" avatar="https://doc.ccommandbot.com/bot-profile.png">
You're on cooldown! Still 4m remaining!
</discord-message>
</discord-messages>

In this example, the command will give the user 100 points. If they try to use the command again within 2 hours in the same channel, they will receive the error message: "You can get points again after [remaining time]".

## Usable Macros in Error Message:
## Placeholders

These macros can be used in your error message to provide dynamic information about the cooldown.
Available placeholders you can use in error message

| Macro | Description | Output Example |
| ------------ | ------------------------------------------------- | ---------------------------------------- |
| `%time%` | Replaced with the remaining time in a readable format. | `5 days 1 hour 54 minutes and 56 seconds` |
| `%days%` | The number of days remaining. | `5` |
| `%hrs%` | The number of hours remaining. | `1` |
| `%mins%` | The number of minutes remaining. | `54` |
| `%secs%` | The number of seconds remaining. | `56` |
| `%timestamp%` | Unix timestamp (seconds) for when the cooldown expires. | `1680711176` |
| `%relative%` | Displays the remaining time using Discord's relative timestamp feature (updates automatically). | ![](https://i.imgur.com/F2bAFnk.png) |
| Placeholder | Description | Output Example |
| ------------- | --------------------------------------------------------- | ----------------------------------------- |
| `%time%` | The full time remaining | `1 day 2 hours 3 minutes and 4 seconds` |
| `%days%` | The number of days remaining | `1` |
| `%hrs%` | The number of hours remaining | `2` |
| `%mins%` | The number of minutes remaining | `3` |
| `%secs%` | The number of seconds remaining | `4` |
| `%timestamp%` | Timestamp of cooldown expiration in seconds | `1735689600` |
| `%relative%` | Shows Discord relative timestamp (Automatically Updates) | `<t:1735689600:R>` - Displays: `in 1 day` |

::: tip Note
You can send styled messages or embeds by using the [Message Curl Format](../CodeReferences/ref.message_curl_format.md) in the error message.
::: warning Warning
Place this function above the code you want to use cooldown for. All code before this function will be executed.
:::

::: tip Related Functions
* [$cooldown](../Cooldown/cooldown.md): Sets a cooldown for a command, *per user*.
* [$serverCooldown](../Cooldown/serverCooldown.md): Sets a cooldown for a command, *per server*.
::: tip Suggestion
You can send embeds, select menus and buttons by using the [message curl format](../CodeReferences/ref.message_curl_format.md).
:::

::: danger Important
Place the `$channelCooldown` function on the **FIRST line** of your command's code. If it's not the first line, the code before it will execute regardless of the cooldown, and the cooldown won't apply correctly.
:::

##### Function Difficulty: <Badge type="tip" text="Easy" vertical="middle" />
##### Related functions: [$cooldown](../Cooldown/cooldown.md) [$serverCooldown](../Cooldown/serverCooldown.md)

###### Tags: <Badge type="tip" text="Cooldown" vertical="middle" /> <Badge type="tip" text="Channel Cooldown" vertical="middle" /> <Badge type="tip" text="Raid Limit" vertical="middle" /> <Badge type="tip" text="Raid Limited" vertical="middle" />
##### Function Difficulty: <Badge type="tip" text="Easy" vertical="middle" />
###### Tags: <Badge type="tip" text="Cooldown" vertical="middle" /> <Badge type="tip" text="Channel Cooldown" vertical="middle" /> <Badge type="tip" text="Limit" vertical="middle" />
64 changes: 34 additions & 30 deletions guide/Cooldown/clearCoolDown_ai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,43 @@
# $clearCooldown

Clears a cooldown set by the `$cooldown` function. This allows you to bypass or reset cooldowns for specific users, channels, or servers.
Clears a cooldown set by cooldown function.

**Type:** Clears or resets a pre-existing cooldown.

## Usage

```bash
$clearCooldown[type (optional, default: user); id (optional, default: "$authorID")]
$clearCooldown[type;id]
```

**Parameters:**

* **`type` (Optional):** Specifies the scope of the cooldown to clear. Can be one of the following:
* `user`: Clears the cooldown for a specific user. (Default)
* `channel`: Clears the cooldown for the current channel.
* `server`: Clears the cooldown for the current server.
* **`id` (Optional):** Specifies the ID of the user, channel, or server to clear the cooldown for. Defaults to `$authorID` (the user who triggered the command) if no ID is provided.

## Example: Cooldown Exception for a Specific User

This example demonstrates how to set a cooldown for everyone *except* a specific user. The user "Mido" will be exempt from the cooldown.

```bash
$cooldown[1m;You are in cooldown because you are not Mido]
$if[$username==Mido]
$clearCooldown[user;$authorID]
$endIf
```

**Explanation:**

1. **`$cooldown[1m;You are in cooldown because you are not Mido]`**: This line sets a 1-minute cooldown for all users executing the command. The message "You are in cooldown because you are not Mido" will be displayed if a user tries to use the command within the cooldown period.
2. **`$if[$username==Mido]`**: This checks if the username of the user executing the command is "Mido".
3. **`$clearCooldown[user;$authorID]`**: If the username is "Mido", this line clears the cooldown specifically for that user (`$authorID`). This means Mido can bypass the 1-minute cooldown.
4. **`$endIf`**: Closes the `$if` statement.

In summary, this example sets a general cooldown but then removes it for the user "Mido", allowing them to use the command without waiting.
1. **type** - (Optional) default value: `user`. Can be `user`, `channel` or `server`. The type of cooldown to clear.
2. **id** - (Optional) default value: `$authorID` if type is user. The ID of a user or channel to clear cooldown from.

## Example

#### Remove cooldown from a user

How to remove cooldown from a user

<discord-messages>
<discord-message :bot="false" role-color="#d6e0ff" author="User" avatar="https://cdn.discordapp.com/embed/avatars/0.png">
!!exec $cooldown[5m]<br>
$clearCooldown<br>
No cooldown
</discord-message>
<discord-message :bot="true" role-color="#5fb0fa" author="Custom Command" avatar="https://doc.ccommandbot.com/bot-profile.png">
No cooldown
</discord-message>
<discord-message :bot="false" role-color="#d6e0ff" author="User" avatar="https://cdn.discordapp.com/embed/avatars/0.png">
!!exec $cooldown[5m]<br>
$clearCooldown<br>
No cooldown 2nd try
</discord-message>
<discord-message :bot="true" role-color="#5fb0fa" author="Custom Command" avatar="https://doc.ccommandbot.com/bot-profile.png">
No cooldown 2nd try
</discord-message>
</discord-messages>

##### Related functions: [$getCooldownTime](../Cooldown/getCooldownTime.md)

##### Function difficulty: <Badge type="tip" text="Easy" vertical="middle"/>
###### Tags: <Badge type="tip" text="Cooldown" vertical="middle"/> <Badge type="tip" text="Clear Cooldown" vertical="middle"/>
83 changes: 43 additions & 40 deletions guide/Cooldown/cooldown_ai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,62 @@
# $cooldown

Sets a per-user cooldown for a command. This prevents users from spamming a command within a specified timeframe.
Sets a cooldown in a command for user.

#### Usage:
## Usage

`$cooldown[time (default 5s);Error message;user id (optional)]`
```bash
$cooldown[time;error message;userID]
```
1. **time** - (Optional) default value: `5s`. The cooldown duration. Example times: `10s`, `1m`, `2h`, `1d`
2. **error message** - (Optional) default value: (none). The message to send if a cooldown is still in progress.
3. **userID** - (Optional) default value: `$authorID`. The ID of a user you want to set a cooldown to.

* **time:** The duration of the cooldown. Defaults to 5 seconds if not provided. Examples: `10s`, `1m`, `2h`, `1d`.
* **Error message:** The message displayed to the user if they try to use the command before the cooldown expires. You can use macros in this message (see below).
* **user id (optional):** Apply the cooldown to a specific user ID instead of the user executing the command. Useful for moderator commands.
## Example

### Example:
#### Using $cooldown

This example sets a 2-hour cooldown on a command that gives the user points. If the user tries to use the command before the cooldown expires, they will receive a message indicating how much time is left.
As you can see, first time it will set the cooldown and execute code below, second time, it won't allow execution

<discord-messages>
<discord-message :bot="false" role-color="#ffcc9a" author="Member">
!!exec $cooldown[2h;You can get points again after %time%]<br>
$sendMessage[You received 100x points.]<br>
</discord-message>
<discord-message :bot="true" role-color="#0099ff" author="Custom Command" avatar="https://media.discordapp.net/avatars/725721249652670555/781224f90c3b841ba5b40678e032f74a.webp">
You can get points again after 1 hour 54 minutes and 56 seconds<br><br>
</discord-message>
<discord-message :bot="false" role-color="#d6e0ff" author="User" avatar="https://cdn.discordapp.com/embed/avatars/0.png">
!!exec $cooldown[5m;You're on cooldown!]<br>
You're not on cooldown!
</discord-message>
<discord-message :bot="true" role-color="#5fb0fa" author="Custom Command" avatar="https://doc.ccommandbot.com/bot-profile.png">
You're not on cooldown!
</discord-message>
<discord-message :bot="false" role-color="#d6e0ff" author="User" avatar="https://cdn.discordapp.com/embed/avatars/0.png">
!!exec $cooldown[5m;You're on cooldown! Still %mins%m remaining!]<br>
You're not on cooldown!
</discord-message>
<discord-message :bot="true" role-color="#5fb0fa" author="Custom Command" avatar="https://doc.ccommandbot.com/bot-profile.png">
You're on cooldown! Still 4m remaining!
</discord-message>
</discord-messages>

## Usable Macros In Message:
## Placeholders

These macros can be used in the `Error message` to provide dynamic information about the remaining cooldown time.
Available placeholders you can use in error message

| Macro | Description | Output Example |
| -------------- | -------------------------------------------- | ------------------------------------- |
| `%time%` | Human-readable time remaining. | 5 days 1 hour 54 minutes and 56 seconds |
| `%days%` | Days remaining. | 5 |
| `%hrs%` | Hours remaining. | 1 |
| `%mins%` | Minutes remaining. | 54 |
| `%secs%` | Seconds remaining. | 56 |
| `%timestamp%` | UNIX timestamp (in seconds) of cooldown expiration. | 1680711176 |
| `%relative%` | Discord's relative timestamp (auto-updates). | ![](https://i.imgur.com/F2bAFnk.png) |
| Placeholder | Description | Output Example |
| ------------- | --------------------------------------------------------- | ----------------------------------------- |
| `%time%` | The full time remaining | `1 day 2 hours 3 minutes and 4 seconds` |
| `%days%` | The number of days remaining | `1` |
| `%hrs%` | The number of hours remaining | `2` |
| `%mins%` | The number of minutes remaining | `3` |
| `%secs%` | The number of seconds remaining | `4` |
| `%timestamp%` | Timestamp of cooldown expiration in seconds | `1735689600` |
| `%relative%` | Shows Discord relative timestamp (Automatically Updates) | `<t:1735689600:R>` - Displays: `in 1 day` |

::: tip Note
You can send an embed as the error message using [Message Curl Format](../CodeReferences/ref.message_curl_format.md).
::: warning Warning
Place this function above the code you want to use cooldown for. All code before this function will be executed.
:::

::: tip Related Functions

* [$channelCooldown](../Cooldown/channelCooldown.md): For a channel-based cooldown.
* [$serverCooldown](../Cooldown/serverCooldown.md): For a server-based cooldown.

::: tip Suggestion
You can send embeds, select menus and buttons by using the [message curl format](../CodeReferences/ref.message_curl_format.md).
:::

::: danger Important

Place this code on the **FIRST** line of your command's code. If it's not the first line, the code *before* `$cooldown` will execute regardless of the cooldown.

:::
##### Related functions: [$channelCooldown](../Cooldown/channelCooldown.md) [$serverCooldown](../Cooldown/serverCooldown.md)

##### Function difficulty <Badge type="tip" text="Easy" vertical="middle" />
###### Tags: <Badge type="tip" text="Cooldown" vertical="middle" /> <Badge type="tip" text="Wait" vertical="middle" /> <Badge type="tip" text="Raid Limit" vertical="middle" /> <Badge type="tip" text="Raid Limited" vertical="middle" />
##### Function Difficulty: <Badge type="tip" text="Easy" vertical="middle" />
###### Tags: <Badge type="tip" text="Cooldown" vertical="middle" /> <Badge type="tip" text="Limit" vertical="middle" />
Loading
Loading