Basalt DevTools

Editor support for Basalt plugins: autocompletion, diagnostics and builds.

Overview

Basalt DevTools is part of the Basalt Project. It turns an editor into a place to write plugins for Basalt Server and Basalt Proxy, and builds on two other pieces instead of reimplementing them:

• LuaLS (the sumneko.lua extension) is the engine. It does the completion, hover documentation, go to definition and type checking.
• Kiln is the verifier. It reads the whole plugin and reports what is wrong with its manifest, its requires and its use of the Basalt API.

DevTools is what connects them to Basalt: it gives LuaLS the API of the product you target, and shows Kiln's findings in the Problems panel.

VS Code is the main editor. A JetBrains plugin (IntelliJ IDEA 2025.3 and newer) lives in intellij/.

Features

• Autocompletion and documentation for the Basalt API (log, players, worlds, on, cmd and the rest), from definitions that LuaLS loads for the target you picked.
• Problems panel: Kiln runs when the extension starts and on every save of a Lua file or plugin.toml.
• Commands: Basalt: Check Plugin and Basalt: Compile Plugin.
• Snippets: on for an event handler and cmd for a command.
• Server and proxy: the basalt.target setting switches the API that is completed and the checks that are run.

Requirements

• VS Code 1.90 or newer. The Lua language server extension installs with it.
• kiln on the PATH, or its location in basalt.kilnPath.

The extension turns on when the open folder contains a plugin.toml.

Settings

Setting	Default	Meaning
basalt.target	server	The product the plugin is for: server or proxy
basalt.kilnPath	kiln	The Kiln executable
basalt.checkOnSave	true	Run Kiln when a Lua file or plugin.toml is saved

How the API reaches the editor

The names of an API live in Kiln, in api/<target>.api. DevTools turns that file into LuaLS annotations:

python3 scripts/generate-definitions.py ../Kiln/api/server.api server \
    --events ../Server/server-plugins/src/PluginEventTypes.cpp \
    --events ../Server/server-plugins/include/basalt/server/plugins/PluginHookEvents.def

A name with a hand-written signature in types/<target>.lua (players, worlds, menus, forms, positions, items and the rest of the objects a plugin touches) keeps it; --events (once per event source) adds one class per event and the on and watch overloads that go with it; any other name is declared with .... This writes definitions/server/basalt.lua. The extension adds definitions/<target>/ to Lua.workspace.library in the workspace settings, so what the editor completes and what Kiln accepts come from the same list.

Adding a target

1. Add api/<target>.api to Kiln and a row for the target there.
2. Run the generator for it, as above, and commit the new definitions/<target>/basalt.lua.
3. Add the target to the basalt.target values in package.json.

Download

Every commit to main publishes a release, <minecraft>.<n> such as 26.3.4, on the releases page, with SHA256SUMS. Take Basalt-DevTools-VSCode-<version>.vsix and install it with Extensions: Install from VSIX, or code --install-extension <file>. The extension also needs Kiln.

To build the package yourself:

npm install -g @vscode/vsce
vsce package

JetBrains

intellij/ holds the IDE plugin: Tools | Basalt | Check Plugin and Compile Plugin run Kiln, its findings appear in a Basalt tool window (double click opens the line), Kiln runs again when a Lua file or plugin.toml is saved, and Sync API Definitions copies the ---@meta definitions of the target into .basalt/api/ so a Lua plugin for the IDE completes them. The target, the Kiln path and the save check are under Settings | Tools | Basalt.

The release carries Basalt-DevTools-IntelliJ-<version>.zip; install it with Settings | Plugins | Install Plugin from Disk. To build it yourself:

cd intellij && ./gradlew buildPlugin   # build/distributions/basalt-devtools-intellij-<version>.zip

License

GPL-3.0-only. See LICENSE.