aikar/commands

Java Command Dispatch Framework - (Bukkit, Spigot, Paper, Sponge, Bungee, JDA, Velocity supported, generically usable anywhere)

Hi there 👋

Hello, I'm Aikar. Been around the block in open source for a long time bouncing between a few game projects. Most of my focus is in Minecraft for the most recent years. Many in the developer community here should know me for my work on Paper (and previously Spigot), working to improve the server performance.

My specialty is in performance optimizations, but also DEATH TO BOILERPLATE software libraries.

• aikar.co - My Personal and mostly dormant blog I occasionally rant.
• empireminecraft.com - My Minecraft Server, Empire Minecraft
• My Minecraft JVM Flags Guide

Paper	Donate	Empire Minecraft
Paper, the highest performance Minecraft Server	Want to donate?	Try out my Survival Server

Check out pinned repo's for some of my most recent work.

commands's Issues

Properly support custom sender objects

18:43> ~Aikar>I do want to add a "SenderAwareOnlyResolver"
18:43> ~Aikar> that never consumes input
18:44> ~Aikar> then we know for sure that its optional and not put it in syntax strings

Auto Help System

Provide a @description type annotation for documenting purpose of command

Provide mechanisms for automatic help display, such as failed to find subcommands

__unknown registered in every command, improve unknown impl

This triggers the duplicate subcommand warning.
do something to improve this overall, moving unknown to an annotation rather than magic command name/signature.

Command Contexts

Need way to register and override Command Context handlers.

Provide way to access old handler before overwriting to fallback

[Question/Suggestion?] User input subcommand?

Is there a way one could use the subcommand inner class/method structure to make one of the subcommands user input? For example, a command like:

/arena <arena name> spawn

or

/perms user <user name> group set <group name>

And if not, could this possibly be implemented?
Thanks!

Add 'addCheck' method to CommandManager

In my opinion, the main problem with command frameworks is that you never have full control over them, which can result in either having to do some hacky methods to get it to do what you want, or just not using the framework but your own solution.

Issue #57 is a good example of this. If you want to add a default cooldown/per command cooldown, you'll have to modify ACF for it to work. My idea is to add a method to the CommandManager, something along the lines of CommandManager#addCheck(Check), where Check is a functional interface which looks like this:

interface Check {
    boolean check(Sender sender, String name, String[] args, Method method);
}

Again, using Issue #57 as an example, you can do this:

myCommandManager.addCheck((sender, name, args, method) -> {
    boolean hasCooldown; //check if sender has cooldown
    if(hasCooldown) return false; //Command will not be executed
    
    int cooldown = method.getAnnotation(CommandCooldown.class).value(); //get cooldown (or default cooldown)
    //set cooldown for sender
   return true; //Command will be executed
});

java.lang.NoSuchMethodError on PluginDisableEvent

[16:50:46] [Server thread/ERROR]: Could not pass event PluginDisableEvent to AdvancedKitsReloaded v1.0.4-pre
org.bukkit.event.EventException
	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:306) ~[spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:62) ~[spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at org.bukkit.plugin.SimplePluginManager.fireEvent(SimplePluginManager.java:502) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:487) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at org.bukkit.plugin.java.JavaPluginLoader.disablePlugin(JavaPluginLoader.java:355) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at org.bukkit.plugin.SimplePluginManager.disablePlugin(SimplePluginManager.java:424) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at org.bukkit.plugin.SimplePluginManager.disablePlugins(SimplePluginManager.java:417) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at org.bukkit.craftbukkit.v1_11_R1.CraftServer.disablePlugins(CraftServer.java:345) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at net.minecraft.server.v1_11_R1.MinecraftServer.stop(MinecraftServer.java:464) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at net.minecraft.server.v1_11_R1.MinecraftServer.run(MinecraftServer.java:612) [spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	at java.lang.Thread.run(Unknown Source) [?:1.8.0_121]
Caused by: java.lang.NoSuchMethodError: org.bukkit.command.CommandMap.getKnownCommands()Ljava/util/Map;
	at hu.tryharddevs.advancedkits.utils.afc.BukkitCommandManager.lambda$unregisterCommand$0(BukkitCommandManager.java:128) ~[?:?]
	at java.util.Collection.removeIf(Unknown Source) ~[?:1.8.0_121]
	at hu.tryharddevs.advancedkits.utils.afc.BukkitCommandManager.unregisterCommand(BukkitCommandManager.java:125) ~[?:?]
	at hu.tryharddevs.advancedkits.utils.afc.BukkitCommandManager.unregisterCommands(BukkitCommandManager.java:141) ~[?:?]
	at hu.tryharddevs.advancedkits.utils.afc.BukkitCommandManager$1.onPluginDisable(BukkitCommandManager.java:69) ~[?:?]
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.8.0_121]
	at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source) ~[?:1.8.0_121]
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source) ~[?:1.8.0_121]
	at java.lang.reflect.Method.invoke(Unknown Source) ~[?:1.8.0_121]
	at org.bukkit.plugin.java.JavaPluginLoader$1.execute(JavaPluginLoader.java:302) ~[spigot-1.11.2.jar:git-Spigot-54ec0b8-e04a179]
	... 10 more

• Group: co.aikar
• Artifact: acf-core
• Version: 0.4.0-SNAPSHOT

Optional resolvers are bugged

Since e50e906 ACF tries to resolve Optional parameters

Problem with the @Default and @Optional annotations.

For some reason the forceuse is always false.
If I change the @Default("false") to @Default("true") the value still remains false, the same when I remove the @Default and the @Optional annotations.
Also there's nothing happening when I hit the tab. (It should autocomplete to true|false)

Code:

@CommandAlias("kit|akit|advancedkits|kits|akits")
public class GiveCommand extends BaseCommand {
	private final AdvancedKitsMain instance;

	public GiveCommand(AdvancedKitsMain instance) {
		this.instance = instance;
	}

	@Subcommand("give")
	@CommandPermission("advancedkits.give")
	@CommandCompletion("@kits @players true|false")
	@Syntax("<kitname> <player> [forceuse]")
	public void onGiveCommand(CommandSender sender, Kit kit, Player player, @Optional @Default("false") Boolean forceuse) {

		if (Objects.isNull(player)) {
			sendMessage(sender, getMessage("playerNotFound"));
			return;
		}
		if (player.isDead()) {
			sendMessage(sender, getMessage("playerIsDead"));
			return;
		}

		User user = User.getUser(player.getUniqueId());

		player.sendMessage(String.valueOf(forceuse));
		// Says forceuse is "false" no matter what.

		if (forceuse) {
			if (!user.isUnlocked(kit)) {
				user.addToUnlocked(kit);
				user.save();
			}
			Bukkit.dispatchCommand(player, "advancedkitsreloaded:kit use " + kit.getName());
			sendMessage(sender, getMessage("successfullyGiven", kit.getName(), player.getName()));
		} else if (!user.isUnlocked(kit)) {
			user.addToUnlocked(kit);
			user.save();
			sendMessage(sender, getMessage("successfullyGiven", kit.getName(), player.getName()));
		} else {
			sendMessage(sender, getMessage("giveAlreadyUnlocked", kit.getName()));
		}
	}
}

With the latest version:

#Generated by Maven
#Sat May 20 12:28:45 EDT 2017
version=0.4.0-SNAPSHOT
groupId=co.aikar
artifactId=acf-core

MinecraftKey / NamespacedKey Context Resolver

This would allow for providing a command with a MinecraftKey / NamespacedKey (ex.: minecraft:stone) as well as a few command completions (blocks, items, achievements/advancements, etc.)

Handle Recursively looking up for Command Permiisson Requirements

right now we support it on sub and class, but if its an inner class, it also needs to inherit from the parent class.

and require all nodes defined.

Support per-issuer Locale (Bukkit)

Provide the ability to define Locales on a per-issuer basis.

Bukkit: Auto look up the locale property in EntityPlayer

Project Name

Aikar Commands is lame

Ideas for name of project?

Allow Innerclasses to provide same base Subcommands

For example I have tons of sub commands labeled @subcommand("roles|roles XXXXX")

I should be able to do

public class EmpireCommand extends BaseCommand {
    @Subcommand("roles|role")
    public class RolesSubcommands extends BaseSubcommand {
         @Subcommand("addperm")
         public void onRoleAddPerm(Player player) { }
    }
}

And on register, it scans all inner classes that extend BaseSubcommand and auto register them using the parent class

This should work recursively if we can....

Timings Error

12.05 15:31:15 [Server] WARN org.bukkit.plugin.AuthorNagException: Deprecated use of CustomTimingsHandler. Please Switch to Timings.of ASAP 12.05 15:31:15 [Server] WARN at org.spigotmc.CustomTimingsHandler.<init>(CustomTimingsHandler.java:58) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.timings.lib.SpigotTiming.<init>(SpigotTiming.java:11) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.timings.lib.TimingType$1.newTiming(TimingType.java:11) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.timings.lib.TimingManager.of(TimingManager.java:62) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.afc.RegisteredCommand.getTiming(RegisteredCommand.java:214) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.afc.BaseCommand.executeCommand(BaseCommand.java:393) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.afc.BaseCommand.executeSubcommand(BaseCommand.java:471) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.afc.BaseCommand.execute(BaseCommand.java:330) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.afc.RootCommand.execute(RootCommand.java:71) 12.05 15:31:15 [Server] WARN at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:151) 12.05 15:31:15 [Server] WARN at org.bukkit.craftbukkit.v1_11_R1.CraftServer.dispatchCommand(CraftServer.java:675) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.PlayerConnection.handleCommand(PlayerConnection.java:1393) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.PlayerConnection.a(PlayerConnection.java:1198) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.PacketPlayInChat.a(PacketPlayInChat.java:45) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.PacketPlayInChat.a(PacketPlayInChat.java:5) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.PlayerConnectionUtils.lambda$ensureMainThread$0(PlayerConnectionUtils.java:14) 12.05 15:31:15 [Server] WARN at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511) 12.05 15:31:15 [Server] WARN at java.util.concurrent.FutureTask.run(FutureTask.java:266) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.SystemUtils.a(SourceFile:46) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.MinecraftServer.D(MinecraftServer.java:830) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.DedicatedServer.D(DedicatedServer.java:403) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.MinecraftServer.C(MinecraftServer.java:754) 12.05 15:31:15 [Server] WARN at net.minecraft.server.v1_11_R1.MinecraftServer.run(MinecraftServer.java:652) 12.05 15:31:15 [Server] WARN at java.lang.Thread.run(Thread.java:745) 12.05 15:31:15 [Server] WARN org.bukkit.plugin.AuthorNagException: Deprecated use of CustomTimingsHandler. Please Switch to Timings.of ASAP 12.05 15:31:15 [Server] WARN at org.spigotmc.CustomTimingsHandler.<init>(CustomTimingsHandler.java:58) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.timings.lib.SpigotTiming.<init>(SpigotTiming.java:11) 12.05 15:31:15 [Server] WARN at hu.tryharddevs.advancedkits.utils.timings.lib.TimingType$1.newTiming(TimingType.java:11)

Register Command Completions

Like Context Resolvers, need ability to register new @ codes, pref as object handlers

CommandFlags annotation to define parameter Flags on all subcommands

@CommandFlags({{Empire.class, "foo"}, {EmpireRole.class, "bar"}}) on the root command node to apply a flag to all subcommands parameters

This would be same as adding @flags("foo") to all parameters of type Empire and "bar" to all of type EmpireRole

Document Exception handling

Wiki lacks documentation for exception handling overall. Please document it, and specifically the fact that the method receives InvocationTargetException as opposed to the exception that caused it. I personally would consider passing the cause, but if this is an umbrella exception catching feature, maybe keep it as is. :)

Thanks

Semantics: rename @UnknownHandler to @CatchAll

This would make no functional difference. This is just a suggestion to rename the wording of the UnknownHandler interface to CatchAll, to better describe its functionality. Since UnknownHandler acts as the default route for those inputs which can't otherwise be routed, CatchAll would make more sense since it catches those which can't be routed. Both make sense as is, but, in my opinion, CatchAll is clearer.

Discuss?

Rename CommandUtil to ACFUtil and expose it

This is mostly what I have in Empire Util class.

While lot of this isn't related to ACF, no harm in exposing it for people to use!

need to rename class and add public to the class (and ensure all methods are public)

Unknown root command handling

May need paper only as a feature, but provide way to auto handle unknown root commands, and provide list of commands /help style, mixing Aikar command and Bukkit Commands

Relates with #3

Another plugin has hijacked the command map

[17:06:34] [Server thread/ERROR]: Failed to get Command Map. ACF will not function.
[17:06:34] [Server thread/ERROR]: Error occurred while enabling AdvancedKitsReloaded v1.1.2 (Is it up to date?)
java.lang.NoSuchFieldException: knownCommands
at java.lang.Class.getDeclaredField(Class.java:2070) ~[?:1.8.0_72]
at hu.tryharddevs.advancedkits.utils.afc.BukkitCommandManager.(BukkitCommandManager.java:59) ~[?:?]
at hu.tryharddevs.advancedkits.utils.afc.ACF.createManager(ACF.java:44) ~[?:?]
at hu.tryharddevs.advancedkits.AdvancedKitsMain.onEnable(AdvancedKitsMain.java:79) ~[?:?]

spigot-1.11.2.jar:git-Spigot-7d78b81-e232e15

CommandCooldown Annotations..

Can you add a system that allows you to put a cooldown on commands?

With a default value (in seconds) and an other value that can be reassigned to the commands you want.

Example:

commandManager.setDefaultCommandCooldown(2.5);

@Default
@CommandCooldown(5.0)
@CommandPermission("staff.example")
@UnknownHandler
public void onCommand(Player player) {

}

Automatic Brigadier Support

Goal is to automatically register ACF commands into Brigadier on Sponge and Bukkit.

https://gist.github.com/Dinnerbone/7370a2846953eee2d8fc64514fb76de8

Command Replacement Strings

Able to register common template strings that are reused in your commands
so you can do @CommandPermission("%staff")
instead of defining your exact perm node every time

Usable in all annotation inputs, syntax, values, default, subcommand, commandalias, commandpermission, flags

register bound to plugin objects

right now its hard coded into "empire" name space. need to figure out how were going to do registration.

Remove automatic registration on instantiation and make Commands.register(plugin, instance) ?

java.lang.NoClassDefFoundError: co/aikar/timings/lib/TimingManager

You could shade this dependency into the repo's jar. :)

Problems with @Default and @CommandAlias annotations

Reproducing: Registering more subcommands in different classes.

Fix: Registering the class after the other ones.

---

Root command doesn't get triggered

		
@CommandAlias("kit|akit|advancedkits|kits|akits")
public class MainCommand extends BaseCommand {
	private AdvancedKitsMain instance;
public MainCommand(AdvancedKitsMain instance) {
	this.instance = instance;
}


@Default
public void onDefault(CommandSender sender) {
	sender.sendMessage("Testing default command");
}

@Subcommand("help")
public void onHelp(CommandSender sender) {
	sender.sendMessage("Testing help command");
}

}

CommandAliases doesn't trigger subcommands

---

With the latest version: 0.4.0-SNAPSHOT
(Source code for the plugin: https://github.com/TryHardDood/AdvancedKitsReloaded)

Support Command Completion @codes in @Values

@values("auto|true|false|yes|no|1|0|on|off")

should be a @values("@truthy")

Where @truthy is all those values
(So need a new Command Completion for it too)

I18N Framework

Refactor messaging and such so that a manager is able to change language files

Then support i18n in all the annotations such as:

• CommandAlias
• Subcommand
• Syntax
• CommandCompletion
• Values
• Optional
• Default

Add annotation for matching an arg with regex

If you run a command, and you need the player to input the information in a specific format: "days:12".

This would be in the command's method: @matches("RegEx") String time

Setting color format using CommandManager#setFormat ignores first argument

The method CommandManager#setFormat gets the current color profile and iterates through its parameters, setting each value to a new one. But this method has a couple flaws:
First of all, the MessageFormatter#setColor method decreases its index parameter by one if above zero and sets everything else to zero. This means that setColor(0, x) and setColor(1, x) are effectively equivalent and the first call is ignored.
Additionally it would probably be a good idea to clear the list and then to just add the new color, to cleanup leftover default colors, in case you add less than there were previously.

Wiki Documentation

document stuff, you know, once this is done and usable

Unit Tests

setup unit test

[Suggestion/Idea] Easier command creation.

It would be easier to register the root command instead of this:
@CommandAlias("root|r")
like this: CommandManager cm = new CommandManager(this, "Prefix tag", "basepermission", "root", "r", "rootaliases")

Then you could register subcommands like this:

cm.loadCommandClass(MainCommand.class);
cm.loadCommandClass(new MyCommand(this));

This is just a suggestion/idea

---

@Stumblinbear made an api like this:

• https://gist.github.com/Stumblinbear/c27f1fe584c130690b8f

Annotation request: Player only.

@Subcommand("command")
@PlayerOnly
public void onMyCommand(CommandSender sender) {}

or

@Subcommand("command")
@Only(Sender.PLAYER)
public void onMyCommand(CommandSender sender) {}

Optional permission nodes

Would it be possible to do something like:

@CommandPermission("test.permission")
public void onTest(Player player, @Optional("test.permission.optional") Player test) {}

root commands do not work on 2+ classes

scenario: 2 classes, both define CommandAlias("foo|bar|baz")

subcommand one is defined in first class, two in 2nd class.

two is not accessible and says unknown command as it routes to first

Issue here: benjaminforras/AdvancedKitsReloaded#48

Locales: Remove Reflections

aikar/locales#1

SpongeRootCommand doesn't override RootCommand#getDefCommand()

This seems like a simple oversight, not sure why it hasn't been reported before.

Stacktrace for reference: https://pastebin.com/4kX2vG6r

Bungeecord being included when shading ACF-Bungee

I forgot to add provided to the bungeecord dependency when I pull requested.
Didn't really know if this was worth a pull request so I just opened an issue

Handle Breaking up Subcommands into multiple classes of same base command

Have the ability for multiple Command instances to use the same root command.
This is so you can organize your commands such as

ResdienceCommand
ResidenceAdminCommand

We will accomplish this by not registering the command instances directly to the Command map, and instead a "Forwarding" command.

This forwarding command will contain the subcommand map, and look up the command instance that owns the registered sub command, and forward the call to it.

We need to add a warning if 2 instances try to register the same subcommand

[Request] Show subcommands instead of /help

When I type an invalid subcommand it says: Unknown Command, please type /help
Why doesn't is shows the available subcommands with the syntax instead of that message.

Edit: Wouldn't it be better When a player types the basecommand it would show the available subcommands with the syntax instead of nothing?

Locales: Handle InvalidCommandArgument

Issuer Only Context messing up completions

@CommandCompletion("@groupmembers") // TODO: Make ACF support skipping group for completions
    @Syntax("<player> &e- Locate a player in your group using a compass.")
    public static void onGroupMemberLocate(Player player, Group group, OnlinePlayer toTarget) {

group members is getting processed for Group, which doesn't need to be completed.

Only supports 1.9+

I am aware that support for versions lower than 1.9 is probably not your primary concern, but since 1.8.x versions are still commonly used I thought this should be brought up.

When checking the player's hand for an item, a method only added in 1.9+ is used to obtain the ItemStack object, namely the PlayerInventory#getItemInMainHand method.

Since this method does not exist in 1.8 it will throw a NoSuchMethodError at runtime, if used on a server running that version.

The use of the version-incompatible method is located here.

Unable to define command completions for an unknown handler

If you have defined a small command class with no other defined SubCommands (only time this is relevant); ACF currently does not read @CommandCompletions from either the class or the @UnknownHandler method.

java.lang.NoSuchMethodError CommandTiming

Successfully shaded the dependencies but there's one missing class.
Caused by: java.lang.NoSuchMethodError: hu.tryharddevs.advancedkits.utils.timings.lib.TimingManager.of(Ljava/lang/String;)Lhu/tryharddevs/advancedkits/utils/timings/lib/CommandTiming;

Google Cache multiple versions compatibility..

Hello, can you add compatibility with versions 1.7 to 1.12 ?

Your ACFPatterns class causes errors due to the LoadingCache and CacheLoader classes. Here is a class that could help you do what I ask:

• UserMap [Essentials]

I would like you to do this because I use this fork in my Stawlkalibur plugin, link here: https://www.spigotmc.org/resources/stawlkalibur-almost-ready-only-java-8.12510/

Rename command.seevanish perm to acf.seevanish