Skript Extension

Skript (.sk) language support for VS Code: syntax highlighting, a snippet library, workspace-aware IntelliSense for {variables}, {@options} and functions, navigation, and diagnostics for the mistakes Skript rejects at load time.

Features

Syntax highlighting — full TextMate grammar for Skript: on / at / every event headers, commands and their sub-properties, functions with :: type return, options: / aliases: / variables: sections and their entries, local/global/list variables, options, built-in values (loop-value, arg-1, event-slot, player, attacker …), ending words (stop, exit loop, cancel event, return), function calls, #d / #dp / #dr doc-comments, and inline Minecraft &-colour formatting (&a&lText is green and bold, &#RRGGBB / <##RRGGBB> hex, %expr% interpolation). Run npm run test:grammar for the scope assertions in test/grammar/.

Skript Tools Dark theme — a Dark+ derived colour theme that renders every Skript scope, including each & colour code in its real Minecraft colour. Pick it with Preferences: Color Theme → Skript Tools Dark. See Colours on other themes for using another theme.

Snippets — common effects, control flow, event handlers, conditions, and PrimalMines patterns (talking lock, stash fallback, giveSlayerItem, rollDrop else-if chain, updateNPCVisibility, doc-comment block). Contributed from snippets/skript.json, so they show up in the completion list with the snippet icon and in Insert Snippet.

Typing helpers — Enter after a line ending in : indents (but not after send "a:", where the colon is inside a string), Enter after stop / exit loop / cancel event / return … outdents, ' auto-closes outside strings, and #!FOLD … #!UNFOLD comment markers fold in addition to indentation folding.

Workspace index — every .sk file in the workspace is indexed once on startup and then re-parsed one file at a time on change, create, delete or save (debounced). Files whose name starts with - are indexed too, but Skript does not load them, so their entries are marked (disabled) and sort last (turn this off with skript.scan.includeDisabledFiles). The "Skript Tools" output channel logs each scan.

Variable IntelliSense — type { to complete any variable seen in the workspace, distinguishing local (_var), global, list (var::*), and option (@var) variables; {_ shows only locals and {@ only options. Go to Definition on a {variable} jumps to its first write (set / add / delete …), Find All References lists every occurrence (locals stay inside the current file), and hover shows the kind, read/write counts and the files it appears in. {@option} resolves to the entry in the same file's options: block; hover shows its value. Nested variables such as {slayer::%{_uuid}%::level} resolve to the outer variable or the inner {_uuid} depending on where the cursor sits.

Function IntelliSense — completion for every function name(...) in the workspace (inserted with one tab stop per parameter), hover with the signature and doc comments, signature help after name( and on each ,, Go to Definition and Find All References. Everything reads the live index, so a function edited in another file is picked up as soon as it is re-indexed. See Doc comments for how to document a function.

Diagnostics — indentation mistakes, wait inside on inventory click, undefined {@options}, never-set locals and unknown function calls show up in the Problems panel with a code each, so any rule can be switched off. See Diagnostics.

Reindent on save — format-on-save is enabled by default for .sk files only. Skript has no closing braces, so nesting is the indentation and there is nothing else to derive it from. The formatter therefore fixes exactly the things Skript would reject at load time, and leaves everything else alone:

• a line indented deeper than the previous line when that line did not end in : (snapped back to its sibling level);
• a line at the same depth as the : line above it (pulled into that section);
• a dedent to a depth no enclosing section uses (snapped to the nearest valid depth);
• an else / else if sitting inside the body of its own if (moved up to line up with it);
• an on …:, command /…:, function …:, every …:, options: header that is not at column 0.

A correction is carried through the whole block that follows it, so a chunk pasted at the wrong depth is shifted as one unit and keeps its internal nesting. Strings and comments are respected (send "a:" and # todo: are not section openers; <#F05532> inside a string is not a comment). Mixed tabs/spaces are normalized to whatever the editor is set to, and trailing whitespace is stripped. Valid code never has its nesting changed. Run npm test for the test-suite.

Enter doesn't hijack autocomplete — editor.acceptSuggestionOnEnter is set to off for .sk files only, so pressing Enter always just makes a new line. Only Tab or a click accepts a suggestion. This is scoped to Skript files; it doesn't touch the setting for any other language.

Doc comments

A run of # comments directly above a function line documents it. Plain # lines become the description; the tagged forms are:

#d Rolls a drop chance, boosted by the Plunder enchant on the player's tool.
#dp p the player who killed the boss
#dp chance percent chance before Plunder is applied
#dr true when the drop should be given
#dex if rollDrop({_a}, 10):
function rollDrop(p: player, chance: number) :: boolean:
    ...

Hover, completion and signature help show the description, a parameter table, the return type, the example and the defining file.

Diagnostics

Problems are reported with source skript and one of these codes:

Diagnostics run when a Skript file is opened, 400 ms after it changes, and whenever the workspace index updates (so unknown-function follows definitions in other files). To switch off one rule, set its code to false:

"skript.diagnostics.rules": {
  "local-never-set": false
}

Set skript.diagnostics.enabled to false to turn all of them off. Functions that come from an addon or another server go in skript.diagnostics.knownFunctions.

Settings

The extension also sets two editor defaults for .sk files only: editor.formatOnSave: true and editor.acceptSuggestionOnEnter: "off".

Colours on other themes

Stock VS Code themes only colour the generic part of a scope (variable, keyword, string …), so on Dark+, Monokai, etc. Skript still looks fine but the Skript-specific distinctions are lost: a {_local} and a {global} look the same, and &a text is plain string colour. To colour them on any theme, add rules to editor.tokenColorCustomizations in your settings:

"editor.tokenColorCustomizations": {
  "textMateRules": [
    { "scope": "variable.other.local.skript",         "settings": { "foreground": "#9CDCFE" } },
    { "scope": "variable.other.global.skript",        "settings": { "foreground": "#4FC1FF" } },
    { "scope": "constant.other.option.skript",        "settings": { "foreground": "#D7BA7D" } },
    { "scope": "variable.language.skript",            "settings": { "foreground": "#569CD6", "fontStyle": "italic" } },
    { "scope": "keyword.control.flow.end.skript",     "settings": { "foreground": "#C586C0", "fontStyle": "bold" } },
    { "scope": "keyword.control.event.skript",        "settings": { "foreground": "#C586C0" } },
    { "scope": "entity.name.type.event.skript",       "settings": { "foreground": "#4EC9B0", "fontStyle": "bold" } },
    { "scope": "entity.name.function.command.skript", "settings": { "foreground": "#DCDCAA", "fontStyle": "bold" } },
    { "scope": "entity.name.function.call.skript",    "settings": { "foreground": "#DCDCAA" } },
    { "scope": "support.type.property.skript",        "settings": { "foreground": "#569CD6", "fontStyle": "italic" } },
    { "scope": "variable.parameter.skript",           "settings": { "foreground": "#9CDCFE", "fontStyle": "italic" } },
    { "scope": "constant.character.escape.hex.skript","settings": { "foreground": "#D7BA7D", "fontStyle": "bold" } },
    { "scope": "markup.inline.mc.green.skript",       "settings": { "foreground": "#55FF55" } },
    { "scope": "markup.bold.mc.skript",               "settings": { "fontStyle": "bold" } }
  ]
}

All Skript scopes, for reference:

Install

1. Download the .vsix from a release, or build one yourself (see below).
2. In VS Code: Extensions panel → ... menu → Install from VSIX... → select the file.

Build from source

npm install -g @vscode/vsce
vsce package --no-dependencies --allow-missing-repository

Structure

package.json                     manifest: language, grammar, snippets, theme, settings, config defaults
src/index.js                     activate / deactivate: wires the modules below
src/scanner.js                   the workspace index (per-file entries with positions, onDidUpdate)
src/parser.js                    text -> variables / options / functions / calls (pure; test/parser.test.js)
src/settings.js                  typed getters for every skript.* setting
src/formatter.js                 reindent logic + formatter registration (pure core; test/formatter.test.js)
src/diagnostics.js               the rules above + quick fix (pure core; test/diagnostics.test.js)
src/log.js                       the "Skript Tools" output channel
src/providers/variables.js       {…} completion
src/providers/functions.js       function completion, hover, signature help
src/providers/navigation.js      go-to-definition, references and hover for functions, variables, options
language-configuration.json      comments, brackets, indent / onEnter rules, folding markers
syntaxes/skript.tmLanguage.json  TextMate grammar (tested by test/grammar/*.test.sk, npm run test:grammar)
snippets/skript.json             snippet contribution
themes/skript-tools-dark-color-theme.json  "Skript Tools Dark" colour theme
test/                            node unit tests (npm test), grammar tests, fixtures, real-editor suite (npm run test:editor)
icons/skript.png                 file icon for .sk files

License

MIT — see LICENSE.