Writing scripts

The tutorial gets a first script running. This page is about writing scripts that stay easy to read, change and repair.

What a script file contains

A script is one .hs file. Everything in it stands at the left margin and opens a block:

They may come in any order. A good order to read is the one the scripts on the Scripts page use: notes, options, functions, commands, events.

# ==============================================================
#  Greeter.hs - welcomes players
# ==============================================================
#
# Requires: 1.5.9
# Tags: chat, welcome
#
# Notes
#  - Change the messages in the options below.

options:
    prefix: "&8[&aHi&8] "
    first_time: "&6Welcome to the server, %player.name%!"

on first join:
    broadcast "{@prefix}{@first_time}"
    give 16 bread to player

on player join:
    send "{@prefix}&7Welcome back."

Notes at the top

Lines that begin with # are comments, for people. Start every script with a few that say what it does and what someone might want to change. Three of them mean something more:

Where files go

• Every .hs file under plugins/HyperScript/scripts/ is loaded, subfolders included. Sort a growing collection into folders: scripts/staff/, scripts/minigames/.
• Files load in alphabetical order of their path. It rarely matters: functions may be called before the file that defines them has loaded, and on load: blocks run after everything is in.
• A file named disabled_<name>.hs is skipped. /hyperscript disable <file> renames it for you.
• One file per feature is easier to live with than one file for everything: a mistake in a file stops only that file from loading.

Making a script easy to change

• Put every setting in options:: prefixes, prices, waiting times, permissions. Someone who wants to change the script then never has to read its code.
• Give a script one prefix and use it in every message, so players can tell where a message comes from.
• Name variables after the script: {warp.spawn}, {%player%.kits.default}. Two scripts that both use {count} will overwrite each other.
• Start a table that is not about players with a fixed word: {warp.%arg.1%}, never {%arg.1%.warp}, which would land in the data of a player of that name.
• Use local function for helpers only one file needs. A plain function is shared by every script, so its name must be unique on the server.
• Check what a player typed before using it: parse arg.1 as number gives unset for text that is not a number, and if arg.1 is not set: catches a missing argument.
• Guard player-only commands with if player is not set: so the console gets a sensible answer instead of an error.

One file for every setting. With options-file: true in config.yml, HyperScript writes the options: of every script into plugins/HyperScript/options.yml, grouped by file:

Shop.hs:
  prefix: '&8[&6Shop&8] '
  price: 50

Whoever runs the server can then change prices and messages there without opening a script. While this is on, a value in options.yml is used instead of the one in the script, so change it there; an option is added to the file the first time a script has it. It is off unless you turn it on, because with it on, editing an option inside a script no longer changes anything.

Finding mistakes

A slip in a variable's name is pointed out. When the scripts load, a saved variable that is read but that no script ever sets, and whose name is a letter away from one that is set, gets a line in the console: shop.hs:14 {%player%.coinz} is read, but no script ever sets it. Did you mean {%player%.coins}? /hyperscript check <file> says the same for one script. Local variables get the same care inside their own block: {_coinz} that is read where only {_coins} is set is pointed out too. It is a remark, not an error: the script loads all the same. Only such near misses are named, since a variable may well be set by something other than a script.

An error about a word HyperScript does not know suggests the nearest one it does: Unknown event 'player joined'. Did you mean 'player join'? That goes for events, statements, functions, the options of a command, the names in an options: block, the word a block starts with (comand /shop:), and for items, blocks, entities, effects and enchantments (Unknown block 'dimond block'. Did you mean 'diamond block'?).

In chat, a mistake 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:

 - shop.hs:12 Unknown block 'dimond block'. Did you mean 'diamond block'?
     12 | set block at player to dimond block
     fix | set block at player to diamond block  [copy]

Click the suggestion or the green line to copy it, and paste it over the old one in your editor. Click the file's name to put /hyperscript check shop.hs in the chat box. The same is shown after /hyperscript reload and /hyperscript check. The console gets the plain report.

Finding out what went wrong. /hyperscript errors lists the scripts that did not load and the last failures of running scripts, newest first:

Failures while running, newest first:
 Shop.hs:54 12s ago, 3 times, last by Steve
   > give 1 {_material} to player
   Cannot give an item: the value is not set

A failure that repeats is listed once, with a count. The player whose command or click failed is told player-error-message from config.yml instead of nothing happening; set it to "" to tell them nothing. Admins see the real message in chat (with notify-script-errors) and not that line.

All at once. When a file has mistakes, HyperScript names one for each part of the file that has any (each command, event and function), not only the first, so they can be fixed in one go. The file is still loaded as a whole or not at all. The first mistake named is always the real one; a later one can be a knock-on of an earlier.

There are two kinds of mistake:

• When a script loads. A line HyperScript cannot read: a missing quote, an unknown event, a misspelt item. The whole file is refused, with the line number, and nothing in it runs. Fix the line and save.
• While a script runs. The line reads fine but cannot be done: adding a number to a location, dividing by zero. That one trigger stops; the rest of the script carries on. The message goes to the console and, with notify-script-errors: true, to admins in chat, at most once a minute per message.

Most surprises come from a value being unset. An unset value counts as 0 in math, as nothing in text and as false in a condition, so a script keeps going where you might expect an error. When something does nothing, log the values on the line before it.

Testing a script

A script can carry its own checks, so that after a change you know in a second whether it still does what it should:

command /daily:
    trigger:
        add 100 to {%player%.coins}
        send "&aYou got 100 coins."

test "daily pays a hundred":
    execute player command "/daily"
    expect {%player%.coins} is 100
    expect test log contains "You got 100 coins"

/hyperscript test runs every test of every script; /hyperscript test Shop only those of Shop.hs. Each is listed as passed or failed, with the line that did not hold.

• Tests run on a pretend server, the same one the playground uses. Nothing they do reaches your world or your players, and saved variables are not touched: every test starts with none. The player is called Steve.
• execute player command "/name" really runs that command of the same script, as Steve. Functions can be called directly.
• Because the server is pretend, it knows nothing of your world: wait does not wait, a question about a block or another player has no answer, and what addons add is not there. Tests are for a script's own reasoning: prices, permissions, what is saved, what is said.

Scripts straight from the website. /hyperscript search kits lists matching scripts, and /hyperscript install <id> puts one in the scripts folder and loads it, without leaving the game. The ready-made scripts install by their name (/hyperscript install Kits); those people sent in by the id shown on their page. Scripts people sent in were looked at before they were put on the website, but they are other people's code: read one before you rely on it.

Using scripts other people wrote

The Scripts page has ready-made scripts. Each shows the commands it adds, the settings you can change, the permissions it uses and the version it needs. Download one into the scripts folder and it is live.

Every script on the website has an id, and Copy id next to it copies that. On the server, /hyperscript install <id> fetches the script and loads it.

A script written for Skript can be turned into HyperScript on the From Skript page. It rewrites the common things and leaves the rest for you to finish.

Before adding a script from anywhere else, read it. A script can run console commands, change files in the plugin folder and send web requests. /hyperscript check <file> tells you whether it loads, not whether you want what it does.

Addons

An addon is a separate plugin that adds statements, values and events to the language. Install it next to HyperScript and its syntax works in every script. The Addons page lists the ones published here, and on the Docs page everything an addon adds carries the addon's name and can be shown or hidden with the From filter.

A script that uses an addon's syntax does not load without the addon; the error names the line.

Scripts in another language

Scripts are written in English, and can be written with the words of another language as well. Which one is chosen with language: in config.yml:

language: english     # english | french | spanish | portuguese | german

/hyperscript reload reads it again, so it can be changed without a restart. With french, a script can say this:

commande /bonjour:
    déclencheur:
        si le joueur a la permission "bonjour.vip":
            envoyer "&6Bonjour, %joueur%!" au joueur
        sinon:
            envoyer "&aBonjour!" au joueur
        attendre 2 secondes
        donner 1 diamond au joueur

and it is read as:

command /bonjour:
    trigger:
        if player has permission "bonjour.vip":
            send "&6Bonjour, %player%!" to player
        else:
            send "&aBonjour!" to player
        wait 2 seconds
        give 1 diamond to player

On this website, the menu at the top right shows the examples and the syntax of the docs with the words of a language, so they can be read, and copied, the way a server with that setting takes them. *Try it* always opens the English, which is what the Playground reads.

Not everything is translated, and not every translation is correct. What to know:

• It is a list of words, not a grammar. The words of a line stay in the order English has them: si le joueur a la permission "x": works, a sentence turned round the way the language would have it may not.
• English works in every script whatever language is chosen, also mixed into a line. A word that is not in the list is left as it is, so everything that has no translation is written in English: the names of items, blocks, creatures, sounds and worlds, and all the syntax the table below does not name.
• With english nothing else is looked for, and a script written in another language does not load.
• Text in quotes, comments, the names of variables, commands, options and functions are yours and are never changed. Code inside text is read as code: "%joueur%" is "%player%".
• A word is also known without its accents: definir for définir, losche for lösche.
• Errors, /hyperscript and these docs stay in English, and an error shows the line as it was read, in English.
• A word that is an English word of a script already keeps its English meaning. That is why Spanish y is not *and* (it is the height of a place; write e or and), si no is *if not* and so sino is *else*, and German Tag is not *day* (write Tage or day).

Addons bring the words for their own syntax (coller le schéma with HyperEdit, créer région with HyperGuard) and take the language from this setting; they have none of their own. Each addon's page lists its words.

To add words, or to say one differently, put a file named after the language into the plugin's languages folder, such as plugins/HyperScript/languages/french.txt, with a line for each:

send = envoyer | balancer
broadcast = crier

The words each language has: