Skript Cooldowns for Dummies

[NixTer]

Hello.

My name is Nix, and this is my (not so) brief essay tutorial about all you should need to know about cooldowns.
The gaming term "cooldown" originates from 1990 RPG games and usually refers to an item, ability, or miscellaneous part of the game that you couldn't use for a certain period of time. Often referred to as being "on cooldown".

To make this reading experience easier I have sliced this up into segments.

• Command cooldowns
• Item cooldowns I - refers to items that can be executed/used in vanilla minecraft (shields, buckets, potions, flint and steel, etc)
• Item cooldowns II - Everything else
• Cooldown messages

And so it begins...

Command cooldowns

If you're looking to add a cooldown to your command, you are in luck, because skript has smiled upon you this day.

Alongside trigger, aliases, permission, permission message, etc, you can add a cooldown, cooldown message, and cooldown bypass permission to your command.
For example:

command example:
    permission: example.use
    cooldown: 10 seconds
    cooldown message: You are on cooldown
    cooldown bypass: example.cooldownbypass
    trigger:
        message "beans" to player

On top of that, you can use additional information in your messages, as well as in further messages in the command. (full documentation can be found here)
cooldown message: You used this command %elapsed time% minutes ago
cooldown message: You have %remaining time% left on your cooldown
message "This command is now on cooldown for %cooldown time%" to player

Item cooldowns I

If you are using an item that does something when you click it in vanilla minecraft (here are all the ones I can think of off the top of my head)

• Fishing rod
• Any potion
• Buckets (milk, empty, water, lava)
• Flint and steel
• Ender Pearl
• Chorus fruit
• Any food item
• Bow/Crossbow
• Shield

Then you are, once again, in luck.
It is literally...1 line (if you are on skript 2.8.0+, if not, see Item cooldown II) And here and here are links to the documentation for both the expression and related condition.

#A few examples:

#cooldown when you eat
on consume:
        set item cooldown of player's tool to 10 seconds for player
     
#cooldown a specific item when they join
on join:
        set item cooldown of water bucket to 10 seconds for player
     
#cooldown an item when you right click it
on right click on flint and steel:
        set item cooldown of flint and steel to 10 seconds for player
     
#cooldown a projectile shooting item (bow/crossbow/enderpearl)
on shoot:
        set item cooldown of player's tool to 10 seconds for player

Item cooldown II

If you're looking to add a cooldown to an item like a sword or a diamond, you are slightly less in luck, but it's still not that bad. To do this, you can set a variable to the time you use the item, and then subtract that from the current time until it passes a specific threshold. For example,

on right click on iron sword:
    time between {cooldown::%player's uuid%} and now is less than 5 seconds:
        message "On cooldown!" to player
    else:
        #do stuff
        set {cooldown::%player's uuid%} to now

'Now' refers to the current time, so if it's 08:47:05 (8 hours, 47 minutes, 5 seconds) when you use the item, thats what {cooldown::%player's uuid%} will be set to. And if you subtract that from the time a second later (08:47:06), it returns 1 second. This is what we're doing here. So once that value returns something higher than 5 seconds (or if the variable is not set), the actual ability will be executed and the variable will be updated to the new time. Otherwise, it sends you a message.

Another (simpler) method is to use the same thing as used in Item Cooldown I

on right click on gold block:
    player has player's tool on cooldown:
        stop
    else:
        #do stuff
        set item cooldown of player's tool to 10 seconds for player

Cooldown messages

While cooldown messages for commands were included in the first section, you can include them for the next 2.
The example for Item cooldown II already includes one, but what if you wanted the time remaining? That can be achieved by subtracting the time passed from the length of the cooldown. Here's an example.

on right click on iron sword:
    difference between now and {cooldown::%player's uuid%} is less than 5 seconds:
        set {_d} to difference between now and {cooldown::%player's uuid%} #makes it easier to read
        message "On cooldown! Time left: %5 - {_d}%" to player
    else:
        #do stuff
        set {cooldown::%player's uuid%} to now

In this example, we set a local variable to the time and then subtract that from the time we're aiming for (5) to get the time left.

For Item cooldown I, the remaining time is displayed as a slowly going down gray sheet over the item icon, but you can still set a message. For example this one for a water bucket:

on right click on water bucket:
    if player has player's tool on cooldown: #requires skript 2.8+
        message "&cOn cooldown" to player

The above code checks if their item is on cooldown when they try to use the water bucket, and sends them a message (as you can probably tell)


With that, you have read all 4 sections. Thank you for suffering through reading my tutorial. I hope it helped you!