Creating Commands

Basic Commands

To create a new command, you need a class to store the command in. The class should be annotated with the @RegisterCommands annotation.

Inside the class you have a method of each command. The name of the command is based-on the method name, so a name of isTutorial would create a command called isTutorial. The command method should be annotated with a @Command annotation.

The @Command annotation can take the following arguments.

@Command(
    // The name of the command, if specified. Otherwise the method name is used.
    value = "",
    // A short summary of what this command does
    shortDescription = "",
    // A detailed description of how to use this command
    helpText = ""
)

Basic command example

The sample command below states if the game is currently running the tutorial. The @Game annotation is used before the method parameter to signify that the SolGame instance should be passed-in there.

package org.destinationsol.game.console.commands;

import org.destinationsol.game.SolGame;
import org.destinationsol.game.console.annotations.Command;
import org.destinationsol.game.console.annotations.Game;
import org.destinationsol.game.console.annotations.RegisterCommands;
import org.destinationsol.game.console.exceptions.CommandExecutionException;

@RegisterCommands
public class TutorialCommandHandler {
    @Command(shortDescription = "States if this is the tutorial")
    public String isTutorial(@Game SolGame game) throws CommandExecutionException {
        if (!game.isTutorial()) {
            throw new CommandExecutionException("This is not the tutorial!");
        }
        return "This is the tutorial!";
    }
}

Commands with arguments

Command arguments are specified as parameters to the command method. Each parameter to be used as an argument is annotated with a @CommandParam annotation.

The @CommandParam annotation takes the following arguments.

@CommandParam(
    // The parameter name
    value = "",
    // Whether the argument value is required to be present on command execution or not
    required = true,
    // The class used for suggesting values for this parameter
    suggester = EmptyCommandParameterSuggester.class
)

The suggester is an optional type that allows for auto-completion of a parameter. It suggests possible values based on the user's partial inputs.

As an example of a position suggester, have a look at the built-in PositionFormatSuggester.

package org.destinationsol.game.console.suggesters;

import org.destinationsol.game.SolGame;
import org.destinationsol.game.console.CommandParameterSuggester;
import org.destinationsol.game.console.commands.PositionCommandHandler;

import java.util.HashSet;
import java.util.Set;

public class PositionFormatSuggester implements CommandParameterSuggester<PositionCommandHandler.PositionFormat> {
    @Override
    public Set<PositionCommandHandler.PositionFormat> suggest(SolGame game, Object... resolvedParameters) {
        Set<PositionCommandHandler.PositionFormat> suggestions = new HashSet<>();
        suggestions.add(PositionCommandHandler.PositionFormat.TERSE);
        suggestions.add(PositionCommandHandler.PositionFormat.VERBOSE);
        suggestions.add(PositionCommandHandler.PositionFormat.INTERNAL);
        suggestions.add(PositionCommandHandler.PositionFormat.BOLD);
        return suggestions;
    }
}

Command with arguments example

package org.destinationsol.game.console.commands;

import org.destinationsol.game.console.annotations.Command;
import org.destinationsol.game.console.annotations.RegisterCommands;
import org.destinationsol.game.console.annotations.CommandParam;

@RegisterCommands
public class EchoCommandHandler {
    @Command(shortDescription = "Echos the input text")
    public String echo(@CommandParam(value = "text") String text) {
        return text;
    }
}