Language Server Details

As a language server, you can simply implement the features provided by the datapack-language-server on any other modern editors. Here are all the technical details you may concern.

• Integrate
• Server Capabilities
• Client Requirements
  • Custom Messages
  • Initialization options
  • Settings
• References
• History

Integrate

Check out this page to see if there's already an LSP client integration available.

You can also launch the language server as a command and connect to it. For that, install the datapack-language-server npm module:

npm i -g datapack-language-server

Start the language server with the datapack-language-server command.

Server Capabilities

The language server supports request on documents of language id mcfunction and json.

• There's no specification for mcfunction files. The language server tries it best to imitate how Minecraft: Java Edition behaves. All inconsistencies are considerd as bugs of either the language server or Minecraft, and should be reported at either Issues or Mojira.
• Only JSON files under specific directories can be handled by the language server. A complete list of glob patterns that match supported JSON files can be found here.

The language server protocol consists of a number of capabilities. Here's a list of capabilities that are implemented by the language server.

• ✅ Call hierarchy provider
  • ✅ textDocument/prepareCallHierarchy
  • ✅ callHierarchy/incomingCalls
  • ✅ callHierarchy/outgoingCalls
• ✅ Color provider
  • ✅ textDocument/documentColor
  • ✅ textDocument/colorPresentation
• ✅ Completion provider
  • ✅ textDocument/completion
  • ❌ completionItem/resolve
• ✅ Definition provider
  • ✅ textDocument/definition
• ✅ Declaration provider
  • ✅ textDocument/declaration
• ✅ Document formatting provider
  • ✅ textDocument/formatting
  • ❌ textDocument/rangeFormatting
  • ❌ textDocument/onTypeFormatting
• ✅ Document highlight provider
  • ✅ textDocument/documentHighlight
• ✅ Document link provider
  • ✅ textDocument/documentLink
• ✅ Execute command provider
  • ✅ workspace/executeCommand
  • ⚠️ Available commands
• ✅ Folding range provider
  • ✅ textDocument/foldingRange
• ✅ Hover provider
  • ✅ textDocument/hover
• ✅ Reference provider
  • ✅ textDocument/references
• ✅ Rename provider
  • ✅ textDocument/prepareRename
  • ✅ textDocument/rename
• ✅ Selection range provider
  • ✅ textDocument/selectionRange
• ✅ Semantic tokens provider
  • ✅ textDocument/semanticTokens
  • ✅ textDocument/semanticTokens/edits
  • ✅ textDocument/semanticTokens/range
  • ⚠️ Semantic legend
• ✅ Signature help provider
  • ✅ textDocument/selectionRange
• ✅ Text document sync
  • ✅ textDocument/didOpen
  • ✅ textDocument/didChange: Incremental update.
  • ❌ textDocument/willSave
  • ❌ textDocument/willSaveWaitUntil
  • ❌ textDocument/didSave
  • ✅ textDocument/didClose
• ✅ Watch files
  • ✅ workspace/didChangeWatchedFiles
  • ⚠️ Here is a list of files that should be watched; glob patterns are relative from the root of workspace folders.
    • **/data/**/*.{json,mcfunction,nbt}: Should trigger create event, change event, and delete event.
    • **/{data,pack.mcmeta}: Should trigger create event and delete event. When events for these entries are received, the language server will start re-detecting data packs. The client should not send change events for these entries, otherwise it would make the language server laggy.
• ✅ Workspace
  • ✅ Multi-root workspace.
  • ✅ workspace/didChangeWorkspaceFolders

Client Requirements

The language server expects the client to only send messages for documents of language ID mcfunction, certain JSON files, and pack.mcmeta:

{
    "documentSelector": [
        { "language": "mcfunction" },
        { "scheme": "file", "pattern": "**/pack.mcmeta" },
        { "scheme": "file", "pattern": "**/data/*/*/**/*.json" }
    ]
}

However, if your client doesn't support the pattern selector, you may send all requests of language ID json to the language server. Hopefully the server can handle them correctly for you.

{
    "documentSelector": [
        { "language": "mcfunction" },
        { "language": "json" }
    ]
}

The client must not throw exceptions when it receives the following messages from the server:

• window/showMessage
• window/showMessageRequest

Also, the client may somehow provide supports for stuff marked as ⚠️ in the Server Capabilities section to enjoy full features provided by the server.

Custom Messages

The client may provide support for the following custom messages that are sent from the server to the client:

• spgoding/datapack/checkServerVersion notification: check if the version where the language server was started last time is older than current version. If so, the client may show an information box indicating the user.
  • currentVersion: A string. The current version of the language server.
  • title: A string. If the client decides to show an information box, this title may be used.
  • action: A string. If the client decides to show an information box, this action may be used as the title of the action button.
  • url: A string. If the client decides to show an information box, clicking the action button may open this URL.

Initialization options

• globalStoragePath: (Optional) A string. Should be a path to a folder where the language server can store global cache files, like the block definitions, registries, and nbtdocs for Minecraft. The folder doesn't need to exist, but the client must ensure that the server has the permission to create, read, and write to that folder. If not specified, the language server will use the platform-specific appdata-path for the spgoding.datapack-language-server APP name.
• storagePath: (Optional) A string. Should be a path to a folder where the language server can store workspace-specific cache file. The folder doesn't need to exist, but the client must ensure that the server has the permission to create, read, and write to that folder. If not specified, the cache file won't be saved and the language server need to generate it every time it starts.
• localeCode: (Optional) A string, defaults to en. Should be a locale code that the server could use when the datapack.env.language setting is set to Default. A list of acceptable locale codes can be fond here.
• customCapabilities: (Optional) An object which indicates the server what custom messages does the client support.
  • checkServerVersion: (Optional) If the client supports the custom spgoding/datapack/checkServerVersion notification.

Settings

If the client indicates that it supports the workspace/configuration request, the response for it must follow the Config interface in src/types/Config.ts.

References

• vscode-json-languageserver

History

Version	Description
?	?
3.0.0	Supported textDocument/declaration request on server. Both storagePath and globalStoragePath are no longer required in the initialization options. Added localeCode and customCapabilities initialization options. The prefix for custom messages is changed from datapackLanguageServer/ to spgoding/datapack/.
3.0.1	Files with the .nbt extension should also be watched on client.