# HyperScript

> HyperScript is a scripting language for Minecraft servers, in the form of a plugin for Paper and Spigot (1.16.5 and newer, Java 8 and newer). Scripts are plain text files ending in .hs in plugins/HyperScript/scripts/. They define commands, react to events, and build menus, scoreboards and more, and are loaded again as soon as they are saved.

Things to know before writing or reading a script:

- A file is made of blocks at the left margin: `command /name:`, `on <event>:`, `every <time>:`, `function name(_a, _b):`, `options:`. A line ending in `:` opens a block; what belongs to it is indented by four spaces.
- `{name}` is a saved variable shared by every script; `{%player%.coins}` belongs to one player; `{_name}` or `_name` lasts for one run only.
- `%player%`, `%arg.1%`, `%server.tps%` and the like are placeholders, usable inside text in quotes and, without the percent signs, as values.
- Text is written in double quotes, with `&` colour codes (`&a` is green). A comment starts with `#`.
- A script that has a mistake is not loaded at all; the server names the file and the line.
- The language is HyperScript's own. It resembles Skript in places but is not Skript: do not assume Skript syntax works. Every statement that exists is in the documentation below.
- The current version is 1.7.71.

## Documentation

- [The complete documentation in one file](https://hyperscript.monoforge.net/llms-full.txt): everything below as one Markdown document. Read this to answer questions about syntax.
- [Docs](https://hyperscript.monoforge.net/Docs/): every statement, condition, value and event, each with an example
- [Overview](https://hyperscript.monoforge.net/overview-and-architecture.html)
- [Installation](https://hyperscript.monoforge.net/installation-and-setup.html)
- [Configuration](https://hyperscript.monoforge.net/configuration.html)
- [Tutorial](https://hyperscript.monoforge.net/quick-tutorial.html)
- [Guide](https://hyperscript.monoforge.net/writing-scripts.html)
- [Cheat sheet](https://hyperscript.monoforge.net/cheat-sheet.html)
- [Playground](https://hyperscript.monoforge.net/playground.html): check and run a script in the browser
- [Ready-made scripts](https://hyperscript.monoforge.net/scripts.html): whole scripts to read and use
- [From Skript](https://hyperscript.monoforge.net/convert.html): turn a Skript script into HyperScript
- [Changelog](https://hyperscript.monoforge.net/changelog.html): what each version changed

## The language, topic by topic

- [File structure](https://hyperscript.monoforge.net/Docs/file-structure.html)
- [Variables](https://hyperscript.monoforge.net/Docs/variables.html)
- [Options](https://hyperscript.monoforge.net/Docs/options.html)
- [Value types](https://hyperscript.monoforge.net/Docs/value-types.html)
- [Conditions](https://hyperscript.monoforge.net/Docs/conditions.html)
- [Loops](https://hyperscript.monoforge.net/Docs/loops.html)
- [Switch](https://hyperscript.monoforge.net/Docs/switch.html)
- [Functions](https://hyperscript.monoforge.net/Docs/functions.html)
- [Waiting](https://hyperscript.monoforge.net/Docs/waiting.html)
- [Handling errors](https://hyperscript.monoforge.net/Docs/handling-errors.html)
- [Complete example: demo.hs](https://hyperscript.monoforge.net/Docs/complete-example-demohs.html)
- [Text](https://hyperscript.monoforge.net/Docs/text.html)
- [Math](https://hyperscript.monoforge.net/Docs/math.html)
- [Lists](https://hyperscript.monoforge.net/Docs/lists.html)
- [Records and tables (custom data)](https://hyperscript.monoforge.net/Docs/records-and-tables-custom-data.html)
- [Dates and times](https://hyperscript.monoforge.net/Docs/dates-and-times.html)
- [Messages in several languages](https://hyperscript.monoforge.net/Docs/messages-in-several-languages.html)
- [Built-in placeholders](https://hyperscript.monoforge.net/Docs/built-in-placeholders.html)
- [Commands](https://hyperscript.monoforge.net/Docs/commands.html)
- [Permissions](https://hyperscript.monoforge.net/Docs/permissions.html)
- [Cooldowns](https://hyperscript.monoforge.net/Docs/cooldowns.html)
- [Events](https://hyperscript.monoforge.net/Docs/events.html)
- [Event values](https://hyperscript.monoforge.net/Docs/event-values.html)
- [Events reference](https://hyperscript.monoforge.net/Docs/events-reference.html)
- [Timers](https://hyperscript.monoforge.net/Docs/timers.html)
- [Actions](https://hyperscript.monoforge.net/Docs/actions.html)
- [Players](https://hyperscript.monoforge.net/Docs/players.html)
- [Offline players](https://hyperscript.monoforge.net/Docs/offline-players.html)
- [Tab list, names and chat](https://hyperscript.monoforge.net/Docs/tab-list-names-and-chat.html)
- [Teams](https://hyperscript.monoforge.net/Docs/teams.html)
- [Parties and queues](https://hyperscript.monoforge.net/Docs/parties-and-queues.html)
- [Moderation](https://hyperscript.monoforge.net/Docs/moderation.html)
- [Top lists](https://hyperscript.monoforge.net/Docs/top-lists.html)
- [A currency of your own](https://hyperscript.monoforge.net/Docs/a-currency-of-your-own.html)
- [Action bars and titles](https://hyperscript.monoforge.net/Docs/action-bars-and-titles.html)
- [Boss bars](https://hyperscript.monoforge.net/Docs/boss-bars.html)
- [Scoreboards](https://hyperscript.monoforge.net/Docs/scoreboards.html)
- [GUIs](https://hyperscript.monoforge.net/Docs/guis.html)
- [Trading](https://hyperscript.monoforge.net/Docs/trading.html)
- [Advancements](https://hyperscript.monoforge.net/Docs/advancements.html)
- [Sounds](https://hyperscript.monoforge.net/Docs/sounds.html)
- [Resource packs](https://hyperscript.monoforge.net/Docs/resource-packs.html)
- [Worlds and regions](https://hyperscript.monoforge.net/Docs/worlds-and-regions.html)
- [Places](https://hyperscript.monoforge.net/Docs/places.html)
- [Entities](https://hyperscript.monoforge.net/Docs/entities.html)
- [Mobs of your own](https://hyperscript.monoforge.net/Docs/mobs-of-your-own.html)
- [Characters](https://hyperscript.monoforge.net/Docs/characters.html)
- [Display entities and particles](https://hyperscript.monoforge.net/Docs/display-entities-and-particles.html)
- [Particle shapes](https://hyperscript.monoforge.net/Docs/particle-shapes.html)
- [Noise](https://hyperscript.monoforge.net/Docs/noise.html)
- [Scenes](https://hyperscript.monoforge.net/Docs/scenes.html)
- [Enchantments of your own](https://hyperscript.monoforge.net/Docs/enchantments-of-your-own.html)
- [Recipes](https://hyperscript.monoforge.net/Docs/recipes.html)
- [NBT and data on things](https://hyperscript.monoforge.net/Docs/nbt-and-data-on-things.html)
- [Files](https://hyperscript.monoforge.net/Docs/files.html)
- [The database](https://hyperscript.monoforge.net/Docs/the-database.html)
- [Web requests](https://hyperscript.monoforge.net/Docs/web-requests.html)
- [Async blocks](https://hyperscript.monoforge.net/Docs/async-blocks.html)
- [Server list](https://hyperscript.monoforge.net/Docs/server-list.html)
- [Other plugins](https://hyperscript.monoforge.net/Docs/other-plugins.html)
- [Discord](https://hyperscript.monoforge.net/Docs/discord.html)
- [Combat and being away](https://hyperscript.monoforge.net/Docs/combat-and-being-away.html)
- [Things kept track of for you](https://hyperscript.monoforge.net/Docs/things-kept-track-of-for-you.html)
- [Quests](https://hyperscript.monoforge.net/Docs/quests.html)
- [Kits](https://hyperscript.monoforge.net/Docs/kits.html)
- [Dialogue](https://hyperscript.monoforge.net/Docs/dialogue.html)
- [The server's own counts and lists](https://hyperscript.monoforge.net/Docs/the-servers-own-counts-and-lists.html)
- [HyperBedrock: Who is on Bedrock](https://hyperscript.monoforge.net/Docs/hyperbedrock-who-is-on-bedrock.html)
- [HyperBedrock: Forms](https://hyperscript.monoforge.net/Docs/hyperbedrock-forms.html)
- [HyperBedrock: Buttons with a picture, and another server](https://hyperscript.monoforge.net/Docs/hyperbedrock-buttons-with-a-picture-and-another-server.html)
- [HyperCitizens: Clicking an NPC](https://hyperscript.monoforge.net/Docs/hypercitizens-clicking-an-npc.html)
- [HyperCitizens: Making and removing](https://hyperscript.monoforge.net/Docs/hypercitizens-making-and-removing.html)
- [HyperCitizens: Moving and talking](https://hyperscript.monoforge.net/Docs/hypercitizens-moving-and-talking.html)
- [HyperCitizens: How an NPC looks and behaves](https://hyperscript.monoforge.net/Docs/hypercitizens-how-an-npc-looks-and-behaves.html)
- [HyperCitizens: Finding NPCs](https://hyperscript.monoforge.net/Docs/hypercitizens-finding-npcs.html)
- [HyperCitizens: The nearest NPC, and its name](https://hyperscript.monoforge.net/Docs/hypercitizens-the-nearest-npc-and-its-name.html)
- [HyperCitizens: More examples](https://hyperscript.monoforge.net/Docs/hypercitizens-more-examples.html)
- [HyperEconomy: One money for scripts and plugins](https://hyperscript.monoforge.net/Docs/hypereconomy-one-money-for-scripts-and-plugins.html)
- [HyperEconomy: When another plugin moves money](https://hyperscript.monoforge.net/Docs/hypereconomy-when-another-plugin-moves-money.html)
- [HyperEconomy: Amounts and the currency](https://hyperscript.monoforge.net/Docs/hypereconomy-amounts-and-the-currency.html)
- [HyperEconomy: The richest, the total, and what was last moved](https://hyperscript.monoforge.net/Docs/hypereconomy-the-richest-the-total-and-what-was-last-moved.html)
- [HyperEdit: Schematics](https://hyperscript.monoforge.net/Docs/hyperedit-schematics.html)
- [HyperEdit: Changing many blocks](https://hyperscript.monoforge.net/Docs/hyperedit-changing-many-blocks.html)
- [HyperEdit: Pyramids and repeating a box](https://hyperscript.monoforge.net/Docs/hyperedit-pyramids-and-repeating-a-box.html)
- [HyperEdit: More examples](https://hyperscript.monoforge.net/Docs/hyperedit-more-examples.html)
- [HyperGrim: When Grim flags somebody](https://hyperscript.monoforge.net/Docs/hypergrim-when-grim-flags-somebody.html)
- [HyperGrim: What Grim knows about a player](https://hyperscript.monoforge.net/Docs/hypergrim-what-grim-knows-about-a-player.html)
- [HyperGrim: Telling Grim to look away, forget or be quiet](https://hyperscript.monoforge.net/Docs/hypergrim-telling-grim-to-look-away-forget-or-be-quiet.html)
- [HyperGuard: Where players are](https://hyperscript.monoforge.net/Docs/hyperguard-where-players-are.html)
- [HyperGuard: Entering and leaving](https://hyperscript.monoforge.net/Docs/hyperguard-entering-and-leaving.html)
- [HyperGuard: Owners and members](https://hyperscript.monoforge.net/Docs/hyperguard-owners-and-members.html)
- [HyperGuard: Flags](https://hyperscript.monoforge.net/Docs/hyperguard-flags.html)
- [HyperGuard: Making regions](https://hyperscript.monoforge.net/Docs/hyperguard-making-regions.html)
- [HyperGuard: Whether there is such a region](https://hyperscript.monoforge.net/Docs/hyperguard-whether-there-is-such-a-region.html)
- [HyperGuard: Claiming land](https://hyperscript.monoforge.net/Docs/hyperguard-claiming-land.html)
- [HyperGuard: Where a region is](https://hyperscript.monoforge.net/Docs/hyperguard-where-a-region-is.html)
- [HyperGuard: Working with HyperScript's own areas](https://hyperscript.monoforge.net/Docs/hyperguard-working-with-hyperscripts-own-areas.html)
- [HyperGuard: When WorldGuard says no](https://hyperscript.monoforge.net/Docs/hyperguard-when-worldguard-says-no.html)
- [HyperHolograms: Making and changing](https://hyperscript.monoforge.net/Docs/hyperholograms-making-and-changing.html)
- [HyperHolograms: Pages and who sees it](https://hyperscript.monoforge.net/Docs/hyperholograms-pages-and-who-sees-it.html)
- [HyperHolograms: Asking and clicking](https://hyperscript.monoforge.net/Docs/hyperholograms-asking-and-clicking.html)
- [HyperHolograms: For a time, the nearest, and how far it is seen](https://hyperscript.monoforge.net/Docs/hyperholograms-for-a-time-the-nearest-and-how-far-it-is-seen.html)
- [HyperHolograms: More examples](https://hyperscript.monoforge.net/Docs/hyperholograms-more-examples.html)
- [HyperLog: Looking things up](https://hyperscript.monoforge.net/Docs/hyperlog-looking-things-up.html)
- [HyperLog: Taking it back](https://hyperscript.monoforge.net/Docs/hyperlog-taking-it-back.html)
- [HyperLog: Who placed it, who broke it](https://hyperscript.monoforge.net/Docs/hyperlog-who-placed-it-who-broke-it.html)
- [HyperLog: More examples](https://hyperscript.monoforge.net/Docs/hyperlog-more-examples.html)
- [HyperMobs: Spawning and removing](https://hyperscript.monoforge.net/Docs/hypermobs-spawning-and-removing.html)
- [HyperMobs: Skills and levels](https://hyperscript.monoforge.net/Docs/hypermobs-skills-and-levels.html)
- [HyperMobs: Events](https://hyperscript.monoforge.net/Docs/hypermobs-events.html)
- [HyperMobs: Items, signals and being hurt](https://hyperscript.monoforge.net/Docs/hypermobs-items-signals-and-being-hurt.html)
- [HyperModels: Items](https://hyperscript.monoforge.net/Docs/hypermodels-items.html)
- [HyperModels: Blocks and furniture](https://hyperscript.monoforge.net/Docs/hypermodels-blocks-and-furniture.html)
- [HyperModels: Events](https://hyperscript.monoforge.net/Docs/hypermodels-events.html)
- [HyperModels: Furniture put down, broken and taken away](https://hyperscript.monoforge.net/Docs/hypermodels-furniture-put-down-broken-and-taken-away.html)
- [HyperPackets: Fake players on the tab list](https://hyperscript.monoforge.net/Docs/hyperpackets-fake-players-on-the-tab-list.html)
- [HyperPackets: Sending any packet](https://hyperscript.monoforge.net/Docs/hyperpackets-sending-any-packet.html)
- [HyperPerms: Groups](https://hyperscript.monoforge.net/Docs/hyperperms-groups.html)
- [HyperPerms: Changing groups](https://hyperscript.monoforge.net/Docs/hyperperms-changing-groups.html)
- [HyperPerms: Single permissions](https://hyperscript.monoforge.net/Docs/hyperperms-single-permissions.html)
- [HyperPerms: Lists and weights](https://hyperscript.monoforge.net/Docs/hyperperms-lists-and-weights.html)
- [HyperPerms: Meta](https://hyperscript.monoforge.net/Docs/hyperperms-meta.html)
- [HyperPerms: Group events](https://hyperscript.monoforge.net/Docs/hyperperms-group-events.html)
- [HyperPerms: Making groups, prefixes and suffixes](https://hyperscript.monoforge.net/Docs/hyperperms-making-groups-prefixes-and-suffixes.html)
- [HyperPerms: More examples](https://hyperscript.monoforge.net/Docs/hyperperms-more-examples.html)
- [HyperPlots: Coming and going](https://hyperscript.monoforge.net/Docs/hyperplots-coming-and-going.html)
- [HyperPlots: Asking about plots](https://hyperscript.monoforge.net/Docs/hyperplots-asking-about-plots.html)
- [HyperPlots: Changing who a plot lists](https://hyperscript.monoforge.net/Docs/hyperplots-changing-who-a-plot-lists.html)
- [HyperPlots: More examples](https://hyperscript.monoforge.net/Docs/hyperplots-more-examples.html)
- [HyperSkin: Changing a skin](https://hyperscript.monoforge.net/Docs/hyperskin-changing-a-skin.html)
- [HyperSkin: A head with the skin somebody wears](https://hyperscript.monoforge.net/Docs/hyperskin-a-head-with-the-skin-somebody-wears.html)
- [HyperVelocity: Proxy players](https://hyperscript.monoforge.net/Docs/hypervelocity-proxy-players.html)
- [HyperVelocity: Proxy commands](https://hyperscript.monoforge.net/Docs/hypervelocity-proxy-commands.html)
- [HyperVelocity: Proxy variables](https://hyperscript.monoforge.net/Docs/hypervelocity-proxy-variables.html)
- [HyperVelocity: Proxy events](https://hyperscript.monoforge.net/Docs/hypervelocity-proxy-events.html)
- [HyperVelocity: Parties and groups](https://hyperscript.monoforge.net/Docs/hypervelocity-parties-and-groups.html)
- [HyperVelocity: Asking another server](https://hyperscript.monoforge.net/Docs/hypervelocity-asking-another-server.html)
- [HyperVelocity: Channels](https://hyperscript.monoforge.net/Docs/hypervelocity-channels.html)
- [HyperVelocity: Server status](https://hyperscript.monoforge.net/Docs/hypervelocity-server-status.html)
- [HyperVelocity: Coming, going and changing server](https://hyperscript.monoforge.net/Docs/hypervelocity-coming-going-and-changing-server.html)
- [HyperVoice: Groups](https://hyperscript.monoforge.net/Docs/hypervoice-groups.html)
- [HyperVoice: Who is connected](https://hyperscript.monoforge.net/Docs/hypervoice-who-is-connected.html)
- [HyperVoice: Muting](https://hyperscript.monoforge.net/Docs/hypervoice-muting.html)
- [HyperVoice: Hearing nothing, and how far a voice carries](https://hyperscript.monoforge.net/Docs/hypervoice-hearing-nothing-and-how-far-a-voice-carries.html)
- [HyperVoice: Events](https://hyperscript.monoforge.net/Docs/hypervoice-events.html)
- [HyperVotes: When somebody votes](https://hyperscript.monoforge.net/Docs/hypervotes-when-somebody-votes.html)
- [HyperVotes: Counting votes](https://hyperscript.monoforge.net/Docs/hypervotes-counting-votes.html)
- [HyperVotes: Testing and resetting](https://hyperscript.monoforge.net/Docs/hypervotes-testing-and-resetting.html)
- [HyperVotes: This month, and round numbers](https://hyperscript.monoforge.net/Docs/hypervotes-this-month-and-round-numbers.html)
- [HyperVotes: More examples](https://hyperscript.monoforge.net/Docs/hypervotes-more-examples.html)

## Ready-made scripts

Complete, working scripts to read as examples or to use as they are.

- [ChatPrefixes.hs](https://hyperscript.monoforge.net/scripts/chatprefixes.html)
- [DeathMessages.hs](https://hyperscript.monoforge.net/scripts/deathmessages.html)
- [JoinMessages.hs](https://hyperscript.monoforge.net/scripts/joinmessages.html)
- [Quests.hs](https://hyperscript.monoforge.net/scripts/quests.html)
- [Ranks.hs](https://hyperscript.monoforge.net/scripts/ranks.html)
- [SetupServer.hs](https://hyperscript.monoforge.net/scripts/setupserver.html)
- [Sidebar.hs](https://hyperscript.monoforge.net/scripts/sidebar.html)
- [TabList.hs](https://hyperscript.monoforge.net/scripts/tablist.html)
- [WorldsManager.hs](https://hyperscript.monoforge.net/scripts/worldsmanager.html)

## Addons

Separate plugins that add words to the language. Their syntax only works where the addon is installed.

- HyperBedrock (https://hyperscript.monoforge.net/addons.html)
- HyperCitizens (https://hyperscript.monoforge.net/addons.html)
- HyperEconomy (https://hyperscript.monoforge.net/addons.html)
- HyperEdit (https://hyperscript.monoforge.net/addons.html)
- HyperGrim (https://hyperscript.monoforge.net/addons.html)
- HyperGuard (https://hyperscript.monoforge.net/addons.html)
- HyperHolograms (https://hyperscript.monoforge.net/addons.html)
- HyperLog (https://hyperscript.monoforge.net/addons.html)
- HyperMobs (https://hyperscript.monoforge.net/addons.html)
- HyperModels (https://hyperscript.monoforge.net/addons.html)
- HyperPackets (https://hyperscript.monoforge.net/addons.html)
- HyperPerms (https://hyperscript.monoforge.net/addons.html)
- HyperPlots (https://hyperscript.monoforge.net/addons.html)
- HyperSkin (https://hyperscript.monoforge.net/addons.html)
- HyperVelocity (https://hyperscript.monoforge.net/addons.html)
- HyperVoice (https://hyperscript.monoforge.net/addons.html)
- HyperVotes (https://hyperscript.monoforge.net/addons.html)

## Cheat sheet


The most-used syntax on one page. Everything here, and everything else, is on the [Docs](Docs/)
page with examples.

#### A script file

```
## Notes about the script
options:
    prefix: "&8[&6Shop&8] "

command /hello <target:player>:
    permission: "hello.use"
    cooldown: 10 seconds
    trigger:
        send "{@prefix}&aHello!" to arg.1

on player join:
    send "&aWelcome, %player.name%!"

every 5 minutes:
    broadcast "&7Remember to vote!"

function double({_n}):
    return {_n} * 2
```

#### Variables and values

| Write | Meaning |
|---|---|
| `{name}` | Saved, shared by every script |
| `{%player%.name}` | Saved, each player's own |
| `{_name}` | For this run only |
| `{@name}` | A setting from `options:` |
| `"%player.name% has %{%player%.coins}%"` | Values inside text |
| `set`, `add ... to`, `subtract ... from`, `delete` | Change a variable |
| `[1, 2, 3]`, `append x to`, `size of`, `item 1 of` | Lists |
| `5 minutes`, `now`, `player's location`, `1 diamond sword` | Durations, dates, places, items |

#### Deciding and repeating

| Write | Meaning |
|---|---|
| `if ...:` / `else if ...:` / `else:` | Choose |
| `unless ...:` | The opposite of `if` |
| `switch arg.1:` with `case "a":` and `default:` | One of many |
| `randomly:` with `70%:`, `30%:` | One of several, by chance |
| `loop 5 times:` / `for each {_x} in <list>:` / `while ...:` | Repeat; `else:` under a loop runs when it never went round |
| `loop from 1 to 10:` / `loop from 10 to 0 by 2:` / `loop {_list}:` | Count, or go through a list |
| `loop-value` / `loop-index` | What the loop is on, and which round it is; in a loop inside a loop `loop-value-1`, `loop-value-2` |
| `loop all players:` with `loop-player` (or `loop player`) | Everyone online |
| `loop all players with permission "staff":` / `loop {_list} where ...:` | Some of them only |
| `loop blocks within 3 blocks of player:` | Every block around a place |
| `break` / `continue` / `stop` | Leave a loop, skip a round, end the trigger |
| `stop if ...` / `continue if ...` / `break unless ...` | The same, on one line with its condition |
| `after 5 seconds:` | Run a block later and carry on now |
| `wait 5 seconds` / `wait until ...` | Pause |
| `try:` / `on error:` | Deal with a failure |

#### Common conditions

| Write | Meaning |
|---|---|
| `==` `!=` `<` `>` `is` `is not` | Compare |
| `is set` / `is not set` | Has a value |
| `contains`, `starts with`, `is in <list>` | Text and lists |
| `player has permission "x"` | Permissions |
| `player has 5 diamond` | Inventory |
| `player is sneaking`, `is op`, `is online` | Player state |
| `chance of 25%` | At random |
| `and`, `or`, `not` | Combine |

#### Common effects

| Write | Meaning |
|---|---|
| `send "..." [to <who>]` / `broadcast "..."` | Chat |
| `send title "..."`, `send action bar "..."` | On screen |
| `give 1 diamond to player` / `remove 1 diamond from player` | Items |
| `teleport player to <location>` | Move |
| `heal player`, `feed player`, `kill player` | Health |
| `apply speed 2 to player for 30 seconds` | Potion effects |
| `set gamemode of player to creative` | Game mode |
| `play sound "..." at player's location` | Sound |
| `execute console command "..."` | Any other command |
| `cancel event` | Stop what the event is about |
| `open gui with title "..." for player:` with `slot 1 is "diamond":` | Menus |