This is a list of known quirks and inconsistencies in Bukkit and CraftBukkit's handling of "vanilla" commands.
The following commands simply do not behave properly on Bukkit. This isn't a matter of not being implemented - these commands have been implemented, but do not work properly.
- spreadplayers - this command actually fails for a large number of reasons. Its most glaring flaw is that it declares 'world = null', and does not attempt to change this because the condition to set 'world' is 'if (world != null)' (surprisingly, Eclipse does not generate an "unreachable code" warning for this). This actually simply prevents the command from doing anything whatsoever. Other issues with this command include mishandling of PlayerSelectors (failing to actually meet any constraints), lacking a failure condition for too many players to meet "spreadDistance" and "maxRange" argument constraints, and defaulting to Far Lands coordinates if coordinates cannot be interpreted. These remaining flaws are detailed in sections below.
The following are Vanilla commands or features which have not yet been implemented in Bukkit.
- ban - does not accept the vanilla "reason ..." argument.
- banlist - does not accept the vanilla "ips" argument.
In Bukkit, PlayerSelectors can only be used within command blocks. In Vanilla, they are also permitted for use by players in chat, and the server console.
A number of commands in Vanilla accept lists of player names, rather than only an individual player name. In these circumstances, a vanilla command block will actually convert PlayerSelectors into lists of player names. Bukkit, however, always executes commands once per player identified by a PlayerSelector, instead of sending the command a list of players.
Situations where this behavior breaks vanilla functionality:
-
spreadplayers - this command can only act properly if its players are provided as a list and the command is invoked once. Bukkit instead invokes the command once for every individual player. Even if the command weren't broken by several other issues (see above and below), it would fail to guarantee players are spreadDistance apart and also fail to respect teams, essentially just moving each player to a random location. The code to behave properly exists; it's just never used if the command is executed with a PlayerSelector.
-
say, tell, and me - in Vanilla, these commands (and even general player chat) accept PlayerSelectors, and if identifying multiple players, will render the player names as a list.
Note that the first argument in tell is not rendered as such, and thus the command is executed once per player for this selector. For example, if a server has Dinnerbone, EvilSeph, and Grumm logged on, and the command "/tell @a[name=!Dinnerbone] @a" is executed, then EvilSeph and Grumm will each recieve the message "@ whispers to you: Dinnerbone, EvilSeph, and Grumm", where @ is the name of the command's sender.
In Bukkit, such a command would send EvilSeph and Grumm 3 messages, "@ whispers Dinnerbone", "@ whispers EvilSeph", "@ whispers Grumm".
Other situations where this issue has an effect:
- scoreboard subcommands "teams join" and "teams leave" are made less efficient by being called once per player, rather than being invoked a single time with a list of players.
Some Bukkit-vanilla commands do not fail in the same situations the Vanilla equivalents fail in.
Commands which are missing failure conditions/messages:
- effect - does not output an error if clearing all effects ("/effect clear") if the player has no effects. Vanilla outputs "Couldn't take any effects from %s as they do not have any". Note that the comparator output of a command block will still be correct even in this situation.
- spreadplayers has a failure condition in vanilla if there are too many players to spread within the given area (namely, so many that they cannot be kept "spreadDistance" distance apart). This failure is never checked in Bukkit; the command will "succeed" and even comparator output will claim this.
- weather - does not provide any output whatsoever if the given weather condition is not recognized. This previously matched Vanilla behavior, but this behavior has since changed (Vanilla will now actually output an error for unrecognized weather conditions). This issue also effects command block comparator output: invalid conditions will still be interpreted as "successful".
Commands which have extra failure conditions:
- gamemode - fails in Bukkit if the player's gamemode was not actually changed. In Vanilla, gamemode is still considered successful whether or not the player's gamemode has changed. This inconsistency will effect command block comparator output.
- scoreboard - in Bukkit, any scoreboard subcommand requiring a player name will fail if that name exceeds 16 characters. This applies to add, remove, set, reset, and list subcommands. In vanilla, no such restriction is made.
Bukkit and Vanilla both prevent certain commands from being executed by command blocks. However, Bukkit allows the following commands to be executed by command block, even while Vanilla does not:
- banlist
- save-all
- save-off
- save-on
- whitelist (all sub-commands are permitted, including removing players from the whitelist, activating it, and reloading it)
Some Bukkit-vanilla commands have default values which are employed when an invalid value is given. Thus, rather than failing as they would in a Vanilla environment (and giving the user a helpful error message), they use a default value which may or may not produce the intended results.
Commands which display this behavior include:
- defaultgamemode - for an invalid/nonexistent "mode" value (numeric or otherwise), defaults to GameMode.SURVIVAL.
- gamemode - same issue as above.
- difficulty - for invalid/nonexistent difficulty modes, defaults to PEACEFUL.
- time - defaults to 0 for invalid time strings.
- give - non-Short values of "data" default to 0, even if they are numeric.
- playsound - invalid "x", "y", or "z" values appear to play the sound at -30000001 on the given axis.
- spreadplayers defaults to -30000001 for invalid "x" or "z" values. This is probably very, very bad, but currently another bug prevents spreadplayers from actually doing anything (see above). For better or worse.
Many Bukkit-vanilla commands will limit the permitted values of numeric arguments to a certain range. When a vanilla command is given an argument outside the valid range, it will fail and notify the user. Bukkit will instead silently limit the value to not be less than the minimum or greater than the maximum, and proceed.
Commands which display this behavior include:
- effect - silently limits "seconds" and "amplifier"
- xp - silently limits "amount"
- give - silently limits "amount"
- playsound - silently limits "volume", "pitch", and "minimumVolume"
- spawnpoint - silently limits coordinates "x", "y", and "z"
- time - silently limits "value" to be no less than 0
- weather - silently limits "duration in seconds"
- clear - silently limits "data" to be at least 0
- difficulty - silently limits "new difficulty" if it is a numeric value
- help - silently limits "pageNumber" if it is not negative
The following Bukkit-vanilla commands provide output messages which are incorrect. Not merely inconsistent or misformatted, but actually factually incorrect.
- effect - outputs the number of ticks the effect was applied for, but claims this is a value in seconds. One second is 20 ticks, so the output effectively claims the effect was applied for 20 times its actual duration.
The following are Bukkit features which Vanilla lacks in its commands, rather than actual issues. These are listed for completeness' sake.
Obviously, if you are working on a vanilla-compatible map, you should avoid using these features in your command blocks until they are added to vanilla. Non-vanilla default commands are not listed.
- clear accepts -1 for "item", representing "don't check an item's id". This allows the command to specify a "data" value without specifying an "item".
- enchant accepts 0 (clears enchantment) and max (highest valid level for given enchantment) for "level", and has a "force" argument. "enchantment" may also be specified by name rather than ID.
- toggledownfall allows the user to specify a world by name. This feature is not mentioned in the usage text, however.
- clear and give allow "item" to be specified by name rather than ID.
- effect allows "effect" to be specified by name rather than ID.
- help is almost entirely different, allowing the user to search for commands, list all commands of a given plugin, and provides detailed information instead of a simple usage text. Note that due to its many differences, command block comparator output will be very different from vanilla with this command.
- stop accepts an additional "reason" argument, displayed to players when they are kicked from the server.