Minecraft Wiki:Style guide/Commands

This style guide includes a specific format for all command instances in all articles, as well as a layout for all command articles (subpages of Commands) to follow.

Command instances

All command instances in all articles should follow the following format.

In this wiki, commands are typically shown using a {{cmd}} template, which automatically adds a link on the command name. If the link is not needed, {{code}} template or <code></code> can be used instead, or specify |link=none in the {{cmd}} template.

The representation of command syntax should strictly follow the format documented in Commands § Syntax. All argument names should be the names provided by the /help command in the game.

For long literal texts or complex argument combinations, if not suitable to list them all, they can be referred as a single fake argument with a customized name, and the name should be in italics to distinguish the fake argument from literal texts in Bedrock Edition. For example, /gamerule <rule name> and /loot <TARGET> <SOURCE>.

For a complex argument, to explain it clearly, it can be decomposed into multiple sub-arguments with customized names, and their names should also be in italics to distinguish them from literal texts in Bedrock Edition. For example, the three-dimensional coordinates <position>‌ or position: x y z‌ can be decomposed into three sub-arguments <X> <Y> <Z> when referring them.

An ellipsis (...) in Java Edition indicates another complete command, e.g. return run .... In this wiki, ellipses can be used in this situation, and it can also be referred as a fake argument <command>, where "command" should be in italics. On the other hand, ellipses can be widely used in this wiki to indicate that some required parts of the command are omitted.

In Java Edition, there is no consistent command syntax format before 17w45a (1.13), and syntaxes displayed by the /help command in the game are also very inconsistent. In version articles before 17w45a and entries before 17w45a in history sections, syntaxes provided by the /help command can be used, or they can be transcribed with the current syntax format in Java Edition as Commands#Syntax shows. For the syntaxes provided by the /help command, all argument names should be in italics to distinguish them from literal texts.

Except for the above four situations, argument names should not be in italics.

The square bracket decorator ([]) indicates that the entry in it is optional. To avoid ambiguity, it can be placed only at the end of a command, but cannot appear in the middle of a command. Square brackets in the middle of a command have the following ambiguity:

• Considering that the order of entries in a command cannot be reversed. For example, given a [b] c, only a and a b c are valid, while a c is invalid as it reverses the order of b and c. This was how square brackets were used in this wiki before. If so, a [b] [c] at the end of a command indicates that only a, a b, anda b c are valid, which is consistent with the usages in the game.
• The part enclosed in square brackets is considered optional and removable. For example, given a [b] c, only a b c and a c are valid, while a is invalid as it lacks the required c. This usage has appeared multiple times in update logs. If so, a [b] [c] indicates that a, a b, a b c, and a c are all valid, which is inconsistent with the usages in the game.

To avoid the above ambiguity, square brackets should not appear in the middle of a command in this wiki. Instead, the command should be split into multiple commands to show all valid syntaxes clearly. However, multiple square brackets are allowed at the end of a command. For example, a [b] [c] at the end of a command means that only a, a b, and a b c are valid. But it should also be split if suitable.

For example, clone [from <sourceDimension>] <begin> <end> [to <targetDimension>] <destination> [replace|masked] [force|move|normal] has serious ambiguity, where square brackets have completely different meanings. It must be split into the following four commands:

• clone <begin> <end> <destination> [replace|masked] [force|move|normal]
• clone <begin> <end> to <targetDimension> <destination> [replace|masked] [force|move|normal]
• clone from <sourceDimension> <begin> <end> <destination> [replace|masked] [force|move|normal]
• clone from <sourceDimension> <begin> <end> to <targetDimension> <destination> [replace|masked] [force|move|normal]

Or further split to avoid multiple square brackets at the end of the command:

• clone <begin> <end> <destination>
• clone <begin> <end> to <targetDimension> <destination>
• clone from <sourceDimension> <begin> <end> <destination>
• clone from <sourceDimension> <begin> <end> to <targetDimension> <destination>
• clone <begin> <end> <destination> (replace|masked) [force|move|normal]
• clone <begin> <end> to <targetDimension> <destination> (replace|masked) [force|move|normal]
• clone from <sourceDimension> <begin> <end> <destination> (replace|masked) [force|move|normal]
• clone from <sourceDimension> <begin> <end> to <targetDimension> <destination> (replace|masked) [force|move|normal]

Command articles

All command articles should use the following layout.

Introduction

Right before the lead, {{Infobox command}} should be placed. See Commands#Restrictions for valid restrictions for this template.

After the template should be an introduction with a general description, briefly describing the usage of the command. The description should not be started with the command name.

Usage

Usages and effects of the command should generally be placed in "Syntax" section. But if they are too long, it is not suitable to cram them all into the "Syntax" section. A "Usage" section for them can be added before the "Syntax" section. If the "Usage" section is too short to be a single section, it should be placed into the introduction as a paragraph.

Note that effects of the command should be placed in the "Syntax" section, the "Usage" section, or the Introduction, rather than in "Result" section.

Syntax

The syntaxes of the command should be fully listed in this section, and each following a usage explanation if necessary.

All argument names should be the names provided by the /help command in the game.

If the syntaxes in Java Edition and Bedrock Edition are a little different, they should be listed in groups, and each is followed by an edition name between parentheses. For example:

whitelist add <targets> (Java Edition)

whitelist add <name: string> (Bedrock Edition)

Adds the player profile(s) to the whitelist. The player does not need to be online.

whitelist list

Displays all player profiles in the whitelist.

They can also be listed separately by edition. For example:

• Java Edition

tag <targets> add <name>

Adds a tag to the targets.

tag <targets> list

Lists all tags on the targets.

tag <targets> remove <name>

Removes a tag from the targets.

• Bedrock Edition

tag <entity: targets> add <name: string>

Adds a tag to the targets.

tag <entity: targets> remove <name: string>

Removes a tag from the targets.

tag <entity: targets> list

Lists all tags on the targets.

Complex syntaxes should be shown in a syntax tree. Syntaxes could also be shown multiple times in various ways, but all except the first one must be collapsed, as /clone page does.

• Java Edition

clone ...

clone from <sourceDimension> ...

• ... <begin> <end> ...
  • ... <destination> ...
  • ... to <targetDimension> <destination> ...
    • ... [replace] [force|move|normal]

      Clones all blocks.

    • ... masked [force|move|normal]

      Clones non-air blocks.

    • ... filtered <filter> [force|move|normal]

      Clones only blocks with the block id specified by <filter>.

Syntax displayed in various ways

Simplified tree: [show]
clone <begin> <end> ... clone from <sourceDimension> <begin> <end> ... ... <destination> ... ... to <targetDimension> <destination> ... ... [replace|masked] [force|move|normal] ... filtered <filter> [force|move|normal]

Maximised: [show]

clone <begin> <end> <destination> clone from <sourceDimension> <begin> <end> <destination> clone <begin> <end> <destination> replace [force|move|normal] clone from <sourceDimension> <begin> <end> <destination> replace [force|move|normal] clone <begin> <end> <destination> masked [force|move|normal] clone from <sourceDimension> <begin> <end> <destination> masked [force|move|normal] clone <begin> <end> <destination> filtered <filter> [force|move|normal] clone from <sourceDimension> <begin> <end> <destination> filtered <filter> [force|move|normal] clone <begin> <end> to <targetDimension> <destination> clone from <sourceDimension> <begin> <end> to <targetDimension> <destination> clone <begin> <end> to <targetDimension> <destination> replace [force|move|normal] clone from <sourceDimension> <begin> <end> to <targetDimension> <destination> replace [force|move|normal] clone <begin> <end> to <targetDimension> <destination> masked [force|move|normal] clone from <sourceDimension> <begin> <end> to <targetDimension> <destination> masked [force|move|normal] clone <begin> <end> to <targetDimension> <destination> filtered <filter> [force|move|normal] clone from <sourceDimension> <begin> <end> to <targetDimension> <destination> filtered <filter> [force|move|normal]

Arguments

All arguments should be listed in this section with detail descriptions.

Each argument is listed starting with an {{argument}} template. The argument type of an argument can be obtained in the generated/reports/commands.json file generated with the data generator Java Edition, or from the official file for Bedrock Edition.

• In Bedrock Edition, all argument types in the "command_enums" field are enum argument types. All of them should be documented as a enum type in the wiki, rather than their own names.
• In Bedrock Edition, if an argument is shown as name: string in the game, but its type in the official file is not ID, it is a soft enum type argument. Soft enum types are argument types that are almost the same with basic_string type, except that they offer autocompletion. All of soft enum types should be documented as basic_string type in the wiki.

A detail description should follow the {{argument}} template. Consisting of:

• The usage of the argument.
• The default value of the argument if it is optional.
• The restrictions of the argument.
  • It is necessary to strictly distinguish between parsing restrictions and execution restrictions:
    • Parsing restrictions are restrictions that otherwise the argument is not regarded as being correctly specified, and the command is unparseable.
      • For a parsing restriction，the word "must" should be used primarily, and words such as "should" and "can" should be avoided.
    • Execution restrictions are restrictions that otherwise the argument is correctly specified, the command is parseable but will be failed.
      • For an execution restriction, the word "must" should be avoided, and the word "should" should be used primarily. If possible, it should be clearly stated that this restriction affects only during command execution.
  • In “Arguments” section, always assuming the reader is typing a command, rather than had executed the command, use present tense for what occurs during parsing, and future tense for what will occur during execution.
  • For example, for the dimension argument type in Java Edition, the parsing restriction is that it must be a namespace ID, and the execution restriction is that the dimension with that ID does exist. Which can be described as the following:
    • Must be a namespace ID and should be the ID of a dimension. It will be resolved into a dimension during command execution.
  • Using the {{arg desc}} template to describe restrictions due to the argument type. Restrictions due to the command itself come after the template.
    • For Java Edition, the {{arg desc}} template not only requires the |je= to specify the argument type, but sometimes also requires some additional parameters, which are also from the generated/reports/commands.json。For examples:
      • {{arg desc|je=entity|amount=multiple|type=players}} for the <targets> argument in the /clear command;
      • {{arg_desc|je=resource_or_tag|registry=minecraft:worldgen/biome}} for the <biome> argument in the /locate command.
    • For enum-like argument types in Java Edition (derived from StringRepresentableArgument class in the code), such asheightmap, the {{arg desc}} template should not be used.
    • For Bedrock Edition, the {{arg desc}} template requires only the |be= to specify the argument type. No additional parameters.
    • For the "BOOLEAN" enum type in Bedrock Edition, it can be specified as |be=bool in the {{arg desc}} template.
    • For the "BLOCK" enum type in Bedrock Edition, it can be specified as |be=block in the {{arg desc}} template.
    • For the "ITEM" enum type in Bedrock Edition, it can be specified as |be=item in the {{arg desc}} template.

The {{arg desc}} template should not be used for removed commands, as the restrictions of argument types change with the version.

For commands in Java Edition that have been removed on or before 17w45a (1.13), the {{argument}} template and {{arg desc}} template should not be used; argument types of arguments are not needed; and there's no need to distinguish between parsing and execution restrictions.

For commands that have only existed in Pocket Edition, the {{argument}} template and {{arg desc}} template should not be used, and argument types of arguments are not needed.

Examples

{{argument|entity|resource|entityType: EntityType|enum}}<!--JE and BE-->
: Specifies the entity to be summoned.
: {{arg desc|je=resource|registry=minecraft:entity_type|be=enum}} And it should{{only|je|short=1}}/must{{only|be|short=1}} not be the player entity.

{{argument|targets|game_profile|player: target|CommandSelector<Player>}}<!--JE and BE, but argument types are completely different-->
: Specifies the player to be granted operator.
: {{IN|java}}:
:: {{arg desc|je=game_profile}}
: {{IN|bedrock}}:
:: {{arg desc|be=player}}

{{el|je|short=1}}: {{argument|sourceDimension|dimension}}<!--only JE-->
: Specifies the dimension to clone the blocks from.
: If not specified, defaults to current execution dimension.
: {{arg desc|je=dimension}}

{{el|be|short=1}}: {{argument|be=1|blockStates: block states|BlockStateCommandParam}}<!--only BE-->
: Specifies the [[block states]] to use for the block.
: {{Arg desc|be=BlockStateCommandParam}}

JE: <entity>: resource
BE: entityType: EntityType: enum

Specifies the entity to be summoned.

In Java Edition, must be an existing registered resource location in minecraft:entity_type registry. In Bedrock Edition, must be an ID of an entity type. And it should‌/must‌ not be the player entity.

JE: <targets>: game_profile
BE: player: target: CommandSelector<Player>

Specifies the player to be granted operator.

In Java Edition:

Specifies one or more game profiles (player profiles). Must be a player name (should be a real one if the server is in online mode) or a player-type target selector.

In Bedrock Edition:

Must be a player name or a target selector.

JE: <sourceDimension>: dimension

Specifies the dimension to clone the blocks from.

If unspecified, defaults to current execution dimension.

It must be a resource location, which resolves into a dimension during command execution.

BE: blockStates: block states: BlockStateCommandParam

Specifies the block states to use for the block.

Must be a blockstate argument as ["<state1>"=<value1>,"<state2>"=<value2>,...]. For example: ["old_leaf_type"="birch","persistent_bit"=true].

Result

In this section, there should only be a table generated by {{result table}} template, unless the command is always successful. If the command is always successful, this section should only contain the sentence "Always successful.".

All valid results can be found in Commands#Results. Unparseable results caused by the required permission level or command restrictions should not be included in this table. For commands in Java Edition that have been removed on or before 17w45a (1.13), the only valid results are "Failed" and "Successful".

For Bedrock Edition, if the command cannot be executed by command blocks or scripts, it technically still has a Success Count, but cannot be obtained. The "Result" section of it can be omitted.

In the "Arguments" section, execution restrictions are restrictions that otherwise the command will fail. All of execution restrictions mentioned in the "Arguments" section should be also described in the "Results" section. For example:

If the "Arguments" section is as the following:

JE: <spreadDistance>: float
BE: spreadDistance: float: float

Specifies the minimum distance between targets.

Must be a [Float]Single-precision floating-point number (from -(2-2^-23)×2¹²⁷ (≈-3.4×10³⁸) to (2-2^-23)2×¹²⁷ (≈3.4×10³⁸) ). In Java Edition, it must be greater than or equal to 0.0. In Bedrock Edition, it should be greater than or equal to 0.0.

So, the "Result" section must be either:

Command	Trigger	Java Edition	Bedrock Edition
Any	The command is incomplete, or any argument is not specified correctly.	Unparseable	Unparseable
	spreadDistance: float is lower than 0.0.	N/A	Failed
	Otherwise	Successful

Or:

Command	Trigger	Java Edition	Bedrock Edition
Any	The command is incomplete, or any argument is not specified correctly.	Unparseable	Unparseable
	spreadDistance: float or <spreadDistance> is lower than 0.0.		Failed
	Otherwise	Successful

Some common trigger examples:

Command	Trigger	Java Edition	Bedrock Edition
Any	The command is incomplete, or any argument is not specified correctly.	Unparseable	Unparseable
	<targets> or player: target fails to resolve to one or more online players.	Failed	Failed
	<targets> or player: target fails to resolve to one or more entities (named player must be online).
	<targets> or player: target fails to resolve to a single entity (named player must be online).
	<targets> or player: target is not specified when the command's executor is not a player.
	player: target is a target selector that is not in player type.	N/A
	<target> fails to resolve to a single living entity.	Failed	N/A
	One or both specified regions are unloaded or out of the world.		Failed
	One or both specified positions are unloaded or out of the world.
	The specified position is unloaded.
	The specified block is not a container.
	Trying to summon hostiles in peaceful difficulty.
	Trying to summon a player entity.		N/A
	spreadDistance: float is lower than 0.0.	N/A	Failed
	Destinated position's <X> or <Z> exceeds the range of [-30000000, 30000000), or <Y> exceeds the range of [-20000000, 20000000)	Failed	Successful
	All the selected entities meet one or more of the following conditions: Condition 1. Condition 2. Condition 3.		Failed
	Otherwise	Successful

Usages and effects of the command should not appear in this section. They should be described clearly in the Introduction, the "Usage" section or the "Syntax" section. For example, "Targeted entities are killed." should not be placed in the "Result" section in /kill article.

Output

In this section, there should only be a table generated by {{output table}} template.

For commands in Java Edition that have been removed on or before 17w45a (1.13), the {{output table}} template should not be used. Instead, the command's success count should be described in several short sentences.

For Bedrock Edition, if the command cannot be executed by command blocks or scripts, it technically still has a Success Count, but cannot be obtained. The "Output" section can be omitted.

Messages sent by the command do not need to be documented in the command article, as most of them are unimportant and easy to understand for players. If messages of the command are complex and difficult to understand, but it is of great help to players, they can also be explained in the "Usage" section, rather than in the "Output" section.

Examples

The "Examples" section should contain some typical examples that are easy to understand.

History

See Minecraft Wiki:Style guide/Features#History.

See also

See Minecraft Wiki:Style guide/Features#See also.