Overview
SimpleCommand is the base class for creating commands in Foundation. It provides a clean, intuitive API that replaces Bukkit’s command system with enhanced features like automatic permission handling, cooldowns, argument validation, and built-in messaging utilities.
Class hierarchy
Creating a command
Constructor
Creates a new simple command with the given label.Separate the label with
| to split between label and aliases.Example: remove|r|rm will create a /remove command that can also be run by typing /r and /rm as its aliases.Creates a new simple command with explicit label and aliases.
Basic example
Registration
register()
Registers this command into Bukkit.Throws an error if the command is already registered.
register(boolean unregisterOldAliases)
Registers this command into Bukkit with options.
unregister()
Removes the command from Bukkit.Throws an error if the command is not registered.
Core methods
onCommand()
Required implementation. Executed when the command is run.You can access
sender and args fields directly within this method.Convenience checks
These methods throwCommandException internally which is caught and displayed to the player.
checkConsole()
Checks if the sender is console and throws an error if they are.Use this for player-only commands.
checkPerm(String permission)
Checks if the sender has the given permission.
checkArgs(int minimumLength, String falseMessage)
Checks if the command has the minimum number of arguments.
checkBoolean(boolean value, String falseMessage)
Checks if the given boolean is true, throws error with message if false.
checkNotNull(Object value, String messageIfNull)
Checks if the given object is not null.
Finding entities and values
findPlayer(String name)
Finds a non-vanished online player by name.Returns an error message to sender if player not found.
findPlayerOrSelf(int argsIndex)
Returns the player at the given args index, or the sender if they are a player and args are too short.
findOfflinePlayer(String name, Consumer<OfflinePlayer> callback)
Finds an offline player by name or UUID asynchronously.The lookup is done async, callback is executed synchronously.
findWorld(String name)
Finds a world by name. Use
~ to get the sender’s current world (if sender is a player).findMaterial(String name, String falseMessage)
Finds a material by name, works for both modern and legacy names.
findEnum(Class<T> enumType, String value, String falseMessage)
Finds an enumeration value by name.
findNumber(int index, String falseMessage)
Parses an integer from the args at the given index.
findNumber(int index, int min, int max, String falseMessage)
Parses an integer within bounds from the args at the given index.
findBoolean(int index, String invalidMessage)
Parses a boolean from the args at the given index.
findTime(String raw)
Converts a time string (e.g., “1 hour”, “30 minutes”) into a SimpleTime object.
Messaging
tell(String… messages)
Sends messages to the command sender.Automatically avoids prefix if 3 or more lines.
tellNoPrefix(String… messages)
Sends messages without any prefix.
tellSuccess(String message)
Sends a success message (typically green).
tellInfo(String message)
Sends an info message (typically blue).
tellWarn(String message)
Sends a warning message (typically yellow).
tellError(String message)
Sends an error message (typically red).
returnTell(String… messages)
Sends messages and stops command execution by throwing CommandException.
Configuration
setMinArguments(int minArguments)
Sets the minimum number of arguments required to run this command.
setCooldown(int cooldown, TimeUnit unit)
Sets the cooldown time before the same player can execute this command again.
setCooldownBypassPermission(String permission)
Sets a permission that allows players to bypass the cooldown.
setCooldownMessage(String message)
Sets a custom cooldown message. Use
{duration} to display remaining time.setPermission(String permission)
Sets the permission required to run this command.Set to
null to allow everyone (unsafe).setTellPrefix(String prefix)
Sets a custom prefix for messages sent by this command.
Tab completion
tabComplete()
Override this method to provide tab completion suggestions.Return
null to complete player names automatically.completeLastWord(T… suggestions)
Automatically completes the last argument with the given suggestions.Only returns suggestions that start with what the player typed.
completeLastWordPlayerNames()
Completes with all visible, non-vanished player names.
completeLastWordWorldNames()
Completes with all world names.
Utility methods
getPlayer()
Gets the sender as a Player, or null if sender is not a player.
isPlayer()
Returns whether the sender is a living player.
hasPerm(String permission)
Checks if the sender has the given permission.
getLastArg()
Returns the last argument in the args array.
joinArgs(int from)
Joins arguments from the given index to the end with spaces.
joinArgs(int from, int to)
Joins arguments from the given range with spaces.
Protected fields
The command sender. Updated dynamically when the command is executed.
The command arguments. Updated dynamically when the command is executed.
An empty list used to disable tab completion.
Complete example
See also
- SimpleCommandGroup - For creating command groups with subcommands
- SimpleSubCommand - For creating subcommands within a group