personthecat.catlib.command.annotations.ModCommand Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of catlib-quilt Show documentation
Utilities for serialization, commands, noise generation, IO, and some new data types.
The newest version!
package personthecat.catlib.command.annotations;

import com.mojang.brigadier.builder.ArgumentBuilder;
import personthecat.catlib.command.CommandContextWrapper;
import personthecat.catlib.command.CommandSide;
import personthecat.catlib.command.CommandType;
import personthecat.catlib.linting.SyntaxLinter;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Indicates that a method should be passed into the registration context as
 * the body of a command. Annotated methods should be static and accept
 * a single parameter: {@link CommandContextWrapper}.
 * 
 *   To begin using this annotation, provide a single value: name.
 *   This token will become the literal argument required for using the
 *   command. Here's an example of a basic command using this setup:
 * 
 *     @ModCommand(name = "command")
 *     private static void myCommand(final CommandContextWrapper wrapper) {
 *         wrapper.sendMessage("Hello, world!");
 *     }
 * 

 *   In addition, CatLib will take care of generating a help command for your
 *   mod. You can enable this feature per command by providing a description.
 * 
 *     @ModCommand(
 *         name = "command",
 *         description = {
 *             "Runs the demo command. You can provide additional lines,",
 *             "but they will be formatted and wrapped automatically."
 *         }
 *     )
 *     private static void myCommand(final CommandContextWrapper wrapper) {}
 * 

 *   Most commands are substantially more complicated than this setup allows.
 *   You can begin adding additional arguments to your command by providing a
 *   branch of {@link Node}s.
 * 
 *     @ModCommand(
 *         name = "command",
 *         description = "Runs the demo command.",
 *         branch = {
 *             @Node(name = "arg1", type = BlockStateArgument.class),
 *             @Node(name = "arg2", type = ItemInput.class, optional = true)
 *         }
 *     )
 *     private static void myCommand(final CommandContextWrapper wrapper) {
 *         // The first argument must exist:
 *         final BlockState block = wrapper.getBlock("arg1");
 *         // But the second is optional and may not:
 *         final Optional<ItemInput> item = wrapper.getOptional(ItemInput.class);
 *     }
 * 

 *   To register more complex tree structures, you may need to provide multiple
 *   annotated methods with the same name. Brigadier will take care
 *   of resolving duplicate arguments into a single tree.
 * 
 *     @ModCommand(name = "sayHello")
 *     private static void sayHello(final CommandContextWrapper wrapper) {
 *         wrapper.sendMessage("Hello!")
 *     }
 *
 *     @ModCommand(
 *         name = "sayHello"
 *         branch = @Node(name = "name", stringValue = @StringValue(type = Type.WORD))
 *     )
 *     private static void sayHelloName(final CommandContextWrapper wrapper) {
 *         wrapper.sendMessage("Hello, {}!", wrapper.getString("name"));
 *     }
 * 

 *   For more information on setting up branches, see {@link Node}.
 * 
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ModCommand {

    /**
     * The first literal argument used to run this command. If absent, this will
     * default to the name of the declaring method.
     */
    String name() default "";

    /**
     * Optional alias for name used for declaring no-argument commands.
     *
     * Note that neither value nor name is required. If both are absent, the
     * command value will default to the name of the declaring method.
     */
    String value() default "";

    /**
     * Optional subtext to display on the help page.
     *
     * 
Note that, if this value is absent, the subtext will be generated
     * from the command node branch.
     */
    String arguments() default "";

    /**
     * The automatically-formatted help information to display on the generated
     * help page. Leave this out if you don't want the library to generate a
     * help entry for this command.
     */
    String[] description() default {};

    /**
     * An optional linter used to highlight text output in the chat. If a linter
     * is not provided, the default {@link SyntaxLinter} instance will be used
     * instead. Note that your output messages will not be linted automatically.
     * 

     *   You must call a variant of {@link CommandContextWrapper#sendLintedMessage}
     *   to take advantage of the feature.
     * 
     */
    Class[] linter() default {};

    /**
     * An array of command node descriptors used for generating {@link ArgumentBuilder}s.
     * 
     *   For more information on using this feature, see {@link Node}.
     * 
     */
    Node[] branch() default {};

    /**
     * The type of command being generated. Either a sub command of the main mod
     * command or a global command registered to the root command node.
     */
    CommandType type() default CommandType.MOD;

    /**
     * The server side required for running this command. You can specify either
     * the dedicated or integrated server side, but by default, either side will
     * be accepted.
     */
    CommandSide side() default CommandSide.EITHER;
}