Annotations

Annotations

This document will describe the available annotations and where and how they can be used.

CatchUnknown

• On a Subcommand to define a fallback method for all uncatched commands. Example if you don't have /foo bar declared, then the method annotated with @CatchUnknown catches the unknown command. ACF tries to convert the given arguments to your method signature.

CommandAlias

• On the Class itself to define the base commands for all sub commands defined, separate with | to define multiple
• On Subcommands to define aliases for the subcommand as root commands. Example if your command is /foo bar then adding a @CommandAlias("fb") makes /fb the same as /foo bar.

CommandCompletion

• Defined on Subcommands. Defines the possible command completions for each argument.
• If you have 3 arguments to your command, and you supply Foo|foo1 bar|bar2 baz|baz3 then when you press tab on the first arg, you will receive Foo and foo1 as completion options, on arg 2 you will receive bar and bar2, etc...

CommandPermission

• On the Class itself to require a permission node to execute all Subcommands in the class @CommandPermission("boo.far").
• On Subcommands to require a permission node to execute the command @CommandPermission("foo.bar").
• It also can restrict the displayed @CommandCompletion list.

Optional

• Can only be used (currently) at end of the command for non Player arguments. Makes it so that if nothing is entered to resolve this context, it will simply return null.
• Any arg of type Player will verify its a Player executing it, and give the console an error. If the player can be optional, you may use @Optional on it and it will be null.

Default

• On an argument: Similar to @Optional, but instead of returning null, it fills in a default value, and passes that value to the context resolver.
• On a method: Indicates the default command without any arguments. Example: /foo will be catched by the @Default annotated method.

Flags

• Used to change the behavior of Context Resolvers. With the introduction of @Conditions, @Flags should be reserved for manipulating how to resolve the object only, to change the behavior of the look up process. For restrictions after the object has been resolved, use @Conditions

Conditions

• Used to apply restrictions on command execution. You can register your own Command Conditions then apply them with @Conditions("id")

Single

• By default, a String argument at the end of command signature is expected to consume "everything remaining", if you want it to ignore extra text and only consume a single word input, use this.

Split

• Applied on String[], defines a character to split on So if the user types foo,bar and you have @Split(",") you will get an array of strings with foo and bar.

Subcommand

• Defines a subcommand on a Command class
• May use spaces to separate depth, for example @Subcommand("foo bar baz") would require the command start with foo bar baz to match to this sub command, and then everything after baz is passed to the arguments for resolve.
• You may pipe delimit every part to provide alter versions, and every possible permutation will be available. For example foo|f bar|b will provide:
  • foo bar
  • foo b
  • f bar
  • f b

Syntax

• ACF will automatically generate syntax formats for you on incorrect usage of commands. This lets you override that. @Syntax("<foo> - Something something")

Values

• Restricts input to a static list of Values, and errors if does not match
• Can be dynamic by using Command Completion codes
• If this is set on the last parameter that happens to be a string, the @Single rule is enforced, and it will not consume the rest of the input.

HelpCommand

• Shortcut for @Default if not set on something else already, @UnknownHandler if not set already on something, and @Subcommand("help")
• If you are using @Default or @UnknownHandler for other purposes, ensure your method with @HelpCommand is BELOW those methods to ensure the other methods are used instead.
• Useful with the Command Help System by using CommandHelp context, to generate help document on any failed command.

Private

• Hides a command from tab completion or help pages.
• Useful for commands that are triggered indirectly, for example by clicking on a chat component in the chat or in a book.

Name

• Changes the display name of a parameter (on help or usage messages).
• The display name is fetched from the key acf-core.parameter.<name>. For example, @Name("player") will get the string from "acf-core.parameter.player".