Literal arguments
Literal arguments are used to represent "forced options" for a command. For instance, take Minecraft's /gamemode
command. The syntax consists of the following:
/gamemode <mode>
/gamemode <mode> <player>
It consists of a gamemode, followed by an optional player argument. The list of gamemodes are as follows:
/gamemode survival
/gamemode creative
/gamemode adventure
/gamemode spectator
Unlike regular commands (as those implemented by Bukkit for example), these four options are "hardcoded" - they're not "suggestions". The user can only enter one of these four examples, no other values are allowed.
Developer's Note:
There is a simpler alternative to the LiteralArgument
class! Instead of having to deal with arguments not being present in the array of arguments, consider using the much more intuitive MultiLiteralArgument
, which is described in more detail here!
Literal arguments vs regular arguments
Unlike regular arguments that are shown in this chapter, the literal argument is technically not an argument. Due to this fact, literal arguments are unlisted by default. In other words, the literal argument is not present in the CommandArguments args
for the command declaration.
Example - Literal arguments and regular arguments
To illustrate the behavior of literal arguments, we create a command of the following form:
/mycommand <literal> <text>
As an example, let's declare the literal "hello" as a valid literal for this command. When we retrieve the result from args.get(0)
, it returns the value of the TextArgument
, as opposed to the literal "hello":
new CommandAPICommand("mycommand")
.withArguments(new LiteralArgument("hello"))
.withArguments(new TextArgument("text"))
.executes((sender, args) -> {
// This gives the variable "text" the contents of the TextArgument, and not the literal "hello"
String text = (String) args.get(0);
})
.register();
CommandAPICommand("mycommand")
.withArguments(LiteralArgument("hello"))
.withArguments(TextArgument("text"))
.executes(CommandExecutor { _, args ->
// This gives the variable "text" the contents of the TextArgument, and not the literal "hello"
val text = args[0] as String
})
.register()
commandAPICommand("mycommand") {
literalArgument("hello")
textArgument("text")
anyExecutor { _, args ->
// This gives the variable "text" the contents of the TextArgument, and not the literal "hello"
val text = args[0] as String
}
}
The LiteralArgument
class also provides the LiteralArgument.of()
and LiteralArgument.literal()
helper methods which can be used as an alternative way to declare literal arguments:
new CommandAPICommand("mycommand")
.withArguments(LiteralArgument.of("hello"))
.withArguments(new TextArgument("text"))
.executes((sender, args) -> {
// This gives the variable "text" the contents of the TextArgument, and not the literal "hello"
String text = (String) args.get(0);
})
.register();
new CommandAPICommand("mycommand")
.withArguments(LiteralArgument.literal("hello"))
.withArguments(new TextArgument("text"))
.executes((sender, args) -> {
// This gives the variable "text" the contents of the TextArgument, and not the literal "hello"
String text = (String) args.get(0);
})
.register();
CommandAPICommand("mycommand")
.withArguments(LiteralArgument.of("hello"))
.withArguments(TextArgument("text"))
.executes(CommandExecutor { _, args ->
val text = args[0] as String
})
.register()
CommandAPICommand("mycommand")
.withArguments(LiteralArgument.literal("hello"))
.withArguments(TextArgument("text"))
.executes(CommandExecutor { _, args ->
val text = args[0] as String
})
.register()
commandAPICommand("mycommand") {
argument(LiteralArgument.of("hello"))
textArgument("text")
anyExecutor { _, args ->
val text = args[0] as String
}
}
commandAPICommand("mycommand") {
argument(LiteralArgument.literal("hello"))
textArgument("text")
anyExecutor { _, args ->
val text = args[0] as String
}
}
If I were to run the following command:
/mycommand hello goodbye
The value of text
in the code above would be "goodbye".
Example - Gamemode command using literal arguments
This is a demonstration of how you could create a command similar to Minecraft's /gamemode
command by using literal arguments. To do this, we are effectively registering 4 separate commands, each called /gamemode
, but with different literal arguments.
// Create a map of gamemode names to their respective objects
HashMap<String, GameMode> gamemodes = new HashMap<>();
gamemodes.put("adventure", GameMode.ADVENTURE);
gamemodes.put("creative", GameMode.CREATIVE);
gamemodes.put("spectator", GameMode.SPECTATOR);
gamemodes.put("survival", GameMode.SURVIVAL);
// Iterate over the map
for(Entry<String, GameMode> entry : gamemodes.entrySet()) {
// Register the command as usual
new CommandAPICommand("changegamemode")
.withArguments(new LiteralArgument(entry.getKey()))
.executesPlayer((player, args) -> {
// Retrieve the object from the map via the key and NOT the args[]
player.setGameMode(entry.getValue());
})
.register();
}
// Create a map of gamemode names to their respective objects
val gamemodes = mapOf(
"adventure" to GameMode.ADVENTURE,
"creative" to GameMode.CREATIVE,
"spectator" to GameMode.SPECTATOR,
"survival" to GameMode.SURVIVAL
)
// Iterate over the map
for ((key, _) in gamemodes) {
// Register the command as usual
CommandAPICommand("changegamemode")
.withArguments(LiteralArgument(key))
.executesPlayer(PlayerCommandExecutor { player, _ ->
// Retrieve the object from the map via the key and NOT the args[]
player.gameMode = gamemodes[key]!!
})
.register()
}
// Create a map of gamemode names to their respective objects
val gamemodes = mapOf(
"adventure" to GameMode.ADVENTURE,
"creative" to GameMode.CREATIVE,
"spectator" to GameMode.SPECTATOR,
"survival" to GameMode.SURVIVAL
)
// Iterate over the map
for ((key, _) in gamemodes) {
// Register the command as usual
commandAPICommand("changegamemode") {
literalArgument(key)
playerExecutor { player, args ->
// Retrieve the object from the map via the key and NOT the args[]
player.gameMode = gamemodes[key]!!
}
}
}
Note how, since we don't have access to the literal from args
, we must access the provided gamemode from elsewhere.
Literal argument warnings
Literal arguments require a string in the constructor. If the literal is an empty String or is null, the CommandAPI will throw a BadLiteralException
.
Because literal arguments are "hardcoded", each literal is effectively mapped to a single command. This is shown when using the configuration option create-dispatcher-json: true
which shows the JSON result of registered commands. For instance, take the /defaultgamemode
command:
"defaultgamemode": {
"type": "literal",
"children": {
"adventure": {
"type": "literal",
"executable": true
},
"creative": {
"type": "literal",
"executable": true
},
"spectator": {
"type": "literal",
"executable": true
},
"survival": {
"type": "literal",
"executable": true
}
}
},
Each option produces a new "command" in the tree of commands. This means that having exceptionally large lists of literals, or nested literals (e.g. /command <literal1> <literal2>
) can cause very large trees which cannot be sent to the clients (it can cause clients to crash).
Developer's Note:
Take care when using literal arguments. If your list of arguments is exceptionally large, or contains many nested arguments, the server may be unable to send the command information to the client. If many command argument choices are required, consider using a
StringArgument
and using.replaceSuggestions()
to create your own list of required arguments.