Docs

How syntax is written on these pages. <name> stands for a value you put there. Something in square brackets, such as [or drop], may be left out. Round brackets with a slash, such as (below/above), mean one of those words. Everything else is written as it stands.

A script is a list of commands, event handlers, timers and functions. Blocks are formed by indentation (spaces or tabs, as long as you are consistent), and every line that opens a block ends with :.

A line that ends with a backslash carries on with the next one, so long text or a long condition can be spread over several lines:

on player join:
    send "&7Welcome to the server. Read the rules, " + \
        "be kind to each other, and have fun."

# starts a comment: everything after it on the line is ignored, so it is where you leave notes for yourself and for whoever edits the script next. A # inside quotes is ordinary text.

# Notes
#  - The reward is the number in /daily. Change it there.

options:
    <name>: <value>

function <name>(<locals>):
    <statements>

on load:
    <statements>

on <event>:
    <statements>

command /<name> [<argument description>]:
    <options>
    trigger:
        <statements>

every <duration>:
    <statements>

on discord command "/<name>":
    <statements>

on load: is not a server event. Its block runs once each time the file is loaded: when the server starts, on /hyperscript reload, and when the file is saved with hot reloading on. It runs with no player, like a console command, and after every script has been loaded, so it may call functions from other files. It is the place to set defaults and create teams:

on load:
    if {motd} is not set:
        set {motd} to "&aWelcome!"

There are two kinds of variable, told apart by the first character of the name.

set {event_active} to true
set {_tempDamage} to 4.5
set {%player%.coins} to 100
delete {%player%.coins}

• Values are numbers, text, the booleans true and false, items, durations, locations, or a list of any of those. See Value types.
• {name} is global: one saved value that any script can read and change.
• {_name} is local: a name that begins with an underscore. It exists for one run of the command, event handler or function it appears in, starts unset every time, and nothing else can see it, not even another trigger in the same file.
• A local may be written without its braces, as plain _name. It is the same variable either way, and a script may use both. The braces are how these pages write it, because every other variable has them too; scripts written the shorter way keep working as they are.
• A local can be a small table: {_data.name} and {_data.kills} are named values inside the local {_data}. The whole table can be handed to a function, returned from one, and looped over with for each {_key}, {_value} in {_data}:. Like any local it is never saved.
• Names are case-insensitive and may use letters, digits, _, - and ..
• A global name that starts with a player belongs to that player. {%player%.coins} is the coins of the player of this trigger, {%arg.1%.coins} the coins of whoever was named in the command, and {%loop-player%.coins} the coins of each player in a loop all players. Everybody has their own value, it is stored with their account so it survives a name change, and it can be read and changed while they are offline.
• A player is anyone online or anyone who has played on the server before. If the first part of a name is not a player, the variable is an ordinary global under the name as written. So for a table that is *not* about players, start the name with a fixed word: {warp.%arg.1%} rather than {%arg.1%.warp}.
• Reading {%player%.<name>} when there is no player (a console command, a timer) gives unset; writing it is a runtime error.
• {player.coins}, without the percent signs, is one global shared by everyone. The word player in a variable name is just part of the name; it is %player% that stands for the player.
• A colon works like a dot in a variable's name, for those who prefer it: {%player%:role} is the same variable as {%player%.role}, and {stats::kills} the same as {stats.kills}.
• Tables in lists. A local table can be put in a list and saved, which is how to keep records of several things each: set {_home.name} to "base", set {_home.spot} to player's location, append _home to {%player%.homes}. Looping gives each one back as a table: for each {_home} in {%player%.homes}: then {_home.name} and {_home.spot}. The list holds its own copy, so the local can be changed and used again for the next one.
• Shared variables. With storage.shared-variables on, a variable whose name starts with shared. is the same on every server that uses the database; see The database.
• Variables for a time. set {%player%.boost} to 2 for 10 minutes sets it and unsets it again by itself when the time is up. The time keeps counting while the server is off, and a variable whose time ran out then is gone when the server starts. Setting it for another time starts the time anew; setting it without for changes the value but not when it ends. This is for saved variables; a local one ends with its trigger anyway.
• Temporary variables. A variable whose name starts with temp. is never saved. {temp.round} lasts until the server stops, and a player's own, {%player%.temp.combat}, is forgotten the moment they leave. Use them for things that should not outlive a session, such as "is in a fight" or "has a menu open", and there is nothing to tidy up when a player joins.
• Unset variables count as 0 in math, as nothing when joined to text with +, and as false in conditions, so counters need no setup: add 1 to {%player%.joins} works the first time. Test for it explicitly with is set / is not set.
• A variable may have any name that is not already a built-in placeholder. {%player%.coins} and {event.start_time} are fine; {player.name} is refused, because player.name is built in. The same name after %player%. is allowed: {%player%.name} is simply a per-player variable.
• To put a variable in a string, wrap it in percent signs: "%{%player%.coins}%" and "%{_reward}%".
• A value between percent signs may have a name in quotes of its own: "Mined: %quest progress "miner"%", "You have %plural({_n}, "home")%.". So inside text, %{...}% is a variable and %...% without braces is a placeholder.
• A value written out works between percent signs too, as long as it is several words or a call: "You have %size of {_list}% items", "That is %round({_n})% coins". Something that does not read as a value is shown as it was written, so "50% off, 20% more" stays what it is. Text in quotes cannot stand inside it; put that in a local variable first.

Settings that a script uses in several places can be named once, at the top of the file, and used anywhere in it as {@name}:

options:
    prefix: "&8[&6Shop&8] "
    price: 50
    wait: 10 minutes

command /buy:
    cooldown: {@wait}
    trigger:
        if {%player%.coins} < {@price}:
            send "{@prefix}&cThat costs {@price} coins."
            stop
        subtract {@price} from {%player%.coins}
        give 1 diamond to player
        send "{@prefix}&aBought a diamond."

• The options: block stands at the left margin, like a command. Each line in it is name: value.
• An option is not a variable. Before a line is read, every {@name} in it is replaced by the option's value exactly as written, so an option can be a number, a duration, text, an item, a permission, or part of a header such as every {@interval}:.
• Inside quotes, an option that is itself quoted text is put in without its quotes, which is why "{@prefix}&aBought" works.
• Options belong to the file they are in and cannot be changed while the server runs. For something that changes, use a variable.
• Using a name that is not in the block is an error when the script loads.

Saying which version a script needs. A comment # Requires: 1.5.7 among the notes at the top of a file makes an older plugin refuse the file with one clear message, "This script needs HyperScript 1.5.7 or newer", instead of an error about whichever line it does not understand. The scripts on the website's Scripts page all carry one.

A variable holds whatever you put in it. Besides numbers, text, booleans and lists there are richer kinds of value: durations, locations and items, described here, and dates, which have a part of their own, Dates and times. All of them are saved with the rest of the variable data.

set {%player%.backpack.item} to diamond sword named "Storage"
set {event.start_time} to 30 minutes
set {%player%.home} to player's location
give {%player%.backpack.item} to player
teleport player to {%player%.home}

Items are Minecraft material names written as plain words, with spaces instead of underscores. The name is checked when the script loads, so a misspelt item is reported straight away.

An item value can be given with give, shown in a GUI slot (slot 5 is {%player%.backpack.item}), kept in a list, or adjusted when used: give player 5 {%player%.backpack.item} gives five of it. Items carry a material, amount, name, lore, enchantments, the unbreakable and glowing marks, a hidden tag, a custom model number, a head's owner and a potion's kind. How worn an item is, is not kept.

Durations are a number followed by ticks, seconds, minutes, hours or days (the unit must be written out in full inside a script line), and may be chained: 1 hour 30 minutes.

• In math and comparisons a duration counts as its number of seconds: 30 minutes > 60 is true and server.time + 30 minutes is the moment half an hour from now.
• Adding or subtracting two durations gives a duration; any other arithmetic gives a number of seconds.
• Wherever a statement takes a time, any duration works: for 10 seconds, for 2 minutes.

Locations remember a world and a position. player's location is where the player stands. A location can be used anywhere a position is expected: teleport player to {%player%.home}, spawn particle "flame" at {%player%.home}.

The parts of a location can be read and changed one at a time:

set {_loc} to player's location
add 1 to y of {_loc}
set x of {_loc} to 0
send "Going to %{_loc}%"
teleport player to {_loc}

Mixing types up. Each kind of value can only do what makes sense for it. Adding a number to a whole location, or doing math on an item, stops the trigger and writes a warning to the log that names the script, the line and both kinds of value:

[HyperScript] kits.hs:14 Cannot add a number to a location (world 10.5, 64, -3.25). To change one coordinate, name it: add 1 to y of <variable>

These warnings are on by default. log-script-errors: false in config.yml hides them; the trigger still stops at the mistake, so leave them on unless the log is being flooded.

if {%player%.coins} >= 100:
    send "&aYou can afford it."
else if {%player%.coins} >= 50:
    send "&eAlmost there."
else:
    send "&cNot enough coins."

A comparison can be written with its sign or in words; both mean the same:

command /check:
    trigger:
        set {_players} to server.online_players
        if {_players} bigger than 50:
            send "&aBusy today."
        if {_players} smaller than 5:
            send "&7Quiet today."
        if level of player is at least 30:
            send "&6You may enter."
        if level of player at most 5:
            send "&7You are new here."
        if arg.1 is equal to "red":
            send "&cRed it is."
        if arg.1 is not equal to "red":
            send "&7Not red."
        if y of player's location is below 0:
            send "&8Deep down."
        if y of player's location is above 200:
            send "&bHigh up."
        if level of player is between 10 and 20:
            send "&eIn the middle."
        if {_players} is greater than or equal to 1 and {_players} is not more than 100:
            send "&7Somebody is here."

• On one line: a short if can have its statement on the same line, after the colon: if arg.1 is not set: stop. It takes one statement and has no else.
• else unless <condition>: joins the chain alongside else if.
• Every is test has an is not form: player is not sneaking, arg.1 is not in {allowed}.
• unless <condition>: is if the other way round; it runs its block when the condition is false:

unless player has permission "fly.use":
    send "&cYou cannot fly here."
    stop

• A bare value is a condition too: if {event_active}: is true for true, any non-zero number, any non-empty list, and any text other than false or empty.
• ==, != and contains ignore case for text, and == compares numerically when both sides are numeric ("5" == 5 is true).
• not binds tighter than and, which binds tighter than or. Use parentheses when in doubt.
• player has permission "x" checks whoever triggered the script, so it is true for the console. To check someone else, put a name on the left: arg.1 has permission "x".
• has <item> counts across the whole inventory, armour and off hand included. A plain item such as 5 diamond matches any diamonds; an item written with a name or lore only matches stacks that carry them. A player who is offline has nothing. Take items away with remove 5 diamond from player; see Actions.

loop 3 times:
    send "Hello!"

for each {_name} in sorted server.players:
    send "&7 - &f%{_name}%"

loop all players: runs its block once for every player who is online:

loop all players:
    add 10 to {%loop-player%.coins}
    send "&a%player.name% gave you 10 coins!" to loop-player

Inside any loop, loop-value is what the loop is on: the number of the round, the element of the list, the player.

loop 3 times:
    send "&7Round %loop-value%"

loop from 10 to 1:
    send "&e%loop-value%..."
    wait 1 second
send "&aGo!"

loop from 0 to 100 by 25:
    send "&7%loop-value%%"

loop {queue}:
    send "&7%loop-index%. &f%loop-value%"

In a loop inside a loop the values are numbered from the outside in: loop-value-1 belongs to the first loop, loop-value-2 to the one inside it.

loop from 1 to 3:
    loop from 1 to 3:
        send "&7%loop-value-1% x %loop-value-2% = &f%loop-value-1 * loop-value-2%"

A loop can take some of what it goes through only, and say what to do when there was nothing:

loop all players with permission "staff.alerts":
    send "&c%player.name% needs help." to loop-player
else:
    send "&7No staff are online."

loop {queue} where loop-value is not player.name:
    send "&7%loop-index%. &f%loop-value%"

loop blocks within 3 blocks of player:
    if block at loop-value is "fire":
        set block at loop-value to air

A counter, and a table's names and values:

loop 5 times with {_i}:
    send "&7Round %{_i}%"

for each {_name}, {_place} in {warp}:
    send "&b%{_name}% &7is at %{_place}%"

break and continue steer a loop from inside:

for each {_name} in {queue}:
    if {_name} is "Steve":
        continue
    if size of {_picked} >= 3:
        break
    append {_name} to {_picked}

A while loop repeats for as long as its condition holds:

set {_n} to 3
while {_n} > 0:
    send "&e%{_n}%..."
    wait 1 second
    subtract 1 from {_n}
send "&aGo!"

• loop <n> times: repeats its block. To protect the server it refuses more than 100,000 (loop-limit in config.yml changes that) repetitions.
• for each {_item} in <list>: runs its block once per element, with the element in the local.
• loop <n> times with {_i}: puts the number of the round, from 1, in the local.
• loop from <a> to <b>: counts from the one number to the other, both included, and loop-value is the number: loop from 1 to 5 is 1, 2, 3, 4, 5 and loop from 5 to 1 is 5, 4, 3, 2, 1. by <n> is how far apart the numbers are: loop from 0 to 10 by 5 is 0, 5, 10, and loop from 0 to 1 by 0.25 works as well. Which way it counts is said by the two ends, so by is never negative, and it stops at the last number that does not pass the end: loop from 10 to 0 by 3 is 10, 7, 4, 1. The same limit as for loop <n> times applies.
• loop <list>: goes through a list without a local to name: loop {queue}:, loop sorted server.players:. The element is loop-value. Given a number it goes round that many times, so loop {_n}: is loop {_n} times:.
• loop-value is what the loop around the line is on. In loop <n> times and while that is the number of the round; in loop from the number; in for each and loop <list> the element (with for each {_key}, {_value} the value); in loop all players the player, like loop-player; in countdown the seconds left; in repeat the round. In text it is %loop-value%, and it can be written loop_value.
• loop-index is which round the loop is on, from 1, whatever the loop goes through: "%loop-index%. %loop-value%" numbers a list.
• In a loop inside a loop, loop-value-1 is the value of the outermost loop, loop-value-2 of the loop inside it, and so on; loop-index-1, loop-index-2 likewise. The plain loop-value is always the innermost loop's, the one the line is directly in. A number that no loop has (loop-value-3 inside two loops) is refused when the script loads, and so is loop-value outside a loop. To subtract from it, leave a space: loop-value - 1.
• for each {_key}, {_value} in {table}: goes through every name under a table and the value stored there, for saved tables ({warp}, {%player%.homes}) and local ones ({_data}) alike.
• repeat every <time> for <time>: runs its block, waits, and runs it again until the time is up; see Waiting.
• countdown 10 seconds: is a repeat that counts: its block runs once a second and seconds left is 10, then 9, down to 1. The lines after the block run when it has reached the end, so they are where "Go!" belongs. break ends it early.
• once every 5 seconds for player: runs its block at most that often for each player, which is a cooldown around any lines you like; else: under it is where "wait a moment" goes. It can also be written at most once every 5 seconds for player:.
• once for player: runs its block the first time a player gets there and never again; once per day for player: once in each day by the server's calendar, so a reward taken at 23:59 can be taken again at 00:00. Put a name after once (once "daily" per day for player:) if the block may be moved or changed later: without one HyperScript tells the once blocks of a script apart by what they say, and one that is rewritten counts as new. else: works as after if.
• loop all players: goes through whoever is online when it starts. Inside it, loop-player (in text, %loop-player%) is the name of the player the loop is on (it can also be written loop player or loop_player, which are the same word), and player is still whoever ran the command or caused the event. Everything that takes a player takes loop-player: loop-player's location, health of loop-player, {%loop-player%.coins}, send "..." to loop-player, loop-player has permission "x". loop-number is which round the loop is on, starting at 1; it is the same as loop-index and works in every loop.
• loop all players takes what says which of them: with permission "<node>", in world "<name>", within <n> blocks of <location>, or where <condition>, in which loop-player is each player in turn: loop all players where health of loop-player < 5:. The same works wherever something is done to all players: send "..." to all players with permission "staff", send title "Go!" to all players in world "arena".
• loop <list> where <condition>: goes through the elements the condition holds for only; in the condition loop-value is the element. loop-index then counts the ones that were kept.
• Anything that gives a list can be looped over: loop blocks within 3 blocks of player: and loop blocks from {_a} to {_b}: (each loop-value is the location of a block, so block at loop-value is what is there), loop entities within 10 blocks of player:, loop players within 10 blocks of player:, loop items in inventory of player:. Blocks are counted before the loop starts, and more than loop-limit of them are refused.
• else: directly under a loop runs when the loop never went round: the list was empty or was never set, nobody was online, the condition of a while did not hold the first time.
• while <condition>: checks the condition before every round.
• break loop 1 and continue loop 1 reach a loop further out, by the same numbers as loop-value-1: 1 is the outermost. break loop 1 leaves that loop and every loop inside it; continue loop 1 ends the loops inside it and starts its next round. They take a condition like the plain ones: break loop 1 if {_found} is set.
• break leaves the loop it is in and carries on after it. continue skips the rest of this round and starts the next. In nested loops both act on the innermost one.
• stop inside a loop ends the whole trigger, not just the loop.
• All three take a condition on the same line: stop if {_coins} < 100, continue if loop-player is player.name, break unless {_found} is set. stop with <text> tells the player something first: stop with "&cNot enough coins." if {_coins} < 100.
• A while loop that goes round 100,000 times (loop-limit in config.yml) without a wait is stopped with an error in the console, so a condition that never becomes false cannot freeze the server. A loop that waits each round may run for as long as you like.

switch runs one block out of several, chosen by a value. It reads better than a chain of else if when a command has many subcommands:

switch arg.1:
    case "on", "enable":
        set {event_active} to true
    case "off", "disable":
        set {event_active} to false
    default:
        send "&eUsage: /event <on|off>"

• The first case with a matching value runs, and only that one; there is no falling through.
• A case may list several values, separated by commas. Text is compared ignoring case, as == does.
• case 1 to 5: is every number from the one to the other, both included, and can stand in a list with others: case 1 to 5, 10, 20 to 30:.
• default: runs when nothing matched. It is optional.

A function is a block with a name. Write it once, at the left margin like a command, and call it from anywhere:

function reward({_who}, {_amount}):
    add {_amount} to {%{_who}%.coins}
    send "&a+%{_amount}% coins" to {_who}
    return {%{_who}%.coins}

command /daily:
    cooldown: 1 day
    trigger:
        set {_total} to reward(player.name, 50)
        send "&7You now have %{_total}% coins."

• The values in the brackets arrive in the locals named there. A function with nothing to take is written function refresh(): and called refresh().
• A parameter may have a default: function reward({_who}, {_amount} = 10): can be called as reward(player.name) or reward(player.name, 50). Parameters with a default come last.
• Call a function on a line of its own (reward(player.name, 50)) or anywhere a value is expected (set {_total} to reward(player.name, 50), if is_rich(player.name):).
• return <value> leaves the function and hands the value back; return on its own just leaves. A function that never returns a value gives unset.
• Inside a function, player and the event values are those of whoever called it. Its locals are its own: it cannot see the caller's locals, and the caller cannot see its.
• A plain function is shared by every script, in whatever order the files load, so two scripts may not both define a shared function of the same name; the second one is refused with a message naming the first. Use local function for helpers that only one file needs. When both exist, a file's own local function is the one it gets.
• Function names are letters, digits and _, and may not be a word that starts a statement, such as send or give.
• A function may call itself. Calls nested more than 64 deep are stopped with an error, so one that never ends cannot freeze the server.
• A wait inside a function pauses the function only: the caller carries on at once, and gets whatever had been returned by then (normally nothing).

wait pauses the trigger it is in, then carries on with the next line. Only that trigger pauses; the server and every other script keep running.

command /launch:
    trigger:
        send "&eLaunching in 3 seconds..."
        wait 3 seconds
        execute console command "effect give %player.name% minecraft:levitation 2 20"
        wait 2 seconds
        send "&aEnjoy the view."

• wait works anywhere, including inside if, loops, GUI click blocks and async:. Local variables keep their values across it.
• Time passes while a trigger waits. The player may have moved or logged out, and variables may have been changed by other scripts, so check again afterwards if it matters.
• After a wait, the event that started the trigger is over: cancel event and statements that change the event, such as set join message, no longer have any effect.
• The shortest wait is one tick (a twentieth of a second). Waits do not survive a server restart or a script reload.

Waiting for something. wait until pauses until a condition holds, looking again four times a second:

send "&7Stand on the gold block to start."
wait until block at (location below player's location) is "gold_block" for at most 30 seconds
send "&aGo!"

It gives up after the time given with for at most, or after five minutes if none is given, and the script carries on either way; test the condition again afterwards if it matters.

Doing something later, and again. run calls a function after a delay without making the rest of the trigger wait, and repeat runs a block at intervals for a while:

function unfreeze_later({_who}):
    unfreeze {_who}
    send "&aYou can move again." to {_who}

command /timeout <player>:
    permission: "staff.timeout"
    trigger:
        freeze arg.1
        run unfreeze_later(arg.1) in 30 seconds

command /countdown:
    trigger:
        set {_n} to 10
        repeat every 1 second for 10 seconds:
            send title "&e%{_n}%" to all players
            subtract 1 from {_n}

Normally a line that cannot be done stops the trigger and reports the mistake. try: lets a script deal with it instead:

try:
    set {_data} to send get request to "https://hyperscript.monoforge.net/api/test"
    log "The website answered: %{_data}%"
on error:
    log "Could not reach the website: %{_error}%"

https://hyperscript.monoforge.net/api/test is a real address kept for trying requests out: it answers with the plain text Yup works.

• If anything in the try: block fails, the rest of the block is skipped and the on error: block runs, with {_error} holding the message.
• on error: is optional. Without it the failure is simply ignored and the script carries on.
• fail "<text>" is a mistake of your own making: the trigger stops there as it does for any other, and a try: around it, also one in the code that called the function it is in, gets the text in {_error}. Outside a try: it ends the trigger and is written to the console.
• Only mistakes made while running are caught. A line HyperScript cannot read still stops the whole file from loading.
• A failure after a wait inside the block is not caught; put the try: after the wait.

This is the file installed to plugins/HyperScript/scripts/disabled_demo.hs on first start, switched off until /hyperscript enable demo (source). It uses commands, every event, math, persistent variables, a GUI, lists, an async block, world effects, cooldowns, titles, a boss bar, an opt-in sidebar driven by a timer, a custom item, a stored location, a text file per player, sounds, a protected region, time and weather, a web API lookup read with json value, fall-damage protection, a countdown built from while and wait, a function, parse, another player's variables, loop all players, inventory checks, and ends with Discord examples that are commented out until config.yml is set up.

# ==============================================================
#  demo.hs - a tour of HyperScript
#  Edit this file, then run /hyperscript reload
# ==============================================================

# ---- Events --------------------------------------------------

on player join:
    if {%player%.joins} is not set:
        set {%player%.joins} to 0
        set {%player%.coins} to 100
        broadcast "&6Welcome &e%player.name% &6to the server for the first time!"
    add 1 to {%player%.joins}
    send "&aHello %player.name%! &7Visit #%{%player%.joins}%, balance &e%{%player%.coins}% coins"
    send "&7Server %server.version% | TPS %server.tps% | Online %server.online_players%"
    if {event_active}:
        send "&d&lThe double coins event is active!"

on player quit:
    log "%player.name% left with %{%player%.coins}% coins (ping %player.ping% ms)"

on block break:
    # Regions made with /protect: only admins may break blocks inside them.
    if region at event's location contains "spawn":
        if player does not have permission "demo.admin":
            cancel event
            send "&cYou cannot break blocks inside the spawn region!"
            play sound "block.anvil.land" with pitch 0.5 and volume 1.0 at player's location
            stop
    set {_reward} to random integer between 1 and 3
    if event.block contains "ore":
        set {_reward} to {_reward} * 5
    if player has permission "demo.vip":
        set {_reward} to {_reward} + 2
    if {event_active}:
        set {_reward} to {_reward} * 2
    add {_reward} to {%player%.coins}
    add 1 to {%player%.blocks}
    # Every 50th block pays a bonus.
    if {%player%.blocks} % 50 == 0:
        add 25 to {%player%.coins}
        send "&b%{%player%.blocks}% blocks mined! &6+25 bonus coins"
        play sound "entity.player.levelup" with pitch 1.2 and volume 0.8 for player

on entity death:
    # The player here is the killer; there is none when a mob dies on its own.
    if event.killer is set:
        set {_bounty} to random integer between 5 and 15
        add {_bounty} to {%player%.coins}
        send "&6+%{_bounty}% coins &7for slaying a %event.entity%"

on player chat:
    # Inside an event, its values have short names: "message" is event.message.
    if message contains "free op":
        cancel event
        send "&cThat phrase is not allowed here."

on entity damage:
    # Fires for every hit on the server, so the cheapest test comes first.
    if cause is "FALL":
        if player has permission "demo.nofall":
            cancel event
            send action bar "&aFall damage negated!" to victim

on right click:
    # At most once every 2 seconds per player; clicks in between are ignored.
    cooldown: 2 seconds
    if event.item == "compass":
        send "&bWorld &f%player.world% &7| &bMode &f%player.gamemode% &7| &bHealth &f%player.health%"

# ---- Commands ------------------------------------------------

command /coins:
    description: Show your coin balance
    usage: /coins
    aliases: bal, balance
    trigger:
        if player is not set:
            send "&cOnly players have a balance."
            stop
        send "&6Balance: &e%{%player%.coins}% coins"

command /gamble:
    description: Bet coins on a 45% chance to double them
    usage: /gamble <amount>
    permission: demo.gamble
    permission message: "&cYou are not allowed to gamble."
    aliases: bet
    trigger:
        if player is not set:
            send "&cOnly players can gamble."
            stop
        if args.count != 1 or arg.1 is not a number:
            send "&cUsage: /gamble <amount>"
            stop
        set {_bet} to arg.1
        if {_bet} <= 0:
            send "&cThe bet must be more than 0."
        else if {_bet} > {%player%.coins}:
            send "&cYou only have %{%player%.coins}% coins."
        else if random integer between 1 and 100 <= 45:
            add {_bet} to {%player%.coins}
            send "&aYou won %{_bet}% coins! &7Balance: %{%player%.coins}%"
        else:
            subtract {_bet} from {%player%.coins}
            send "&cYou lost %{_bet}% coins. &7Balance: %{%player%.coins}%"

command /event:
    description: Toggle the double coins event
    usage: /event <on|off>
    permission: demo.admin
    trigger:
        if arg.1 == "on":
            set {event_active} to true
            broadcast "&d&lDouble coins event started!"
            create bossbar "event" titled "&d&lDouble Coins Event" with color purple with progress 100 for all players
        else if arg.1 == "off":
            set {event_active} to false
            broadcast "&7The double coins event has ended."
            remove bossbar "event"
        else:
            send "&eEvent active: %{event_active}% &7- usage: /event <on|off>"

# ---- GUIs, lists, async and world effects --------------------

command /shop:
    description: Open the coin shop
    usage: /shop
    trigger:
        if player is not set:
            send "&cOnly players can open the shop."
            stop
        open gui with title "&8Coin Shop" with 3 rows for player:
            slot 12 is "diamond" named "&bDiamond" lore "&7Price: &e50 coins|&7Click to buy":
                if {%player%.coins} < 50:
                    send "&cYou need 50 coins for that."
                else:
                    subtract 50 from {%player%.coins}
                    execute console command "give %player.name% diamond 1"
                    spawn particle "dust" colored "#55ffff" count 20 at player
                    send "&aBought a diamond. &7Balance: %{%player%.coins}%"
                close gui
            slot 14 is "gold_ingot" named "&6Balance: &e%{%player%.coins}% coins"
            slot 16 is "barrier" named "&cClose":
                close gui

command /who:
    description: List online players in alphabetical order
    usage: /who
    trigger:
        send "&6Online (%server.online_players%):"
        for each {_name} in sorted server.players:
            send "&7 - &f%{_name}%"

command /sethome:
    description: Remember where you are standing
    usage: /sethome
    trigger:
        if player is not set:
            stop
        # A variable can hold a location (world and coordinates) as one value.
        set {%player%.home} to player's location
        spawn text display "&e%player.name%'s home" at player for 10 seconds
        send "&aHome set."

command /home:
    description: Return to your home
    usage: /home
    trigger:
        if {%player%.home} is not set:
            send "&cUse /sethome first."
            stop
        teleport player to {%player%.home}
        send "&aWelcome home. &7(%{%player%.home}%)"

command /highscores:
    description: Show the balances recorded with /cashout
    usage: /highscores
    trigger:
        # {scores} is a list; /cashout appends to it.
        async:
            # Sorting and filtering run off the server thread...
            set {_ranked} to reversed sorted {scores}
            set {_count} to size of {_ranked}
            set {_best} to item 1 of {_ranked}
            set {_rich} to size of (filter {_ranked} where it >= 500)
            sync:
                # ...and the result is reported back on it.
                if {_count} == 0:
                    send "&7No scores yet. Use /cashout to record yours."
                else:
                    send "&6Best score: &e%{_best}% &7(%{_count}% recorded, %{_rich}% of 500 or more)"

command /cashout:
    description: Record your current balance on the high score list
    usage: /cashout
    trigger:
        if player is not set:
            stop
        append {%player%.coins} to {scores}
        send "&aRecorded &e%{%player%.coins}% &aon the high score list."

# ---- Functions, other players and parsing --------------------

# A function can be called from any script. Written as "local function"
# it could only be used in this file.
function pay({_from}, {_to}, {_amount}):
    subtract {_amount} from {%{_from}%.coins}
    add {_amount} to {%{_to}%.coins}
    return {%{_to}%.coins}

command /pay <player> <amount>:
    description: Give some of your coins to another player
    usage: /pay <player> <amount>
    trigger:
        if player is not set:
            stop
        # Arguments arrive as text; parse turns "52" into the number 52.
        set {_amount} to parse arg.2 as integer
        if {_amount} is not set or {_amount} < 1:
            send "&c'%arg.2%' is not an amount."
            stop
        # A name that starts with a player is that player's own variable,
        # whether they are online or not.
        if {%arg.1%.joins} is not set:
            send "&c%arg.1% has never played here."
            stop
        if {%player%.coins} < {_amount}:
            send "&cYou only have %{%player%.coins}% coins."
            stop
        set {_total} to pay(player.name, arg.1, {_amount})
        send "&aSent &e%{_amount}% &acoins to %arg.1%."
        send "&e%player.name% &asent you &e%{_amount}% &acoins. You now have &e%{_total}%&a." to arg.1

command /bonus <amount>:
    description: Give every online player some coins
    usage: /bonus <amount>
    permission: op
    trigger:
        set {_amount} to parse arg.1 as integer
        if {_amount} is not set:
            send "&cUsage: /bonus <amount>"
            stop
        # "player" is still whoever ran the command; "loop-player" is each player in turn.
        loop all players:
            add {_amount} to {%loop-player%.coins}
        send "&6Everybody received &e%{_amount}% &6coins from %player.name%!" to all players

command /sell:
    description: Sell 8 cobblestone for 4 coins
    usage: /sell
    trigger:
        if player does not have 8 cobblestone:
            send "&cYou need 8 cobblestone to sell."
            stop
        remove 8 cobblestone from player
        add 4 to {%player%.coins}
        send "&aSold 8 cobblestone for &e4 coins&a."

on player death:
    subtract 5 from {%player%.coins}
    send "&cYou died and lost 5 coins."

# ---- Cooldowns, titles, scoreboards and particle shapes ------

command /kit:
    description: Claim a starter kit once an hour
    usage: /kit
    cooldown: 1 hour
    cooldown message: "&cYou must wait %cooldown% before using /kit again!"
    trigger:
        if player is not set:
            send "&cOnly players can claim a kit."
            stop
        give 1 diamond to player
        give 16 bread to player
        send title "&6Kit claimed!" with subtitle "&eCome back in an hour" to player with fadein 10 stay 60 fadeout 20
        send action bar "&a+1 Diamond  +16 Bread" to player
        draw particle circle with radius 1.5 using particle "flame" at player's location

command /sidebar:
    description: Show or hide the stats sidebar
    usage: /sidebar
    trigger:
        if player is not set:
            stop
        if {%player%.sidebar}:
            set {%player%.sidebar} to false
            clear player's scoreboard
            send "&7Sidebar hidden."
        else:
            set {%player%.sidebar} to true
            send "&aSidebar shown."

# Runs once a second for every online player; only those who asked get the sidebar.
every 1 second for all players:
    if {%player%.sidebar}:
        set title of player's scoreboard to "&e&lHYPERSCRIPT"
        set line 1 of player's scoreboard to "&7Coins: &a%{%player%.coins}%"
        set line 2 of player's scoreboard to "&7Ping: &f%player.ping% ms"
        set line 3 of player's scoreboard to "&7Online: &f%server.online_players%"
        set line 4 of player's scoreboard to "&7TPS: &f%server.tps%"

# ---- Custom items, files and text ----------------------------

command /excalibur:
    description: Receive a named sword, once a day
    usage: /excalibur
    cooldown: 1 day
    trigger:
        if player is not set:
            send "&cOnly players can wield it."
            stop
        give player 1 diamond sword named "&6Excalibur" with lore "&7A legendary blade", "&7Forged in fire."
        # Items are values too: remember what was handed out.
        set {%player%.last_reward} to diamond sword named "&6Excalibur"
        send "&aYou received &f%{%player%.last_reward}%&a."

command /note:
    description: Save a note to a text file, or read it back
    usage: /note [text]
    trigger:
        if player is not set:
            stop
        # One file per player, named by UUID so nothing a player types ends up in the path.
        set {_path} to "plugins/HyperScript/notes/%player.uuid%.txt"
        if args.count > 0:
            set file at {_path} to args
            send "&aNote saved."
        else if file at {_path} exists:
            set {_note} to read file at {_path}
            set {_words} to split {_note} by " "
            set {_count} to size of {_words}
            set {_shout} to uppercase (first 20 characters of {_note})
            send "&eYour note (%{_count}% words): &f%{_note}%"
            send "&7Starts with: &f%{_shout}%"
        else:
            send "&7You have no note yet. Write one with /note <text>"

# ---- Worlds, regions, sounds and web requests ----------------

command /day:
    description: Set the time to day and clear the weather in your world
    usage: /day
    permission: demo.admin
    trigger:
        if player is not set:
            send "&cRun this as a player, so there is a world to change."
            stop
        set time in world "%player.world%" to 1000
        set weather in world "%player.world%" to clear
        broadcast "&e%player.name% set the time to day in %player.world%!"
        play sound "block.note_block.pling" with pitch 2.0 and volume 0.5 for all players in world "%player.world%"

command /protect:
    description: Protect the area within 5 blocks of you as the spawn region
    usage: /protect
    permission: demo.admin
    trigger:
        if player is not set:
            stop
        create region "spawn" from player.x - 5, 0, player.z - 5 to player.x + 5, 255, player.z + 5
        send "&aSpawn region set around you. Remove it with /unprotect."

command /unprotect:
    description: Remove the spawn region
    usage: /unprotect
    permission: demo.admin
    trigger:
        delete region "spawn"
        send "&7Spawn region removed."

command /lookup <player>:
    description: Look up a player's UUID using Mojang's web API
    cooldown: 5 seconds
    trigger:
        if args.count != 1:
            send "&cUsage: /lookup <player>"
            reset cooldown
            stop
        send "&eFetching data from the API..."
        # Web requests wait for an answer, so they belong in an async block.
        async:
            set {_response} to send get request to "https://api.mojang.com/users/profiles/minecraft/" + urlencoded arg.1
            # The answer is JSON such as {"id":"...","name":"..."}; pick the id out of it.
            set {_uuid} to json value "id" of {_response}
            sync:
                if {_uuid} is set:
                    send "&aUUID of %arg.1%: &f%{_uuid}%"
                else:
                    send "&cPlayer profile not found."

command /countdown:
    description: Count down from 3, one number a second
    usage: /countdown
    cooldown: 10 seconds
    trigger:
        set {_n} to 3
        # 'wait' pauses this trigger only; the server carries on as normal meanwhile.
        while {_n} > 0:
            send title "&e%{_n}%" to player with fadein 0 stay 20 fadeout 5
            play sound "block.note_block.pling" for player
            wait 1 second
            subtract 1 from {_n}
        send title "&aGo!" to player

# ---- Server list, tab list and chat (remove the leading '#' to use) ----
#
# on server ping:
#     set motd to random item of ["&6HyperScript demo server", "&bNow with double coins!"]
#     set max players to 100
#
# on player join:
#     set join message to "&a+ &f%player.name%"
#     set tab header of player to "&6&lMy Server"
#     set tab footer of player to "&7Online: %server.online_players%"
#
# on player chat:
#     set chat format to "&7[&bMember&7] &f%player.name%&7: &f%event.message%"

# ---- Resource packs (remove the leading '#' and use your own pack) ----
#
# on player join:
#     send resource pack "https://example.com/pack.zip" with hash "da39a3ee5e6b4b0d3255bfef95601890afd80709" to player
#
# on resource pack decline:
#     send "&cYou declined the resource pack. Some custom items may look wrong."
#
# on resource pack successfully loaded:
#     send "&aResource pack loaded!"

# ---- Discord (remove the leading '#' after setting up config.yml) ----
#
# Webhooks need a URL under discord.webhooks in config.yml:
#
# on player join:
#     send webhook "alerts" with content "%player.name% joined the server" as "HyperScript"
#
# Slash commands need discord.bot.enabled and a bot token:
#
# on discord command "/online":
#     reply "%server.online_players% player(s) online: %server.players%"

command /banner <text>:
    trigger:
        set {_title} to arg.1 centered to 30
        send "&8[&f%{_title}%&8]"
        for each {_word} in words of "red green blue":
            send "&7%{_word}%"
        set {_inner} to between("Hello [world]!", "[", "]")
        set {_bar} to lerp(0, 20, 0.25)
        send "&7%{_inner}% %{_bar}%"

set {_data} to "Coins:500"
set {_parts} to split {_data} by ":"
set {_coins} to item 2 of {_parts} + 100
send "You have %{_coins}% coins"

• parse is how text that came from a player, a file or a web page becomes a number you can rely on. If the text is not a number the result is unset, which is easy to test for:

set {_amount} to parse arg.1 as number
if {_amount} is not set:
    send "&c'%arg.1%' is not a number."
    stop

• Directly after send, the word title means a title on screen, so put title case in a variable first or in brackets: send (title case {_item}).
• Any colour: besides &a style codes, text may use <#rrggbb> for an exact colour, as in "<#ff8800>Orange <#00c8ff>and blue". It works wherever colour codes do, on Minecraft 1.16 and newer.
• now formatted as takes Java's date letters: yyyy year, MM month number, MMMM month name, d day, EEEE weekday name, HH hour, mm minute, ss second. "d MMMM yyyy 'at' HH:mm" gives 11 October 2026 at 18:30. Text inside single quotes is taken as it is.
• The separator in split is taken literally, and splitting by "" gives the single characters.
• Pieces of split text still work as numbers, as item 2 of {_parts} + 100 shows.
• Slices that run past either end of the text are cut to fit; they never cause an error.
• Each of these takes the single value right after it. To apply one to a longer expression, use parentheses: uppercase (first 3 characters of {_name}).
• A new line in text is written %nl%, or %new line%: send "&6Rules%nl%&71. Be kind". It works in every text: chat, holograms, lore, files, and text in front of a player.

*, / and % bind tighter than + and -, as usual.

set {%player%.coins} to {%player%.coins} + 50
set {_rand} to random integer between 1 and 10
set {_tax} to ({%player%.coins} - 100) * 0.05
add 5 to {%player%.coins}            # shorthand for set ... to ... + 5
subtract {_tax} from {%player%.coins}  # shorthand for set ... to ... - {_tax}

Details:

• + adds when both sides are numbers and joins text otherwise: "Level " + 5 is Level 5. Text that looks like a number counts as a number, so arg.1 + 1 adds.
• Numbers print without a trailing .0; other decimals are shown to at most 4 places.
• Dividing (or taking a modulo) by zero, or doing math on non-numeric text, stops the trigger and logs a warning with the script name and line.
• These functions come with the language, so a script cannot define a function called min, round and so on.
• duration(...) is how a number of seconds becomes readable: set {_left} to duration({%player%.ready} - server.time) then send "Wait %{_left}%." says "Wait 9 minutes 30 seconds." In math it still counts as seconds.
• The upper bound of random ... between A and B extends to the end of the arithmetic, so random integer between 1 and 10 + 5 means 1 to 15. Use parentheses to say otherwise: (random integer between 1 and 10) + 5.

set {_nums} to [5, 3, 9, 1]
set {_names} to ["Steve", "Alex"]
set {_empty} to []

Statements that change a list variable:

append player.name to {winners}
set {_top} to reversed sorted {scores}
set {_rich} to filter {_top} where it >= 500
send "Best: %{_top}% (of which %{_rich}% are 500 or more)"
if {winners} contains player.name:
    send "You already won."

• A list prints as its elements joined by , .
• Lists can be stored in global and player variables and are saved like any other value.
• Operations never modify a list in place; they produce a new one. set {_b} to {_a} followed by a change to {_b} leaves {_a} alone.
• More ways to take a list apart:

• keys of {warp} looks at every saved variable whose name starts with warp. and gives the next part of each name: with {warp.spawn} and {warp.arena} set, it is the list arena, spawn. That is how a script loops over a table it has built. It works for a player's own tables as well: keys of {%player%.homes}.
• filter reads to the end of the condition, including any and / or. Wrap it in parentheses to use the result in a larger expression: size of (filter {_nums} where it > 4).

HyperScript has no user-defined types. Structured data is built from variable names instead, in two ways that combine freely.

Records: group related values under one prefix.

set {%player%.home.x} to player.x
set {%player%.home.y} to player.y
set {%player%.home.z} to player.z

Tables: put a run-time value inside the name with %...%, giving one variable per key.

set {balance.%player.name%} to 250
set {_target} to arg.1
send "%{_target}% has %{balance.%{_target}%}% coins"

The inserted part is lower-cased like the rest of the name, so Steve and steve are the same key. Combined with lists (below), this covers most data a script needs to keep.

now is the present moment as a value. It can be stored, compared, and moved forward or back with a duration.

command /daily:
    trigger:
        if {%player%.next_daily} is set and now < {%player%.next_daily}:
            set {_left} to time until {%player%.next_daily}
            send "&cCome back in %{_left}%."
            stop
        set {%player%.next_daily} to now + 1 day
        give 3 diamond to player
        send "&aSee you again on " + ({%player%.next_daily} formatted as "EEEE 'at' HH:mm")

• A date prints as 11 October 2026 18:30 unless you format it. The letters for formatted as are Java's: yyyy year, MM month number, MMMM month name, d day, EEEE weekday, HH hour, mm minute, ss second. Text inside single quotes is taken as it is.
• Dates compare with < and >, and can be saved in variables like any other value.
• In arithmetic with plain numbers a date counts as seconds since 1970, the same scale as server.time, so the two mix: now > server.time - 60.
• Times follow the clock of the machine the server runs on.

Another place's clock. <date> formatted as "<pattern>" in time zone "<zone>" writes a moment as the clock shows it somewhere else: now formatted as "HH:mm" in time zone "Europe/Berlin". The zone is one of the world's names for them, such as "America/New_York", "Asia/Tokyo" or "UTC".

A script that speaks to players can keep its texts in one place, once for each language, and let every player read their own:

messages:
    en:
        welcome: "&aWelcome, %player%!"
        no-money: "&cYou cannot afford that."
    de:
        welcome: "&aWillkommen, %player%!"
        no-money: "&cDas kannst du dir nicht leisten."

on player join:
    send message "welcome"

• The language is the one the player has set in Minecraft. de_at uses de if there is no de_at; a language or a message that is missing falls back on the first language in the block, so write the complete one first.
• A text may use colours, placeholders and saved variables (%player%, %{%player%.coins}%) but not local variables: put a value that changes into a saved variable, or add it after the message with +.
• The messages belong to the file they are written in. The name must be written out in quotes (message "welcome"), and a name the block does not have is a mistake found when the file loads.
• In a file without a messages: block, message keeps its other meaning: what was said in chat.

Placeholders are read-only live values that HyperScript provides, such as the player's name or the server's TPS. They are written in two ways, depending on where they stand:

Braces are never used for placeholders. {...} always means a variable of your own; see Variables.

The table lists each placeholder as it is written inside text. In code, leave the percent signs off: server.tps, arg.1, event.block. (The percent form is accepted in code as well, so %arg.1% == "on" still works.)

Two more describe the player as a whole: player is the player, for use wherever a player is expected (send "hi" to player), and inside text %player% is their name. player.location is where they stand, as a location.

Writing a placeholder in braces, as in {player.name} or %{player.name}%, is an error that says how to write it instead. That was the syntax before version 1.5.4, so scripts from older versions need those places changed.

"The player" is whoever caused the trigger: the player who joined, broke the block, ran the command, clicked the GUI slot, or, for on entity death, the killer. A placeholder with nothing to report (for example %player.name% when the console runs a command) is unset and prints as <none>.

send "TPS is %server.tps% and your ping is %player.ping% ms"
if player.health < 6:
    send "&cYou are badly hurt!"

command /heal:
    description: Restore your health
    usage: /heal [player]
    permission: demo.heal
    permission message: "&cYou cannot use /heal."
    aliases: h, mend
    trigger:
        execute console command "effect give %player.name% minecraft:instant_health 1 10"
        send "&aHealed."

A number within limits. An argument that is a number can say what it has to lie between: <amount:number 1 to 10000>, <level:integer at least 1>, [percent:number at most 100]. A player who gives another number is told amount must be between 1 and 10000. and the trigger does not run.

command /pay <target:player> <amount:number 1 to 10000>:
    trigger:
        subtract arg.2 from {%player%.coins}
        add arg.2 to {%arg.1%.coins}
        send "&aYou paid %arg.1% %money(arg.2)%."

The command line may describe its arguments after the name, as in command /pay <player> <amount>:. It becomes the usage text unless a usage: line is given, and it decides what pressing Tab offers while the command is typed:

Subcommands. A command with several jobs can give each one its own block instead of a switch on the first argument. Each subcommand has its own permission, description, checked arguments and trigger, and arg.1 inside it is the first word *after* its name:

command /warp <name>:
    tab complete: keys of {warp}
    trigger:
        teleport player to {warp.%arg.1%}
    subcommand set <name>:
        permission: "warps.manage"
        trigger:
            set {warp.%arg.1%} to player's location
            send "&aWarp %arg.1% set."
    subcommand list:
        trigger:
            send "&7Warps: &f" + join keys of {warp} with ", "

• /warp set base runs the set block; /warp base runs the command's own trigger.
• A command may consist of subcommands only. Used without one, it answers with their names.
• Tab offers the subcommands a player is allowed to use, then each one's own arguments.
• tab complete: takes any list and is worked out when Tab is pressed, so it can offer warp names, team names or anything else a script keeps.

What Tab offers, argument by argument. tab complete: can also be a block. Its lines run each time Tab is pressed, and set arg.1 to ... in it says what is offered for the first argument, set arg.2 to ... for the second, and so on. The lines are ordinary code, so what is offered for one argument can depend on what was typed for the ones before it:

command /rank [action] [target] [rank]:
    permission: "ranks.admin"
    tab complete:
        set arg.1 to "set", "remove", "list"
        set {_online} to server.players
        if arg.1 is "set" or arg.1 is "remove":
            set arg.2 to {_online}
        if arg.1 is "set":
            set arg.3 to "owner", "admin", "moderator", "vip"
    trigger:
        send "&7You typed: %args%"

What stands after to may be values written one after the other, a list, or both.

• Typing /rank and pressing Tab offers set, remove and list; after /rank set Steve it offers the ranks; after /rank list nothing, because the block set nothing for that.
• An argument the block says nothing about is offered what the command's header says: the players who are online for <player>, the words of <on|off>.
• Only what begins with what has been typed so far is shown, whatever the capitals.
• The block runs on every press of Tab, so keep it to working out what to offer. It is not the place to send messages or change variables.
• Outside this block an argument cannot be set: in a trigger arg.1 is what was typed.

Checked arguments. Give an argument a type and HyperScript checks it before the trigger runs, answering with what is wrong, and the usage line for a missing argument or a number that is not one:

command /pay <target:player> <amount:number> [note]:
    players only: true
    trigger:
        subtract arg.2 from {%player%.coins}
        add arg.2 to {%arg.1%.coins}

An argument without a type is not checked, as before. The types are not shown in the usage line.

A command declared without any arguments keeps the server's default, which is player names. The arguments are still read with %arg.1%, %arg.2% and so on, and are not checked for you.

A short command can also simply use a switch on the first argument, without subcommand blocks:

command /kit <starter|food>:
    trigger:
        switch arg.1:
            case "starter":
                give 1 stone sword to player
            case "food":
                give 16 bread to player
            default:
                send "&eUsage: /kit <starter|food>"

Commands can be run from the console; there is then no player. players only: true keeps the console out, or test if player is not set: yourself.

A command can be limited to players holding a permission node, or to server operators:

command /fly:
    permission: "server.fly"
    trigger:
        execute console command "fly %player.name%"

command /shutdown:
    permission: op
    trigger:
        execute console command "stop"

Scripts can also hand out permissions themselves:

command /buyfly:
    trigger:
        if {%player%.coins} < 500:
            send "&cFlying costs 500 coins."
            stop
        subtract 500 from {%player%.coins}
        permission player add "server.fly"
        send "&aYou can now use /fly."

• <who> is player, all players, or a player name; the player has to be online.
• Granted permissions are saved with the player's data and applied again each time they join.
• remove only undoes what add gave. A permission the player has from a rank or another plugin stays; change that in the plugin that manages your ranks.

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!"

• 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}.