Configuration

Settings live in plugins/HyperScript/config.yml. Changes need a server restart.

send-analytics: true
language: english         # english | french | spanish | portuguese | german
combat-time: "15s"        # how long "player is in combat" holds after a hit
afk-time: "5m"            # how long doing nothing makes "player is afk"
money-format: "$%amount%" # how money(...) writes an amount
limits:                   # the most HyperScript keeps going by itself; see Limits below
  particle-shapes: 200
  particles-a-tick: 3000
  slow-down-below-tps: 15
  floating-texts: 300
  temporary-blocks: 5000
  structure-blocks: 250000
word-filter: censor       # censor | block: what happens to chat with a blocked word in it
mute-commands: [msg, tell, w, whisper, me, r, reply, say]   # what a muted player cannot use
hot-reloading: true

storage:
  type: json          # json | csv | sqlite | h2 | mysql
  autosave: "5m"
  shared-variables: false   # {shared.name} is the same on every server that uses the database
  shared-refresh: "2s"
  sqlite:
    file: "data.db"
  csv:
    file: "data.csv"
  h2:
    file: "data-h2"
  mysql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: ""
    use-ssl: false

backups:
  enabled: true
  interval: "1h"
  keep: 24

update-check: true
auto-update: false        # true downloads newer versions by itself; they take effect at the next restart
log-script-errors: true
notify-script-errors: true
sidebar-numbers: false    # true shows the numbers beside the lines of a sidebar
loop-limit: 100000
player-error-message: "&cSomething went wrong with that. The staff have been told."

files:
  enabled: true

web:
  enabled: true
  allow-private-addresses: false
  server:               # the plugin's own web address, for 'on web request'
    enabled: false
    port: 8765
    bind: "0.0.0.0"
    token: ""

discord:
  webhooks: {}
  bot:
    enabled: false
    token: ""
    guild-id: ""
    read-messages: false

options-file: false       # every script's options: in one options.yml
update-project: hyperscript

Durations are a number and a unit: 30s, 5m, 1h, 1d.

loop-limit is how often a loop <n> times may be asked to go round, and how often a while may go round without waiting, before the script is stopped as runaway: from 1,000 to 50,000,000. update-project is the name /hyperscript update looks for on Modrinth. language is the language scripts are written in; see Scripts in another language.

log-script-errors writes a line to the console when a script fails while it is running, and notify-script-errors also tells players with hyperscript.admin in chat, at most once a minute for the same message. Mistakes found when a script loads are always reported.

Limits

Some lines keep something going after they have run: a particle shape that stays, text in front of a player, a block that is put back later. HyperScript does the keeping, every tick, and limits: in config.yml says how much of it there may be, so that a script written with too free a hand cannot slow the server down.

Setting	Unless changed	What happens beyond it
`particle-shapes`	200	A new shape that stays takes the place of the oldest
`particles-a-tick`	3000	Shapes wait for their next turn, so they are drawn less often; the console is told, at most once every five minutes
`slow-down-below-tps`	15	Not a limit but a brake: while the server manages fewer ticks a second than this, shapes that stay are drawn half as often
`floating-texts`	300	A new one takes the place of the oldest
`temporary-blocks`	5000	`set block ... for` does nothing until some have been put back

/hyperscript timings shows how much of each there is right now and how many milliseconds of a tick it takes. A tick has fifty; anything of HyperScript's taking more than two is shown yellow, more than five red.

Update check

With update-check: true, HyperScript asks its website once, each time the server starts, which version is the newest (https://hyperscript.monoforge.net/api/latestversion). If a newer one exists it says nothing in the console; instead, operators and players with hyperscript.admin are told when they join, and /hyperscript status shows it.

Nothing is downloaded or installed. The request carries only the version of the plugin.
It runs in the background and gives up after five seconds, so it never delays a start.
If the website cannot be reached, one line is written to the log: Error: couldn't fetch newest version on startup, and the server carries on as usual.
Set update-check: false to switch it off.
/hyperscript version shows the version the server runs and asks the website again there and then, whether or not the check at startup is on. It answers with the newer version, with "You are on the newest version", or with why the website could not be reached.

Usage numbers

With send-analytics: true (the default) the plugin tells the HyperScript website that a server is running it: once at start, every half minute, a moment after players join or leave, and once at stop. It sends:

a random id made for the server, which says nothing about it;
the versions of HyperScript, Minecraft, the server software and Java;
how many players are online and how many fit;
how many scripts are loaded, how many commands, events and timers they make, and how many scripts did not load;
the names of installed HyperScript addons;
a few numbers about the server itself: how long it has been up, its ticks a second, how much memory Java may use, how many processor cores there are, the kind of operating system (Windows, Linux or Mac), how many worlds and plugins are loaded, whether it is in online mode, and the language scripts are read in.

It never sends player names, addresses, script contents, world names or the names of other plugins. send-analytics: false sends nothing at all. While it is on, the console says so at every start.

Hot reloading

With hot-reloading: true, HyperScript watches plugins/HyperScript/scripts/. Saving, creating or deleting a .hs file re-parses the scripts about half a second later, on the server thread, exactly as /hyperscript reload would. The console reports the result:

[HyperScript] Scripts changed on disk. Loaded 2 script(s): 9 command(s), 6 event handler(s)

If the saved file has an error, it is reported and that file's commands and handlers are unavailable until the next save that fixes it. The other files are unaffected.
Variables are not touched by a reload. GUIs that are already open keep working with the code they were opened with.
Subfolders are watched too, including folders made while the server runs.

Storage and fallback

Variables are always held in memory while the server runs. storage.type decides where they are saved:

`storage.type`	Saved to	Read from	Set up
`json` (default)	`data.json`	`data.json`	Nothing to do
`csv`	`data.csv` and `data.json`	`data.csv`	Nothing to do: the file is made by itself. A spreadsheet opens it
`sqlite`	The SQLite file `data.db` and `data.json`	The SQLite file	Nothing to do: the database is made by itself
`h2`	The H2 file `data-h2.mv.db` and `data.json`	The H2 file	Nothing to do on Minecraft 1.17 and newer: the server downloads H2 the first time, and the database is made by itself
`mysql`	The MySQL/MariaDB server and `data.json`	The MySQL server	A server and a database of yours, given under `storage.mysql`

Which is fastest? For scripts, none: while the server runs every variable is in memory, and a script never waits for a file or a database. The kinds differ in what you can open the data with (csv in a spreadsheet, sqlite and h2 with a database tool, mysql from several servers and from a website), and that is what to choose by. json stays the default because it needs nothing and is written in every mode anyway.

data.csv has a row for each variable: whose it is (global, or a player's id), its name, and its value the way data.json writes it. Change it by hand only while the server is stopped; what you change is read when it starts.

data.json is written in every mode, which is what makes the fallback work:

The database is unreachable at startup, or disappears later. HyperScript logs a warning and carries on using data.json. Nothing is lost and scripts do not notice.
The database comes back. At the next autosave HyperScript reconnects and copies across every player and global scope that changed during the outage, then resumes normal operation. This works across restarts too: the list of scopes still to copy is kept in data.json.
A database is switched on for the first time. If its table is empty, the contents of data.json are copied into it, so moving from JSON to a database needs no migration step.

/hyperscript status shows which store is active right now.

Things to know:

Changes are written when a player quits, every storage.autosave, and on shutdown. A server crash can lose up to one autosave interval of changes.
The database table is hyperscript_variables (scope, name, value), one row per variable, with the value stored as JSON text. HyperScript uses the MySQL and SQLite drivers bundled with the server; H2 is fetched by the server itself (it is named in the plugin's libraries).
With MySQL, a value can be up to 16 MB (a table made by an older version is widened by itself), text is kept as utf8mb4, and MySQL 8 servers that refuse a login without SSL are logged into all the same.
The fallback assumes one server per database. If several servers share a MySQL database, each one's data.json only knows about its own players, so a fallback on one server can serve data that another server has since changed.
If data.json cannot be parsed at startup, HyperScript disables itself rather than start empty and overwrite the file. Restore a copy from Backups/ or fix the file, then restart.

Backups

With backups.enabled: true, HyperScript saves all pending changes and then copies data.json to plugins/HyperScript/Backups/data-<date>_<time>.json every backups.interval. Only the newest backups.keep files are kept (0 keeps them all). To restore, stop the server, replace data.json with a backup, and start it again.

Backups are copies of data.json, so they are useful in every storage mode; with a database they are a second, independent copy. A folder written backups by an older version is renamed to Backups, with what is in it.