Script updates and the editor
Mass, network and category updates, and the browser script editor.
Mass updates #
Mass updates (/mass-updates, permission network.deploy). One zip for the whole network, with a folder for each part: core, network, pit, survival, lobby, tag and so on. Publish it and each server installs only the folders its category takes, replacing scripts/<folder>/ and keeping the old one as -<folder>.old-…. Which folders a category or single server takes is set on the same page, or on the category's or server's edit page (permission network.folders): a category starts with core, type more names with commas between them, none for nothing, and leave a server blank to follow its category. Adding a folder installs it within a minute, with no new upload. A server only installs folders it doesn't have at this version, and a folder that isn't in the zip is left alone, so a zip with only core updates only core. Taking a folder off the list doesn't delete it from the server.
A server looks only at the newest live zip that has a folder it takes, so a server that was off for two zips gets the second one's folders only. Leave updater and addons out of the zip: they're refused, because the updater can't replace itself and addons belongs to the Script editor. A broken core stops a server talking to the panel, and that has to be fixed by hand from scripts/-core.old-…, so publish a new core to one server first. To build the zip, in PowerShell from skript/:
Compress-Archive -Path core,network,pit,lobby,survival,tag -DestinationPath update.zip -Force
Network updates #
Network updates (/network-updates, permission network.deploy). Upload a .zip (or loose .sk files) and send it to every server, or tick categories and/or single servers. Servers download it, check its SHA-256, unpack it safely into scripts/network/ (keeping the previous version as -network.old), reload, and report back (see Update results). Withdrawing a version makes servers go back to the newest one still live for them.
Category updates #
Category updates (/category-updates, same permission). The same, for a game mode's own scripts (Pit's levels and shop, survival's gameplay...): upload a zip, name the folder it goes into (scripts/<folder>/, e.g. pit or survival; network, addons and core are refused) and tick the categories and/or servers that get it. The zip replaces the whole folder, with the old one kept as -<folder>.old-…, so include every script that belongs there, and use the folder the scripts are in now (a new folder name loads next to the old one). Each server installs the newest live version that includes it: a version sent to one server (a hotfix or a test) is used there until a newer one for its category comes out, and withdrawing it sends the server back. /networkupdate shows what's installed; the updater checks network, then the category update, then addons.
The tag folder is one set: Tag.sk calls TagMap.sk (maps built from schematics at the map spawn point) and TagBoosters.sk (boosters from [booster] signs), so always send all of them together, with TagSkills.sk. The scripts read schematic maps, booster presets and their signs from the panel, so update the panel (and run its migrations) first; a Tag server on older scripts ignores them.
Update results #
Every server reports how each mass, network, category and Script editor update went, and the panel shows it per server: on the Mass, Network and Category updates pages (the Servers table, and Results under each version, e.g. "5 of 6 succeeded · 1 failed"), and on the Projects page for each category's Script editor version. A result is one of:
- Installed: in, with how many files (and, for a mass update, which folders).
- Failed: with the reason the server gave (download failed, checksum mismatch, unsafe path, a locked folder...). A failed version is tried again after 10 minutes, and a later success replaces the failure.
- Installing: the server has started downloading and unpacking it.
- Waiting: no answer yet.
- Timed out: no result within 15 minutes of the update going out, or of the server starting it (
App\Support\UpdateResults::TIMEOUT_MINUTES); it says when the server is offline. A late report still replaces it.
Only servers the version is still meant for are counted, plus any that reported: once a newer version replaces it, servers that never got to it drop out. updater/Updater.sk sends the results (POST /server/network-package/{id}/started, then .../installed with {ok, message}; App\Http\Controllers\Api\V1\NetworkPackageApiController). Installed and Failed work with any copy of Updater.sk; Installing needs the current one copied to each server by hand. "Installed" means the files are in and scripts were reloaded: a script that then fails to load isn't caught here, so still check the console after a big update.
Script editor #
Script editor (Developers → Projects). Colours Skript as you type, and marks problems on their lines about 1.5 seconds after you stop typing, using the same linter that checks publishing. Pick a theme (Dark+, Monokai, Dracula, Nord, High contrast, Light or Solarized light) and text size; until you pick one it matches the panel (Dark+ in dark mode, Light in light mode). Suggestions pop up as you type (Tab or Enter takes one, Esc closes them, Ctrl+Space asks for them): the network functions in the reference panel and the functions in this project's files (with their parameters to fill in, Tab moving to the next), the variables used in the open file, and common Skript lines that fit where you are, such as on join, command, function and every at the left edge and if, loop all players, set, send or wait inside a block, each written out with its indent. What the file already uses most comes first. (App\Support\SkriptCompletions.) Make it bigger by dragging the bar under the code, hiding the side panels, or going full screen (Esc leaves). These choices are remembered per browser. Ctrl+S saves, Ctrl+F finds, Ctrl+Z undoes, Ctrl+/ comments lines out. It uses CodeMirror, loaded only on this page, so run npm install and npm run build when deploying.
Linting before publishing #
Every script is checked by the panel's Skript linter (App\Services\SkriptLinter) before it can reach a server, so a mistake that would stop it loading is caught on the panel instead of breaking a live server.
- Mass, network and category updates: every
.skfile in the upload is linted (SkriptLinter::lintZip), except files and folders whose name starts with-, which Skript skips. An error refuses the upload: nothing is stored or sent, and the message lists the file, line and problem (the first 8, then "and N more"). Warnings never block; the success message says how many there are. If you're sure the linter is wrong (it knows the common mistakes, not every Skript syntax), tick Publish anyway if the linter finds errors; the audit log records the upload with itslint_errorsandlint_warnings. - Script editor: saving always stores your file, but the category is linted first and, with any error in any enabled project, nothing is sent to the servers until it's fixed ("Saved, but not sent to servers"). Publish now and Prioritize changes are held back the same way. Custom Tag skills and quest scripts are linted when they're built, before they join the addons package.
What blocks and what doesn't: errors are things Skript refuses to load (unclosed text or %expressions%, bad indentation, empty sections, unknown top-level lines, syntax Pit's Skript 2.6.5 or Paper's 2.17 can't read, a ? b next to other arguments in a function call, names that clash with the network scripts). A server with a refused file loses everything in it, so those block. Warnings (a variable name starting with %...%, colored text going into Java, a risky console command) still load, so they only warn.
Script load results #
The linter can't know everything, so each server also tells the panel what Skript itself said when it loaded its scripts. After every load that includes updater/Updater.sk (server start, an update's reload, /sk reload all or /sk reload scripts, /networkupdate clean), the updater reads the Skript ERROR and WARN lines (with the indented lines under each) written to logs/latest.log since that reload began, and sends them to POST /server/script-load (App\Http\Controllers\Api\V1\ScriptLoadApiController). App\Services\SkriptLoadLog reads both layouts: Skript 2.17's Line 3: (addons/koth/main.sk) block and Skript 2.6.5's one-line message (file.sk, line 3: code'). Each server keeps only its last load (script_load_reports), so a clean reload clears old errors.
They show:
- In the Script editor, under the code: "On the servers: N error(s)… when main.sk last loaded", with each line, Skript's message, the code and which servers had it. Files with load errors get a red count in the file list.
- On the Mass, Network and Category updates pages: a Last script load column in the Servers table (No errors, or the error count with each file and line).
The updater marks where the log ends (Updater_MarkLoad) just before every reload it starts and when someone types /sk reload all or scripts, then reports 3 seconds after it has loaded again (Updater_ReportLoad, read in the background). At most 2 MB of log and 400 Skript lines are sent per load. It reads the log file like network/Panel/Console.sk does, so it works on 1.8 (Skript 2.6.5) and Paper 26 (Skript 2.17). A reload of a single file that isn't the updater isn't reported.
Projects / script editor #
Projects / script editor (Developers → Projects; permissions scripts.edit and scripts.publish). Write Skript in the browser and the system does the rest:
- Developers → Projects → Create: give it a name (e.g. "Random events") and pick the category (e.g. Pit). It becomes
plugins/Skript/scripts/addons/random_events/on that category's servers, and starts with a workingmain.sk. - Write your code (add more files or sub-folders if you like), using the hooks listed next to the editor to talk to the network.
- Save (Ctrl+S). The category is checked; if nothing would break, the change is queued and goes live on every server in the category within a minute. Saves are batched once a minute (the
publish-addonstask), so a burst of saves means one reload, not ten. If something would break, it isn't sent, the editor says why, and the Projects page shows it as Held back until it's fixed. - Prioritize changes (the switch next to Save, needs
scripts.publish): the save is published straight away and every server in the category is told to install it now (a few seconds), instead of waiting up to a minute. Publish now on the Projects page does the same for a whole category.
The editor has line numbers, Tab / Shift+Tab, auto-indent after :, Ctrl+S, Check (without saving) and a project log. Each project has an Enabled tick box (on the Projects list, at the top of the editor, and when creating one; tick it off to write a project before it goes live). Unticking it, or deleting the project, removes its folder from every server in the category within a minute and reloads their scripts. This works even while a mistake in another project holds the category back: the last published version goes out again without the removed project. Only addons/ is touched; /networkupdate shows the installed addons version.
- Validation runs on Check, on every save and before publishing; errors block publishing, warnings don't. It catches: indentation that doesn't match, tabs and spaces mixed in one block, empty sections (a
:with nothing indented under it, including option values ending in:), unknown top-level lines, unclosed text, unclosed%expressions%(use%%), a single#inside text (use##), unbalanced brackets,loop-value-2.method(),MyFunction(uuid of player, …)without brackets,on right click on block:(newer Skript refuses it: useon right click:and checkclicked block),wait (…) tickswith a calculation inside (make the timespan first), areturnafter a Skriptteleportorwaitin a function that returns a value (Paper countsteleportas a delay; use{_p}.teleport({_to}); waits inside arun … later:orcreate new sectionblock don't count), a bareloop-numberinside twoloop … times:loops (use a counter), and function or command names that clash with the network scripts or another project in the category. Warnings: variable names starting with an expression, and console commands likeoporstop. It doesn't know every Skript syntax, so a clean check means "no known problems", not "guaranteed to load". - Hooks (
network/Panel/Hooks.sk, listed next to the editor; click one to insert it):Net_DataGet/Set/Add(per-player values saved with their game mode save),Net_Stat,Net_Quest(custom quest and badge objectives),Net_Money,Net_MoneyGive,Net_MoneyTake,Net_Tr,Net_Language,Net_Setting,Net_InCombat,Net_Badge,Net_Crew,Net_Group,Net_Server,Net_Rule, the mana hooks (Net_ManaOn,Net_Mana,Net_ManaMax,Net_ManaRegen,Net_ManaHas,Net_ManaUse,Net_ManaGive,Net_ManaSet,Net_ManaBonus,Net_ManaBonusRemove,Net_ManaListen; see gameplay.md → Mana),Net_CustomMessage,Net_CustomMessageText,Net_Link,Net_Notify(message a player on any server) andNet_Log(writes to the project's log, shown under the editor). Projects can also react to events (a dungeon cleared, a Tag round ending, a level up...) by definingOn_...functions; every function and event, with its arguments and an example, is in Script hooks reference in skript.md, linked from the editor.
Live patch messages #
While a server installs a mass, network, category or Script editor update, updater/Updater.sk tells everyone on it in chat: when it starts, once it's in (after scripts reload, with the update's {version}), and if it failed. Developers > Live patch messages (network.deploy) turns these on or off and rewords each one per language. An empty English box uses the default (App\Support\LivePatch::MESSAGES), and an empty box in another language uses the English text. Servers get the texts with their config, so they can still announce while the panel is busy or unreachable.
Inventories are locked while a server updates (and on any /sk reload all): everyone's open inventory, chest or menu is closed when the update starts and again right before scripts reload, and until they're back nobody can open an inventory, click or drag items (a menu's own click handlers are gone mid-reload, so items could otherwise be taken out of it). They unlock as soon as the scripts have loaded, if the update fails, or after 5 minutes at most. This works even with the messages turned off.
updater/ is never touched by updates, so copy the new Updater.sk to each server by hand once. Without it, updates install quietly as before.