Changelog

More on the website for user-made scripts, the server list, profiles and the forum. The plugin itself is unchanged.

Added

• Tags on user-made scripts. Whoever sends a script in picks up to four of fourteen tags (economy, minigame, pvp, survival, admin, moderation, chat, cosmetics, quests, gui, worlds, utility, fun, roleplay). The list of user-made scripts has a row of them to press, and each script shows its own. Scripts that are on the site already get theirs with their next version.
• Screenshots on user-made scripts. Whoever made a script can add up to three pictures to it from the script's own page. A picture is made smaller in the browser before it is sent (no wider or taller than 1280 pixels, as WebP), the site takes nothing over 350 KB, and each one shows once it has been looked at.
• The server list has kinds and an order. A server is put on the list as survival, skyblock, minigames, creative, pvp, factions, prison, roleplay, anarchy, modded or other; the list can be narrowed to one kind and put in order of players online, newest or name.
• A Minecraft face on profiles. An account can say which Minecraft player it is, on the Account page; its profile then shows that player's head. The picture comes from mc-heads.net, which is asked for it by whoever opens the profile. Nothing is shown for an account that gave no name.
• Achievements on profiles, for what an account has done here: a first script, five of them, ten, a hundred or a thousand downloads, a well-liked script, a third version, a resource pack, a server on the list, helping in threads that were solved, a year on the site.
• Reporting on the forum. A thread or a single reply can be reported, with a few words on what is wrong, the way a script can.

More on the website: profiles, favourites, following, live numbers on the server list, badges, and a few things for finding your way around the docs and the changelog. The plugin itself is unchanged.

Added

• Profile pages. A name on a script, a resource pack, a server or a forum thread now leads to a page with everything that account has shared, and the month it joined.
• Favourites. A *Favourite* button on every ready-made and user-made script keeps it in a list on your Account page.
• Following. *Follow* on a user-made script tells you when it gets a new version, and *Follow this thread* on the forum tells you of replies, without having written there yourself. Both arrive with your other notifications and can be switched off there.
• Most downloaded this week, and top authors, above the list of user-made scripts.
• What is different in a new version. A user-made script that has been updated can be compared with its earlier versions, line by line. The text of earlier versions is kept from now on; for updates made before this there is nothing to compare with.
• The server list shows who is online. The website asks each listed server what the game's own server list asks, every few minutes, and shows "online, 12 of 100 players" when it got an answer. A server that does not answer is shown as before, without a number, and is never called offline. Whoever put a server on the list can switch the asking off for it, under *A badge for your website or your Discord* on the Servers page.
• Badges. A small picture that says a server runs HyperScript, and one for each listed server with its name and how many players are on, to put on a website or in a Discord. The Servers page has them ready to copy as HTML or Markdown.
• How often a jar was downloaded from the website is shown beside its download button.
• "Was this page helpful?" under every topic of the docs, with room for a few words. No account is needed and nothing about who answered is kept.
• The whole reference as one file, from the top of the Docs page, for reading without the internet.
• "What changed since your version?" on the Changelog page: pick the version you have and everything after it is listed on one page, oldest first. changelog.html#since=1.7.60 opens with the answer already there.

What the plugin tells the HyperScript website about a server, for those who have that switched on. Nothing changes for scripts.

Changed

• The usage numbers are sent more often and there are a few more of them. With send-analytics: true in config.yml (the default) they now go out every half minute and a moment after players join or leave, instead of every minute. Besides what was sent before (a random id, versions, players, scripts, the names of HyperScript addons) they now say:
• how many commands, events and timers the scripts make, and how many scripts did not load;
• how long the server has been up and its ticks a second;
• how much memory Java may use and how many processor cores there are;
• the kind of operating system: Windows, Linux or Mac, and no more than that;
• how many worlds and plugins are loaded, as numbers;
• whether the server is in online mode, and the language scripts are read in.

Still never sent: player names, addresses, script contents, world names, and the names of other plugins. send-analytics: false sends nothing at all, as before. The comment in config.yml and the documentation list all of it.

Clicks on one kind of block, places behind and beside a player, and two shorter words.

Added

• on right click on <block>: runs only for a click on that kind of block, and on left click on <block>: likewise. with <item> may follow.

  on right click on gold block:
      send "&6That is solid gold."

  on right click on gold block with stick:
      send "&7Tap."

A block's name with a slip in it is said when the script loads.

• Places behind and beside somebody. location 2 blocks behind player, location 3 blocks left of player and location 3 blocks right of player, to go with in front of. Without a number it is one block: location behind player. They are on the level, from where the player stands.
• announce <text> is another word for broadcast, and tp is short for teleport: tp player to {spawn}.

More for blocks, more ways to push, and a few other ways to say things.

Added

• A block with its details in a variable. block data at <position> is the block that is there together with which way it faces, whether it is open, which half it is, and so on. set block at {_loc} to {_data} puts the same block back the same way round. What is inside a chest and what a sign says are not part of it.

  set {_data} to block data at {_loc}
  set block at {_loc} to air
  wait 3 seconds
  set block at {_loc} to {_data}

• fill ... replacing <block> changes only the blocks of that kind: fill from {_a} to {_b} with air replacing stone.
• fill ... hollow sets only the outside of the box: walls, floor and roof.
• break blocks from <location> to <location> breaks every block of a box, 4,096 at most. over <duration>, without particles and without drops work as they do for one block; with more than 256 blocks the cracks and the crumbs are left out.
• Cracks without breaking. show cracks 7 on block at {_loc} makes a block look that broken, from 1 to 10, and clear cracks on block at {_loc} takes them away. The game lets cracks fade after about twenty seconds. Needs a Paper server, or Spigot 1.19.4 or newer.
• Falling blocks. drop block sand at {_loc} lets a block fall from there the way sand does; drop falling sand at {_loc} says the same.
• is liquid, is passable and is air for a block, beside is solid: if block at {_loc} is liquid:.
• More ways to push. push player away from {_place}, the opposite of towards, and push player left / right.
• launch <who> is a push that goes upward unless it says otherwise, and without fall damage makes the landing after it harmless: launch player upward at speed 2 without fall damage. push takes those words too.
• tell <who> <text> and message <who> <text>, other ways to say send <text> to <who>.
• place <block> at <position>, another way to say set block at <position> to <block>.

Changed

• A block's name with a slip in it, as in set {_block} to Gold blok, is now said to be no block or item, with the name that was probably meant, instead of "Expected a value".

A block that breaks over a time, cracking as it goes, and a block that breaks without leaving anything.

Added

• break block at <location> over <duration>. The block cracks the way one being mined does, a little more all the time, and breaks when the time is up, dropping what it would.

  break block at {_loc} over 5 seconds
  break block at {_loc} over 5 seconds without particles

The lines after it run at once; they do not wait for the block. A block that somebody mines or changes in the meantime is left alone. Everybody within 64 blocks sees the cracks. They need a Paper server, or Spigot 1.19.4 or newer; elsewhere the block simply breaks when the time is up.

• break block at <location> without drops. The block breaks and nothing is left lying there. It goes together with the others, in any order:

  break block at {_loc} without drops
  break block at {_loc} without particles and drops
  break block at {_loc} over 3 seconds without drops

A block's name as the value of a variable, more in the ready-made scripts, and the Scripts page says who made each of them.

Added

• A block in a variable, by its name in plain words. set {_block} to Red concrete keeps that kind of block, and set block at {_spot} to {_block} places it. Capitals do not matter, and a name that is no block is said when the script loads. set {_block} to block at {_spot} for the block that is somewhere, and "red concrete" in quotes, work as before.

  set {_block1} to Red concrete
  set {_block2} to Orange concrete
  set block at player's location to {_block1}

• More ways to say a push. forwards, backwards, upwards and downwards are read like forward, backward, upward and downward, and at speed <n> says what with force <n> does: push player forwards at speed 2.
• send actionbar in one word, beside send action bar, and with description beside with subtitle for the small line under a title: send title "&6Welcome" with description "&7Have fun" to player.
• break block at <location> without particles breaks a block silently and without the crumbs. Plain break block at {_loc} now shows the crumbs and plays the sound of a block breaking, as mining it does; before, it showed neither.
• Items taken from a player who is in a variable. remove 5 diamond from {_target} takes the diamonds out of that player's inventory when {_target} holds a player. A variable that holds a list is treated as before.
• firework as an item. give 3 firework to player gives firework rockets; the game's own name, firework rocket, still works.
• Quests.hs has eleven quests instead of five. New are Farmer, Builder, Fisher, Saver (have 1000 coins), Speed run (300 blocks within two minutes, once an hour) and Weekly slayer. The menu got a book with how many quests you have done, a top 10, and a button to give up the quests you are on; /questtop and /queststop do the same from chat. Finishing a quest plays a sound and shows a title, a player can be on three quests at once (max_active), and everybody is told when somebody has done 5, 10, 25, 50 or 100 of them.
• /setupserver asks about extras. Before it installs anything it asks whether you want Quests as well, and installs it only when you answer y. /updateserver keeps it up to date like the others. With AskQuests: false the question is not asked.
• DeathMessages.hs: lines for five more kinds of death (lightning, being squashed or stuck in a block, cactus and thorns, potions and the wither, freezing) and more lines for the kinds there were. Deaths are counted: whoever died is told which death that was, /deaths says how many there have been, and everybody hears about every 50th (count_deaths, milestone).
• JoinMessages.hs: twice as many lines for joining and leaving. Somebody who comes back is told how long they were away, a new player is announced with which player of the server they are and gets a tip of their own, and whoever joins can get a title on their screen and everybody a sound (show_title, play_sound).
• Who made a script. A # Author: line in a script's notes is shown as a badge on the Scripts page and on the script's own page. The nine ready-made scripts say HyperScript Team.

To get the new texts of scripts you have: /updateserver for the ones the setup installed, or /hyperscript install <name> again. What you set in their options: stays.

Changed

• on right click: no longer runs for a click on a creature or another player. It runs for a right-click on a block or in the air, with anything in the hand, and not when the player is looking at a creature or a player that is near enough to click. That click is on entity click:, as it always was. A script that used on right click: for clicks on creatures needs on entity click: for them now.

Names in quotes inside a text's values, more for menus, events, scoreboards and quests, and two fixes.

Added

• A name in quotes inside the percent signs of a text. "Mined: %quest progress "miner"%" and "You have %plural({_n}, "home")%." now work as written. A line that could be read before is still read the way it was.
• Several menu slots in one line. slots 1 to 9 are "black_stained_glass_pane" and slots 11, 13, 15 are "barrier" named "&cLocked"; with a block under it, clicking any of them runs it.
• worlds: and permission: on events, at the top of the block: it runs only in those worlds, or only for players who have the permission. Commands get worlds: too, with worlds message: for what is said elsewhere.

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

• A scoreboard that keeps itself up to date. The lines under update scoreboard of player every 2 seconds: run now and again that often while the player is on the server; stop updating scoreboard of player ends it.
• Slips in the names of local variables are pointed out. {_coinz} that is read where only {_coins} is set gets a remark when the scripts load and in /hyperscript check.
• More for quests.
• Goals: craft 8 bread, fish 5, walk 500 blocks, and reach 1000 {coins} for a variable of the player's.
• repeat: daily (or weekly, or a length of time) lets a quest be done again, and time limit: 30 minutes gives it an end.
• active quests, and on quest progress: with {_quest}, {_progress} and {_goal}.
• A ready-made script, Quests.hs, with five quests and a /quests menu that shows how far the player is: /hyperscript install Quests.
• Heads with a skin of their own. 1 player head textured "<value>", for heads that are decoration and nobody's face. Needs Minecraft 1.18.1 or newer.
• /hyperscript check without a file checks every script.

Fixed

• An if ...: block directly followed by a one-line if <condition>: <statement> did not load ("Unexpected character ':'"). The same went for a loop or a try: followed by one.
• quest progress "<name>" of player, quest state "<name>" of player and cooldown of command "<name>" for player gave nothing when the player was named as player.

Quests, menus that take items, and events for redstone and machines.

Added

• Quests. A quest "<name>": block is something to do a number of times, counted for each player and kept across restarts. The server counts blocks broken and placed and creatures killed; goal: do 3 is one a script counts itself with advance quest.

  quest "miner":
      goal: break 50 stone
      reward:
          give 5 diamond to player

  command /quest:
      trigger:
          start quest "miner"
          send "&eNew quest: mine 50 stone."

  on quest complete "miner":
      broadcast "&6%player.name% finished the Miner quest!"

With it come start quest, stop quest, advance quest, quest progress, quest goal, quest state, all quests and on quest complete.

• Menu slots that take items. slot 14 takes items: is a slot a player can put an item into, from the cursor or by shift-clicking. The block under it runs with the item as {_item}: for selling, trading in and upgrading.

  slot 14 takes items shown as "hopper" named "&ePut diamonds here":
      if type of {_item} is "diamond":
          add amount of {_item} * 10 to {%player%.coins}
      else:
          give {_item} to player

• Events for redstone and machines. on redstone: (with event.power), on piston extend:, on piston retract:, on dispense: and on hopper move:.
• cooldown of command "/kit": how long until a player may use a command again, for a menu or a scoreboard that shows it.
• yaml value "<key>" of file at "<path>" reads one value out of a YAML file, such as another plugin's config.yml.

A fix found by trying the last releases on a running server.

Fixed

• The remark about a variable's name that looks like a slip no longer comes for a variable each player has when it is named without its player, as in showing top 3 by {coins} or delete {coins} for all players, while a script sets it as {%player%.coins}.

Menus that fill, close and refresh themselves, items changed where they are, and variables for everybody at once.

Added

• Menus. In an open gui block:
• fill empty slots with "gray_stained_glass_pane" and border with "<item>".
• on close: runs when the window closes.
• refresh every 1 second keeps what the menu shows current while it is open.

  open gui with title "&6Bank" for player:
      border with "black_stained_glass_pane"
      refresh every 1 second
      slot 14 is "gold_ingot" named "&eCoins: %{%player%.coins}%"
      on close:
          send "&7Come again."

• An item changed where it is. set name of tool of player to "&6Excalibur", set lore of tool of player to "&7Line one", "&7Line two", add "&cSoulbound" to lore of tool of player, remove line 2 of lore of ... and delete lore of .... It works for every place an item can be in: a hand, an armour slot, an inventory slot.
• Variables for everybody. delete {coins} for all players and set {coins} to 100 for all players reach players who are offline too, and delete all variables of arg.1 clears one player.
• Lists in pages. send {_warps} to player in pages of 8 titled "&6Warps" shows a page at a time, with arrows under it to click.
• Chat slow mode. set chat slow mode to 5 seconds and set chat slow mode off. Players with the permission hyperscript.chat.bypass are not slowed.
• fail "<text>" stops a trigger like a mistake does, so that try: and on error: can catch what your own code decides is wrong.
• /hyperscript backup makes a backup of the saved variables now.
• /hyperscript check <file> also names variables whose names look like a slip, as the console does when the scripts load.
• More words in French, Spanish, Portuguese and German: fail, border, slow mode, as sentence, when they join and others.

Changed

• A command with both cost: and cooldown:: somebody who cannot pay no longer has to wait out the cooldown as well.

Commands that wait and cost, permissions and messages that take care of themselves, and a remark when a variable's name looks misspelt.

Added

• warmup: on a command. warmup: 3 seconds has the player stand still that long before the trigger runs, with the time counting down above the hotbar. Moving or being hurt calls it off.
• cost: on a command. cost: 100 takes the server's money (Vault with an economy plugin), cost: 5 gems a currency of the script's own. Somebody who has not got it is told so, with cost message: if you want to say it your way.

  command /heal:
      cost: 50
      warmup: 3 seconds
      trigger:
          heal player

• Permissions for a time. permission player add "server.fly" for 1 hour is taken back by itself afterwards, also if the player was away or the server off meanwhile.
• Messages for players who are not online. send "&aYou were paid." to arg.1 when they join is said now if they are online and otherwise the next time they join.
• A slip in a variable's name is pointed out. When the scripts load, a saved variable that is read but never set by any script, and is a letter away from one that is, gets a remark in the console: {%player%.coinz} is read, but no script ever sets it. Did you mean {%player%.coins}? The script loads all the same.
• on unload: runs when a script is read again or switched off, and when the server stops.
• closest match of <text> in <list>, for commands of your own that say "did you mean".
• <list> as sentence gives Steve, Alex and Bob.
• Amounts written short. parse "1.5k" as number is 1500, and <amount:number> arguments take 1.5k, 2m and 1b.
• ask <who> <text> as number into <variable> asks again until the answer is a number.
• with click copy <text> puts text on the clipboard of whoever clicks the message.
• nearest block of <type> within <n> blocks of <location>.
• at most once every 5 seconds for player: as another way of writing once every 5 seconds for player:, which was there already and is now in the documentation: a cooldown around any lines, with else: for "wait a moment".

Commands that check more for you, events for one kind of thing, and two commands for trying and watching scripts from inside the game.

Added

• More kinds of argument. Next to player, number and integer:
• <time:duration> takes 30s, 10m, 2h; in the trigger it is that many seconds.
• <on:boolean> takes true, yes, on, false, no or off.
• <what:item>, <where:world> and <who:offline player> have to exist.
• <words:text> is everything to the end of the line, as one argument.
• <on|off> now has to be one of its words.

  command /announce <words:text>:
      trigger:
          send "&6[!] &f%arg.1%" to all players

• Events for one kind of thing. on block break of diamond ore:, on entity death of zombie: and on chat containing "help":.
• /hyperscript run <line> reads one line of script and runs it at once, as you: for trying something without writing a file.
• /hyperscript watch {variable} tells you each time that variable is set, what it became and which line of which script ran last. /hyperscript watch off stops.
• randomly: runs one of the blocks under it, by chance:

  randomly:
      70%:
          give 1 bread to player
      25%:
          give 1 diamond to player
      otherwise:
          give 1 gold block to player

• Sorting by anything. {_words} sorted by length of loop-value, lowest first, or with highest first behind it.
• A player's whole state. save state of player as "before-arena" and restore state of player from "before-arena": what they carry, health, food, experience, game mode and where they stand.
• random 3 of {list}: several different elements at once.
• Text that fits. <text> shortened to 16 ends in … when it had to be cut, and <text> wrapped to 30 gives lines of that length, for lore and signs.
• A boss bar that counts down. create bossbar ... for 30 seconds counting down empties as the time runs.
• More words in French, Spanish, Portuguese and German: randomly, any of, all of, sorted by, players only, containing and others.

Changed

• <on|off> in a command's header was only what Tab offered; another word is now answered with the usage line and the trigger does not run.
• Where a variable that was set for a time keeps its end is no longer listed by /hyperscript variables. A time that was running when the server is updated from 1.7.58 no longer ends by itself; set it again.

More things that took several lines and now take one.

Added

• One block for several events. on player join, player respawn: runs the same lines for each of the events it names.
• Arguments with a default. command /coins [amount:number = 1]: makes arg.1 1 for a player who gave no amount. Works without a type too: [note = "a gift"].
• Variables for a time. set {%player%.boost} to 2 for 10 minutes unsets the variable again by itself when the time is up. The time keeps counting while the server is off.
• Leaving an outer loop. break loop 1 and continue loop 1 reach a loop further out, by the same numbers as loop-value-1:

  loop {teams}:
      loop {players}:
          break loop 1 if {%loop-value-2%.team} is loop-value-1

• Conditions about a whole list. if any of {_scores} is above 100: and if all of {team} are online:.
• amount of <item> in inventory of <who>: how many of them a player carries, all stacks together.
• Several variables in one line. set {_a}, {_b} to 0 and delete {_a}, {_b}.
• return if <condition> and return unless <condition>, to leave a function early.
• Percent changes. add 10% to {_price} and subtract 25% from {_price}.
• multiply, divide, where and after can be written in French, Spanish, Portuguese and German.

Changed

• players only: and console only: on a command work without writing true after them.

/hyperscript update asks before it updates addons and shows how far every download is, and loops and everyday lines got shorter to write.

Added

• /hyperscript update asks about addons. It fetches a newer HyperScript as before. If addons that are installed have a newer version too, it lists them and asks whether to update them as well; /hyperscript update addons is the yes, and a player can click the line. /hyperscript update all fetches everything without asking.
• Download progress everywhere. Updating HyperScript, updating addons, /hyperscript addon install and /hyperscript update scripts now show how far each download is, by name: to a player on the action bar as a bar that fills, to the console at every quarter. Installing a script already did.
• Loops over some players only. loop all players with permission "staff":, in world "arena":, within 20 blocks of player:, or where <condition>: with loop-player as each player in turn. The same after all players anywhere:

  send "&d[Staff] %player.name%: &f%arg.1%" to all players with permission "staff.chat"

• loop <list> where <condition>: goes through the elements the condition holds for.
• Loops over the world. blocks within <n> blocks of <location> and blocks from <location> to <location> give the location of every block there, and items in inventory of <who> what a player carries, so:

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

loop entities within 10 blocks of player: works the same way.

• else: under a loop runs when the loop never went round: an empty list, nobody online.

  loop {%player%.homes}:
      send "&7- &f%loop-value%"
  else:
      send "&7You have no homes."

• One-line checks. stop if {_coins} < 100, continue if loop-player is player.name, break unless ..., and stop with "&cNot enough coins." if {_coins} < 100, which tells the player why first.
• case 1 to 5: in a switch: every number from the one to the other, also in a list with other values (case 1 to 5, 10:).
• after 5 seconds: runs the block under it later, while the lines below carry on at once.
• multiply {x} by 2 and divide {x} by 2, next to add and subtract.
• plural(5, "coin") gives 5 coins, and 1 coin for 1; a third value is the word for many where an s is not it: plural(2, "wolf", "wolves").
• wait between 1 and 3 seconds: a pause of another length every time.

Changed

• loop {list}: over a list that was never set goes round no times, as for each does, where 1.7.56 refused it.
• plural, multiply, divide and after are words of the language now, so a function of your own cannot have one of these names.

Loops know what they are on: loop-value, numbered for a loop inside a loop, and a loop that counts from one number to another.

Added

• loop-value is what the loop around a line is on, in every kind of loop: the number of the round in loop <n> times, the element in for each, the player in loop all players, the seconds left in countdown. In text it is %loop-value%.

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

• In a loop inside a loop the values are numbered from the outside in: loop-value-1 is the first loop's, loop-value-2 the one inside it, and so on. The plain loop-value is always the innermost loop's.

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

• loop from <number> to <number>: counts from the one to the other, both included, up or down: loop from 1 to 10:, loop from 10 to 1:. by <number> is how far apart the numbers are: loop from 0 to 100 by 25:, loop from 0 to 1 by 0.25:.
• loop <list>: goes through a list without naming a local for the element: loop {queue}:. The element is loop-value.
• loop-index is which round a loop is on, from 1, whatever it goes through, so "%loop-index%. %loop-value%" numbers a list. loop-index-1, loop-index-2 for loops inside loops.

Changed

• loop-number works in every loop and is the same as loop-index. Before, it was only set in loop all players.
• loop-value outside a loop, and a number no loop has (loop-value-3 inside two loops), are refused when the script loads, with a message that says how many loops there are.

Everything that worked before still does: loop 5 times with {_i}:, loop-player, for each {_x} in ....

Dialogue, the game's statistics, a selection wand, structures, a word filter, angles and places, random codes, other time zones, and brewing.

Added

• Dialogue. A dialogue "<name>": block holds a conversation, with choice "<answer>": blocks the player answers by, clicked or typed. start dialogue "<name>" begins it.

  dialogue "blacksmith":
      send "&6Blacksmith: &fWhat do you need?"
      choice "A sword":
          give 1 iron sword to player
      choice "Nothing":
          send "&6Blacksmith: &7Come back any time."

choice works anywhere a script runs for a player, not only in a dialogue.

• The game's statistics. statistic "deaths" of player, and for the ones kept for each block, item or creature, statistic "mine_block" of player for "stone". For players who are offline too.
• A selection wand. give selection wand to player: left-click and right-click mark two corners. selection start of player, selection end of player and selection size of player give them to a script, for making regions and arenas by pointing.
• Structures. save structure "house" from <a> to <b>, place structure "house" at <place> (with rotated 90), structure "house" exists, delete structure "house". They are the game's own structure files. Needs Minecraft 1.17.1 or newer.
• A word filter. block word "<word>" and unblock word: chat with a blocked word in it is sent with stars, or not sent, as word-filter in config.yml says. Words are found however they are dressed up (b4dw0rd, b.a.d.w.o.r.d), and only where they stand by themselves, so blocking ass leaves class alone. on blocked word: runs with %event.word%.
• The lists of commands and permissions. all commands, commands of player (the ones they may use) and all permissions of player.
• Angles. sin, cos, tan, asin, acos, atan and atan2, in degrees as the game's own angles are.
• Places. yaw from <a> to <b> and pitch from <a> to <b> say which way to look, and <a> moved 3 blocks towards <b> gives the place that far along the way.
• Random text. random text of 8 characters, random code of 6 digits and new id, for vouchers, codes and keys.
• Other time zones. now formatted as "HH:mm" in time zone "Europe/Berlin".
• Brewing. on brew: runs when a brewing stand finishes. A brewing recipe for <item>: with from: and with: adds a recipe of your own to the stand; that part needs a Paper server, version 1.18 or newer.

Changed

• The home page counts HyperScript itself, kind by kind, so that the numbers add up to the total, and says under them how many addons there are and how much each adds on top.
• A script cannot have a function of its own called sin, cos, tan, asin, acos, atan or atan2 any more, as those come with HyperScript now.

Kits, colours to work with, and limits on what HyperScript keeps going by itself.

Added

• Kits.

  kit "starter":
      cooldown: 1 day
      items:
          1 stone sword
          16 bread

  command /kit:
      trigger:
          claim kit "starter"

• claim kit "starter" hands it over if the player may have it, and tells them why if not: how long is left, that they had it already, or that they lack the permission.
• A kit can also have once: true, permission: "kit.starter", and a trigger: that runs when it is handed over.
• give kit "starter" to player hands the items over without asking.
• player can claim kit "starter", cooldown of kit "starter", reset kit "starter" and kits (the names of all of them).
• When a kit was last claimed is kept through restarts.
• Colours to work with.
• lerp("#ff0000", "#0000ff", 0.5) gives the colour that far between two. lerp also takes two locations and gives the place between them; with numbers it is what it was.
• mix(a, b), lighten(colour, amount), darken(colour, amount).
• rainbow(t) goes round the colours: red at 0, green at a third, blue at two thirds.
• rgb(255, 136, 0) gives #ff8800.

  spawn particle "dust" colored lerp("#ff0000", "#00ff00", player.health / 20) count 10 at player

• Limits, under limits: in config.yml, on what goes on after a line has run: particle shapes that stay, floating texts, blocks waiting to be put back.
• At most 200 shapes stay at once, and at most 3000 particles are asked for in a tick; shapes beyond that wait for their next turn, and the console is told.
• While the server manages fewer than 15 ticks a second, shapes that stay are drawn half as often.
• All of it can be changed.
• /hyperscript timings shows HyperScript's own work under the scripts': particles, text in front of players, action bars, pointers, glows, mutes. Each line says how much of it there is right now and how many milliseconds of a tick it takes, in green, yellow or red.

Changed

• A script cannot have a function of its own called mix, lighten, darken, rainbow or rgb any more, as those come with HyperScript now. One that has is told so when it loads; give it another name.

Particles that stay, move, follow, and are seen by one player; eight more shapes; trails; and a docs search that knows what everything is about.

Added

Particles:

• Shapes that stay. draw particle circle ... at player for 10 seconds, or until <condition> or while <condition>. No timer needed.
• Shapes that stay with somebody. around player (or a creature) in place of at: the shape moves as they do.

  draw particle circle with radius 1 using particle "dust" colored "#ff66cc" around player for 30 seconds

• Particles one player sees. visible to <who> after the place, on spawn particle and on every shape.
• Shapes that move. spinning turns one round its middle, growing to radius 6 over 1 second makes a shockwave, rising 3 blocks over 2 seconds lifts it.
• More shapes: box from <a> to <b>, outline of region "spawn", helix with radius 1 and height 3, spiral, star, heart with size 2, beam from <a> to <b> (which travels from one end to the other), and text "GG" in letters made of particles.
• Colours that run and fade. colored "#ff0000" to "#0000ff" runs from one colour to the other along a shape. fading to "#000000" makes each particle change colour while it lives (Minecraft 1.17 or newer).
• Speed and spread. with speed 0.1 and spread 2, 0.2, 2 after the particle's name.
• Block and item particles. spawn particle "block" of stone and "item" of diamond: the crumbs of breaking a block and of eating.
• Trails. give player a trail of "flame", with for, until or while; remove trail of player.
• Effects with a name.

  particle effect "level up":
      draw particle helix with radius 1 and height 2 using particle "end_rod" at effect location rising 1 blocks over 1 second

  on level up:
      play particle effect "level up" at player

The docs:

• Tags. Everything in the docs now says what it is about: player, block, block display, particle, inventory, combat and some forty more.
• Typing a tag into the search finds everything that carries it, also where the entry itself uses another word, and shows more results than usual. A line at the top leads to all of it on the Docs page.
• Results show their tags.
• On the Docs page, an entry that is opened shows its tags; a click on one shows everything with that tag.

More that used to take a timer and a handful of variables: random teleports, mutes, kill streaks, stopwatches, /back, spawn protection, countdowns and daily rewards.

Added

• A safe random place. random safe location within 2000 blocks of {spawn} gives a place to put a player: ground to stand on, room for the body, nothing that burns or drowns. With teleport ... after 3 seconds unless they move that is a whole /rtp.
• Mutes. mute arg.1 for 10 minutes because "spam", unmute arg.1, player is muted, mute time left of player, mute reason of player. A muted player cannot chat or use the commands for talking, and is told why and for how long. Works for somebody who is offline and lasts through restarts.
• Safe from harm. make player invulnerable for 5 seconds, or until <condition> or while <condition>; make player vulnerable (also unmake player invulnerable) ends it, and player is invulnerable asks. It is HyperScript's own and ends when the server stops, so nobody stays unhurtable by accident.
• Kill streaks. kill streak of player is how many players they have killed in a row since they last died. on kill streak: runs at every kill with %event.streak%.
• Stopwatches. start stopwatch "race", stop stopwatch "race", stopwatch "race" of player (a duration), stopwatch "race" of player is running, reset stopwatch "race". For parkour and races; one that is running goes on through a restart.
• Where they were. last location of player is where they were before they were last taken somewhere, which makes /back two lines. death location of player is where they last died.
• Keeping things on death. keep inventory and keep experience in on player death:.
• Countdowns.

  countdown 5 seconds:
      send title "&e%seconds left%" to player
  send title "&aGo!" to player

The block runs once a second with seconds left counting down; what comes after it runs at the end.

• Things done once.

  once per day for player:
      add 100 to {%player%.coins}
  else:
      send "&7You have had today's reward."

once for player: is the first time only; per day, per hour, per week, per month or per 30 minutes bring it round again. Without for it is once for the whole server.

• Numbers within limits for a command. command /pay <target:player> <amount:number 1 to 10000>: tells a player who gives another number amount must be between 1 and 10000. Also at least 1 and at most 100.
• Money. money(1250.5) gives $1,250.50. How it is written is money-format in config.yml.
• loop player and loop_player are the same as loop-player inside loop all players:. loop-player works as it always did.

The demo is switched off on a new server, /hs install shows how far a download is, text in front of a player can be locked to them, and the ready-made sidebar looks better.

Changed

• demo.hs is switched off by default. On a new server the example script is put into the scripts folder as disabled_demo.hs, so its commands (/coins, /gamble, /shop and the rest) are not there unasked. /hyperscript enable demo switches it on.
• A server that has the demo already is not touched: it stays as it is, on or off.
• /hyperscript remake demo keeps a demo that is switched off switched off.
• /hyperscript install shows the download. A player sees a bar on the action bar that fills as the script arrives, with the percentage and the size; the console is told at every quarter. Scripts are small, so on a good connection it is over at once.
• The ready-made sidebar (Sidebar.hs) is drawn anew:
• a title that shimmers between two colours with a flash of white, and a sign on either side of it;
• a line above and below, a rule down the side, and an arrow between what a line is called and its value;
• ping and TPS in green, yellow or red by how good they are;
• coins written short: 1.2k, 3.4M.

All of it is in the script's options:, the signs too. It needs HyperScript 1.7.50 or newer. /updateserver, or /hs update scripts, fetches it and keeps the options you set.

Added

• locked for text in front of a player.

  show text "&aSaved." in front of player locked for 3 seconds

Without it the text glides after the player and trails a little when they run. With locked it is put where the player is about to be and gets there within a tick, so it looks fastened to them. It goes anywhere before for, until or while.

clear all fake blocks, also with for <who> or for all players, is in HyperScript since 1.7.14 and takes away every fake block scripts have shown a player.

Ten things that used to take a timer and a handful of variables are one line now, and there is a ready-made script for managing worlds.

Added

• A teleport that waits.

  teleport player to {spawn} after 5 seconds unless they move

It counts down on the player's action bar and takes them there when the time is over. With unless they move, walking away calls it off. What it says is in config.yml under messages:.

• An action bar that stays. send action bar "&cIn combat" to player for 10 seconds, or until <condition> or while <condition>. It is said again every second instead of fading.
• Combat. player is in combat is true for 15 seconds after a player hit another player or was hit by one. on combat start: and on combat end: run when a fight begins and is over, with %event.opponent%. put <who> in combat [for <duration>] and take <who> out of combat say it yourself. The time is combat-time in config.yml.
• Being away. player is afk is true once a player has done nothing for 5 minutes: not moved, looked around, clicked, chatted or run a command. on afk: and on afk return: run when they go and come back. The time is afk-time in config.yml.
• Blocks for a time. set block at {_spot} to glass for 10 seconds puts back what was there afterwards, also when the scripts are reloaded or the server stops.
• Numbers that float up. show floating text "&c-%event.damage%" at victim puts text at a place, a creature or a player; it drifts up a block and is gone. This is how damage numbers are made. for 2 seconds says how long.
• Pointing the way. point player to {quest.chest} draws a trail of sparks from the player towards a place, which only they see. It ends when they get there, with stop pointing <who>, or with for, until or while.
• A glow one player sees. make {_target} glow for player [for 30 seconds] gives a creature or a player the outline that shows through walls, for that one player only; make {_target} stop glowing for player takes it away. Needs a Paper server, version 1.20.5 or newer; elsewhere it does nothing and says so once in the log. The outline is white.
• A bar made of text. bar of {_xp} out of 100 gives &a█████&7█████. Add with 20 characters, using "|" and colored "&a" and "&8" as wanted.
• Short numbers. short(1250) gives 1.3k, short(3400000) gives 3.4M.
• WorldsManager, a ready-made script on the website's Scripts page: /hs install WorldsManager. /world makes worlds (normal, flat, void, amplified, nether, end), lists them, takes you or somebody else to one, loads, unloads and deletes them, sets the spawn, and changes time, weather, difficulty and game rules of the world you are in. Deleting asks twice, and only worlds made by a script can be deleted. The server setup (/setupserver) installs it with the others.

Text in front of a player's face, CSV files, two more kinds of storage, and the addons in four languages.

Added

• Text in front of a player. Text that floats before one player's eyes, follows where they look, and is seen by nobody else. It goes when they leave.

  show text "&6Welcome!%nl%&7Open the chest in front of you" in front of player until player is sneaking
  show text "&aSaved." in front of player for 3 seconds
  show text ["&6Shop", "&7Right-click to buy"] in front of player while player is in region "shop"
  hide text in front of player

• for <duration> gives it a time. until <condition> takes it away once the condition is true, while <condition> once it no longer is; the condition is looked at four times a second. Without any of these it stays until hide text in front of <who>.
• at distance <n> says how many blocks in front of the eyes, from 0.5 to 16 (2.2 if it is not said).
• Several lines: %nl% in the text, or a list with a line for each element.
• On Minecraft 1.19.4 and newer it is a text display; before that, name tags. Showing it to one player only needs 1.18: on 1.16 and 1.17 everybody nearby sees it.
• A new line in any text: %nl%, also written %new line% or %newline%. send "&6Rules%nl%&71. Be kind".
• CSV files.

  set {_rows} to csv of file at "plugins/HyperScript/prices.csv" with headers
  for each {_row} in {_rows}:
      send "&e%{_row.item}% &7costs &f%{_row.price}%"

• csv of file at <path> gives the rows as a list, each row a list of its cells, so a cell is item 2 of item 1 of {_rows}. with headers takes the first row as the names of the columns and gives each later row as a table: {_row.price}.
• column <number or name> of <rows> is one column, top to bottom.
• csv of <rows> writes rows out as CSV text, for set file at ... to.
• parse <text> as csv reads text that is not in a file.
• Numbers are numbers, an empty cell is not set, quotes are handled the way spreadsheets write them, and files with semicolons or tabs between the cells are read too.
• Two more kinds of storage, so there are four that need no setting up, and MySQL:
• storage.type: csv keeps the variables in data.csv, a row for each, which a spreadsheet opens. Change it by hand only while the server is stopped.
• storage.type: h2 keeps them in a local H2 database, data-h2.mv.db. The server downloads H2 by itself the first time, on Minecraft 1.17 and newer.
• json and sqlite are as they were; sqlite also sets itself up.

json stays the default. While the server runs every variable is in memory, so no kind of storage makes a script faster or slower, and data.json is written in every mode as the copy HyperScript falls back on. Choose by what you want to open the data with.

• Addons in other languages. Every addon now brings the words for its own syntax in French, Spanish, Portuguese and German, and takes the language from language: in this plugin's config.yml. It needs the addon releases of today; each addon's page lists its words.
• 33 more words in each language for HyperScript itself: create, make, say, show, hide, exists, replace, fill, copy, move, save, line, page, group, region, server, owner and others.

Changed

• Backups are kept in plugins/HyperScript/Backups. A folder written backups by an older version is renamed, with the backups in it.
• MySQL:
• A value can be up to 16 MB; it was 64 KB, which a long list could exceed. A table made by an older version is widened by itself.
• Text is kept as utf8mb4, so every character fits.
• MySQL 8 servers that refused the login with "Public Key Retrieval is not allowed" are logged into.
• The rows of a save are sent together, which is quicker on a database far away.
• With French, Spanish, Portuguese and German, existe / existiert now mean exists (si file at "x" existe:); they used to be another way of saying is set. German Server and Tag are the English words they are.
• With another language set, what follows permission: is left exactly as written. A permission such as serveur.admin used to have its words put into English.

The docs can show their examples in French, Spanish, Portuguese or German, and scripts in those languages are read more carefully.

Added

• A language menu on the website. At the top right of every page, next to the switch for light and dark, a menu picks the language the docs show their examples in. With *Français*, every script example and every line of syntax in the reference is shown with French words, the way a server with language: french takes it:

  quand joueur rejoint:
      envoyer "&aWelcome, %joueur%!" au joueur

• A note at the top of the page says which language is shown, that not everything is translated and not every translation is correct, and has a button back to English.
• *Copy* copies what is shown. *Try it* opens the English, which is what the Playground reads.
• The choice is remembered for the next page and the next visit.
• The text of the docs itself stays English; only the code is shown differently.

Fixed

Scripts written in another language (language: in config.yml):

• English scripts are read as they are in every language. Before, a few English words were taken for words of the chosen language: with French, send action bar did not load, and is not a player was misread.
• en:, de: and the other language codes under messages: are left alone.
• A name with hyphens such as no-money in options: is left alone. boucle-joueur is still loop-player, because every part of it is a word.
• Spanish: sino is *else*. si no is now *if not*, as it reads; it used to be *else*, which made si no {x}: impossible to write.
• German: Fall is no longer *case*, since fall distance is English; write case.
• French: action is no longer *trigger*; write déclencheur.

Scripts can be written with the words of French, Spanish, Portuguese or German, and text can be read as a time.

Added

• Scripts in another language. language: in config.yml chooses the language scripts are written in: english (the default), french, spanish, portuguese or german. With french, a script can say:

  quand un joueur rejoint:
      envoyer "&aBienvenue, %joueur%!" au joueur
      si le joueur a la permission "vip.join":
          donner 1 diamond au joueur

Not everything is translated, and not every translation is correct. It is a list of about 165 words and phrases for each language, not a grammar, so the words of a line stay in the order English has them. What has no translation is written in English: the names of items, blocks, creatures and sounds, and the syntax the list does not name.

• English keeps working in every script whatever language is chosen, also mixed into a line. With english nothing else is looked for.
• Text in quotes, comments and the names of variables, commands, options and functions are never changed.
• A word is also known without its accents.
• /hyperscript reload reads the setting again, so no restart is needed. The log says which language is in use, with the warning above.
• A file such as plugins/HyperScript/languages/french.txt adds words of your own, or says one differently: send = envoyer | balancer.
• Errors, commands and the docs stay in English.

The docs list every word, under *Writing scripts → Scripts in another language*.

• parse <text> as time reads text such as "1h 30m", "90 seconds" or "2 days and 4 hours" as a duration, and is unset if the text is not one. Also written as duration, <text> parsed as time and try parse <text> as time.

  set {_long} to parse arg.2 as time
  if {_long} is not set:
      send "&cSay how long, such as 1h 30m."

A list of servers on the website. Uploading a server's variables to the website is gone.

Removed

• Uploading variables to the website. /hyperscript variables upload is gone, and so are the website-key and website-server-name settings in config.yml; a line for either that is still in your file is ignored and can be deleted. The website no longer takes uploads, and the page where they could be looked through and changed is gone with them.
• Server keys. An account on the website no longer has a key. Keys that were made no longer open anything.

/hyperscript variables, with everything else it does, is as it was. Variables stay on your server, in the file or database they were always saved in.

Added

• Servers. People who run a Minecraft server with HyperScript can put it on a list on the website. *Submit a server* in the Community menu asks for the server's name, its address (IP) and a sentence or two about it. Once it has been looked at and accepted it is listed under *Servers* with your name, and you are told by the bell when it is accepted or turned down. You can take your server off the list again.
• Copy IP on each server copies its address. Before it does, a warning says that the server may have inappropriate things on it, and that HyperScript does not run it and cannot moderate what happens there.

An address has to be one people elsewhere can join by: a name such as play.example.com, or four numbers, with a port if it needs one. One account can send in two servers a day, and a server can be on the list once.

Resource packs on the website, a Community menu, and more for the forum. The plugin itself is unchanged.

Added

• Resource packs. People can share resource packs they made for servers. *Submit a resource pack* takes a .zip of up to 25 MB; once it has been looked at and accepted it is listed under *Resource packs* with a download and a button that copies the line a script needs to hand the pack to its players:

  send resource pack "<address>" with hash "<hash>" to player

There is a limit to how much room all packs together may take; when it is reached the page says so, and nobody can send another until there is room again.

A zip is checked before it is taken: it has to be a resource pack, with pack.mcmeta at the top, and one with programs in it is refused. You are told by the bell when yours is accepted or turned down, and you can remove a pack of your own.

• A Community menu at the top of every page holds what people made and say: the forum, the user-made scripts, the resource packs, and the two pages to submit from.
• The forum:
• Likes on threads and replies; the list shows how well a thread is liked.
• The order of the list can be chosen: last written in, newest, most replies, most liked, or the ones nobody has answered yet.
• Quote puts what somebody wrote into your reply, set apart as their words.
• Three more things to write about: *Resource packs*, *Servers* and *Off topic*.

A batch of small things: new conditions, the block under somebody's feet, sounds for whoever is near, and a block that runs by chance.

Added

• Conditions
• <who> is riding, and vehicle of <who> for what they sit on or in.
• <who> is looking at <target>, where the target is a location or somebody: true when their crosshair is on it, give or take a few degrees.
• <who> is in biome <name>; a location works in place of a player.
• <number> is even, is odd and is divisible by <n>.
• Each takes not: player is not riding.
• block below <who> and block above <who>: the kind of block under somebody's feet or over their head. block under means the same as block below, and a location works in place of a player.

  on player jump:
      if block below player is "slime_block":
          push player upward with force 2

• play sound <name> for players within <n> blocks of <location> plays a sound to everybody that close, each hearing it beside them.
• chance of <n>%: as a block of its own. Its lines run about that often; it is if chance of <n>%: without the if.

  on block break:
      chance of 10%:
          give player 1 emerald

• give <item> to <who> or drop. Giving has always dropped what does not fit at the player's feet; or drop may now be written to say so.

Changed

• The docs say how syntax is written. <name> stands for a value, something in square brackets such as [or drop] may be left out, and round brackets with a slash such as (below/above) mean one of those words. The new entries are written that way.
• The VS Code extension is 1.0.8 and knows the new syntax.

Containers, the creatures around a place, and a handful of values.

Added

• More to do with a chest. remove 5 diamond from chest at <location> takes items out, number of <item> in chest at <location> counts them, and chest slot <n> at <location> reads one slot, sets it, or empties it with delete.
• Where an opened container stands. on inventory open: and on inventory close: now have event's location, so a chest can be locked in a few lines:

  on inventory open:
      if nbt "owner" of block at event's location is set:
          if nbt "owner" of block at event's location is not player.name:
              cancel event

• The creatures around a place.
• entities within <n> blocks of <location> is a list of them, nearest first, and entities of zombie within ... the same for one kind.
• nearest player to <location>, nearest other player to player, nearest zombie to <location> and nearest entity to <location>.
• entities in region <name>.
• random location in region <name>: a place somewhere inside a region.
• horizontal distance between <a> and <b>: how far apart on the map, whatever the heights.
• time until schedule <name>: how long a named schedule still has; unset when nothing waits under that name, so is set says whether one is pending.
• Text: <text> centered to <n>, words of <text> as a list, and between(text, before, after) for what stands between two pieces of a text.
• lerp(from, to, t): the number that far along from one to the other.

Changed

• The VS Code extension is 1.0.7 and knows the new syntax.
• Two addons have something new of their own: HyperHolograms 1.0.2 (a hologram that follows a player) and HyperPerms 1.1.2 (how long a time-limited group still lasts).

Notifications and pages of their own for an account on the website; in the plugin, more NBT and one command that brings every installed script up to date.

Added

The plugin

• /hyperscript update scripts brings every script that was installed from the website up to date in one go. Each keeps the options you set, and the file as it was stays beside the new one as <name>.hs.old. Which scripts were installed, by which id, in which version and when, is now kept in plugins/HyperScript/installed-scripts.json; scripts installed before this version are found by the line an install writes at their top.
• Items carry data from the start. give player diamond sword with nbt "owner" player.name makes the item with that data on it, and nbt "owner" of {_item} reads it from an item in a variable. with nbt may be said several times and goes with named, with lore and the rest; {_item} with nbt "kills" 5 makes an item in a variable anew with more on it. The data is kept when the item is saved in a variable.
• The game's own NBT can be written. set nbt of tool of player to "{Unbreakable:1b}", set nbt of {_mob} to "{NoAI:1b,Silent:1b}" and set nbt of block at {_chest} to "{...}" lay tags, written as the game writes them, over what the thing has. Keys of your own, as in nbt "kills" of ..., stay the way for a script's own bookkeeping.

The website

• Notifications. A bell beside the Docs button shows how many things have happened that you have not looked at: somebody replied in a forum thread you started or wrote in, a moderator wrote to you about a script, a script of yours was accepted or turned down, or somebody commented on one. Which of these you are told about is chosen in your account settings.
• An account has pages of its own: *Your scripts*, *Submit a script*, *Notifications* and *Account settings*, where they were one long page before.
• A moderator can ask you about a script you sent in. The question stands under that script on *Your scripts*, and you can answer there.
• A new version of a script can say what changed, and the script's page lists it.
• The forum can be searched, in titles and in everything that was written, and the list can be narrowed to threads that are solved or still open.
• The home page says how many things the language has in all, beside the count of each kind.

Changed

• A script sent in may be up to 512 KB, where it was 20,000 characters.
• The page a script is sent in from says what makes a script likely to be turned down: fetching from a website address that is written into the script.
• The VS Code extension is 1.0.6 and knows the new syntax.

Comparisons in words, data kept on things, and three smaller additions.

Added

• Comparisons can be written in words. Beside ==, >= and the other signs, which work as before:

  if event.message is "Welcome":
  if {_players} bigger than 50:
  if level of player is at least 30:
  if {%player%.coins} is less than 10:
  if y of player's location is between 60 and 80:

• bigger than, greater than, more than, larger than, higher than mean >; smaller than, less than, lower than, fewer than mean <.
• at least and at most mean >= and <=, as do greater than or equal to and less than or equal to. is equal to means ==.
• is above and is below; is between <a> and <b>, where both ends count.
• All of them may follow is or stand without it, and is not turns each around.
• NBT: data kept on things. A script can keep values on the item in somebody's hand, on a player or a creature, and on a block that holds something (a chest, a sign, a furnace). The server saves them in the thing's NBT, so they travel with the item and survive a restart:

  set nbt "owner" of tool of player to player.name
  if nbt "owner" of tool of player is not player.name:
      send "&cThis item is not yours."
  set nbt "locked" of block at {_chest} to true
  delete nbt "tutorial" of player

A key with a colon, such as "otherplugin:level", reads and changes what another plugin keeps under that name. nbt of tool of <who> gives the whole NBT of an item as text.

• hide <who> from tab list of <who> takes a player off the list another player sees when they hold Tab, while they stay visible in the world. show <who> in tab list of <who> puts them back. Needs a Paper server, 1.20 or newer.
• make <who> shoot a <projectile>, with at speed <n> if wanted: make player shoot an arrow at speed 3. It is shoot <projectile> from <who> said the other way round.
• set <who>'s yaw to <number> and set <who>'s pitch to <number>, the same as set yaw of <who> to and set pitch of <who> to.

Changed

• The VS Code extension is 1.0.5 and knows all of the above.

Local variables are written with braces: {_name}.

Changed

• A local variable is now written {_name} everywhere HyperScript shows one: in the documentation, in every example, in the ready-made scripts, in the demo script and the scripts /hyperscript new writes, in the Playground's examples and in the VS Code extension. It looks like every other variable that way: {coins} is saved, {%player%.coins} is a player's own, {_coins} lasts for one run.

  on player join:
      set {_name} to player.name
      send "&aWelcome, %{_name}%!"

• Nothing breaks. _name without braces is the same variable as {_name}, as it has been all along, and a script may use both, even in one line. Scripts you have do not need to be changed.
• The seven ready-made scripts were rewritten this way. If you installed them, /updateserver (or /hyperscript install <name> again) fetches the new text and keeps your options; the old ones keep working if you leave them.
• The documentation of every addon was changed the same way, and the VS Code extension is 1.0.4, with its snippets written the new way.

A small release about the anonymous "this server is running" message.

Changed

• The message that a server is running is sent every minute instead of every ten, so the number of servers and players the website shows is at most a minute old. What is sent is what it was: versions and counts, never names or addresses. send-analytics: false in config.yml still turns all of it off.
• A server that is stopped by closing its window says that it stopped. Before, only a server stopped with /stop did, and one that was closed any other way was still counted as running for up to 25 minutes.

Fixed

• Two servers that were copied from the same folder were counted as one.

A round of work on the website: the docs, the search and the forum. The plugin itself is unchanged.

Added

• How do I...? A new page under Learn with short scripts for things nearly every server wants: a kit once a day, homes, warps, coins for kills, a protected spawn, tips in chat, a welcome for new players, and hills made of noise. Each one works as it stands.
• Common mistakes. A new page under Learn that goes through what HyperScript says when a script does not load, what each message means and how to put it right. The headings are the messages themselves, so the one you got can be typed into the search.
• Try it. Every example in the docs, and every script on the two new pages, has a Try it button next to Copy that opens it in the Playground, ready to be changed and run.
• Since which version. Syntax that came after the first release has a small tag saying since which version it has been there, so that it is clear why an older server does not know it.
• Addon events show what they give. An event that comes from an addon now opens to a table of what it hands a script, like the events of HyperScript itself do.

Changed

• The search finds the thing itself. What you type is matched against the syntax without its brackets, quotes and percent signs: x of location finds x of <location>, kill as finds kill <who> as <who>, and player.name finds %player.name%. An entry that begins with exactly what was typed comes first.
• The forum:
• You can change what you wrote: an Edit button on your own threads and replies. A changed post says that it was changed.
• A script between two lines of ``` ` ``` is shown as code, coloured like the docs.
• Whoever started a thread can mark it as solved, and the list shows which ones are.
• The Copy button of an example also works on the pages of a single subject, where it did nothing.

A kill that counts for somebody, and death messages with some wit.

Added

• kill <who> as <who> kills a player or a creature and has the server take it for a kill by the second one, who may be a player or a creature too: the death message names them, %event.killer% is them, and they get the drops, the experience and whatever other plugins give for a kill. kill <who> without as works as it did.

  command /smite <player>:
      trigger:
          kill arg.1 as player

• DeathMessages.hs, a new ready-made script. Instead of "Steve fell from a high place" everybody sees one of a handful of lines for that kind of death, picked at random: falling, burning, drowning, blowing up, the void, mobs, starving, and being killed by another player. The lines are lists at the top of the file, to add to or take from. It can also tell whoever died where it happened. Changing death messages needs a Paper server.

Changed

• SetupServer.hs installs DeathMessages.hs too, unless InstallDeathMessages is set to false, and /updateserver keeps it up to date with the rest.

Updating the scripts a server was set up with, without losing how they were set.

Added

• /updateserver in SetupServer.hs fetches the newest version of every script the setup installed: the sidebar, the tab list, the ranks, the chat prefixes and the join messages, whichever of them are in its folder. What you set in their options: stays as you set it. It is for server operators, like /setupserver. SetupServer.hs now needs HyperScript 1.7.38.

Changed

• Installing a script again updates it and keeps its options. /hyperscript install <id> on a script that was installed that way now compares it with what the website has. If the website's text is another one by now, the script is replaced, and every option you had changed is given your value again in the new file; an option that is new keeps what it came with. Before, a ready-made script was never updated, and an update of a user-made one put all options back to what the author chose.
• Your file as it was is still kept beside the new one as <name>.hs.old. Anything you changed outside the options: block is in that copy, not in the new file.
• A script that is already what the website has is left alone, and said to be the newest.

Noise generators, and turning somebody to look where you want.

Added

• Noise generators. Noise is a number for every place that changes smoothly from one place to the next: what hills, caves, ore veins and flower patches are made of. A generator is a value you keep in a variable and ask for a number between 0 and 1:

  set {_hills} to noise generator "perlin" with seed 42 and scale 24 and octaves 3
  set {_height} to round(noise of {_hills} at player's location * 12)

• The kinds are "perlin" (soft hills), "simplex" (the same, rounder), "value" (blockier blobs), "cells" (points scattered about, rising between them), "ridged" (sharp ridges and rivers) and "white" (every block on its own).
• with seed says which noise it is: the same seed gives the same numbers every time, on every server. with scale is how many blocks one hill spans, and with octaves how many layers of finer detail are laid over each other.
• noise of <generator> at <location> reads it as on a map, where only x and z count; at <x>, <z> and at <x>, <y>, <z> take numbers; solid noise of <generator> at <location> counts the height too, for caves.
• A generator can be kept in a saved variable. What is kept is its recipe, not a table of numbers.
• make <who> look at <location> turns a player or a creature to face a place, written as a location, as x, y, z, or as somebody: make player look at arg.1. They stay where they are. make <who> look north (or east, south, west, up, down) turns them that way.

Changed

• The VS Code extension is 1.0.3 and knows the new syntax: it completes and explains noise generators, make <who> look at and world <name> exists.

The docs show what every event gives a script. The plugin itself is unchanged.

Changed

• Clicking an event in the docs shows what it gives. Every event in the Events list now opens to its example and, under it, a table of everything the event hands a script: %event.block%, %event.location%, the player and so on, each with its short form, its type and what it means, plus whether the event can be cancelled and who player is.
• The parts of a location are listed with every event that has one. Where an event gives a location, the table also shows x of event's location, y of event's location and z of event's location (or player's location), and the try-it box of the Events reference has a button for each.

Fixed

• The Playground and the script check on the website knew fewer event values than the plugin. A script using %event.gamemode%, %event.effect%, %event.advancement%, %event.weather% or %event.inventory% was reported there as having an unknown value, although it runs on a server. They are known now.

Addons from inside the game, scripts into a folder of their own, and a clearer mistake when a command has no trigger.

Added

• /hyperscript addon install <name> fetches the newest jar of an addon from the HyperScript website into the plugins folder, after checking that the file is the one the website describes. Tab offers the addons the server does not have yet. The addon is loaded when the server is next started. /hyperscript addon list shows every addon with its newest version and whether the server has it.
• /hyperscript install <id> [folder] can put a script into a folder inside the scripts folder: /hyperscript install Ranks ServerSetup. The folder is made if it is not there.
• world <name> exists says whether there is a world of that name, loaded or not:

  if world "arena" exists:
      teleport player to spawn of world "arena"

Changed

• A command whose code is not under trigger: says so. Code written straight under command /x: used to be reported as Expected 'key: value' inside a command, or as an unknown option. Now the mistake reads Command /x has no 'trigger:' section, on the line the code starts, and a line that stands after the trigger instead of inside it is told that. A misspelt option such as triger: is still answered with what was meant.
• SetupServer.hs keeps its scripts in a folder of their own, scripts/ServerSetup, apart from yours, and fetches all of them at once instead of one every three seconds. The folder's name is the option folder. A script from an earlier setup that is still in the scripts folder itself is taken out, so that nothing runs twice. It now needs HyperScript 1.7.36.
• The VS Code extension is 1.0.2: Enter starts a new line. With the list of suggestions open, Enter used to write the highlighted suggestion into the script. Now Tab takes a suggestion and Enter never does, and the list no longer opens after every space.

Fixed

• The status page showed /api/scripts/get as answering 404, because it asked for a script that is no longer among the ready-made ones.

One rank system for the sidebar, the tab list and the chat. The plugin itself is unchanged.

Changed

• Sidebar.hs and TabList.hs show the rank Ranks.hs keeps. Both used to work a rank out for themselves from the permissions rank.vip, rank.mod and so on, each with its own way of writing it. Now they show what /rank set gave, written the way Ranks.hs writes it, which is also what ChatPrefixes.hs puts in front of chat messages. A rank you add to Ranks.hs shows in all three without touching the other scripts.
• A server operator is no longer shown as the owner just for being an operator: what counts is the rank they were given.
• Both scripts have a new option no_rank for a player without a rank, and TabList.hs has name_colour for the names. Without Ranks.hs everybody is shown that way.

A forum on the website, and a tag that shows who speaks for HyperScript. The plugin itself is unchanged.

Added

• The website has a forum. Under More > Forum anybody with an account can start a thread and write replies: to ask for help with a script, show what they made, or say what HyperScript should do next. Threads are sorted into Announcements, Help, Show your script, Ideas and General, and the list can be narrowed to one of them. You can remove what you wrote yourself.
• The HyperScript Team tag. A member of the HyperScript team has the tag next to their name wherever they write: on the forum, in the comments under a script, and on the scripts they made. Announcements can only be started by the team.
• What people write is checked for words that are not welcome. Forum threads, replies and the comments under a script are refused when they have swear words or slurs in them, also when those are written with digits or with the letters spread out. A post with more than four links, one that is shouted in capitals, or one with a letter repeated over and over is refused as well, and its writer is told why.

Changed

• A script made by the HyperScript team is taken without the question the website asks before a user-made script is downloaded or copied. For everybody else's it asks as before.

What Tab offers for a command, argument by argument.

Added

• tab complete: can be a block. Its lines run each time Tab is pressed, and set arg.1 to "set", "remove" in it says what is offered for the first argument, set arg.2 to ... for the second, and so on. They are ordinary lines, so what is offered for one argument can depend on what was typed before it:

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

• An argument the block says nothing about is offered what the command's header says, as before. tab complete: <list> on one line works as it did.

Changed

• Ranks.hs and ChatPrefixes.hs use this: /rank offers its actions, then the players who are online, then the ranks; /prefix offers set and clear, then the players. Both now need HyperScript 1.7.35.
• SetupServer.hs is for server operators only. It no longer goes by the permission hyperscript.admin.

• The website asks before a user-made script is taken. Download, Copy and Copy id on a user-made script first say who made it, that an admin has looked through it and accepted it, and that this check is not a guarantee, and ask whether to go on. Cancel, Escape or a click beside the box leaves everything as it was.

The ready-made scripts are now the set a server is set up with. The plugin itself is unchanged.

Added

• Sidebar.hs and TabList.hs are ready-made scripts: a sidebar with a title that changes colour and a line for everything about the player and the server, and a tab list with a header, a footer and ranks in front of the names. Both are set up in their options:.

Changed

• SetupServer.hs installs the sidebar and the tab list from the ready-made scripts, by their names, like the three it installed that way already.
• The sidebar and the tab list show the ranks Ranks.hs gives, and say so in their notes.

Removed

• The other ready-made scripts were taken off the Scripts page. What is left is the six that belong together: SetupServer, Sidebar, TabList, Ranks, ChatPrefixes and JoinMessages. A script you installed before keeps working on your server; it can no longer be fetched with /hyperscript install. User-made scripts are not affected.

Three ready-made scripts for a new server, and a setup that installs them. The plugin itself is unchanged.

Added

• Ranks.hs: ranks without a permissions plugin. /rank set <player> <rank> gives one, /rank remove <player> takes it back, and /rank list and /rank info <player> show them. A rank comes with a permission of its own (rank.vip), so other scripts and plugins can go by it.
• ChatPrefixes.hs: everybody's rank in front of what they say in chat, or a prefix of their own given with /prefix set <player> <text>.
• JoinMessages.hs: a line picked at random when somebody joins or leaves, a welcome for whoever joined, and an announcement when somebody is new to the server.
• All three have name among their options, and JoinMessages has address too, so SetupServer.hs fills in your server's name and address for them.

Changed

• SetupServer.hs asks before it takes anything out. It always asks whether the other scripts should go first; say n and they stay, and the new ones are installed beside them. The option that switched this on is gone.
• SetupServer.hs installs the three new scripts as well as the sidebar and the tab list. Each can be left out in its options.

"Last updated" on the home page says how long ago. The plugin itself is unchanged.

Changed

• On the home page, when HyperScript was last updated is said as how long ago and not as a date: under a minute ago, 5 minutes ago, 1 hour ago, 1 day ago, and on through weeks, months and years. It moves on while the page is open, and pointing at it shows the date.

When the HyperScript website is offline, the plugin says so.

Changed

• An offline website is called offline. When the HyperScript website cannot be reached, /hyperscript version, search, install, update and variables upload now say The HyperScript website is offline right now. Try again in a while. Before, they showed the number the network answered with, such as the website answered 502.
• At startup the same thing is one quiet line in the console and no longer a warning: nothing is wrong with your server when the website is away.
• This covers the answers that mean the website is down (502, 503, 504 and 520 to 530) and the website not answering at all. A real mistake, such as a script that is not there, is still reported as what it is.

Three commands: help, uninstall, and reloading one script. And no more word of an update that is none.

Added

• /hyperscript help lists every command of /hyperscript with a line about what it is for.
• /hyperscript uninstall <script> takes a script out of the scripts folder and reloads. It is not destroyed: it is moved to plugins/HyperScript/removed-scripts, from where it can be put back.
• /hyperscript reload <script> reads one script again and leaves the others as they are: their on load: does not run again. Without a name it reloads everything, as before. Tab completes the names for both.
• On the website's home page, when HyperScript was last updated stands beside what it runs on.

Fixed

• A version that only changed the website was announced as an update. /hyperscript version and the note at startup said a newer version was out when the only thing newer was the website. They now go by the newest version of the plugin itself. This is put right on the website, so it holds for servers that have not updated too.

Changed

• The line /hyperscript answers with when it does not know a command points to /hyperscript help instead of listing every word.

Scripts that look after scripts, and a ready-made script that sets a new server up.

Added

• A script can see and manage the scripts folder, which the statements for files cannot reach:
• all scripts is the names of the scripts there are, and this script the name of the file a line is in;
• script <name> exists is a condition;
• delete script <name> takes a script out. It is not destroyed: it is moved to plugins/HyperScript/removed-scripts, from where it can be put back.
• A script can read and change another script's options. option <name> of script <name> is what its options: block says, and set option <name> of script <name> to <value> writes another value into it. Nothing else of the file is touched, and a note after the value stays.
• SetupServer.hs, a new ready-made script: /setupserver installs a sidebar and a tab list from the website, asks in chat what your server is called and what its address is, and writes both into what it installed. It can take out every other script first, if you switch that on and say yes.

One ready-made script fewer. The plugin itself is unchanged.

Removed

• A ready-made script that was of no use on an ordinary server was taken off the Scripts page. If you had installed it, your copy keeps working; remove the file if you do not want it.

More to do with files: what is in a folder, a file's lines, size and date, and folders of your own.

Added

• What is in a folder. files in <folder> and folders in <folder> give the names in it as a list, and all files in <folder> gives every file in it and in the folders inside it, each as its path: logs/monday.txt.
• A file line by line. lines of file at <path> is the file as a list of its lines, to loop over or to count.
• About a file. size of file at <path> in bytes, and last modified of file at <path> as a date.
• Copying and moving. copy file at <path> to <path> and move file at <path> to <path>, which is also how a file is renamed. The folders the new place needs are made.
• Folders. create folder <path>, folder at <path> exists, and delete folder at <path>. A folder with something in it is only removed with with its files after it.
• The limits are the ones files always had: only inside plugins/HyperScript/, never HyperScript's own files and folders, and nothing at all with files.enabled: false. Looking into plugins/HyperScript itself is allowed and leaves HyperScript's own out of the answer.

A sidebar without the numbers down its side, and search results you can click.

Added

• The red numbers beside a sidebar are gone. Minecraft puts a number next to every line of a sidebar; it is only how the game sorts the lines. HyperScript now leaves them out. This needs a Paper server for Minecraft 1.20.3 or newer; on older servers and on Spigot they are still shown, and the console says so once.
• sidebar-numbers: true in config.yml shows the numbers again.
• A result of /hyperscript search can be clicked. Clicking one puts /hyperscript install <id> in your chat box; press Enter and the script is installed. Pointing at a result says what a click does.

Sending a script in as a file, and changing one you have sent. The plugin itself is unchanged.

Added

• A script can be sent in as a file. On the Account page, choose a .hs file or drop it on the form. Its text is put in the box, where you can look it over before you send it, and a new script is named after its file.
• A script you sent can be changed, whatever became of it. Beside each of your scripts is Change it:
• one that is on the site: change the script, what it says about itself, or both. The site keeps the version it has until the change is accepted;
• one that is still waiting: what you send takes the place of what you sent before;
• one that was not accepted: change it and send it again.
• Every change is looked at before it shows. Nothing you change reaches the User-made scripts page without being accepted again.

Changed

• Changing only what a script says about itself counts as a change. Before, a new version had to have a different script.
• Changing a script that is still waiting does not use up one of the three a day.

The Docs, organised by subject. The plugin itself is unchanged.

Changed

• The Docs are in groups. The topics used to stand in one long list in the order they were written. They are now grouped by subject, in the order somebody learning HyperScript would want them: the basics, working with values, commands and events, players, what players see, the world, items, and data and the outside. Each addon is a group of its own.
• A contents at the top of the Docs. Every group is a card that lists its topics, with how many entries each has, so a subject can be found without knowing a word to search for. It makes way for the results as soon as you filter.
• Each group has a heading in the list, and the box that picks one topic is grouped the same way.
• A topic's own page leads on. It says which group it is in, links the topic before and after, and lists the other topics of its group.
• Newcomers are pointed to the tutorial and the cheat sheet from the top of the Docs.

Fixed

• On a phone, a topic's own page was wider than the screen when one of its examples had a long line. The example now scrolls inside its box.

Sizes on the website are written the way downloads are counted. The plugin itself is unchanged.

Changed

• The size of the plugin on the home page, and of each addon on the Addons page, is counted in thousands and never rounded up. Once a jar passes a million bytes it is shown in MB: the plugin is now 1 MB.

A Status page that tells a fault from something that is simply not there, with a section for the API. The plugin itself is unchanged.

Added

• An API section on the Status page. Every address the plugin and other programs ask is listed with what it is for. Each is asked once from your browser as the page opens, and shown with whether it answered and how long that took, beside how often the site was asked it over the last seven days, the average time and the errors.

Fixed

• The Status page said the playground checker was not working on a site whose host has no Java. That is not a fault: the playground checks and runs scripts in the browser, and the checker on the site is only what it falls back on. It is now shown as switched off, with the reason.
• Where the site does have Java, the checker is no longer taken to work because Java is there: it is tried with a script, at most every ten minutes, and shown as not working only if that fails.
• The VS Code extension, 1.0.1: it was switched off in a window in Restricted Mode (a folder that has not been trusted), so a .hs file opened there was plain text. It works there now.

Mistakes you can click, an extension for VS Code, a Status page, a page for every script, and the addon HyperEconomy. This version was run on a Paper 26.2 server and what that showed up is fixed.

Added

• Mistakes in chat can be clicked. When a script does not load, whoever has hyperscript.admin is shown the report, the line it is about, and, where HyperScript can tell what was meant, the line as it should be. Click the suggestion or the corrected line to copy it; click the file's name to check the file again. The same after /hyperscript reload and /hyperscript check.
• More mistakes come with a suggestion. A misspelt item, block, entity, effect or enchantment is answered with the one that was meant (Unknown block 'dimond block'. Did you mean 'diamond block'?), and so are the options of a command (cooldwn:), the names in an options: block, and the word a block starts with (comand /shop:).
• A block at the left margin that has no : at its end is told so.
• HyperScript for VS Code. An extension with colours, completion, the documentation on hover, an outline, snippets, and mistakes underlined as you type with a quick fix where HyperScript can tell what was meant. It is on the website's new VS Code extension page.
• A value between percent signs in text is worked out, if it is several words or a call: "You have %size of _list% items", "That is %round(_n)% coins". Anything that does not read as a value stays as it was written, so "50% off" and another plugin's %placeholder% are untouched.
• "gold block" and "gold_block" are the same name when compared, so if block at _spot is "gold block": is true for a gold block.
• A Status page on the website: whether each part of the site is working, how much of each day it was up, and how long it takes to answer, with the numbers as a chart and as a table.
• A page of its own for every user-made script, at an address that can be shared and that says what the script is before anything is clicked. Search engines can read them.
• The pages of the ready-made scripts say what the script does, what it needs and what is in it, and have Download and Copy buttons.
• HyperEconomy, a new addon: a currency of your scripts becomes the server's money, for every plugin that pays through Vault. It is on the Addons page.
• For addons: currencies(), balance(uuid, currency) and setBalance(uuid, currency, amount) in HyperScriptAPI.

Changed

• The website's checker, the playground and the editor know the items, blocks and creatures of Minecraft up to 26.2, not only those of 1.16.5.

Fixed

• After loading, the number of files with errors counted every mistake as a file: three broken files with six mistakes between them were "6 file(s) had errors".
• A script that needs an addon which is not installed is reported with that one message, not with every line in the addon's words as a further mistake.
• /hyperscript test reported every script without tests that it could not read on its pretend server as a failed test. Scripts without a test block are now left out.
• In chat, the corrected line for a misspelt block word (comand /shop:) was not offered.
• Toasts stopped working after a restart. A toast that had been shown before the server was restarted could not be shown again: this server could not make a toast.
• player has 1 paper tagged "key" did not find the item if it also had a name or lore. An item written with a tag and nothing else is now any item of that kind with that tag, and remove ... from goes by the same rule.

Bug fixes on the website. The plugin itself is unchanged.

Fixed

• Bug fixes.

A footer that leads everywhere, and a home page script that talks to the website. The plugin itself is unchanged.

Changed

• The script on the home page is now an on load: that sends a request to the website. Once it is written it is saved, and a server console appears under it: the file is reloaded, and the script runs and logs what the website answered. The answer is real, fetched as you watch; the reload time shown is an example of what a script this size takes.
• A new footer on every page, in columns: getting HyperScript, learning it, scripts, and the project itself, with links to pages the old footer left out.

Added

• Download (Modrinth) in the footer, next to the download page, leading to HyperScript and its addons on Modrinth.

A home page that shows how fast things are, and an Addons page you can take in at a glance. The plugin itself is unchanged.

Added

• How fast it is, on the home page: how many lines of script are read a second, how long a saved script takes to go live, how large the plugin is, and how many calculations a script does a second. The reading speed is measured on the ready-made scripts each time the website is made, and the page says so.
• Two of the numbers are yours: how long the website took to answer your browser, and how long the page took to load. They are measured as you open the page and left out if they cannot be.
• An overview on the Addons page. Every addon has a card with its logo, the plugin it works with, what it does in one sentence, its version, its size and the HyperScript it needs, with a download button on the card.
• A box on the Addons page that finds an addon by its name or by the plugin it is for.

Changed

• An addon's full documentation is folded away under its heading and opens when you ask for it, or by itself when a link leads into it, so the page is no longer one very long scroll.
• The Addons page says in three steps how an addon is installed, and that /hyperscript update keeps addons up to date too.

A plainer From Skript page, and names for accounts that everybody can live with. The plugin itself is unchanged.

Changed

• From Skript says in red what it cannot do. It goes line by line and gets simple scripts right; menus, addon syntax, event values and other complex things come out half converted, and the page now says so before you start and lists what it does not do.
• After converting, the lines you have to look at yourself are listed in red, and the result of the check has its own heading. A result without mistakes is said to load, not to be right.
• The converter knows more: player's health, level, food and balance, kick ... due to, damage player by 2 hearts, and execute command.
• Names for accounts. A name that is rude, hateful, or made to look like it speaks for the site is refused when an account is made.

Housekeeping on the website. The plugin itself is unchanged.

Changed

• The website counts how often its pages are looked at, by day. Nothing about who looked is kept.

Mobs, money and placeholders of a script's own, starter scripts, updates for addons, two new addons, and a website where scripts get new versions, comments and reports.

Added

Mobs of your own

• A mob "Frost Giant": block describes a creature once: its type:, health:, damage:, speed:, what it is holding: and wearing:, its drops: and experience:. The blocks on spawn:, on death:, on hit: and on hurt: inside it say what happens.
• spawn mob "Frost Giant" at <location> makes one, and mob name of <entity> says which mob a creature is. A creature remembers its mob across restarts.

A currency of your own

• currency "gems" of player is money without another plugin: saved with the player, never below nothing, changed with set, add and subtract. A currency "gems": block gives it a start: and a max:.
• pay 50 of currency "gems" from player to arg.1 moves it from one player to another.
• It works for players who are offline and can be ranked: top 10 players by {currency.gems}.

Placeholders of your own

• A placeholder "rank_colour": block returns a value for whoever is looking, and other plugins show it as %hyperscript_rank_colour% through PlaceholderAPI.

Commands

• /hyperscript new <kind> <name> writes a small script to start from: command, shop, kit, join or minigame.
• /hyperscript update also updates the addons that are installed, each under a jar named after its new version.
• auto-update: true in config.yml does that by itself a moment after every start.
• /hyperscript install <id> updates a script it installed before when the website has a newer version of it. Your old copy is kept beside it as <name>.hs.old.

Two new addons

• HyperMobs (MythicMobs): spawn mythic mob, cast mythic skill, levels, and on mythic mob death.
• HyperHolograms (DecentHolograms): holograms with pages, shown to some players only, with on holo click.

The website

• New versions of user-made scripts. "Send a new version" beside a script of yours on the Account page sends a change in. Once it is accepted the script keeps its id, stars, downloads and comments, and shows its version.
• Comments under every user-made script, for anybody who is signed in.
• Report on every user-made script tells whoever runs the site that something is wrong with it.
• Addon logos on the Addons page.
• Share project in the playground copies one link that opens every file of a project in somebody else's playground.
• Paste a Skript script in the playground turns it into a new file there.

Five new addons, and the whole documentation read against the plugin and put right where the two had drifted apart.

Added

• Five new addons, each on the Addons page with its own documentation:
• HyperVotes (NuVotifier or Votifier): on vote:, vote counts and streaks, votes kept for players who are offline, and vote parties.
• HyperBedrock (Geyser and Floodgate): platform of player, the device a Bedrock player is on, and Bedrock's own forms with show form and on form.
• HyperVoice (Simple Voice Chat): voice groups, muting, and on voice connect:.
• HyperModels (ItemsAdder, Oraxen, Nexo): giving, placing and recognising custom items, blocks and furniture.
• HyperEdit (WorldEdit, FastAsyncWorldEdit): saving and pasting schematics, large edits, and undo last edit.
• The documentation now has a table of every addon and what it works with.

Fixed

• A character with a coloured name is known by its plain name, as the documentation says: after create npc "&aGuide" ..., on npc click "guide":, npc "guide" and delete npc "guide" now find it. Before, the colour code was part of the name.
• send "..." to party of player reaches every member of the party. Before, a message sent to a list of names reached nobody.
• on bed leave: and on projectile hit: can be cancelled, and no longer run for an event another plugin has already cancelled.
• The usage line of /hyperscript lists every subcommand.
• The hint for a missing website-key says to restart the server, which is what the setting needs.

Documentation

Every part of the documentation was compared with what the plugin does. Corrected:

• Configuration lists every setting, among them shared variables, the plugin's own web address, options-file and the website key, and explains loop-limit.
• Items carry enchantments, unbreakable, glowing, a hidden tag and a model number: the page said they did not.
• Scripts in subfolders are watched for changes too, up to eight folders deep.
• <list> without <value> takes out the first such value, not every one.
• The health a summoned creature can have is given with with health <n>; max health of is for players.
• bed location of <who> is where a player respawns; set bed spawn of changes it.
• npc <name>: what can and cannot be done with a character.
• The two descriptions of subcommands no longer contradict each other.
• Smaller things: ping of on older servers, worlds that were unloaded, what created worlds lists, the list of /hyperscript subcommands, what a script file may contain, the Discord bot, and the description of the website and of the plugin's own source.

Players who are not online, written the short way.

Added

• "Progamer52" as offlineplayer is that player, online now or not. If they have played on the server, the name comes back written the way the server has it ("progamer52" gives Progamer52); a name that has never joined stays as written, and has not played before tells the two apart. as offline player, parsed as offlineplayer and parse ... as offlineplayer mean the same.
• uuid of <who> is a player's id, for someone offline too.
• name of <who> now also works for someone offline.
• all offline players is a list of everybody who has ever played on the server.
• The documentation has a new part, Offline players, that says what works for someone who is away (their variables, balance, first join, last seen, bans) and what needs them online.

After an update, the jar in the plugins folder is named after the version that is in it.

Changed

• /hyperscript update names the new jar after the new version. Updating HyperScript-1.7.24.jar now leaves HyperScript-1.7.25.jar in the plugins folder instead of the new version under the old name. The old jar is removed when the server stops, or at the next start at the latest.
• A jar you renamed yourself (hs.jar, say) keeps its name, as before.
• If the server ever starts with an older jar although a newer one is there, the console says which file to delete.

Added

• /hyperscript upgrade is the same command as /hyperscript update.

A playground that helps while you type, a page that turns Skript scripts into HyperScript, and scripts on the website that say which version they were written for.

Added

The playground

• Colours while you write. The editor colours a script as the documentation does: keywords, text, variables, numbers and comments.
• Mistakes as you type. A moment after you stop typing, the script is read in your browser and its mistakes are listed, with the lines marked and underlined. Nothing is run. "Check as I type" under the editor switches it off.
• Names from your own script. The suggestions now also offer the variables and functions the script already uses, for the word being typed.
• Enter keeps the indent of the line, and adds a step after a line that opens a block. Shift+Tab takes a step of indent away.

From Skript

• A new page, From Skript (under More), turns a Skript script into HyperScript: events, command options and arguments, variables and lists, messages, comparisons and functions. What it does not know stays as it was, and the result is checked so you can see what is left to do.

Scripts

• Copy id on every script, ready-made and user-made, copies the id for /hyperscript install <id>. A script's own page shows the whole command.
• User-made scripts say which HyperScript they were written for: a # Requires: 1.7.20 note at the top of the script, or else the newest version when it was sent in. /hyperscript install tells you when your server's HyperScript is older than that.

Changed

• The home page says ~50'000'000 calculations a second, and its first two lines now fade in with the rest.
• llms.txt and llms-full.txt are in the sitemap.

Characters and trading without another plugin, the database open to scripts, variables several servers share, and better tools for finding out what a script is doing.

Added

Characters

• create npc "Guide" at <location> makes a character that stands still, cannot be hurt, and runs on npc click "guide": when a player clicks it. as <entity> makes it another creature, delete npc takes it away, and npc "guide" is the creature itself for make ... say and the like. Characters are remembered across restarts. They cannot look like players; that still takes Citizens and HyperCitizens.

Trading

• open trades "Blacksmith": opens the window villagers trade in, with a line for each offer under it: 5 emerald for 1 iron sword, or 8 emerald and 1 stick for 1 diamond sword.

Questions

• ask player "Name your pet" with anvil into _name asks in an anvil's text box instead of chat, which works from inside a menu. Needs a Paper server; elsewhere it asks in chat.

The database

• run sql "..." and sql rows of "..." ask the database the variables are kept in, with with <value>, <value> for the question marks. For servers whose storage is sqlite or mysql.
• Shared variables. With storage.shared-variables: true, a variable whose name starts with shared. is the same on every server that uses the database, a couple of seconds after it changes on one.

Limits

• limit: 5 per second on a command or event lets a burst through and drops the rest, for each player. For chat, clicks and other things a player can set off many times a second.

Finding out what a script does

• /hyperscript debug <player> now also shows what each line did: what a variable became, and which way an if went.
• /hyperscript timings <script> times every line of one script for thirty seconds and lists the slowest.
• /hyperscript docs <word> searches the documentation from inside the game.

/hyperscript update finds a newer version in more cases, and the website is easier to find, to share and to read by machine.

Fixed

• /hyperscript update said "it is not there (404)". It only asked Modrinth, which does not show a project to everybody until it has been listed there. When Modrinth has no answer, the HyperScript website is now asked instead, and the update is downloaded from it. The file is checked against what it should be either way.
• /hyperscript search and /hyperscript install answered with a bare 404 when the website did not know a script, or was older than the plugin. They now say which of the two it is, and where the scripts are.

Added

Website

• Links show as cards. A link to any page of the website, sent in Discord or another chat, now appears with the page's title, a sentence about it and the HyperScript logo.
• Easier to find. Every page has a description of its own and tells search engines its proper address, and the home page says what HyperScript is in the form they read facts in. Account pages are kept out of search results.
• Readable by AI assistants. /llms.txt is a short guide to HyperScript with the rules of the language and a link to every topic, and /llms-full.txt is the complete documentation, addons included, as one Markdown file. Give either address to an assistant and it has what it needs to write a script correctly.

A server's variables in the browser, and a playground that is easier to work in.

Added

Your server's variables on the website

• /hyperscript variables upload sends the server's saved variables to your account on the HyperScript website, where they can be looked through and changed in a browser. It is for operators and the console only, asks whether you are sure, and needs a key from your account page in config.yml as website-key. Up to 10 MB can be sent.
• A new Servers page shows each uploaded server: its own variables, its players by name with theirs, and how many of each there are. Variables can be searched, changed, added and deleted.
• Changing many at once: delete or rename everything whose name starts a certain way, set or delete one variable for every player, and remove players who have nothing left.
• When you are done, Download data.json gives the result back, to put in place of the server's own. Only you can see what you upload, and it can be deleted from the website.

Playground

• The editor is on the left and the mistakes and log on the right, each in a window of its own, so nothing has to be scrolled to before it can be pressed.
• Projects and files. Scripts are kept in files, files in projects, and all of it in your browser on your own computer: it is there again next time and is never sent anywhere.
• Copy script and Download script.
• wait 5 seconds now really waits in the log, and can be skipped.
• The log says what happened in plainer words, and starts with how to use it.

Website

• The home page says how fast HyperScript is.
• Hovering over the stars of a user-made script shows what each rating means, and pressing one without being signed in leads to signing in and back.

Scripts and updates fetched from inside the game, advancements of your own, loot tables, regular expressions and a Discord bot that writes.

Added

Commands

• /hyperscript search <word> looks on the HyperScript website for scripts, the ready-made ones and those people sent in, and /hyperscript install <id> puts one in the scripts folder and loads it. A script that is already there is never overwritten.
• /hyperscript update asks Modrinth for a newer HyperScript and downloads it for the next restart. The file is checked against what Modrinth says it should be.
• /hyperscript version also lists the addons that are installed, each with its version.

Advancements

• advancement "first kill": with title:, description:, icon:, frame:, parent:, announce: and hidden: adds an advancement to the game's own screen. grant advancement "first kill" to player, revoke advancement ... from ... and the condition player has advancement "first kill" go with it.

Loot tables

• drop loot "entities/zombie" at <location> and fill chest at <location> with loot "chests/simple_dungeon" use the game's own loot tables.

Text

• replace regex <pattern> with <text> in <text>, regex matches of <pattern> in <text> and regex groups of <pattern> in <text>.
• try parse <text> as number: the same as parse, said so that it is plain that text which is not a number gives unset and never an error.

Players

• game version of <who>: what their game calls its version, such as 1.21.4, for servers that let several versions in.

Discord

• send discord message <text> to channel <id> lets the bot write in a channel, and on discord message <id>: runs when somebody writes there. Listening is off until discord.bot.read-messages is switched on in config.yml.

A small release for addons, which HyperVelocity 1.2.0 builds on.

Added

• Parties can travel. An addon can now ask who is in a player's party, and tell a server that some players belong together, so that they are one party again as they join. This is what lets HyperVelocity 1.2.0 move a whole party from one server to another with send party of player to server "arena". Both servers need this version for that.

An update to the documentation website. The plugin itself is unchanged from 1.7.17.

Added

Website

• User-made scripts have a page of their own, under Scripts in the menu, beside the ready-made ones.
• A menu for your account. When you are signed in, "Account" at the top shows your name and opens into Account settings, Send in a script, Your scripts and Sign out.
• Changing your password, under Account settings. Other devices are signed out when you do.

Fixed

Website

• The entries of the menu at the top were not on one line: those that open sat lower, and in bolder letters, than the rest.

Upkeep of the documentation website. The plugin itself is unchanged from 1.7.17, and nothing about using the website is different.

Upkeep of the documentation website. The plugin itself is unchanged from 1.7.17, and nothing about using the website is different.

An update to the documentation website. The plugin itself is unchanged from 1.7.17.

Added

Website

• A page for each community script, with its own address to link to. It shows the script, who sent it in, and the author's other scripts, and has a button that opens it in the playground.
• Ratings. With an account you can give a community script one to five stars, change your mind, or take the rating back. Everyone sees the average and how many rated; nobody sees who gave what. You cannot rate your own script.
• Download counts. Each community script shows how often it has been copied or downloaded.
• The community scripts can be shown with the newest, the best liked or the most downloaded first.

Creatures that do as they are told, a camera, parties and queues, enchantments of your own, scripts that can be called from outside, and tests a script carries with it.

Added

Creatures

• make <creature> follow <who>, make <creature> walk to <location> (both need a Paper server), make <creature> stay still / move again, and make <who> ride <creature> / dismount.
• summon takes more details: invisible, and for armor stands small, marker, with arms, without gravity and without base plate, so they can be used as props.

Scenes

• move camera of player from <location> to <location> over 6 seconds, with looking at <location> if wanted, and stop camera of player. The player is put back where they stood afterwards, also if they log out in the middle.
• set border of player to 32 blocks around <location> gives one player a world border of their own (Minecraft 1.18.2 or newer); reset border of player takes it away.

Parties and queues

• invite <who> to party, accept party invite, decline party invite, leave party, remove <who> from party, disband party; the values party of <who>, party leader of <who> and party invites of <who>; and the condition player is in a party.
• on queue "duels" of 2: runs each time two players are waiting, with them in {_players}. add player to queue "duels", remove player from queue "duels", queue "duels" and player is in queue "duels" go with it.

Enchantments of your own

• enchantment lifesteal: with on hit:, on hurt: and on block break: blocks, and max level:. Items get it like any other: enchanted with lifesteal 2. Inside the blocks {_level} is the level on the item.

Web requests from outside

• on web request "/vote": runs when the server's own web address is called, with what was sent in {_body}. Off until web.server is switched on in config.yml, and it needs a token that every request has to carry.

Testing

• test "what it shows": blocks with expect <condition>, run by /hyperscript test. They run on a pretend server, so nothing they do reaches the world or the saved data.

Changed

• The words newer statements begin with (save, start, end, copy, move and the like) can still be used as the names of your own functions.

An update to the documentation website. The plugin itself is unchanged from 1.7.15.

Added

Website

• Scripts from the community. You can send in a script of your own from the new Account page. Every script is looked at before it is shown; once accepted it appears on the Scripts page under your name, ready to copy or download.
• Accounts. Making one takes a name and a password; no e-mail address is asked for. It is only needed for sending in a script. An account can be deleted again from the same page.
• What's new. One page with the latest releases of HyperScript and all of its addons, newest first.

Changed

Website

• The menu at the top is shorter. The written pages (Overview, Installation, Configuration, Tutorial, Guide, Cheat sheet) are under Learn, and What's new, the Changelog and reporting an issue are under More. On a phone they open in place inside the menu.

What minigames and boss fights are made of: inventories that are put away and given back, creatures with health and equipment of their own, areas that are copied and put back, and texts in each player's language.

Added

Inventories

• save inventory of player as "before-arena" puts away everything a player carries, armour and off hand included. restore inventory of player from "before-arena" gives it back, and delete saved inventory "before-arena" throws the copy away.
• The condition player has saved inventory "before-arena".
• Saved inventories are kept with the other data, so they survive a restart.

Creatures of your own

• summon takes details after the position: with health 200, with speed 1.5, with damage 12, holding <item>, wearing <item>, <item>, dropping <item>, <item>, and glowing, silent, baby.
• What a creature holds and wears does not fall when it dies; dropping says what does.

Drops

• In on entity death:: set drops to <item>, <item>, add <item> to drops, clear drops.
• %event.drops% now also works in on entity death:.

Shooting

• shoot arrow from player, with with speed 2 if wanted. Works with arrows, snowballs, eggs, fireballs, ender pearls, tridents and the like.

Copying areas

• copy blocks from <location> to <location> as "name", or copy region "arena" as "name".
• paste "name" puts the blocks back where they came from; paste "name" at <location> puts them somewhere else. delete copy "name" forgets a copy.
• A copy holds up to 250,000 blocks. What is inside chests and written on signs is not kept.

Chance

• random item of <list> weighted by <list> picks unevenly, for crates and loot.

Recipes

• smelting recipe for <item>: adds a furnace recipe, with from:, and time: and experience: if wanted.

Languages

• A messages: block holds a script's texts once for each language, and message "welcome" gives the one in the player's own. A language or text that is missing falls back on the first language in the block.

Items with a name of their own, crafting recipes, cooldowns you start yourself, fake blocks by the box, and a way to watch a script run line by line.

Added

Items you name once

• item magic wand: at the left margin of a file, with one line under it that describes the item as give takes it. After that magic wand works wherever an item is expected, in any script: give player magic wand, player is holding magic wand, slot 5 is magic wand.
• Such an item is recognised by a hidden tag, so it is still the same item after a player renames it on an anvil.
• on right click with <item>: and on left click with <item>: run only for players holding that item. Any item can be written there.

Recipes

• recipe for <item>: adds a crafting recipe. Give it a shape: with a line for each letter, or ingredients: when the arrangement does not matter. What it makes can be an item of your own.

Cooldowns by name

• start cooldown "kit" of 1 hour, end cooldown "kit", the condition player is on cooldown "kit", and cooldown "kit" for the time left. Add for <who> or of <who> for another player. For waits that cooldown: does not cover: one that starts only when the trigger succeeds, one shared by several commands, one on an item or a menu button.

Fake blocks

• set fake blocks from <location> to <location> to <block> shows a whole box of them.
• clear fake blocks from <location> to <location>, and clear all fake blocks for every one a player has been shown.

Regions

• The condition player is in region "spawn".

Finding mistakes

• /hyperscript debug <player> shows every line of every script as it runs for that player, with its file and line number. /hyperscript debug off stops it.

Settings in one file

• With options-file: true in config.yml, the options: of every script are collected in plugins/HyperScript/options.yml, where they can be changed without opening a script. It is off unless you turn it on.

Website

• The playground can copy a link that carries the script, so a script can be sent to someone ready to check and run. The script is kept in the part of the address that is not sent to the website.
• The playground suggests what to write as you type; Ctrl+Space takes the first suggestion.

Changed

• An item with a hidden tag is now matched by that tag alone. Before, is holding and has also compared the display name, so a tagged item that a player had renamed was no longer recognised.

A small update to the documentation website. The plugin itself is unchanged from 1.7.13.

Fixed

Website

• The website now also runs on Python 3.8, which some hosts still provide. It used two things that only exist from Python 3.9 on, and would not start there.

A small update to the documentation website. The plugin itself is unchanged from 1.7.13.

Added

Website

• The website prints Done when it starts, so a hosting panel that waits for that word can tell that it is running.

Blocks that only one player sees, and a fix for the playground on the live website.

Added

Fake blocks

• set fake block at <position> to <block> shows the player a block that is not really there. Only that player's game is told; the world is not changed and nobody else sees it. Add for <who> or for all players to show it to someone else.
• clear fake block at <position> shows what is really there again.
• The position is written as for set block: at player, at event's location, at 10, 64, -5 in "world".
• The server still has the real block. A player cannot stand on a fake block over air, and the real one comes back by itself when they click it, when it changes, or when they go away and return.

Fixed

Website

• The playground said "Scripts cannot be run on this site." on the live site. Running in the browser fetches the plugin jar piece by piece. The site compressed everything it sent, the jar included, and a compressed answer has no size and cannot be sent in pieces; so Cloudflare, in front of the site, kept a copy it could only hand out whole, and the browser's Java gave up. Jars are now never compressed, and the jar has an address that changes with each version so the old cached copy is not used. The message itself came from the fallback, the website running the script, which needs Java on the website's machine.
• When neither the browser nor the website can run a script, the page now says why for both, instead of only the second.

Removed

• Vanish.hs from the ready-made scripts. It hid a player from others with hide ... from, but anyone with the vanish.see permission, which includes every operator, kept seeing them, so to the person testing it nothing seemed to happen. That makes 37 scripts.

A file's mistakes are now all reported at once, there is a built-in speed test, and the playground on the website runs scripts, on the visitor's own computer.

Changed (check your server)

• A file with mistakes now reports one for each part that has any, not only the first: each command, event and function is checked on its own. The console, /hs reload, /hs check and /hs errors all list them. The file is still loaded as a whole or not at all, as before. The first mistake listed is always the real one; a later one can be a knock-on of an earlier.
• The note about {player.something} is gone. 1.7.3 said it had been removed; in fact only the setting and the documentation were, and the note was still printed. It is removed now.
• SpeedTest.hs is no longer among the ready-made scripts. /hs speed replaces it. A copy already on a server keeps working.

Added

/hs speed

• Measures how fast scripts run on the server, in twelve sections: local variable, arithmetic, conditions, function calls, building text, reading a list, colour codes, temporary variable, saved variable, a player's own variable, asking for a block, asking for health.
• For each section it first finds a number of rounds that takes long enough to time, then runs that 25 times and reports the middle result as "this many a second".
• It is spread over ticks, a few thousandths of a second at a time, so the server keeps running. Run from the console, the three sections that need a player are left out.

Website

• The playground runs scripts. Type a command (/hello Alex) or an event (on join) and press Run: the script is run against a pretend server with one pretend player, and a Log tab shows, in order, everything it told the server to do, with how long reading and running took. Nothing really happens, and a wait does not wait.
• It runs on the visitor's own computer. HyperScript itself, the same code as the plugin, runs in the browser page, so scripts are not sent anywhere. The first use fetches a Java runtime for browsers (CheerpJ, from its maker's servers) and the plugin jar, which took about seven seconds when tried; after that a run takes a fraction of a second. If that cannot start, the website's own server does the work instead, as before.
• The playground lists the script's commands and events as buttons to run, and has Mistakes and Log tabs under the box.
• Usage numbers are kept in Servers/Data.json beside app.py, so a restart of the site no longer forgets them. The folder is not served to anybody. SAVE_ANALYTICS=FALSE in .env keeps them in memory only.

Things to know

• The playground loads a script from another company's servers (CheerpJ) when a visitor presses Check or Run. It is free for personal and open-source use; check its licence if the site ever becomes commercial. Without it the playground still works, through the site's own server.
• Times shown in the playground's log are for the browser, where Java is many times slower than on a server. /hs speed gives real numbers.

The limit on how long a loop may run is now a setting, and there is a ready-made speed test.

Added

• loop-limit in config.yml (100000 by default, from 1000 to 50000000). It is the most rounds loop N times accepts, and how often a while loop may go round without a wait before it is stopped. It used to be fixed at 100000. The message when a loop is refused now names the setting. A config.yml from an older version has no such line and keeps 100000.
• SpeedTest.hs, a ready-made script: /speedtest [rounds] times twelve kinds of work, from adding to a local variable up to asking the world for a block, and says for each how long it took and how many it would do in a second. That makes 39 scripts.

First speed numbers from a live server

Measured on Paper 26.2 with a one-line loop: 100,000 rounds of add 1 to _k in 1 to 3 milliseconds once warmed up (10 ms the first time), which is about fifty million simple steps a second. A server tick is 50 ms.

That is the cheapest thing a script can do. Lines that ask the server for something cost more, and the speed test shows how much.

Gradients and a second way to write hex colours, events that scripts fire for each other, delayed calls that survive a restart, tables in lists, and a website with settings, a public server count, an inbox for issues and a better playground.

Changed (check existing scripts)

• fire and schedule now start a statement, so a function of either name must be renamed.
• on event "<name>": is a new kind of event line.
• Text that contains &# followed by six hex digits, or <gradient:...>, is now a colour.

Added

Colours

• Gradients: <gradient:#ff5555:#5555ff>text</gradient>, with as many colours as you like. A format code inside, such as &l, applies along the gradient.
• &#ff5555 as a second way to write a hex colour. <#ff5555> already worked and was never in the documentation; both are documented now.
• They work wherever text is coloured: chat, titles, sidebars, the tab list, item names, holograms. uncolored removes them.

Events between scripts

• fire event "<name>" runs every on event "<name>": block in every loaded script. fire event "boss killed" with {_boss}, {_reward} hands local variables over under the same names. Inside the block, player is the player of the trigger that fired it.
• An event that sets itself off is stopped after sixteen rounds, with an error.

Calls that survive a restart

• schedule <function>(...) in <duration> is run ... in written down: the call still happens after the server restarts, and one that came due while it was off runs soon after it starts. as <name> lets a later schedule under the same name replace it, and cancel schedule <name> call it off.
• The values given to the function are worked out when the line runs and saved with the call. If the player who caused it is online when it is due, the function runs as that player.

Tables in lists

• A local table can be appended to a list and saved: append _home to {%player%.homes}. Looping gives each one back as a table ({_home.name}). The list keeps its own copy.
• Tables are now saved to disk as tables. Before, a table in a saved variable did not survive being written out.

Website

• Settings in .env, beside app.py. The export writes .env.example with every setting explained, and a first .env if there is none; it never overwrites yours. SHOW_PUBLIC_SERVER_AMOUNT, SHOW_PUBLIC_PLAYER_AMOUNT, ANALYTICS_ENABLED, ISSUES_ENABLED, ISSUES_PER_DAY, ISSUES_MAX_FILES, DISCORD_WEBHOOK_URL, PLAYGROUND_ENABLED, COMPRESS_PAGES.
• A public count on the home page: "Live on N servers with M players", from the usage numbers. Each half can be switched off in .env; with no server online nothing is shown. GET /api/stats gives the same two numbers.
• An inbox for issues, at /inbox: the issues people sent, behind the analytics code. Each can be marked done, reopened or deleted. With DISCORD_WEBHOOK_URL set, a line is posted to Discord when one arrives (title, name and id only).
• A page for every ready-made script (scripts/kits.html) with its code on it, listed in the sitemap in place of the old addresses.
• Playground: line numbers beside the box, and more than the first mistake. The plugin stops at the first; the checker looks on and lists one for each command, event or function that has any, each a link to its line.

Faster

• Coloured text. Text without any hex colour takes a shorter path than before, and text with hex colours or gradients is worked out once and remembered.
• Holograms. Changing one line of a hologram used to take it down and put it up again; now the line is renamed where it stands, and writing the text it already has does nothing at all. This is what a hologram updated from a timer does every few seconds.
• Holograms and worlds read their files once instead of every time one is used.
• The website sends pages compressed. The Docs page and the search index are several times smaller on the wire.

These are places where work was plainly being repeated. Nothing was measured on a busy server.

The website has a page for reporting problems. The plugin itself is the same as 1.7.9, which fixed game rules on new Minecraft versions and absorption.

Added

Website

• An Issues page, at /issues (and issues.html), in the tabs and the footer. Anyone can send a title, a description and their name, and optionally how to reach them, their HyperScript version and their server.
• Each issue is saved as one text file, Issues/<random id>.txt, in the folder beside app.py. That folder is not served: the files can only be read on the machine the site runs on.
• Limits: three issues a day from one address; at most 500 files in the folder at once (after that the page says the box is full until some are removed); a title of 100 characters, a name of 40, a description of 4000.
• A hidden box catches programs that fill in every field: such a report is thrown away.

Nothing in the plugin changed. A server on 1.7.9 gains nothing by updating.

Two fixes found by the first run of the self-test on a real server (Paper 26.2).

Fixed

• Game rules on new Minecraft versions. Minecraft renamed its game rules in 1.21.11 (keepInventory became keep_inventory, doDaylightCycle became advance_time, and so on). Reading or setting a rule by its old name failed with Unknown gamerule and stopped the trigger. Now either spelling works on every version, and a rule the server does not have is simply unset (or, when setting it, a warning) instead of an error.
• set absorption of <who> did nothing on Minecraft 1.20.2 and newer. The game no longer lets a player have more absorption than their "max absorption", which starts at zero. The limit is now raised first.

First results from a live server

Run on Paper 26.2 with SelfTest.hs, Worlds.hs and a chat, sidebar and tab list script:

• Worked: every language and variable check; ping, free slots, tab names, item cooldowns, ender chests; world spawn, difficulty, regions and region rules, holograms; toasts, titles, boss bars with notches, fireworks, player heads and potions as items; questions in chat and yes/no prompts; a menu with a player head; creating, visiting and deleting a void world; chat format; the sidebar; /analytics.
• Failed, fixed here: game rules by their old names, and absorption.
• Not reached: the two timer checks at the end of the self-test (run ... in and cancel run), because the game rule error stopped the test before them. They run now.

A fix for the website. The plugin itself is the same as 1.7.8, which added the usage numbers, the /api/test address and the addon logos.

Fixed

Website

• Analytics

Nothing in the plugin changed. A server on 1.7.8 gains nothing by updating.

The plugin now tells the HyperScript website that a server is running it, so the project can count its servers. It is on by default and one line in config.yml turns it off.

Changed (check your server)

• HyperScript now sends anonymous usage numbers to hyperscript.monoforge.net: once when the server starts, every ten minutes while it runs, and once when it stops. To send nothing, set send-analytics: false, the first setting in config.yml. A config.yml from an older version has no such line, which counts as on; add the line to turn it off. The console says at every start that the numbers are being sent and how to stop it.

What is sent

• a random id made for the server, kept in plugins/HyperScript/analytics-id.txt; it is not made from anything about the server;
• the versions of HyperScript, Minecraft, the server software (Paper, Spigot ...) and Java;
• how many players are online and how many fit; how many scripts are loaded;
• the names of installed HyperScript addons.

What is never sent: player names, addresses, script contents, world names, or anything typed by a player. The website does not keep the address a message came from either.

Added

Website

• POST /api/analytics takes those messages. The numbers are held in memory only: they start again when the site restarts and fill up as servers send their next message. A server that has not been heard from for 25 minutes no longer counts as online.
• GET /api/analytics?code=<code> gives the totals: servers and players online, scripts loaded, which versions of the plugin, of Minecraft, of Java and which server software, which addons, the peaks, and since when it has been counting. The code is 25 letters, made new every time the site starts, printed in the site's console and written to analytics-code.txt beside app.py (a file the site does not serve). Without the right code the answer is a refusal.
• GET /api/test answers with the plain text Yup works: somewhere real to try a first web request from a script. The Docs example that fetched https://api.example.com/stats now uses it.

Ready-made script

• Analytics.hs: /analytics <code> shows those totals in game. It is for whoever runs the website; with a wrong code it only says so. That makes 38 scripts.

Logos

• A logo for each addon, in the family of the HyperScript one: HyperVelocity, HyperPerms, HyperGuard and HyperCitizens, plus HyperScript itself for the organization. Each as an SVG and as 512 and 256 pixel PNGs, in the Logos folder beside the site.

Fixes for loops over players and for right-clicks, and new versions of all four addons.

Changed (check existing scripts)

• looped-player is now loop-player. A script that still says looped-player no longer loads; change the word. The ready-made scripts that used it (Chat, Warnings) are updated.
• on right click: now also runs when a player right-clicks a creature or another player, and for a click made with the off hand. A script that only wants clicks on blocks or air should check event.block, or use on entity click: for the others.

Fixed

• loop-player's location works. <anyone>'s location used to be understood only for player and event, so draw particle circle ... at looped-player's location failed. It now works after any value that names a player: loop-player's location, arg.1's location, _name's location, "Alex"'s location.
• Right-clicks with the off hand are no longer lost. When the main hand is empty and the other holds something usable, the game reports the click for the off hand only, and HyperScript threw it away. One click still runs the block once, whichever hand it came from.

Added

• loop-number: which round a loop all players: is on, starting at 1.
• <who>'s location, as above.

One thing no plugin can see: right-clicking the air with a completely empty hand. The game does not tell the server about that click. Holding any item, or clicking a block or a creature, works.

Addons (separate jars, on the Addons page; each has its own changelog)

• HyperVelocity 1.1.0: broadcast ... to network, kick ... from network, server "pvp" is online, and player counts for every server from the start.
• HyperPerms 1.1.0: single permissions with a time limit (grant player permission "fly" for 1 hour), all groups, players in group, group weights, and LuckPerms meta.
• HyperGuard 1.1.0: create guard region and delete guard region, guard allows building at, overlap checks, priority and parent. New script Plots.hs.
• HyperCitizens 1.1.0: equipment, floating text above an NPC, watch players, follow, and patrol.

That makes 37 ready-made scripts.

Scripts can now make their own worlds: create world "arena" flat, then teleport players there, set its rules, and unload or delete it again.

Changed (check existing scripts)

• load and unload now start a statement, so a function of that name must be renamed.
• created worlds is a value (the list of worlds scripts have made).

Added

Worlds

• create world <name> makes a world and loads it. Options, in any order:
• what it is made of: flat, void (nothing but one block to stand on), amplified, large biomes; without one it is an ordinary world;
• which dimension: nether or end; without one it is an overworld;
• with seed <value> (a number or any text) and without structures.

create world "skyblock" void, create world "plots" flat without structures, create world "hell" nether with seed 42.

• Creating a world that already exists does nothing, so an on load: block may do it every time.
• Worlds are remembered. Every world a script makes is listed in plugins/HyperScript/worlds.yml and loaded again when the server starts, before any script runs, so locations saved in it stay good.
• load world <name> and unload world <name> (add without saving to throw away changes). Players inside are sent to the main world's spawn first. A world that is unloaded stays unloaded after a restart until it is loaded again. load world also takes a world folder that is already on the server but was not made by a script.
• delete world <name> unloads a world and deletes its files for good. Only worlds made by a script can be deleted; the server's own worlds, and ones only loaded by a script, are refused.
• created worlds: a list of the worlds scripts have made, loaded or not.
• Everything that already worked on a world works on these: teleport player to spawn of world "arena", set spawn of world, game rules, difficulty, pvp, time, weather, borders, regions and holograms.

Ready-made script

• Worlds.hs: /world list|create|tp|unload|delete, with a permission for managers and a lighter one for players who may only travel. Deleting asks for a yes first. That makes 36.

on join: now works as well as on player join:, a colon may be used in variable names, and the website has a sitemap with a page for every Docs topic and every release.

Changed (check existing scripts)

• A colon in a variable's name now means the same as a dot. {%player%:role} is {%player%.role}. A colon in a variable name used to be an error, so no working script changes its meaning.

Added

Language

• Short event names. The word player may be left out wherever what remains still names an event: on join:, on quit:, on chat:, on death:, on respawn:, on command:, on move:, on kill:, on teleport: and so on. on entity death: and the other events that are not about a player keep their full names.
• Colons in variable names. {%player%:role}, {stats:kills} and {stats::kills} are accepted and are the same variables as with dots. This also works inside text ("%{%player%:role}%"), for local tables ({_data:name}) and in a one-line if.

Website

• /sitemap.xml, listing every page of the site with the day it last changed, and /robots.txt pointing to it.
• So that there is something to list, every Docs topic now has a page of its own (Docs/<topic>.html), with its entries and their examples shown in full, and every release has a page of its own (changelog/v1-7-5.html), for HyperScript and for each addon. Each links back to the full Docs or changelog page.
• Each ready-made script is listed by its own address as well.

A sitemap can only list pages. The single entries inside a Docs topic are parts of a page, not pages, so they are reached through their topic's page rather than listed one by one.

Finding out what went wrong is now one command, /hs errors, and a player whose command failed is told so instead of nothing happening. The website works properly on phones, and there are two new addons: HyperGuard for WorldGuard and HyperCitizens for Citizens NPCs.

Changed (check existing scripts)

• Players now see a message when a script fails on something they did. By default: "Something went wrong with that. The staff have been told." Change it, or set it to "" to tell players nothing, with player-error-message in config.yml. A config.yml from an older version has no such line and gets the default.
• does not contain is now part of the language.

Added

Errors

• /hs errors lists what went wrong lately: the scripts that did not load, and the last failures of running scripts, newest first. Each failure shows the file and line, the line itself as written in the script, how long ago, how many times, and which player caused it. A failure that repeats is listed once with a count. /hs errors clear empties the list.
• player-error-message in config.yml, as described above. Players with hyperscript.admin get the real message (with notify-script-errors) and not this line. A player is told at most once every five seconds.

Language

• <list> does not contain <value> and <text> does not contain <text>.

For addons

• HyperScriptAPI.fire(event, key, locals, player): an addon's event can now be about a player. Inside the block that player is player, so send, {%player%.coins} and cooldown: work as they do in HyperScript's own events. The older three-argument form is unchanged.
• A cooldown: line is now accepted at the top of an addon's event block.

Addons (separate jars, on the Addons page)

• HyperGuard 1.0.0: WorldGuard regions in scripts. guard regions of player, players in guard region "arena", owners and members, reading and setting flags, and on guard region enter "spawn": / leave.
• HyperCitizens 1.0.0: Citizens NPCs in scripts. create npc, make npc "Guide" say ..., walk to, look at, skins, and on npc click "Guide":.
• Both need HyperScript 1.7.4.

Website

• On a phone the tabs are behind a menu button instead of a row that scrolls sideways, and the home page, script cards, playground and footer are laid out for a narrow screen.
• No page scrolls sideways at phone width.

A new look for the website. The plugin itself is the same as 1.7.3, which brought questions in chat, temporary variables, player heads in menus, a self-test script and the playground.

Changed

Website

• The home page opens with a script being typed into an editor window, next to the title.
• A darker night theme with a faint block grid behind the page, a glass header and mint and blue light on whatever is live; the light theme follows the same lines.
• Cards, Docs entries and scripts light up at the edge when the pointer is over them.
• A thin bar at the top of the page fills as the page is read.
• With all its tabs the header is two rows on screens narrower than about 1500 pixels, so no tab is cut off. The Docs filters and jump targets follow the header's real height.

Nothing in the language or the plugin changed. A server on 1.7.3 gains nothing by updating.

Scripts can now ask players questions, keep variables that are never saved, and put player heads in menus. There is a self-test script to run on your own server, eight more ready-made scripts, and a playground on the website that checks a script without a server.

Changed (check existing scripts)

• Variables whose name starts with temp. are no longer saved. {temp.x} lasts until the server stops and {%player%.temp.x} until that player leaves. A script that already used such a name for something it wanted kept must rename it.
• ask, confirm and format(...) are now part of the language: a function called format must be renamed, and ask or confirm at the start of a line is the new statement.
• While a script waits for an answer to ask or confirm, the player's next chat message is taken as the answer and is not shown in chat.
• on step on ...: is a new kind of event line.
• The setting warn-player-variables and the note it printed about {player.something} are gone. {player.coins} is still one variable shared by everyone; nothing points it out any more.
• A new command, /hsanswer, belongs to the plugin. Players never need to type it: clicking an offered answer runs it.

Added

Questions

• ask <who> <text> into <variable> waits for the player to answer in chat. for at most 30 seconds changes the wait (a minute by default); with no answer the variable is unset.
• ask <who> <text> with options "Red", "Blue" into <variable> offers answers to click.
• confirm <text>: runs its block only if the player answers yes. confirm <text> for <who>: asks someone else.

Variables

• Temporary variables, as described above: nothing to tidy up when a player joins.

Items

• player head owned by <name>: a head with that player's skin, as a value. It can be given, saved, and shown in a menu: slot 1 is "player_head" owned by _name.
• potion with potion <kind>, also for splash and lingering potions and tipped arrows: strength, long_swiftness, strong_healing and the game's other kinds.
• An item's name may now come after its other details.

Players and world

• location of <who>: where another player is.
• items in ender chest of <who>, add <item> to ender chest of <who>, clear ender chest of <who>.
• create hologram ... with lines ... showing <item>: an item floating above the text.
• create bossbar ... with segments 10: a bar with 6, 10, 12 or 20 notches.

Events

• on step on <block>: runs for players standing on that kind of block.

Text and data

• format(n, "0.00") writes a number with a pattern.
• json of <value> writes a list, a local table, a number or text as JSON.

Ready-made scripts (each # Requires: 1.7.3)

• SelfTest.hs: /hstest runs about fifty checks on your own server and prints PASS or FAIL for each; /hstest look, ask and menu cover what has to be seen or clicked.
• Auction.hs: /ah and /ah sell <price>, a paged menu of what players are selling.
• Trade.hs: /trade <player> <coins> offers the item in your hand; the other player is asked yes or no.
• Clans.hs: found (the name is asked for in chat), invite, join, leave, clan chat.
• Quests.hs: mining, hunting and fishing jobs with a progress menu and a toast when done.
• Scoreboard.hs: a sidebar that keeps itself up to date, with /sb to hide it.
• Parkour.hs: a timed course built from emerald, iron and gold blocks.
• ServerSelector.hs: a menu to hop between servers; needs the HyperVelocity addon.
• Afk.hs was rewritten: it now notices movement as it happens instead of comparing positions.

That makes 35 scripts.

Website

• Playground: paste a script and have it checked for mistakes, with the line of the first one. It uses the same reading the plugin does. This needs Java on the machine that runs app.py; without it the page says the checker is not available.
• The home page shows what the newest version brought.
• The Scripts page has tag chips, and a "My HyperScript version" choice that hides scripts needing a newer one.

Not included

• Potions with effects of your own making: only the game's kinds.
• Setting one particular slot of an ender chest.
• Holograms that follow a player.

Holograms, toasts, player heads, item cooldowns, eight more events and eight more ready-made scripts. Most of what 1.7.1 listed as left out is in this one.

Changed (check existing scripts)

• stop sound ... and stop all sounds are now statements. stop on a line of its own still ends the trigger.
• holograms is a value (the list of hologram names), and item cooldown of ... is no longer read as "item number cooldown of a list".
• set item <n> of <list> to <value> used to be an error; it now changes the list.

Added

Holograms

• create hologram <name> at <location> with lines <text>, <text> puts floating text in the world. Creating one under a name that exists replaces it, which is also how to move it.
• set line <n> of hologram <name> to <text> rewrites one line; a line past the end is added.
• delete hologram <name>, and holograms for a list of their names.
• Holograms are saved in the world and listed in plugins/HyperScript/holograms.yml, so they are still there, and can still be changed, after a restart.

Toasts

• send toast <text> [with icon <item>] [as task|goal|challenge] [to <who>] shows the pop-up in the top corner that advancements use, with the frame and sound of the kind chosen.

Players

• give head of <name> to <who>: a player head with that player's skin.
• set item cooldown of <item> for <who> to <duration> greys an item out the way ender pearls are; item cooldown of <item> for <who> reads what is left.
• stop sound <name> [for <who>] and stop all sounds [for <who>].
• absorption of <who> (settable), protocol version of <who> (from ViaVersion if installed, otherwise Paper) and client brand of <who> (Paper).
• <who> has not played before, the opposite of has played before.

Lists

• set item <n> of <variable> to <value> replaces one element of a list.

Events

• on player move: (only when the player ends up in another block), on portal use:, on bed leave:, on item damage:, on harvest:, on glide toggle:, on entity mount: and on entity dismount:.

Ready-made scripts (on the website's Scripts page, each # Requires: 1.7.2)

• Bounties.hs: /bounty, /bounties; the killer takes the coins and the victim's head.
• Mail.hs: /mail send|read|clear, with a toast on joining when mail is waiting.
• Nicknames.hs: /nick, /realname; checked for length, letters and names already taken.
• Reports.hs: /report for players, /reports for staff, who are told at once.
• RandomTeleport.hs: /rtp to dry ground somewhere in the wild.
• Coinflip.hs: players bet coins against each other.
• Vanish.hs: /vanish for staff, kept through a relog.
• Holograms.hs: /holo create|add|set|move|delete|list, with a live player count.

That makes 27 scripts.

Documented, not new

• give has always dropped at the player's feet whatever does not fit in the inventory. The Docs now say so; there is no separate "give or drop".
• The fade times of a title are set where it is sent: send title "..." with fadein 10 stay 60 fadeout 10.

Not included

• The name of a player's game version (1.20.4): protocol version of gives its number.
• Player heads as values, for example in a menu slot: only give head of exists.
• Holograms that show an item or follow a player.

A release of many small things: shorter ways to write common lines, subcommands, tab completion, region rules, two admin tools, seven more ready-made scripts, and a light and dark button on the website.

Changed (check existing scripts)

A few more words now mean something.

• increase, decrease, toggle, swap, default, respawn, show and hide start a statement. A function with one of those names can no longer be called on a line of its own.
• Inside a value, if ... else ... now chooses between two values, and without, padded and sorted by continue a value. Text is not affected, only bare words.
• type of <item> and amount of <item> are expressions; clamp(...) and random(a, b) are built-in functions, so a script's own function of that name is no longer the one called.
• A line that ends with a backslash \ is joined to the next line.
• A command with disabled: true is not added to the server.

Added

Shorter ways to write things

• if <condition>: <statement> on one line, e.g. if arg.1 is not set: stop.
• else unless <condition>: alongside else if.
• <a> if <condition> else <b> picks one of two values: "on" if {flag} else "off".
• increase {x} by 1 / decrease {x} by 1, toggle {flag}, swap {a} and {b}, default {motd} to "Welcome" (sets it only if it has no value).
• A long line can be split with a backslash at the end of each part.
• clamp(n, least, most) and random(a, b).

Lists and text

• <list> without <value>, <list> sorted by {<name>} (player names by each one's own variable), map each <list> to <expression>.
• <text> padded to <n> and padded left to <n> for lining up columns.
• type of <item> (its material) and amount of <item>.

Waiting

• run <function>(...) in <duration> as <name> gives a delayed run a name, and cancel run <name> calls it off. Starting another run under the same name replaces the first.

Players

• respawn <who>, clear title of <who>, hide <who> from <who> / show <who> to <who>, show <who> a book titled <text> with pages <text>, <text>.
• tab name of <who> (settable), free slots of <who>, ping of <who>.
• Conditions has space for <item> / does not have space for <item>, is bedrock (through Floodgate) and is dead.

World

• spawn firework at <location> with colored, shaped and with power.
• play effect <name> at <location>.
• Signs: line <n> of sign at <location>, readable and settable.
• Containers: items in chest at <location>, add <item> to chest at <location>, clear chest at <location>.
• gamerule <name> of world <name>, difficulty of world <name>, pvp of world <name>, spawn of world <name>.
• Region rules: set pvp of region "spawn" to false and set build of region "spawn" to false. HyperScript enforces them itself; hyperscript.region.bypass (operators by default) may still build. players in region <name> lists who is inside.

Events

• on shield block:, on anvil use:, on villager trade:.

Commands

• Subcommands: subcommand <name> <arguments>: inside a command, each with its own permission, description, checked arguments and trigger. Tab offers the ones a player may use.
• Tab completion from a script: tab complete: <list> for the first argument, tab complete 2: <list> for the second, worked out when Tab is pressed.
• disabled: true keeps a command in the file without adding it.

Admin tools

• /hs variables <name> shows a saved variable or everything under a name; /hs variables <name> set <value> and /hs variables <name> delete change it.
• /hs timings lists which scripts have taken the most time; /hs timings reset starts again.
• "Did you mean": an unknown event, statement or function name suggests the nearest known one.

Ready-made scripts (on the website's Scripts page, each # Requires: 1.7.1)

• Tpa.hs: /tpa, /tpaccept, /tpdeny with clickable answers and requests that run out.
• DailyRewards.hs: /daily with a streak that pays more.
• Shop.hs: a paged menu shop, /sell and /sellall.
• Crates.hs: a crate block opened with a tagged key, weighted prizes, a spin and a firework.
• CombatLog.hs: fighting players cannot use chosen commands, and logging out kills them.
• Afk.hs: marks players who stand still, in chat and in the tab list; /afk.
• Vote.hs: /vote with links, /votereward for a vote listener to run, /votetop.
• Announcements.hs now makes a message written as text | address a clickable link.

Website

• A light and dark button in the header. Without a choice the site follows the system setting; the choice is remembered in the browser.
• Every Docs entry has a link button that copies the address of that entry.
• Every script has a page of its own, scripts.html?script=<name>, with a Link button to copy its address; the script's name on the Scripts page leads there.

Not included

Asked for or listed, and left out of this release:

• Toasts (the pop-up in the corner of the screen).
• Events for mounting and dismounting an entity (vehicle enter / vehicle exit cover carts and boats).
• client version of <player>.
• A way to change how long a title fades in and out after it is sent; clear title of is the only new title statement.
• give ... or drop: use if player has space for <item>: and drop <item> at.

The biggest release so far: the language roughly doubles in size.

Changed (check existing scripts)

A few words now mean something after is, and one statement was split in two.

• is empty, is text, is day, is night, is raining, is solid, is loaded, is online, is op, is between ..., is in ..., is within ..., is holding ... and is wearing ... are now tests of their own. A script that compared a value with a variable or item of one of those names (if {mode} is day:) must put the word in quotes: if {mode} is "day":.
• break block at <location> breaks a block. break on a line of its own still leaves a loop.
• Directly after send, title case cannot be told from send title. Put it in a variable first, or in brackets: send (title case _item).
• Local variables written with a dot, such as {_data.name}, are now fields of a local table. They used to be saved globals with an odd name; nothing in the documentation used them.

Added

Events: 39 more

• Player actions: left click, player sneak, player sprint, player swim, flight toggle, hand swap, slot change, item break, book edit.
• Player state: gamemode change, hunger change, player heal, experience gain, effect gained, effect ended, player kick, advancement.
• Combat: player kill (one player kills another), projectile shoot, projectile hit, totem use.
• Blocks and world: block burn, explosion, leaves decay, crop grow, bucket fill, bucket empty, weather change.
• Entities: entity tame, entity breed, shear, mob target, vehicle enter, vehicle exit.
• Inventories: inventory open, inventory close, enchant item, furnace smelt.
• Server: console command, and on server start: / on server stop:, which run once when the server comes up and goes down.

Types

• Dates: now, today, tomorrow; now + 1 day; one date minus another is a duration; time since, time until; <date> formatted as "d MMMM yyyy". Dates can be saved and compared.
• Entities: last summoned entity, event entity, victim entity, attacker entity, clicked entity and target entity of player are creatures a script can keep in a local variable and act on.
• Local tables: {_data.name} is a named value inside the local _data.

Conditions

• Players: is sneaking, sprinting, swimming, blocking, sleeping, on ground, in water, is op, is online, has played before, is holding <item>, is wearing <item>, can see <player>.
• World: <world> is raining, is day, is night; <block> is solid; <location> is loaded; <location> is within <n> blocks of <location>.
• Values: is between, is in <list>, is empty, is alphanumeric, is a list, a location, an item, a date, an entity, a table, a player, is text.
• unless <condition>:, the opposite of if.

Effects

• Creatures: kill, damage <who> by <n>, push <who> upward / forward / towards <location>, make <who> say <text>, make <mob> target <who>, remove entity, remove all zombies within 20 blocks of ..., and set name of / set health of for a mob.
• Players: open workbench for, open enderchest for, and settable fly speed, walk speed, saturation, air, held slot, compass target, bed spawn, yaw and pitch.
• Tools: damage tool of player by <n>, repair tool of player, enchant tool of player with <enchantment> <level>.
• World: strike lightning at (and strike fake lightning at), create explosion at ... with power <n> (optionally without breaking blocks, with fire), fill from ... to ... with <block>, break block at, grow tree at, drop <item> at, set spawn of world, and set world border of world ... to <size> over <time>.
• Flow: wait until <condition> for at most <duration>, run <function>(...) in <duration>, and repeat every <duration> for <duration>:.

Expressions

• Players: ip of, locale of, first join date of, last seen of, time played of, bed location of, target block of, direction of, yaw of, pitch of, held slot of, saturation of, air of, fall distance of, fly speed of, walk speed of.
• Places: <location> offset by x, y, z, location above / below, location <n> blocks in front of <who>, midpoint between, highest block at, biome at, light level at. Coordinates can be written out at the end of a set line: set {spawn} to 0, 64, 0 in "world".
• Lists: first <n> of, last <n> of, numbers from <a> to <b>, count of <value> in, min of, max of.
• Text: capitalized, title case, uncoloured, word <n> of, <text> repeated <n> times, and exact colours with <#ff8800>.
• Numbers: pow(a, b), round(n, places), percent(part, whole), commas(n), ordinal(n), roman(n).
• Server: %server.worlds%, %server.operators%, %server.banned%, %server.whitelist%, %server.plugins%, %server.uptime%, %server.memory_used%, %server.memory_max%.

Functions and structures

• Default values for parameters: function reward(_who, _amount = 10):.
• try: / on error: lets a script deal with a line that fails instead of stopping.
• loop 5 times with _i: gives the loop a counter.
• for each _name, _value in {table}: goes through a table's names and values together.
• Commands: players only: true, console only: true, and checked arguments such as <target:player> and <amount:number>, which answer with the usage line when they are missing or wrong.
• # Addons: HyperPerms in a script's notes refuses the file, with a clear message, on a server that does not have that addon.

Addons

• HyperPerms 1.0.0, a new addon for LuckPerms: group of player, add player to group "vip" for 30 days, set group of player to "member", on group change:. See the Addons page.

Documentation website

• The home page shows how many events, conditions, effects, expressions and functions the language has; each number opens the Docs filtered to that kind.
• A Cheat sheet page with the most-used syntax on one screen.
• Three more scripts: Chat.hs (format, mentions, slow mode, word filter), Duels.hs (challenges, score and a top list) and RankUp.hs (a rank ladder, for HyperPerms).
• Scripts that need an addon say so on their card.

Not done from the plan

• No any of / all of / none of; and, or and not already cover them.
• Blocks are still their type as text rather than a value of their own.
• No shield block, redstone change, piston move, entity mount, anvil use, villager trade or player count change events. Some fire too often to be useful from a script, and the mount events moved between packages across Minecraft versions.
• No books, toasts, biome setting, list without, sorted by or map each, text padding, or cancelling a pending run.
• The second addon, HyperGuard for WorldGuard, was not started.

Added

Addons

• Other plugins can now add to the language. An addon registers statements, values and events through dev.hyperscript.api.HyperScriptAPI, and they work in every script like built-in ones. The first addon is HyperVelocity, for servers behind a Velocity proxy; see the Addons page.
• Scripts are now loaded a moment after the server has finished starting, once every plugin is enabled, so that addons have added their syntax by then.

Language

• <value> parsed as number, the same conversion as parse ... as number written after the value. Also integer, text and player.
• Text tests: starts with, ends with, and matches for a regular expression.
• chance of 25%, true about that often.
• Lists: shuffled <list>, unique <list>, sum of <list>, average of <list>.
• random player, and players within 10 blocks of <location>.
• Dates: %server.date%, %server.clock%, %server.weekday%, %server.hour%, %server.minute%, and now formatted as "HH:mm" for any other form.
• on first join: for someone who has never played on the server before.

Finding mistakes

• Errors while a script runs are shown in chat to players with hyperscript.admin, not only in the console; the same message at most once a minute. Switch it off with notify-script-errors: false.

Documentation website

• The Docs page has simpler filters. Instead of a long list of topics there are seven kinds to choose from: Events, Conditions, Effects, Expressions, Types, Functions and Structures, each with a count. The topics are still there, in a drop-down.
• A "From" filter shows or hides what comes from HyperScript itself and from each addon, so the list can be only HyperScript, only HyperVelocity, or both.
• An Addons page: what each addon is, how to install it, its jar and its changelog.
• Search is better. It finds a word by its beginning (boss finds send bossbar), forgives a typo in longer words (telport finds teleport), and shows results in groups: Docs, Scripts, Pages and guides, Examples. Each result says what kind of thing it is and which addon it is from.
• A Guide page, "Writing scripts": what a script file contains, notes and # Requires:, where files go, how to make a script easy to change, and how to find mistakes.
• Script cards say what is inside: each command with its description and the permission it needs, the settings in its options: block with what they are set to, the permissions it asks about, and the events it reacts to. A "How to use a script" box sits above the list.
• /api/latestversion?addon=HyperVelocity answers for an addon.

Added

Players

• heal and feed, and values that can be read and set: health of player, max health of player, food of player, level of player, gamemode of player, flight of player. The numeric ones work with add and subtract.
• Potion effects: apply speed 2 to player for 30 seconds, clear effects of player, clear speed effect of player, and the condition player has effect speed.
• ignite / extinguish, freeze / unfreeze (held in place, can still look around) and vanish / unvanish (hidden from everyone else), with the conditions is frozen, is vanished and is flying.

Events

• Eleven more: on block place:, on sign change:, on player teleport:, on entity click:, on craft:, on consume:, on fish:, on level up:, on bed enter:, and on region enter: / on region leave: for the regions made with create region.
• New values: %event.region%, %event.lines%, %event.clicked%, %event.level% and %event.old_level%. block, item, entity and cause work in the new events too.

GUIs

• Pages. A gui knows its page: gui page, page <n> of <list> with <k> per page, pages of <list> with <k> per page, and in a click block next page, previous page and set gui page to <n>.
• refresh gui draws the gui again after a click changed what it shows.
• Turning a page or refreshing happens in the same window; it does not close and reopen.

Top lists

• top 10 players by {coins} gives the names of the players with the most, including those who are offline, and rank of player by {coins} gives one player's place.

Items

• tagged "wand" puts a hidden label on an item that players cannot see or fake, and <item> is tagged "wand" recognises it. has and remove ... from respect tags.
• model 12 sets an item's custom model number, for resource packs.

Timers

• Times of day: every day at 18:00: and every monday at 00:00: (any weekday), by the server's clock.

Files

• Subfolders. Scripts can be sorted into folders inside scripts/. Every .hs file under it is loaded and hot-reloaded, and is named by its path: /hyperscript check minigames/spleef.hs.

Changed

• event's location now also answers inside player events that had no location before, such as on player command:, where it is where the player is standing.
• Local variables changed inside an open gui block no longer change them for the lines after the block. The block runs on its own copy so that it can be run again for another page.

Documentation website

• Four more scripts on the Scripts page: Spawn.hs (a spawn with a protected area), StaffTools.hs (/heal, /feed, /fly, /gm, /vanish, /freeze), Warps.hs (warps with a paged menu and a navigator compass) and Playtime.hs (time played, top lists, and a weekly winner).

Added

• /hyperscript version shows the version the server runs and checks for an update right then. It answers with the newer version, with "You are on the newest version", or with why the website could not be reached. It works even when the check at startup is switched off.
• # Requires: 1.5.7 in the notes at the top of a script is now enforced. A plugin older than that refuses the file with one clear message, "This script needs HyperScript 1.5.7 or newer, and this server runs ...", instead of an error about whichever line it does not understand. This only helps from this version on: a plugin older than 1.5.7.1 does not know the rule.

Documentation website

• Fixed: the site looked half-updated behind Cloudflare. Cloudflare kept the stylesheet and scripts for hours, so new pages were shown with an old stylesheet and an old search index: the Scripts page, the search results, the changelog's "Big change" mark and the code colouring all appeared unstyled or out of date. Two changes stop that:
• Every stylesheet, script and logo is now linked with a version code (style.css?v=...) that changes whenever the site does, so an old copy can never be shown next to a new page.
• app.py now says how long each file may be kept: versioned files for ever, pages never.
• Looks. The header no longer breaks onto two lines: the tabs stay on one line and scroll sideways on small screens, with the search box below them. The search box has an icon and its results are easier to scan: coloured labels per kind of result and two lines of preview. Pages have a footer, cards lift when pointed at, wide tables scroll instead of overflowing, and script notes sit in their own box.

Added

Writing scripts

• options: names a script's settings once, at the top of the file, to be used anywhere in it as {@name}: a price, a waiting time, a chat prefix, a permission. Changing a script no longer means reading its code.
• on load: runs a block each time a script is loaded: the place to set defaults and create teams.
• switch with case and default, for commands with several subcommands.
• break and continue inside loops.
• Tab completion for arguments. command /kit <default|pro|master>: offers those three words when Tab is pressed, and <player> offers the players who are online.

Values

• Math functions: min(), max(), abs(), round(), floor(), ceil(), sqrt(), and rounded up / rounded down.
• duration(seconds) turns a number into readable time: "9 minutes 30 seconds".
• distance between <a> and <b> for two locations.
• Lists: items 1 to 5 of <list>, index of <value> in <list>, and keys of {warp}, which lists the names under a table so a script can loop over what it has stored.

Players and chat

• Teams: add player to team "red", a colour, prefix and suffix per team, friendly fire on or off, team of player, players of team "red". A team's colour changes the name above a player's head.
• Moderation: kick <who> because <text>, ban <who> for 7 days because <text>, unban, the condition is banned, and on player login: with refuse login because <text> to turn someone away before they are in the game.
• Clickable chat: send "&a[Home]" with click command "/home" with hover "&7Go home", plus click suggestion and click url.

Items and inventories

• Enchantments and flags: enchanted with sharpness 5, fire aspect 2, unbreakable, glowing. They are kept when an item is stored in a variable.
• Wearing and holding: set helmet of player to ..., and the same for chestplate, leggings, boots, tool and offhand; inventory slot 3 of player; clear inventory of player. Each can be read as well as set.
• GUI slots from a loop. The block under open gui is now ordinary code, so slot lines can come out of a for each or sit behind an if, and a slot can be a whole item (for a glowing button, say).

Updates

• Update check. When the server starts, HyperScript asks its website which version is the newest. If a newer one exists it says nothing in the console; operators are told when they join, and /hyperscript status shows it. If the website cannot be reached, the log says Error: couldn't fetch newest version on startup. Nothing is downloaded. Switch it off with update-check: false in config.yml.

Documentation website

• /api/latestversion answers with the newest version that has a jar, for example {"version": "1.5.7"}. This is what the plugin's update check asks.
• Three more scripts on the Scripts page: Teams.hs (coloured teams with a team chat), Warnings.hs (warn players, ban after three) and Announcements.hs (rotating messages, managed in game). Kits.hs and Homes.hs were rewritten around options: so that their settings sit at the top, and /kit <name> was added beside the /kits menu.
• Badges on scripts. A # Requires: 1.5.7 line in a script's notes shows the plugin version it needs, and # Tags: kits, gui shows tags that filter the page when clicked.
• Script examples are coloured on every page.

This release changes the documentation website and the documentation. The plugin itself behaves as in 1.5.6.

Documentation website

• A Scripts page with ready-made scripts. Each one shows what it does, the commands it adds, and has two buttons: Copy puts the script on the clipboard, Download saves it as a .hs file to drop into plugins/HyperScript/scripts.
• The page has its own search box, which looks through script names and their contents, and the site-wide search finds scripts too.
• Scripts live in the Scripts folder beside the site, one Name.hs each. The comment block at the top of a file is shown as its description, so a script explains itself with # notes. While the site is running, a file put in the folder appears on the next page load.
• A downloaded script contains the script's text and nothing else: no author, dates or paths.
• Two scripts to start with:
• Kits.hs: /kits opens a menu with three kits. Default (stone tools, chainmail armour) is for everyone; Pro (iron) and Master (netherite) each need a permission. Every kit has its own waiting time, and what a kit contains is a plain list of give lines.
• Homes.hs: /sethome, /home and /delhome, with a three-second stand-still before teleporting.
• The site listens on port 25648 on every network interface, and exporting no longer resets that.

Documentation

• The overview, tutorial and file-structure pages were brought up to date with 1.5.6: functions, loop all players, parse, inventory checks, Vault and PlaceholderAPI are now in the feature list, and the tutorial no longer describes per-player variables the old way.
• Comments are described properly: # starts a note, and a # inside quotes is ordinary text.

Changed (check existing scripts)

Variables: there are now just two kinds, and a name that starts with a player belongs to that player.

• The global. prefix is gone from the documentation and the demo. {global.event_active} is now written {event_active}. The old spelling still loads, but it is simply a variable whose name happens to begin with "global.": {global.scores} and {scores} are two different variables, so rename them in your scripts in one go. Values saved under the old names stay where they were.
• A name whose first part is a player is that player's own variable. {%arg.1%.coins} and {%_target%.coins} used to be ordinary globals named after the text (alex.coins). They now read and write the same value as that player's {%player%.coins}, online or offline. If the first part is not the name of someone who has played on the server, the variable is a global as before.
• So for tables that are not about players, start the name with a fixed word: {warp.%arg.1%} rather than {%arg.1%.warp}. Otherwise a warp called "Alex" would land in the data of the player Alex.
• {%player%.name} is unchanged.

Added

• Functions. function reward(_who, _amount): defines a block that any script can call, as a statement (reward(player.name, 50)) or for its value (set _total to reward(player.name, 50)). return <value> hands a value back. local function defines one that only the file it is written in can use. Functions may call each other across files in any order, and may call themselves up to 64 levels deep.
• parse <text> as number turns text such as "52" into the number 52, and gives unset when the text is not a number, so input can be checked with is not set. Also parse ... as integer (rounded down) and parse ... as text.
• loop all players: runs a block for everyone online. Inside it looped-player (%looped-player% in text) is the player the loop is on, while player is still whoever ran the command.
• send "..." to all players messages everyone online. send "..." and send "..." to player go to whoever ran the command, and send "..." to <name> to a named player, as before.
• Other players' variables: {%arg.1%.coins}, {%looped-player%.coins}, {%_name%.coins}, for anyone who is online or has played before.
• Inventory checks: if player has 5 diamond:, if player does not have 1 iron pickaxe:, and remove 5 diamond from player to take items away. They work with a name or all players too.
• Six events: on player death: (with set death message to and hide death message), on player respawn:, on item pickup:, on item drop:, on world change: and on player command:, which sees every command a player types and can cancel it. New values: command, amount, %event.from%, and message / cause / killer for deaths.
• Vault: with Vault and an economy plugin, balance of player is a player's money, and add 100 to balance of player, subtract ... and set balance of ... to change it.
• PlaceholderAPI, both ways: placeholder "%vault_rank%" fills in other plugins' placeholders, and other plugins can show script variables as %hyperscript_<name>% (a global) and %hyperscript_player_<name>% (the viewing player's own). Neither plugin is required.
• /hyperscript check <file> reads a script and reports any mistake without loading it, so nothing that is running changes. It works on disabled files and suggests file names on Tab.
• The bundled demo.hs gained /pay, /bonus, /sell and a death handler that show the above. A copy already on a server is not replaced automatically; /hyperscript remake demo writes the new one.

Documentation website

• A red "Big change" mark now sits beside the version name of every release that changes how existing scripts work. Clicking it shows what changed. Versions 1.5.4 and 1.5.5 carry it as well.
• The Docs page lists the new syntax and events, each with an example.

This release changes the documentation website only. The plugin itself behaves as in 1.5.5.1.

Documentation website

• HyperScript has a logo: a pair of braces with a lightning bolt between them, on the site's green-to-blue gradient.
• It is the website's icon (the one shown on the browser tab and in bookmarks), sits beside the name in the header, and appears on the home page.

The plugin itself behaves as in 1.5.5.1.

Licence

• HyperScript is now released under the MIT License, copyright HyperScript.
• The licence text is in the LICENSE file of the project and is included in the jar.

This release changes the documentation website only. The plugin itself behaves as in 1.5.5.1.

Documentation website

• The home page now shows the supported version range: Minecraft 1.16.5 to 26.x, Paper and Spigot, Java 8 or newer.
• The range is labelled as an estimate. The lower end is the server API the plugin is built against; the upper end is the newest server it has been reported working on (Paper 26.2). The versions in between are expected to work but have not each been tried.

Added

• /hyperscript remake demo writes scripts/demo.hs again, as it ships with the installed version, and reloads. It replaces any demo.hs that is there, including edits made to it. Tab completion suggests remake and demo.

Changed (check existing scripts)

A variable each player has their own of is now written {%player%.name}.

• {player.coins} still loads, but now means something else: one value shared by everyone instead of one per player. A script that is not updated will give every player the same coins.
• To make that hard to miss, HyperScript points out every variable written {player.something} when scripts load, in the console and to whoever ran /hyperscript reload. Turn the remarks off with warn-player-variables: false in config.yml once your scripts are updated.
• Saved data is not affected. {%player%.coins} reads the same stored value that {player.coins} used to, so nobody loses anything when the scripts are updated.
• The bundled demo.hs uses the new spelling. A copy already on a server is not replaced automatically; delete it and restart to get the new one.

Added

• set block at <position> to <block>: set block at 0, 64, 0 in "world" to gold block, set block at player's location to air. Block names are checked when the script loads.
• block at <position> gives the type of block that is there: if block at event's location is "bedrock":.
• /hyperscript disable <file> and /hyperscript enable <file> switch a script off and on without deleting it. A disabled script is renamed to disabled_<name>.hs; any file with that prefix is skipped when scripts load. Pressing Tab suggests the files that can be disabled or enabled, and /hyperscript list shows disabled scripts too.

Downloads

• The jar no longer carries build metadata. The copy of the build file and its properties, the build tool and JDK versions in the manifest, and the time each file was built are all gone; every entry in the jar has the same fixed date.
• The jars of earlier versions offered on the Changelog page were cleaned the same way. Their classes and resources are byte-for-byte what they were.
• An example path in the README that came from the author's machine was replaced by a neutral one, in this release and in the README packaged inside the earlier jars.

Changed (check existing scripts)

Braces now mean variables and nothing else. Built-in values such as the player's name are no longer written with braces:

• Your own variables are unchanged: {player.coins}, {global.event_active} and, inside text, %{player.coins}%.
• Scripts written for older versions need updating. A script that still writes a built-in value in braces does not load; the error names the line and shows how to write it instead, for example {player.name} is a built-in value, not a variable. Write it as player.name in code and as %player.name% inside text.
• %player.name% is also accepted in code, so only the braces have to go.
• A variable can now have any name that is not a built-in, including ones starting with event. or server..
• The bundled demo.hs uses the new style. A copy already installed on a server is not replaced automatically; delete it and restart to get the new one, or edit it.

Added

• Parts of a location can be read and changed: add 1 to y of {_loc}, set x of {_loc} to 0, subtract 5 from z of {player.home}, and as values y of {_loc} and world of {_loc}.
• Clearer errors when types are mixed up. Adding a number to a whole location, or doing math on an item, stops the trigger and logs what went wrong with both kinds of value named, for example 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>.
• log-script-errors in config.yml (default true). Set it to false to hide warnings about scripts that fail while running. The failing trigger still stops; mistakes found when a script is loaded are always reported.
• args can be written on its own in code for all command arguments together.

Unchanged, for the record

• A variable whose name starts with _ is local: it lasts for one run of the trigger and is never saved. {_loc} and _loc are the same variable. This was already the case.

This release changes the documentation website only. The plugin itself behaves as in 1.5.2.

Documentation website

• Click any entry on the Docs page to see an example of it. Often that is a single line; where one line would not make sense on its own (a command option, a GUI slot, an event), the whole small block is shown. Every example has a Copy button.
• Clicking an entry also puts its address in the address bar, so a link to exactly that entry can be shared. Opening such a link scrolls to the entry and shows its example.
• Entries can be opened from the keyboard too: Tab to one and press Enter. Escape clears the filter box.
• New Changelog tab listing what changed in each version, newest first, with a download button for each jar. It is built from the HyperScript Versions folder beside the site.
• The home page shows the latest version and links to what is new.

How the examples are made

• Each example is taken from code that is already in the documentation (the guide, the tutorial, the demo script and the event reference), so examples cannot drift apart from the rest of the docs. About fifty entries that nothing matched well have a short example written for them.

Added

Server list

• New event on server ping, fired when a client refreshes its server list.
• set motd to "<line 1>\n<line 2>", set max players to <n>, set server icon to "<path>.png" (Spigot and Paper).
• set shown players to <n>, set player list to "<line>", "<line>" (the hover text) and hide player count (Paper only; on Spigot they log one warning and do nothing).
• Placeholders %{server.motd}% and %{event.address}%.
• random item of <list>, for rotating MOTDs and anything else.

Tab list, names and chat

• set tab header of <who> to <text> and set tab footer of <who> to <text>.
• set join message to <text>, set quit message to <text>, hide join message, hide quit message.
• set chat format to <text> and set chat message to <text> in on player chat.
• set display name of <who> to <text> (chat and tab list name).

Language

• wait <duration>: pauses a trigger and carries on afterwards, anywhere, including inside if, loops, GUI click blocks and async:. Local variables are kept.
• while <condition>: loops. A loop that goes round 100,000 times without a wait is stopped with an error, so it cannot freeze the server.
• json value "<path>" of <text>: reads values out of JSON, such as web API answers. Paths use dots; list positions count from 1.

Other

• The demo script gains /countdown (while and wait), /lookup now reads its answer with json value, and there is a commented-out block for the server list, tab list and chat format.
• The Docs page of the website has new topics: Waiting, Server list, and Tab list, names and chat.

Limits worth knowing

• The name above a player's head cannot be changed; set display name affects chat and the tab list only.
• on server ping has no player and runs off the server thread; keep it to a few set lines.
• After a wait, the event that started the trigger is over, so cancel event and statements such as set join message no longer do anything.
• Waits do not survive a server restart or a script reload.

Added

• summon <entity> at <location>, with an optional amount and name: summon zombie at player's location, summon 3 chicken at event's location, summon iron golem named "&6Town Guard" at 0, 80, 0 in "world". Entity names are checked when the script loads. Up to 50 at a time.
• permission: op on a command limits it to server operators and the console. permission: "<node>" works as before.
• permission player add "<node>" and permission player remove "<node>" give and take back permissions from scripts. Grants are saved with the player's data and applied again every time they join. remove only undoes what add gave; permissions from ranks or other plugins are not touched.
• Reload errors are shown to whoever ran /hyperscript reload, not only in the console. When a hot reload finds an error, it is sent to online players with the hyperscript.admin permission.

Removed

• /hyperscript docs and the docs.output-directory setting. The documentation website is now generated only from a terminal: java -cp HyperScript-1.5.1.jar dev.hyperscript.docs.DocsExporter "<folder>".

Documentation website

• Smaller site. The tabs are Home, Overview, Installation, Configuration and Tutorial. The Java implementation and Building from source pages are gone from the site (they remain in the README).
• New Tutorial page: a first script in a few minutes.
• New Docs page at /Docs, reached from a Docs button to the left of the search box. It lists every statement, expression, placeholder and event on one page, with type and topic filters on the left and a box that filters as you type. Each topic keeps its full guide and examples behind "Guide and examples", and each event has its values, an example and a try-it box.
• Effects: an animated headline on the home page, cards and entries that rise into view, hover movement, animated tab underlines, and a highlight on the entry a search result takes you to. All of it is switched off for visitors who ask their system for reduced motion.
• The exporter no longer writes docs/*.md or mkdocs.yml.

Added

Events

• on entity damage (also written on hit): any entity taking damage. Values: attacker, victim, damage, cause, entity, %{event.location}%. Cancellable.
• on player jump: works on Spigot and Paper. Cancellable (the player is snapped back, so a small hop may be visible).
• on mob spawn: values entity, reason, %{event.location}%. Cancellable.
• on inventory click: values slot, item, %{event.click_type}%. Cancellable.

Event values

• Short words inside event blocks: attacker, victim, damage, cause, message, block, entity, killer, reason, slot, item. For example if message contains "badword":.
• Built-in placeholders can be written without %{ }% in conditions and expressions: event.cause, player.health, server.tps, arg.1.
• New placeholders: %{event.recipients}% (chat), %{event.drops}% and %{event.location}% (block break), %{player}%, %{player.location}%.
• is and is not as comparisons: if event.cause is "FALL":, if {player.frozen} is true:.

Documentation site

• events_metadata.json: every event with its values, whether it can be cancelled, who player is, and an example. Also served by app.py at /events_metadata.json and /api/events?name=....
• An Events reference page with a section per event and a "try it" box: click a value to add a line that uses it to a small script, then copy the result.
• Every event and every event value is in the search index, so searching attacker, damage or jump goes straight to the event.

Changed (check existing scripts)

• event's location now also works in on entity damage, on mob spawn and on player jump (the victim's, the spawn's and the player's position).
• %{event.entity}% is now set in on entity damage and on mob spawn as well as on entity death.
• %{event.item}% is now set in on inventory click as well as on right click.
• The words listed under "Event values" are now reserved inside expressions. item followed by a number is still the list lookup item 2 of <list>.

Added

Resource packs

• send resource pack "<url>" [with hash "<sha1>"] to <who>
• Events: on resource pack accept, on resource pack decline, on resource pack successfully loaded, on resource pack failed.
• A hash that is not a 40-character SHA-1 hash is reported and the pack is sent without it, since a wrong hash makes clients reject the pack.

Web requests

• send get request to "<url>" and send post request to "<url>" with body "<body>" [headers "<Name: value>", ...].
• As a value (set {_response} to send get request ...) a request must be inside async:; as a statement it can be used anywhere and is sent in the background.
• Requests may only go to public internet addresses. Local and private network addresses are refused unless web.allow-private-addresses is enabled. New config section web (enabled, allow-private-addresses).
• urlencoded <text> for putting player input into a URL safely.

Sounds

• play sound "<name>" [with pitch <n>] [and volume <n>] followed by at <location>, for <player>, for all players or for all players in world "<world>".

Worlds and regions

• set time in world "<world>" to <ticks> and set weather in world "<world>" to clear|rain|thunder.
• Box regions: create region "<name>" from <location> to <location>, delete region "<name>", and region at <location>, which gives the names of the regions containing a location.
• event's location: the block being broken or clicked.
• player does not have permission "<node>".

Smaller additions

• A command line may describe its arguments: command /lookup <player>:. The description becomes the default usage text.
• {_list.2} / %{_list.2}% reads element 2 of a list held in a local variable.
• The demo script gains /day, /protect, /unprotect and /lookup, a protected-region check and a level-up sound, plus a commented-out resource pack example.

Changed (check existing scripts)

• <unset value> contains "..." is now always false. It used to compare against the text <none>, so contains "on" was accidentally true for an unset value.
• {_name.2} used to be a saved global variable with that literal name; it now means element 2 of the local _name.

Not included

• Regions are HyperScript's own; WorldGuard regions are not read. "Region permissions" are written in scripts (as in the spec's example) rather than configured per region.
• Web answers are plain text; there is no JSON reader yet.

Added

Custom items

• Items can be given with a custom name and lore: give player 1 diamond sword named "&6Excalibur" with lore "&7A legendary blade", "&7Forged in fire."
• Item names are written as plain words (diamond sword, golden apple) and are checked when the script loads, so a misspelt item is reported immediately.
• The recipient may come first (give player ..., give all players ...) or last (give ... to player).

Value types

• Variables can now hold items, durations and locations as well as numbers, text, booleans and lists. All of them are saved to data.json and to MySQL/SQLite.
• set {player.backpack.item} to diamond sword named "Storage"
• set {event.start_time} to 30 minutes
• set {player.home} to player's location
• Durations: 5 ticks, 30 seconds, 1 hour 30 minutes. In math and comparisons a duration counts as seconds; two durations add and subtract to a duration.
• Locations can be used wherever a position is expected (spawn ... at {player.home}).
• New statement teleport <who> to <position>.
• New placeholder %{server.time}% (seconds since 1970) for timestamps.
• GUI slots accept item values: slot 5 is {player.backpack.item}.

Files

• create file <name> [at <folder>], set file at <path> to <text>, append <text> to file at <path>, read file at <path>, file at <path> exists, delete file at <path>.
• File access is sandboxed to plugins/HyperScript/. Paths that leave it are refused, and the plugin's own files (config.yml, data.json, the database, scripts/, backups/) cannot be touched by scripts. New config option files.enabled (default true).

Text

• split <text> by <separator>, join <list> with <separator>, uppercase, lowercase, trimmed, replace <a> with <b> in <text>, first/last <n> characters of <text>, characters <a> to <b> of <text>, length of <text>, rounded <number>.
• \n inside a string is a line break.

Other

• {_name} is accepted as another way to write the local _name.
• A name starting with server. or event. can be used as a variable of your own if the script assigns it somewhere (for example {event.start_time}); otherwise an unknown one is still reported as a mistyped placeholder.
• The demo script gains /excalibur (custom item) and /note (a text file per player), and /sethome / /home now store a location and teleport.

Changed (check existing scripts)

• {_name} used to be a saved global variable called _name; it is now the local _name. A script that relied on {_something} keeping its value between runs needs a different name.
• A number followed by a time unit is now a duration. for 10 seconds behaves as before, but an expression such as _x * 2 seconds now means "two seconds" where it used to be an error.
• \n in a string is now a line break, where it used to be a backslash and the letter n.
• A bare word that is not a known item is an error at load time (give 1 dimond to player).

Documentation site

• Unchanged in structure from 1.2.0: a FastAPI application (app.py, requirements.txt) with search_index.json and instant search (Ctrl+K or /). Re-exported for 1.3.0; the index now also covers the new statements, the value types, files and text operations.

Added

• Cooldowns on commands and events: cooldown: 1 hour and cooldown message: "... %cooldown% ...", per player, saved with player data. reset cooldown refunds one; the permission hyperscript.cooldown.bypass skips them.
• Timers: every 5 seconds: and every 1 second for all players:.
• Action bars and titles: send action bar ..., and send title ... with subtitle ... to player with fadein 10 stay 70 fadeout 20.
• Boss bars: create bossbar [id] titled ... with color red with progress 100 for all players, remove bossbar [id]. Creating a bar whose id exists updates it.
• Scoreboards: per-player sidebars with set title of player's scoreboard to ..., set line N of player's scoreboard to ..., delete line N of ..., clear player's scoreboard.
• Particle shapes: draw particle circle|sphere with radius R using particle "..." at ... and draw particle line from ... to ... using particle "...".
• give <amount> <item> to <who>.
• Documentation site: the exporter now generates a FastAPI application (app.py, requirements.txt) with search_index.json and instant search (Ctrl+K or /).