Release Notes 3.0.0

This is the largest update to the language server throughout the history. Tons of handy features have been added. You should really sponsor me to support this project. Well, perhaps.

💥 Breaking Changes in 3.0.0

Programming

The underlying API structure has been completely re-designed. Now the DatapackLanguageService class is considered as the public API of this package, any other exported classes/variables/functions are not considered as stable API and are subject to change in any versions.

✨ Features in 3.0.0

Renaming

The brand name of the extension family has been changed from "Datapack Helper Plus" to "Data-pack Helper Plus". I also changed all references of "datapack" in error messages to "data pack".

Programming

There are some features/changes that might sound interesting to people who'd like to extend the language server or make the language server a dependency of their project.

Initialization Options

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Language-Server-Details

Both the storagePath and globalStoragePath initialization options are no longer required.
Added a new optional localeCode option which defaults to en. It should be a locale code that the server could use when datapack.env.language is set to Default in the config.
Added a new optional customCapabilities option to indicate which spgoding/datapack/* messages are supported by the client.

Plugin System

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Plugins

The language server now has support for its own plugins. The language features for commands and IMP-Doc are now provided by built-in plugins. Note that these built-in plugins are using a lot of non-APIs which cannot be accessed by external plugins. We will expose those part of functions slowly.

We are planning to collaborate with MulverineX to bring Trident Language support to the language server by using the new plugin system. There is a really long way before that, however.

JSON Support

The language server can now provide language features for data pack JSON files, including advancements, dimensions, dimension types, functions, loot tables, predicates, recipes, all kinds of tags, and all kinds of worldgen files.

The legacy Datapack Helper Plus (JSON) VS Code extension has been abandoned. Please uninstall it if you were using it.

By using the language server's JSON support, you can enjoy completions within string values, which is a huge plus to your quality of life.

You can now also use almost all of the features that you can use in mcfunction files in JSONs, e.g. finding referenes, semantic coloring, etc.

The JSON support is a quite complicated feature, and there might be a lot of issues. Please report any of them in GitHub Issues; they will get fixed!

Declaration Support

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Declare-Comment

The old #define comment is renamed to #declare. But don't worry, #define is still an alias of it 😅.

Resources declared by the #declare comment are now considered as declarations instead of definitions. You can use the new "Goto Declaration" feature to navigate to these comments.

The game will treat declaration comments as normal comments and simply ignore them.

Syntax: #declare|#define <type: string> <value: string>

declaration-comments

Here's a table showing how to declare or define each type of resource:

Type	Declaration	Definition
Advancement	`#declare advancement <ID>`	An advancement file.
Biome	`#declare worldgen/biome <ID>`	A biome file.
Block Tag	`#declare tag/block <ID>`	A block tag file.
Bossbar	`#declare bossbar <ID>`	`bossbar add <ID>`
Configured Carver	`#declare worldgen/configured_carver <ID>`	A configured carver file.
Configured Feature	`#declare worldgen/configured_feature <ID>`	A configured feature file.
Configured Structure Feature	`#declare worldgen/configured_structure_feature <ID>`	A configured structure feature file.
Configured Surface Builder	`#declare worldgen/configured_surface_builder <ID>`	A configured surface builder file.
Dimension	`#declare dimension <ID>`	A dimension file.
Dimension Type	`#declare dimension_type <ID>`	A dimension type file.
Entity	`#declare entity <ID>`	N/A
Entity Type Tag	`#declare tag/entity_type <ID>`	An entity type tag file.
Fluid Tag	`#declare tag/fluid <ID>`	A fluid tag file.
Function	`#declare function <ID>`	A function file.
Function Tag	`#declare tag/function <ID>`	A function tag file.
Item Tag	`#declare tag/item <ID>`	An item tag file.
Loot Table	`#declare loot_table <ID>`	A loot table file.
Objective	`#declare objective <ID>`	`scoreboard objectives add <ID>`
Predicate	`#declare predicate <ID>`	A predicate file.
Processor List	`#declare worldgen/processor_list <ID>`	A processor list file.
Recipe	`#declare recipe <ID>`	A recipe file.
Score Holder	`#declare score_holder <ID>`	N/A
Storage	`#declare storage <ID>`	N/A
Tag	`#declare tag <ID>`	N/A
Team	`#declare team <ID>`	`team add <ID>`
Template Pool	`#declare worldgen/template_pool <ID>`	A template pool file.

IMP-Doc Support

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/IMP-Doc

IMP-Doc is a special type of comment that can increase the readability of your mcfunctions and make it easier for you to write data packs.

Basic

The IMP-Doc support provided by DHP is based on the Interoperable Module Protocol Documentation Format proposed by Arcensoth, please take a look at the specification first. We will then cover the things that you should know when using IMP-Doc in DHP.

DHP's Implementation

Annotations

Most of the annotations in IMP-Doc haven't gotten a special meaning in DHP yet. We will provide support for them gradually.

Exceptions are @api, @public, and @within. They are used to change the visibility of resources in DHP; see Access Modifiers for more information.

Certain annotations proposed by IMP-Doc require some parameters, e.g. the @input score <name> <objective> [description] annotation that can lists all the score inputs of the function. In DHP's implementation, you can break at any spaces that separate different parameters of an annotation and turn into a new line with indentation (>= 2 spaces). For example, all the following comments are legal and have the same meaning in DHP:

#> example:foo
# @input score $bar mypack.baz Description for the first score.
# @input score $bar mypack.qux Description for the second score.

#> example:foo
# @input
#   score $bar mypack.baz Description for the first score.
#   score $bar mypack.qux Description for the second score.

#> example:foo
# @input
#   score $bar mypack.baz
#       Description for the first score.
#   score $bar mypack.qux
#       Description for the second score.

#> example:foo
# @input score $bar
#   mypack.baz
#       Description for the first score.
#   mypack.qux
#       Description for the second score.

#> example:foo
# @input
#   score
#       $bar
#           mypack.baz
#               Description for the first score.
#           mypack.qux
#               Description for the second score.

IMP-Doc for Commands

Apart from writing IMP-Doc in the first line of a mcfunction to describe the whole file, you can also write IMP-Doc in front of certain commands to describe the resources defined/declared by them. The key difference is that you do not write the function ID after the #> characters in the first line of the comment. Here are some examples:

#>
# A bossbar that is for xxx.
# - Max: 100.
# - Value: should be the amount of xxx.
# @internal
bossbar add spgoding:foo ""

#> This tag is used by xxx.
#declare tag qux

For a complete list of commands/comments that can define/declare resources, see Declare Comment.

You can add an indentation (>= 2 spaces) before the commands after the IMP-Doc to make a single doc comment affect multiple definitions/declarations at the same time. e.g.

#> A set of teams with colors.
    team add example.red
    team add example.blue

#> 
# Score holders for xxx calculation.
# @within spgoding:calc/**
    #declare score_holder a
    #declare score_holder b
    #declare score_holder c

References

IMP Documentation Format (IMP-Doc)

Access Modifiers Support

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Access-Modifiers

`@within`

Restrict the visibility of this resource to certain files that match the namespaced ID pattern.

Syntax

within <id: namespaced ID pattern>
within * <id: namespaced ID pattern>
within <type: file type> <id: namespaced ID pattern>

File Type

You can see a full list of file types in this page. Only the specified type of files that match the namespaced ID pattern can access to the resource.

Specifying * or not specifying file type at all results in allowing any types of files that match the pattern to access the resource.

Namespaced ID Pattern

A namespaced ID pattern is really similar to a namespaced ID. The difference is that you can use certain wildcards in it:

?: Represents an arbitrary character that matches [a-z0-9_\-\.].
*: Represents 1 or more characters that matches [a-z0-9_\-\.].
**: Represents any amount (including 0) of any characters (including : and /).

Some examples of the namespaced ID pattern:

spgoding:foo: Matches spgoding:foo.
spgoding:ba?: Matches spgoding:bar and spgoding:baz, but not spgoding:foo.
spgoding:*/qux: Matches spgoding:foo/qux and spgoding:bar/qux, but not spgoding:abc nor spgoding:qux.
spgoding:**/foo: Matches spgoding:foo, spgoding:bar/foo, and spgoding:bar/qux/foo.
spgoding:**: Matches any files that is under the spgoding namespace.
**: Matches everything.

Examples

#> spgoding:foo
# This function can be accessed from any files under the `example` namespace.
# @within example:**

#> spgoding:foo
# This function can be accessed from any files under the `example` namespace.
# @within * example:**

#> spgoding:foo
# This function can only be accessed from functions under the `example` namespace.
# @within function example:**

#> spgoding:foo
# This function can be accessed from both functions and function tags under the `example` namespace.
# @within 
#   function example:**
#   tag/function example:**

`@private`

Restrict the visibility of this resource to the current file.

Syntax

@private

Examples

#>
# This objective can be accessed from the current file.
# @private
scoreboard objectives add foo dummy

#>
# The effect of @private can actually be implemented with @within:
# @within <The ID of the current function file>

`@internal`

Restrict the visibility of this resource to the same namespace as the current file and the default namespace (minecraft).

Syntax

@internal

Examples

#> spgoding:foo
# This function can be accessed from any files under the `spgoding` namespace and the `minecraft` namespace.
# @internal

#> spgoding:foo
# The effect of @internal can actually be implemented with @within:
# @within
#   spgoding:**
#   minecraft:**

`@public` and `@api`

No restrictions to the visibility of this resource.

Syntax

@public
@api

Examples

#> spgoding:foo
# This function can be accessed from everywhere.
# @public

#> spgoding:foo
# The effect of @public can actually be implemented with @within:
# @within **

Default Visibility Config

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Env-Options#defaultvisibility

Specify the default access modifier for resources. See also Access Modifiers.

Available options

"public": (Default) Public.
"internal": Internal.
"private": Private.
(Object) Simulates a @within modifier.
- type: The type of files that can access this resource. Can be one of the file types or "*".
- pattern: A namespaced ID pattern. See Access Modifiers for more information.
(Array) Simulates a series of @within modifiers.
- (Object) Using the same format as the above object.

Strict Check Configs

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Lint-Rules

You can enable several strict check configs to show diagnostics for undefined resources. See Lint Rules for more information.

Nested Data Pack Detection

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Env-Options#detectiondepth

Added a new config called datapack.env.detectionDepth which defaults to 1. Instead of seeing all workspace roots as data packs, the language server now actually detects recursively to see if there is a pack.mcmeta file and a data folder. By changing the value of this config, you can alter the data pack detection depth of the language server. Note that higher values require more time to check and might reduce the performance.

By setting a value greater than or equal to 1, you can open the .minecraft/saves/<save name>/datapacks folder directly in your editor and enjoy editing all data packs within it instead of having all data packs added to the workspace manually.

Creating Non-existent Files Quickly

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/Code-Actions

Added a new quick fix (id-create-file) to create non-existent resources in the current data pack.

Key	Name	Ex. Before	Ex. After
`id-create-file`	Create %0% in the same data pack	A file that doesn't exist.	The file is created.

NBT Array Length Check

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/nbtArrayLengthCheck

Added a new config called datapack.lint.nbtArrayLengthCheck to decide whether to show diagnostics for NBT arrays that don't have the required amount of tags in it.

Examples

Default

{
    "nbtArrayLengthCheck": ["warning", true]
}

Disabled

{
    "nbtArrayLengthCheck": null
}

NBT List Length Check

Wiki: https://github.com/SPGoding/datapack-language-server/wiki/nbtListLengthCheck

Added a new config called datapack.lint.nbtListLengthCheck to decide whether to show diagnostics for NBT lists that don't have the required amount of tags in it.

Examples

Default

{
    "nbtListLengthCheck": null
}

Enabled

{
    "nbtListLengthCheck": ["warning", true]
}

Diagnostics

The language server now provides warnings when there are too many blocks affected by the /clone or /fill command.

🌐 Localizations in 3.0.0

Add Chinese (Traditional).
Translations for German, Japanese, and Chinese (Simplified) are updated to 100%.
Translations for Italian are updated to 90%.

⚡ Performance in 3.0.0

The initialization process of the language server is now 100% asynchrouns and no longer blocks the requests from the client, which means you can use all the features right after you launch the server. No more "Loading..." prompts!
The initialization time in general has been reduced by approximately 81%*.
The command syntax tree navigation mechanism has been improved from a time complexity of O(n) to O(1), which reduces the cost by approximately 39%*.
- This change only applies to Java Edition 1.16 as syntax trees for older versions aren't maintained.

* The data isn't accurate as I only tested it once.

🐛 Bugfixes in 3.0.0

Notable fixes:

#434 - No completions for commands in text components
#435 - Wrong completion range for special characters
#606 - Missing minecraft:empty loot table
Not supporting Sublime Text 3 because of how it handles URIs.

See all known 21 bugs that were fixed in 3.0.0: query.

♻ Refactors in 3.0.0

Changed completion logic from using insertText to using textEdit.
Moved all ./utils/handlers to ./services.
Wrapped a lot of messy logic into the DatapackLanguageService class.
Changed the implementation of function parser to be based on plugins.SyntaxComponent.
Changed LineNode to CommandComponent which implements the plugins.SyntaxComponent interface.
Migrated the function command parser logic to the McfunctionPlugin.
Changed to use string URIs internally.
Moved the language detection logic out of the server.

🕙 Future Plans

See all backlogged issues: query.

💛 Thank You

A big thank you goes to these wonderful people! (sorted by the Unicode of names)

_AOOAcat	🐛 #724	_Arcensoth	⬆️ Maintains mcdata repository
_ChenCMD	💎 Collaborator	_Ghoulboy	🌐 Italian (it)
_{K_bai}	☕ Coffee	_Misode	⬆️ Maintains minecraft-schemas repository 💻 #711 ✨ #445 🐛 #592 🐛 #593
_NeunEinser	🌐 German (de) 🐛 #652 🐛 #653 🐛 #654 🐛 #661	_Yurihaia	⬆️ Maintains mc-nbtdoc repository
_boon4681	🐛 #681	_eke0909	🐛 #700
_kakagRou	☕ Coffee	_lakejason0	🌐 Chinese (Traditional) (zh-tw) 🐛 #655
_mathaym25	🐛 #434	_pca006132	✨ #605
_shurik204	🐛 #678	_zyjking	☕ Coffee
_Ξи	🐛 #660 🐛 #671

This project follows the all-contributors specification. Contributions of any kind are welcome!

Looking to contribute?

Thanks a lot! You can consider contributing by sponsoring, reporting bugs/sharing ideas, or helping localization!

Home
Features
Configuration
Release Notes
- 3.1.0
- 3.0.0
- 2.1.0
- 2.0.1
- 2.0.0
Technical Detail

Release Notes 3.0.0

🔷 Data-pack Language Server 3.0.9

🔷 Data-pack Language Server 3.0.8

🔷 Data-pack Language Server 3.0.7

🔷 Data-pack Language Server 3.0.6

🔷 Data-pack Language Server 3.0.5

🔷 Data-pack Language Server 3.0.4

🔷 Data-pack Language Server 3.0.3

🔷 Data-pack Language Server 3.0.2

🔷 Data-pack Language Server 3.0.1

🔷 Data-pack Language Server 3.0.0

💥 Breaking Changes in 3.0.0

Programming

✨ Features in 3.0.0

Renaming

Programming

Initialization Options

Plugin System

JSON Support

Declaration Support

IMP-Doc Support

Basic

DHP's Implementation

Annotations

IMP-Doc for Commands

Further Reading

References

Access Modifiers Support

@within

Syntax

File Type

Namespaced ID Pattern

Examples

@private

Syntax

Examples

@internal

Syntax

Examples

@public and @api

Syntax

Examples

Default Visibility Config

Available options

Strict Check Configs

Nested Data Pack Detection

Creating Non-existent Files Quickly

NBT Array Length Check

Examples

Default

Disabled

NBT List Length Check

Examples

Default

Enabled

Diagnostics

🌐 Localizations in 3.0.0

⚡ Performance in 3.0.0

🐛 Bugfixes in 3.0.0

♻ Refactors in 3.0.0

🕙 Future Plans

💛 Thank You

Looking to contribute?

Clone this wiki locally

`@within`

`@private`

`@internal`

`@public` and `@api`