CommandAPI

Appearance

Velocity ​

Developer's Note:

This section assumes you are already familiar with how to set up a Velocity plugin.

Adding the dependency ​

Add the dependency to your list of dependencies in your build script:

xml
<dependencies>
    <dependency>
        <groupId>dev.jorel</groupId>
        <artifactId>commandapi-velocity-shade</artifactId>
        <version>10.0.0</version>
    </dependency>
</dependencies>
groovy
dependencies {
    implementation "dev.jorel:commandapi-velocity-shade:10.0.0"
}
kotlin
dependencies {
    implementation("dev.jorel:commandapi-velocity-shade:10.0.0")
}

Setting up the CommandAPI ​

The CommandAPI requires two steps: loading and enabling. We will perform these steps in Velocity's loading stages, construction and initialization. These two stages are explained in their documentation. We will perform the CommandAPI's loading step in the construction phase first:

java
@Inject
public ExamplePlugin(ProxyServer server, Logger logger) {
    this.server = server;
    this.logger = logger;

    CommandAPI.onLoad(new CommandAPIVelocityConfig(server, this));
}

Next, we want to utilise Velocity's ProxyInitializeEvent to perform the CommandAPI's enabling step:

java
@Subscribe
public void onProxyInitialization(ProxyInitializeEvent event) {
    // Any CommandAPI command registrations...
    CommandAPI.onEnable();
}

Current limitations ​

The CommandAPI currently only offers support for a very limited number of arguments on Velocity. This is because arguments are primarily implemented on the backend servers. However, the CommandAPI offers access to the primitive type arguments:

Registering a simple command ​

Command registration works the same way as it does in Bukkit. To visualize this, we want to register a simple command that generates a random number between a chosen minimum and a chosen maximum value:

Example – Registering a simple command ​

Example – Registering a simple command

We want to register the command /randomnumber with the following syntax:

mccmd
/randomnumber <min> <max>

To accomplish that, we register the command like this:

java
new CommandAPICommand("randomnumber")
    .withArguments(new IntegerArgument("min"))
    .withArguments(new IntegerArgument("max"))
    .executesPlayer((player, args) -> {
        int min = (int) args.get("min");
        int max = (int) args.get("max");
        Random random = ThreadLocalRandom.current();
        int randomNumber = random.nextInt(min, max);
        player.sendMessage(Component.text().content("Your random number is: " + randomNumber));
    })
    .register();

Updating Requirements ​

As explained on the page about command and argument requirements, you should run CommandAPI.updateRequirements(player) whenever conditions that affect whether a player can access a command change. However, Velocity is not able to resend commands to a client by itself; it only knows how to add commands to a packet the backend server sent. So, in order for updateRequirements to work, the CommandAPI needs to be able to tell the backend server to resend commands.

The CommandAPI Velocity plugin handles this by sending a plugin message to the backend server. In order for the backend server to process this message, you must add a plugin that understands CommandAPI plugin messages. You can easily do this by installing the CommandAPI Bukkit plugin or any plugin that shades CommandAPI version 10.0.0 or later to each backend server. However, the CommandAPI Bukkit plugin includes a lot of extra stuff to make registering commands work, which isn't necessary if you only need updateRequirements to work on Velocity. In this case, you can install the special CommandAPI Bukkit Networking plugin, which simply contains the code necessary to respond to plugin messages.

Whether you want to install the CommandAPI Bukkit plugin or the CommandAPI Bukkit Networking plugin, you can find the latest releases here.

So far, the CommandAPI only uses the plugin messaging system to implement updateRequirements on Velocity. If you're not using updateRequirements on Velocity, you don't need to install a CommandAPI plugin on your backend servers. It is possible that future features will take advantage of the plugin messaging system as CommandAPI Velocity is further developed. If this ever happens, you should see a clear error message prompting you to update to a compatible version.