[MC-80856] Command syntax inconsistencies

I don't know if this is a valid report, but I hope so. Else I am pretty much fine with it, if you say it "Invalid" as long as your explanation would be this is a suggestion.

Notes:

This does not include the required changes from MC-69822
This does not include "sub commands" like for example /scoreboard players ...
See this crowdin discussion (German)

It seems like the command syntax suggestions are inconsistent or irritating.

Considering:

<arg> = argument
text = literal
[] = optional
- [<arg>] = optional argument
- [<arg1> <arg2>] = optional arguments, either both have to be provided or both have to be omitted
- [text] = optional literal
| as or
- text1|text2 = either text1 or text2 has to be provided literal

Note: This implies that arguments never use one of these characters

General

achievement

/achievement <give|take> <stat_name|*> [player]
/achievement give|take <stat name>|* [<player>]

~~Note: The underscore is not needed as it doesn't exactly uses an argument called "stat_name". However something like~~ <stat or achievement> ~~would make more sense as the~~ /achievement ~~command was mainly made to interact with achievements (I guess, see also MC-80826)~~

ban

/ban <name> [reason ...]
/ban <name> [<reason ...>]

ban-ip

/ban-ip <address|name> [reason ...]
/ban-ip <address|name> [<reason ...>]

clear

/clear [player] [item] [data] [maxCount] [dataTag]
/clear [<player>] [<item>] [<data>] [<maxCount>] [<dataTag>]

clone

/clone <x1> <y1> <z1> <x2> <y2> <z2> <x> <y> <z> [maskMode] [cloneMode]
/clone <x1> <y1> <z1> <x2> <y2> <z2> <x> <y> <z> [<maskMode>] [<cloneMode>]

debug

/debug <start|stop>
/debug start|stop

effect

/effect <player> <effect> [seconds] [amplifier] [hideParticles] OR /effect <player> clear
/effect <player> <effect> [<seconds>] [<amplifier>] [<hideParticles>] OR /effect <player> clear

enchant

/enchant <player> <enchantment ID> [level]
/enchant <player> <enchantment ID> [<level>]

fill (See also MC-80823)

/fill <x1> <y1> <z1> <x2> <y2> <z2> <TileName> [dataValue] [oldBlockHandling] [dataTag]
/fill <x1> <y1> <z1> <x2> <y2> <z2> <TileName> [<dataValue>] [<oldBlockHandling>] [<dataTag>]

gamemode

/gamemode <mode> [player]
/gamemode <mode> [<player>]

gamerule

/gamerule <rule name> [<value>]

give

/give <player> <item> [amount] [data] [dataTag]
/give <player> <item> [<amount>] [<data>] [<dataTag>]

help

/help [page|command name]
/help [<page>|<command name>]

kick

/kick <player> [reason ...]
/kick <player> [<reason ...>]

kill

/kill [player|entity]
/kill [<player|entity>]

particle

/particle <name> <x> <y> <z> <xd> <yd> <zd> <speed> [count] [mode]
/particle <name> <x> <y> <z> <xd> <yd> <zd> <speed> [<count>] [<mode>]

Note: I assume the "d" means delta (or difference), however then it is inconsistent with the arguments dx, dy and dz from selectors

playsound

/playsound <sound> <source> <player> [x] [y] [z] [volume] [pitch] [minimumVolume]
/playsound <sound> <source> <player> [<x>] [<y>] [<z>] [<volume>] [<pitch>] [<minimumVolume>]

recipe

/recipe <give|take> [player] <name|*>
/recipe give|take <player> <name>|*

replaceitem

/replaceitem <entity|block> ...
/replaceitem entity|block ...

scoreboard

/scoreboard <objectives|players|teams> ...
/scoreboard objectives|players|teams ...

setblock

/setblock <x> <y> <z> <TileName> [dataValue] [oldBlockHandling] [dataTag]
/setblock <x> <y> <z> <TileName> [<dataValue>] [<oldBlockHandling>] [<dataTag>]

spawnpoint

/spawnpoint [player] [<x> <y> <z>]
/spawnpoint [<player>] [<x> <y> <z>]

stats

/stats <entity|block> ...
/stats entity|block ...

summon

/summon <EntityName> [x] [y] [z] [dataTag]
/summon <EntityName> [<x> <y> <z>] [<dataTag>]

Note: For summon the current help is anyways incorrect as you cannot set only one coordinate, or at least it will have no impact on where the entity gets spawned

testfor

/testfor <player> [dataTag]
/testfor <player> [<dataTag>]

testforblock

/testforblock <x> <y> <z> <TileName> [dataValue] [dataTag]
/testforblock <x> <y> <z> <TileName> [<dataValue>] [<dataTag>]

testforblocks

/testforblocks <x1> <y1> <z1> <x2> <y2> <z2> <x> <y> <z> [mode]
/testforblocks <x1> <y1> <z1> <x2> <y2> <z2> <x> <y> <z> [<mode>]

time

/time <set|add|query> <value>
/time set|add|query <value>

title

/title <player> <title|subtitle|clear|reset|times> ...
/title <player> title|subtitle|clear|reset|times ...

tp

/tp [target player] <destination player> OR /tp [target player] <x> <y> <z> [<y-rot> <x-rot>]
/tp [<target player>] <destination player> OR /tp [<target player>] <x> <y> <z> [<y-rot> <x-rot>]

trigger

/trigger <objective> <add|set> <value>
/trigger <objective> add|set <value>

weather

/weather <clear|rain|thunder> [duration in seconds]
/weather clear|rain|thunder [<duration in seconds>]

worldborder

/worldborder <set|center|damage|warning|get|add> ...
/worldborder set|center|damage|warning|get|add ...

xp

/xp <amount> [player] OR /xp <amount>L [player]
/xp <amount> [<player>] OR /xp <amount>L [<player>]

spreadplayers

/spreadplayers <x> <z> <spreadDistance> <maxRange> <respectTeams true|false> <player ...>

<respectTeams true|false> would mean either respectTeams true or false as value. That is not correct. Maybe something like this would make more sense:

/spreadplayers <x> <z> <spreadDistance> <maxRange> <respectTeams> <player ...>

See for example effect as there hideParticles is an argument as well

Proof for the inconsistency

For example the /execute command has this syntax:

/execute <entity> <x> <y> <z> detect <x> <y> <z> <block> <data> <command>

According to all the other commands it should look like this instead:

/execute <entity> <x> <y> <z> <detect> <x> <y> <z> <block> <data> <command>

~~Another example is the~~ /achievement ~~command:~~

/achievement <give|take> <stat_name|*> [player]

~~This would imply that the second argument is either~~ stat_name or * ~~which is not correct. It is~~ a ~~stat name or "*"~~

Linked issues

is duplicated by 1

MC-118552 /recipe issue with optional arguments Resolved

relates to 3

MC-109833 "commands.title.usage" uses a different syntax Resolved

MC-69042 /summon coordinate syntax should be different Resolved

MC-87365 Incorrect syntax for scoreboard players tag Resolved

Comments 19

kumasasa 2015-05-31T00:30:15Z

Confirmed.

http://pic.dhe.ibm.com/infocenter/db2luw/v9r7/index.jsp?topic=%2Fcom.ibm.db2.luw.admin.cmd.doc%2Fdoc%2Fr0053134.html

Minecraft's German translation is already harmonzied according that specs, see discussion in https://crowdin.com/project/minecraft/discussions/2921

marcono1234 2015-05-31T12:48:47Z

Thank you, I wasn't aware of the fact that there is a standard...

SunCat 2016-03-19T13:12:23Z

Still in 1.9.1-pre3

SunCat 2016-05-25T17:57:56Z

Still in 16w21a

mrpingouin1 2016-06-10T07:46:10Z

You suggest a kinda new syntax, with some new rules, but the question is : "Is the current syntax inconsistent?". Mojang apparently never pretended to follow any kind of known command syntax specifications. So I looked at all the current command usage syntax, and I tried to understand the current rules.

Here are the rules I find :

text = required literal
<arg> = required argument
<text1|text2> = required one of the literal
[arg] = optional argument
[arg1|arg2] = optional argument (arg1 and arg2 are a different type of input)
[<arg1> <arg2>] = optional arguments, either both have to be provided or both have to be omitted
/cmd ... = command continue
[arg ...] OR <arg ...> = multiple argument can be specified
/cmd1 OR /cmd2 = Different command syntax

Some inconsistencies you describe are not :

In the /execute command (and in the second OR branch), detect is a required literal, so it must be written a plain text, and not <detect>
About <name|*>, this one is a special case. It should be interpreted as 2 required literals, but it's not because * mean "all the possible argument".
... is not inconsistent, it just has different meaning depending if it's at the end of the command, or inside [] or <>
/tell <player> <private message ...> This syntax is correct, your suggested one is not. What is not specified is that you can use selectors as a message argument

Your syntax replace all [arg] into [<arg>] just to make room for a [text] as optional literal, but this syntax is almost never used. That's what the big OR is used to.

You also replace all <text1|text2> by text1|text2, and this suggestion make sense, but the current syntax is still valid and consistent.

Instead of changing 90% of the command usages as you suggest, we just need to change some few ones:

Here ips and players are literal, so they can't be in the same []

/banlist [ips|players]
/banlist OR /banlist <ips|players>

In this case, address and name are arguments, so they can't be in the same <> as they will be interpreted a literals

/ban-ip <address|name> [reason ...]
/ban-ip <address> [reason ...] OR /ban-ip <name> [reason ...]
or
/ban-ip <address OR name> [reason ...]

As you noted, the following ones are real inconsistancies or mistakes (+from related issues):

/spreadplayers <x> <z> <spreadDistance> <maxRange> <respectTeams true|false> <player ...>
/spreadplayers <x> <z> <spreadDistance> <maxRange> <respectTeams> <player ...>

/summon <EntityName> [x] [y] [z] [dataTag]
/summon <EntityName> [<x> <y> <z>] [dataTag]

/scoreboard teams join <team> [player]
/scoreboard teams join <team> [player ...]

... can also solve this syntax problem, but it's less convinient to see and understand how the command is working

/scoreboard players tag <player> <add|remove|list> <tagName> [dataTag]
/scoreboard players tag <player> <add|remove> <tagName> [dataTag] OR /scoreboard players tag <player> list

/fill <x1> <y1> <z1> <x2> <y2> <z2> <TileName> [dataValue] [oldBlockHandling] [dataTag]
/fill <x1> <y1> <z1> <x2> <y2> <z2> <TileName> [dataValue] [oldBlockHandling] [dataTag] OR /fill <x1> <y1> <z1> <x2> <y2> <z2> <TileName> [dataValue] replace <TileName> [dataValue]

I agree that the current syntax is weird when it comes to know if an argument is a literal are not. But despite what you can think, it is consistent. Changing the syntax as you suggest is not totally justified. Seeing the related issues, you have to keep in mind that the command usage is just an indication, complex commands can't be explained in a single line, and Mojang probably want the indication as simple as possible, instead of being complex but complete, as long as the tab completion is correct, the command usage can omit some detail to make things easier ([oldBlockHandling] could be replaced by [destroy|hollow|keep|outline|replace], but it's not needed thanks to tab completion)

9 more comments

bob 2016-11-06T11:10:13Z

Is this still an issue in the latest snapshot 16w44a? If so please update the affected versions.

This is an automated comment on any open or reopened issue with out-of-date affected versions.

tryashtar 2016-11-23T23:51:30Z

Some other things to note as well:
Some commands that accept entity selectors claim <player> (/tp, for example, allows entities, but /give doesn't, so there's no distinction)
Also, some arguments use inconsistent casing/spaces (e.g. "dataTag" or "oldBlockHandling" vs "duration in seconds" or "enchantment ID")

SunCat 2016-11-24T06:06:12Z

@unknown, the first one is MC-69822

Sonicwave 2017-03-24T18:28:22Z

I'm not sure if this would be the same issue, but data tags have inconsistent capitalization. For example, "id" is lowercase in "HandItems" and enchantment tags, but "Id" is capitalized for ActiveEffects; "Motion" is capitalized while "direction" isn't even though they have similar functions.

marcono1234 2017-03-25T20:05:42Z

That affects NBT data while this here is only command syntax help. Changing that would break many existing commands and require many data upgraders just for capitalization, which makes me think that they very likely won't fix it.

user-f2760 2017-04-13T12:01:51Z

Crossed out /achievement, as it's removed in 1.12.

Aside from that, isn't /banlist correct?

FaRo1 2017-06-30T11:20:42Z

/summon creeper {Health:21}

wouldn't be valid, right? So then it would have to be

/summon <EntityName> [<x> <y> <z> [<dataTag>]]

instead of

/summon <EntityName> [<x> <y> <z>] [<dataTag>]

. And the same for many other of the commands.

SunCat 2017-06-30T12:58:19Z

@unknown, in that case this

/clear [<player>] [<item>] [<data>] [<maxCount>] [<dataTag>]

would become this

/clear [<player> [<item> [<data> [<maxCount> [<dataTag>]]]]]

Your change doesn't make sense, as it's always the case that if you want to specify one optional tag, you need to specify all the tags before it

FaRo1 2017-06-30T13:47:09Z

Is that really always the case? Is there no command which has multiple optional parameters that are independent of each other? Or maybe there could be some in the future?

marcono1234 2017-07-05T14:50:40Z

There is /tp [target entity] <destination entity> and /tp [target entity] <x> <y> <z> .... In both cases an optional argument is left out in between. This is not exactly what you are searching for but similar.

In my opinion these cases should not exist since you either need to use the command length to determine which argument is which or you will have to guess. Maybe it should rather be like /give or /replaceitem where you always have to specify the target player.

FaRo1 2017-07-05T14:58:33Z

A list of commands that should be changed as you described is in MC-108965. That would also automatically "fix" MC-79677 by making it impossible to encounter.

marcono1234 2017-07-05T15:14:33Z

I think these cases are fine since there the optional argument is not in between.

tryashtar 2017-07-05T20:24:21Z

Seems to have been fixed for 1.13: https://cdn.discordapp.com/attachments/154777837382008833/332255253539848192/image.png

Nathan Adams 2017-07-05T20:25:09Z

In 1.13 all usage text is automatically generated based on context (how far in a command you got), your permissions, and your language. Argument names are translated, literals are not.

Examples for syntax are as follows:

literal

[optionalLiteral]

<argument>

[<optionalArgument>]

(literal|otherLiteral)

(literal|<argument>)

This isn't complete yet though so I'm keeping this issue open for now.

Command syntax inconsistencies