Command Rework

[APickledWalrus]

Problem

There are a few main problems I am focusing on with this attempt:

• Skript relies on commands being parsed as syntax patterns, which is not in line with how Minecraft commands are structured. This makes validation nearly impossible.
• We depend on reflection-based registration into legacy command structures (Bukkit's CommandMap).
• Modern Brigadier features (first implemented in 1.13) are not at all supported.

A goal of prior PRs was to decouple the system from Bukkit, but I am not so focused on that this time around.
I'm not sure that it would really end up being that valuable given the increased complexity, but we can continue looking at it. I'm intentionally keeping the scope smaller so that it is easier to review and more likely to be implemented.

Solution

Third time is the charm right!? Before I get into it, I want to thank the previous efforts put forth in #7032 and #8111, which provided plenty of valuable information for this PR.

Caution

This proposal is still under heavy development. However, the system has reached a point such that it should be equivalent with Skript's existing system. There is more to talk about in this description as well, but the key ideas are highlighted. I'm really looking for high-level feedback/suggestions at this time. Do feel free to peek around the code though.

The main thing implemented by this PR is a Brigadier-based command system.
Most, if not all, existing script commands are compatible.

Command Parsing

Command parsing has been completely overhauled, with a dedicated command parser being created in CommandCompiler. This was originally built on Skript's PatternCompiler, though it works pretty differently at this point. However, the goal is the same: allow Skript-like patterns to be compiled into Brigadier commands. Consider the following example:

command /options (a|b) [c] confirm

This would build the following tree:

options
|- a
    |- c
        |- confirm
    |- confirm
|- b
    |- c
        |- confirm
    |- confirm

I'm not sure these patterns are generally valuable, but it works!

Note

Optional arguments are fully supported. Arguments in choice groups are untested currently.

Command Registration

I have implemented two registration strategies in RuntimeCommandRegistrar:

• Native/safe approach: Uses Paper's lifecycle event system to register commands natively. This can be triggered through a reload of the server data (Bukkit#reloadData). However, this is expensive: in my experience, it takes around 400MS. It also reloads advancements and recipes, which can be problematic for plugins implementing custom versions of those (if they are not handling reloads properly).
• Reflection-based approach: This is probably as safe as a reflection-based approach can be. It is also significantly faster as it bypasses the required data reloads.

Command Entry Changes

permission message has been deprecated. Commands that a player does not have permission for are no longer sent to their client (to them, the command does not exist).

New Command Features

Subcommands

Probably the most desired feature is the new subcommand entry:

command /alert:
    subcommand one:
        trigger:
            send "Alert One" to all players
    subcommand two:
        trigger:
            send "Alert Two" to all players

Subcommands are not very restricted. They can start with arguments. They can also have multiple literals/arguments.

Native Argument Support

While all types with parsers can be used as arguments, some can be resolved to native argument types, including numeric types, players, and entities (potentially more to be added as I experiment).

Numeric options can also be ranged:

command /feed <players> <double from 0 to 10)

There is real-time validation support for this on the client as well.

Breaking Changes

One breaking change is that it is no longer possible to write a command like:

command /test hello to<number>:

That is, literals and arguments cannot be placed directly next to each other.
Brigadier does not allow this.

The other breaking change relates to plural arguments. Consider:

command /plural <numbers> <player>:

texts cannot be greedy, meaning /plural 5 and 10 APickledWalrus is not valid.
Instead, you must surround it with quotes: /plural "5 and 10" APickledWalrus
This does not apply if the plural argument is the last argument in the tree.

This example also reveals another limitation: not all plural arguments can be native types, even if the single version is.
There is no way to allow an argument to be repeated an unlimited number of times.

last usage date for commands has been removed. It was not implemented properly, and the config option to enable it is only used by one server according to bStats. This can be easily implemented by a user if necessary.

Testing Completed

Mix of commands.sk test script and in-game testing.

Supporting Information

There is plenty of work to do with regard to deprecating the classes related to the existing system. There are also still some syntaxes to port (e.g., ExprCommandInfo). And, of course, improved organization/documentation 🙂.

Other ideas I am considering:

• Custom command completions
  • Most types now already have custom completions powered by the ClassInfo supplier.
  • Probably useful for like text or numeric types
• Argument validation section

The main thing is that this provides us with a strong foundation for expanding the command system in the future.
Even if everything we could want is not accomplished in this PR, it is easily possible to add it in another.

---

Completes:

• TBD

Related: none
AI assistance: none