Cooldowns

structurecooldown: <duration>

Time between uses. Units: ticks, seconds, minutes, hours, days, or short forms such as 90s and 1h 30m

on right click:
    cooldown: 2 seconds
    send "&7Click!"

Try it

structurecooldown message: <text>

Sent instead of running the trigger. %cooldown% becomes the time left, e.g. 59 minutes 30 seconds

command /kit:
    cooldown: 1 hour
    cooldown message: "&cYou must wait %cooldown% before using this again!"
    trigger:
        give 1 diamond to player

Try it

expressionworlds: <name>, <name>since 1.7.64

At the top of an event's block: the block runs only when it happens in one of those worlds

on block break:
    worlds: "survival", "resource"
    add 1 to {%player%.mined}

Try it

structurepermission: <node>since 1.7.64

At the top of an event's block: it runs only for a player who has that permission

on player join:
    permission: "vip.perks"
    send "&6Welcome back, VIP."

Try it

effectreset cooldown

A statement: gives the player their cooldown back, for when the trigger decides not to do anything

reset cooldown

Try it

expressionlimit: <n> per <duration>since 1.7.23

At most that many runs in that long for each player: limit: 5 per second, limit: 20 per 10 seconds, limit: 1 per minute. Runs beyond it are dropped without a word. Goes where cooldown: goes, on a command or as the first line of an event

on chat:
    limit: 3 per 5 seconds
    add 1 to {%player%.messages}

Try it

expressionstart cooldown <name> of <duration>since 1.7.14

Starts a cooldown of your own for the player, by any name you like. Add for <who> to start it for someone else. Starting it again replaces the time left

on right click with stick:
    if player is on cooldown "zap":
        stop
    start cooldown "zap" of 3 seconds
    strike lightning at player

Try it

expressionend cooldown <name>since 1.7.14

Ends it early; for <who> as above

command /resetkit <player>:
    permission: kits.admin
    trigger:
        end cooldown "kit" for arg.1
        send "&aDone."

Try it

structurecooldown <name>since 1.7.14

An expression: the time left, or unset once it is over. cooldown <name> of <who> for someone else

command /kittime:
    trigger:
        set {_left} to cooldown "kit"
        if {_left} is set:
            send "&7Kit ready in &f%{_left}%"
        else:
            send "&aYour kit is ready."

Try it

Guide and examples

A cooldown limits how often each player can run a command or trigger an event.

command /kit:
    cooldown: 1 hour
    cooldown message: "&cYou must wait %cooldown% before using this again!"
    trigger:
        give 1 diamond to player

On an event, the cooldown lines come first inside the block:

on right click:
    cooldown: 2 seconds
    send "&7Click!"

Line	Meaning
`cooldown: <duration>`	Time between uses. Units: `ticks`, `seconds`, `minutes`, `hours`, `days`, or short forms such as `90s` and `1h 30m`
`cooldown message: <text>`	Sent instead of running the trigger. `%cooldown%` becomes the time left, e.g. `59 minutes 30 seconds`
`worlds: <name>, <name>`	At the top of an event's block: the block runs only when it happens in one of those worlds
`permission: <node>`	At the top of an event's block: it runs only for a player who has that permission
`reset cooldown`	A statement: gives the player their cooldown back, for when the trigger decides not to do anything
`limit: <n> per <duration>`	At most that many runs in that long for each player: `limit: 5 per second`, `limit: 20 per 10 seconds`, `limit: 1 per minute`. Runs beyond it are dropped without a word. Goes where `cooldown:` goes, on a command or as the first line of an event
`start cooldown <name> of <duration>`	Starts a cooldown of your own for the player, by any name you like. Add `for <who>` to start it for someone else. Starting it again replaces the time left
`end cooldown <name>`	Ends it early; `for <who>` as above
`cooldown <name>`	An expression: the time left, or unset once it is over. `cooldown <name> of <who>` for someone else

Commands have a default message if none is given. Events stay silent unless one is given, since an event is usually not something the player asked for.
limit: or cooldown:? A cooldown makes a player wait after one use and can tell them how long. A limit lets a burst through and stops a flood: it is for events a player can set off many times a second (chat, clicks, movement), where a script that does real work on every one of them would be made to work as hard as the player cares to click. Limits are not saved.
cooldown: or start cooldown? cooldown: is for the common case, one wait per command or event. start cooldown is for everything else: a wait that starts only when the trigger succeeds, one shared by several commands, or one on an item or a menu button. Test it with player is on cooldown "<name>". These too are saved and survive restarts.
The cooldown starts when the trigger starts. If your trigger can refuse (wrong arguments, not enough coins), use reset cooldown before stop so the player is not charged for nothing.
Cooldowns are saved with the player's data, so they survive relogs and server restarts.
The console is never on cooldown. Players with the permission hyperscript.cooldown.bypass are not either; it is not granted to anyone by default, not even operators.
The expiry time is stored in an ordinary player variable, {%player%.hs.cooldown.command.<name>} for commands. Deleting it ends the cooldown: delete {%player%.hs.cooldown.command.kit}.