Command conversion

Developer's Note:

If you're a server owner, you're probably lost! This section is for developer command conversion. If you're looking for how to convert plugins with the config.yml file, you want 2. Configuration for server owners.

The CommandAPI has the ability to convert plugin commands to vanilla Minecraft commands using its config.yml's plugins-to-convert option. Nevertheless, the API for command conversion is not hidden and you're free to use it as you see fit!

Before you continue, let's clear up a few naming conventions which is used in the following sections!

  • Target plugin - This refers to a non-CommandAPI plugin which registers normal Bukkit commands. This typically uses the old boolean onCommand(CommandSender ... ) method
  • Your plugin - This refers to your plugin, the one that uses the CommandAPI and wants to add compatibility to a target plugin

Entire plugins

To register all commands that are declared by a target plugin, the Converter.convert(Plugin) method can be used. This attempts to register all commands declared in a target plugin's plugin.yml file, as well as any aliases or permissions stated in the plugin.yml file.

Example - Converting commands for a target plugin

Say you have some plugin.yml file for a target plugin that adds some basic functionality to a server. The target plugin in this example is called "TargetPlugin":

name: TargetPlugin
main: some.random.package.Main
version: 1.0
commands:
  gmc:
    aliases: gm1
  gms:
  i:
    permission: item.permission

As you can see, it declares 3 commands: /gmc, /gms and /i. We can now begin writing your plugin that uses the CommandAPI converter. We will call this plugin "YourPlugin":

public class YourPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        Converter.convert((JavaPlugin) Bukkit.getPluginManager().getPlugin("TargetPlugin"));
        // Other code goes here...
    }
    
}

class YourPlugin : JavaPlugin() {

    override fun onEnable() {
        Converter.convert(Bukkit.getPluginManager().getPlugin("TargetPlugin") as JavaPlugin)
        // Other code goes here...
    }

}

When this is run, the commands /gmc, /gm1, /gms and /i will all be registered by the CommandAPI.

Only specific commands

In addition to converting all commands from a target plugin, the CommandAPI allows you to convert single commands at a time using the following methods from the Converter class:

public static convert(Plugin plugin, String cmdName);
public static convert(Plugin plugin, String cmdName, List<Argument> arguments);
public static convert(Plugin plugin, String cmdName, Argument... arguments);

In these commands, the plugin refers to the plugin which has the command you want to convert and cmdName is the name of the command declared in the target plugin's plugin.yml file (just the main command, not the aliases!).

The List<Argument> or Argument... can be used to provide argument checks that lets you apply the command UI to a bukkit command.

Example - Converting EssentialsX's speed command

Say we want to convert EssentialsX's /speed command using the CommandAPI. The plugin.yml entry for the /speed command is the following:

  speed:
    description: Change your speed limits.
    usage: /<command> [type] <speed> [player]
    aliases: [flyspeed,eflyspeed,fspeed,efspeed,espeed,walkspeed,ewalkspeed,wspeed,ewspeed]

From this, we can determine that there are the following commands, where "walk" and "fly" are the different types that the command can take:

/speed <speed>
/speed <speed> <target>
/speed <walk/fly> <speed>
/speed <walk/fly> <speed> <target>

With the EssentialsX plugin, the <speed> value can only take numbers between 0 and 10. As such, we'll ensure to apply these limits using the IntegerArgument. In addition, since the speed type can only be "walk" or "fly", we'll add that to our converter as well using a MultiLiteralArgument:

JavaPlugin essentials = (JavaPlugin) Bukkit.getPluginManager().getPlugin("Essentials");

// /speed <speed>
Converter.convert(essentials, "speed", new IntegerArgument("speed", 0, 10));

// /speed <target>
Converter.convert(essentials, "speed", new PlayerArgument("target"));

// /speed <walk/fly> <speed>
Converter.convert(essentials, "speed", 
    new MultiLiteralArgument("modes", List.of("walk", "fly")),
    new IntegerArgument("speed", 0, 10)
);

// /speed <walk/fly> <speed> <target>
Converter.convert(essentials, "speed", 
    new MultiLiteralArgument("modes", List.of("walk", "fly")),
    new IntegerArgument("speed", 0, 10), 
    new PlayerArgument("target")
);

val essentials = Bukkit.getPluginManager().getPlugin("Essentials") as JavaPlugin

// /speed <speed>
Converter.convert(essentials, "speed", IntegerArgument("speed", 0, 10))

// /speed <target>
Converter.convert(essentials, "speed", PlayerArgument("target"))

// /speed <walk/fly> <speed>
Converter.convert(essentials, "speed",
    MultiLiteralArgument("modes", listOf("walk", "fly")),
    IntegerArgument("speed", 0, 10)
)

// /speed <walk/fly> <speed> <target>
Converter.convert(essentials, "speed",
    MultiLiteralArgument("modes", listOf("walk", "fly")),
    IntegerArgument("speed", 0, 10),
    PlayerArgument("target")
)

An image showing /execute run for EssentialsX's /speed command