Refined-DenizenScript
Syntax highlighting, completion, hover and diagnostics for Denizen scripts in Visual Studio Code.
A fork of DenizenVSCode by McMonkey and the DenizenTeam, maintained independently with extra features and fixes.
Install
In VS Code press Ctrl+Shift+X, search for refined DenizenScript (humusus.refined-denizenscript) and click Install. Updates arrive automatically through the Marketplace.
Offline: download the .vsix from the releases page, then Ctrl+Shift+X → ··· menu → Install from VSIX… → pick the file.
File and folder icons
A DenizenScript Icons file icon theme, with distinct icons for .dsc files and for 28 recognised Denizen folder names — handlers, data, dialogs, utils, worlds, commands, entities, tasks, animations, extensions and more, including their singular/plural spellings.
Enable it with Ctrl+Shift+P → Preferences: File Icon Theme → DenizenScript Icons.
Mute diagnostics
Silence warnings you don't want without touching the script:
Refined DenizenScript: Mute Diagnostics in Selection — select a range and mute everything reported inside it.
Refined DenizenScript: Unmute Diagnostics — undo it.
##ignorewarning <key> at the top of a file silences one specific check for that whole file.
Escaped symbol helper
- Select text and press / to convert Denizen special characters into escape codes.
- Type a delimited value like
/[]/ to turn it into <&lb><&rb>.
- Press Backspace right after a conversion to undo it back to the original
/…/ text.
Automatic tag separators
Pressing Space directly inside <map[…]> inserts ;, and inside <list[…]> inserts |. It fires nowhere else, a quoted value inside the parameters suppresses it, one Backspace turns the separator back into a plain space, and denizenscript.autoInsertTagSeparators switches it off.
DenizenM support
Completion and hover documentation for DenizenM — escape tags, base tags, dot tags, commands, command arguments and events. DenizenM syntax is also excluded from diagnostics, so the base Denizen checker doesn't flag it as invalid.
Denizen-Utilities support
dialog snippet for scaffolding a dialog container.
- Completion for
<context.KEY> values, read from inputs.*.key in the surrounding dialog container.
- Dialog containers are excluded from the diagnostics that don't apply to them.
→ Denizen-Utilities
Workspace completion
- Local
- define names offered inside <[...]>.
- Player and server flags, kept in separate indexes so they never mix in suggestions.
- Indexed across the whole open folder, not just the current file (
denizenscript.behaviors.track_full_workspace).
Completion in the places that used to offer nothing
Each of these was an empty suggestion list before:
<entry[123].…> — the sub-tags of the command that wrote the save:, narrowed to that command. Entry tags are documented per command, so they are absent from the tag index entirely.
- Event lines under a world container's
events: key, with the on /after prefix handled and <block>-style placeholders turned into tabstops.
- Data actions after
- define name: and - flag <object> name: — ++, --, +:, ->:, |: and the rest, described from the meta.
- Container types on a container's
type: line, and your entity scripts beside the vanilla types on entity_type:.
- EntityTag mechanisms as keys under an entity container's
mechanisms:.
- Event switch values —
bukkit_priority:, cancelled: and ignorecancelled:. Only these three: the rest take flag names, permissions, areas and numbers, where there is no list to offer.
- Implicit definitions —
<[value]>, <[loop_index]>, your own as:/key: names inside a loop, and <[filter_value]> / <[parse_value]> inside the tag that provides them.
<map[…]> keys and mechanism names in - adjust, read from the meta rather than a hand-kept list.
as[…] — object type names in the short form, which is what the 23 deprecated as_* tags point at.
filter[…], parse[…], sort_by_value[…] and friends — the tag path applied to each entry, written without its <>.
<custom_color_name> — the colour names from your own Denizen colour map.
- playsound sound_category: — the ten Bukkit sound categories. The meta documents the argument but links out to a javadoc rather than listing the values, so these ship with the extension.
Enum argument values also complete case-insensitively — sound_category:MAST and give QUAR both work, where an uppercase prefix used to match nothing at all.
Quick Fixes
Lightbulb actions, offered only where the checker already reports something and its message already names the edit:
- Add a missing
: or - to a line that needs one, including - if true == false with no trailing colon.
- Rewrite a deprecated tag —
as_entity → as[entity]. Offered for the 24 tags whose deprecation names a single, unambiguous replacement, and deliberately withheld for the rest rather than guessing at a rewrite that would lose your arguments.
Async-safety checks
Inside a DenizenM - async: block, a command or tag that isn't safe off the main thread is reported. It still runs — Denizen hands it back to the main thread — but the async queue then waits on it, which is usually the opposite of why the block was written.
async_unsafe_command — - teleport inside async. Commands Denizen can defer to the main thread without waiting (compass, fakeequip, actionbar) count as safe, so they stay quiet.
async_unsafe_tag — <player.health> inside async. <player.name> is fine: the safe list is per object type, and name is on it.
Reported only when a tag resolves to exactly one documented type. <[ent].location> matches several types at once and the real runtime type is precisely what the checker cannot know, so it says nothing rather than guessing.
The lists are transcribed from DenizenM's own machine-readable @asyncsave / @asynccmd markings — the meta has no field for thread-safety. The whole check switches itself off unless the loaded meta actually has the async command, so plain Denizen sees nothing new.
Silence them per file with ##ignorewarning async_unsafe_command or ##ignorewarning async_unsafe_tag.
→ DenizenM
Go to definition
F12 on a flag jumps to where it is set; on a script name, to the container that defines it.
Script names on - run
Typing - run offers the script containers in your workspace, each labelled with its type and the file it lives in. Only the types a run-like command can actually execute are listed — task, procedure, command — which on a real script folder is about half the containers; items, inventories, worlds and the rest are left out. A container whose type: couldn't be read is still offered rather than hidden.
Covers run, runlater, inject, clickable and bungeerun.
Script definitions on - run
Hovering the script name in - run ribalksa lists the definitions that script declares in its definitions: key, with the [square bracket] documentation shown next to each name — those brackets are documentation, not default values.
Typing past the script name offers the def. arguments to go with it: one suggestion that fills the whole line at once (def.__player: def.hook:, with tab stops between the values), plus one per name if you only want a couple. Names already written on the line are not offered again.
Offered for run, runlater, clickable and bungeerun — not for inject, which runs in the current queue and takes no def arguments.
Hover on <[definitionName]>
Shows what that definition was last set to — the closest - define at or above the line you're hovering, with its line number.
Scoped to the enclosing container, because a definition is queue-scoped: a - define hook in another container of the same file is a different variable that happens to share a name. If the name is assigned more than once in the container, the hover says so.
Works whether or not anything is read off it — <[ent]> and <[ent].some.tags> both resolve.
Inline argument hints
Grey text at the end of the line you are editing, showing the arguments the command still accepts. Only the caret's line is annotated (denizenscript.inlineArgumentHints).
To see them on demand only, leave the setting on and set editor.inlayHints.enabled to offUnlessPressed — the hint then appears while you hold Ctrl+Alt.
Offline math
Hovering an arithmetic tag such as <element[1].sub[<element[2].mul[3]>]> shows what it works out to, without a server (denizenscript.evaluateMathTags).
Anything the server would have to answer — definitions, flags, <player.…> — is listed as a value to supply rather than guessed at; Refined DenizenScript: Evaluate Math Tag asks for those and shows the result. A result that is not exactly representable is labelled as rounded.
A clickable Expand tag lens above any line holding a multi-entry <map[…]> or <list[…]> opens it formatted across several lines. The expanded view is editable and writes back as a single line — the file never holds the multi-line form, which Denizen's parser would reject (refinedDenizenscript.mapTag.showExpandLens).
Syntax highlighting and inline colours
- Custom colour containers from your Denizen
config.yml are parsed and applied where possible.
- Inline colour rendering for colour tags (
denizenscript.behaviors.do_inline_colors), with an option for very dark colours (display_dark_colors).
- A colour picker on hex colours — a swatch beside
<&color[#2596be]> opens VS Code's own picker, and both the #RRGGBB and #RRGGBBAA forms are handled. Only inside a tag, and never on a commented-out line.
- Prefixed arguments are coloured too, not just the command name.
- Uses the DenizenScript palette by default (
denizenscript.theme_colors.*); set denizenscript.behaviors.use_custom_syntax_colors to false to use your VS Code theme's colours instead. The palette is drawn with semantic tokens, so it stays smooth in files of several thousand lines.
| Write |
Shows as |
# note |
a plain comment (grey) |
## careful |
a warning (yellow) |
### do not touch |
a critical block (red, with a light red band across the line) |
# TODO … / # - narrate … |
a TODO / commented-out code, each in its own palette colour |
- A block of comment lines folds as a whole from its first line — a
# ==== banner with notes and examples collapses to one line — and runs of one level inside it fold on their own.
##ignorewarning … and other ##word directives stay plain comments — they are instructions to the checker, not emphasis.
- In theme-colour mode
## and ### use the markup.changed / markup.deleted scopes, which most themes colour yellow and red.
Settings page
Refined DenizenScript: Settings, or the gear in the title bar of any .dsc editor, opens a page for the palette and the extension's options:
- Each palette colour is a card showing a real line of script in that colour, with a HEX field, a colour picker and B / I. A live
test_script.dsc preview beside the cards shows exactly what the editor will — it is coloured by the same highlighter — and hovering a card outlines what it colours there.
- Suggestions, checks, inline text colours, the
config.yml colour names and header symbols are cards too.
- Everything is written to your user
settings.json, so Settings Sync and hand edits keep working; a hand edit shows on the open page at once. A value overridden in the workspace is marked on its card.
- With VS Code theme colors selected the preview can't show your theme's colours, so it shows the code in plain text.
Script scaffolding
Refined DenizenScript: Create Category — Ctrl+Alt+D then C
Refined DenizenScript: Create Script File — Ctrl+Alt+D then F
- Automatic
.dsc extension handling for files created under denizen/script.
Commands, tags and events come from the meta of the sources you enable. Manage them on the settings page (Refined DenizenScript: Settings → Meta sources):
- Official — Denizen, Denizen-Core, Depenizen and dDiscordBot, always loaded.
- Add-ons — DenizenM and DenizenM-Core (EnergoBro), denizen-utilities and denizen-reflect (isnsest). Off by default; a disabled add-on is never downloaded.
- Your own — paste a direct
.zip link or just a GitHub repository (github.com/owner/repo); each has its own switch.
- Use custom sources instead of official ones — for a Denizen fork that removes things from upstream.
Switching a source restarts the language server by itself. Every start asks GitHub whether each source changed (an unchanged one costs no download), so an updated add-on is picked up on the next start; Reinstall instances (or the command Refined DenizenScript: Reinstall Meta Sources) clears the cache and downloads everything again. The settings behind the page are denizenscript.server.enabled_addons, extra_sources and replace_default_sources.
When a command, tag or event is unknown and some source is switched off, the warning says which ones may have it, and the quick fix Open meta sources takes you there.
Reporting lag
If a large file feels slow, turn on denizenscript.debug.performance, work in that file for a minute — scroll, type — then run Refined DenizenScript: Show Performance Report and paste what it prints into your issue. It shows how long each editor feature took, so the report says which one to fix.
Defects this fork corrects that the original gets wrong:
- Squiggles land on the text, not the indentation. Three separate cases where a warning underlined the leading whitespace instead of the thing it complained about, including one where a capitalised key produced a broken range.
- Colour-code warnings report on the right line.
§ used for colour codes was reported on the wrong line when a command spanned several lines, and missed entirely when it appeared on a continuation line.
Language server
Completion, hover, signature help and diagnostics come from a language server written in TypeScript that runs on the Node.js bundled with VS Code — nothing extra to install, and it starts with the editor. It loads the official Denizen meta (plus any extra_sources) and caches it locally.
Setup
npm install
Build
node node_modules/typescript/bin/tsc -p ./ --skipLibCheck
Don't use npm run compile to verify a build — on some setups it exits 0 without writing anything, even when the code is broken. Invoke the compiler directly and check the exit code; it prints nothing on success.
The compiled output in out/ is committed to the repository and is what actually ships in the VSIX. After changing anything in src/, rebuild and commit out/ too, or the change won't reach users.
Test
node node_modules/vitest/vitest.mjs run
Use this rather than npx vitest, which can swallow the output.
scripts/verify-phase*.js are end-to-end checks that download real Denizen meta and drive the server the way it runs in production. Run them after any language-server change:
node scripts/verify-phase2c3.js
Each prints ALL CHECKS PASSED or a list of failures.
Package
Builds the shareable .vsix — compiles, runs the tests, then packages:
node scripts/build-vsix.js
npm run package does the same thing. Prefer the node form: on some setups npm run starts the child process and it produces nothing, which is how a broken build once got packaged silently.
The result is refined-denizenscript-<version>.vsix in this folder, about 2 MB. Install it with Ctrl+Shift+X → ··· → Install from VSIX…, or code --install-extension refined-denizenscript-<version>.vsix.
Add --fast to skip the tests.
If npm install fails with ERESOLVE, you are on a checkout from before 2026-09-02 — the @types/node conflict behind it is fixed. Pull, or use npm install --legacy-peer-deps once.
Current state
The TypeScript language server is a faithful port of SharpDenizenTools, not a reimplementation. The C# is treated as the specification, warts included: behaviours that look like bugs are ported verbatim and marked C# QUIRK in the source. Where the port knowingly disagrees, the site is marked DELIBERATE DEVIATION and the reason recorded.
|
|
| Unit tests |
1553 passing, 52 files |
| End-to-end verification |
21 scripts, all passing against live meta |
| TypeScript compile |
clean |
Open source, free for everyone, to use and contribute to. If you make changes that could benefit the community, please contribute them upstream to DenizenVSCode.
MIT.
- Original project — Copyright (c) 2019-2025 The Denizen Scripting Team — LICENSE.txt
- This fork — Copyright (c) 2026 Humususus
- Ported third-party code — THIRD_PARTY_NOTICES.md