Commands/execute

From Minecraft Wiki
Jump to: navigation, search
execute
Restrictions

Operator

First introduced

Java Edition 1.8 (14w07a)
PE Alpha 0.16.0 (PE Alpha 0.16.0 build 1)

/execute is a versatile command that modifies variables or procedures in the execution of another command.

Java Edition[edit]

In Java Edition, there are twelve instructions (or sub-commands) for the /execute command. Multiple sub-commands are connected after /execute. Subcommands are divided into 4 categories: modify subcommands, condition subcommands, store subcommands, and run subcommand.

  • Modify subcommands modify command variables and change the situation the command is executed, and execute subcommands following it with specific executor(s), execution position(s), execution dimension(s), and execution rotation(s).
  • Condition subcommands are used to test whether certain conditions are true and output results or limit conditions of execution.
  • Store subcommands can store the return values of the command in a scoreboard or the data of an entity, block entity or storage, and can also change the maximum or current value of a boss bar.
  • run subcommand is used for carrying out another command.

A number of sub-commands needed can be chained together. Subcommands other than the run subcommand can be arranged arbitrarily or used multiple times. But the run subcommand can only be used once and must at the end of the subcommands chain. A run subcommand or a condition subcommand finalizes the command, otherwise the command does nothing. The game processes these subcommands in order from front to end, for example, the following commands are different:

  • All entities move one block forward: execute as @e at @s run tp ^ ^ ^1
  • All entities move to one block in front of the executor: execute at @s as @e run tp ^ ^ ^1

The game processes other subcommands before processing run and store subcommands, so the run and store subcommands cannot affect other subcommands. The run commands and store subcommands cannot affect each other as well. In some cases, the command terminates halfway and does nothing.

After the command is executed (if it does not terminate halfway), it returns a success and a result value (see #Store subcommands for details). These two values ​​come from the last subcommand (may be a condition subcommand or run subcommand). Note that the return value of the command must be an integer, if not, it is rounded down. The success value is usually 0 or 1. When the command fails, both return values ​​are 0. When the last subcommand (may be a condition subcommand or run subcommand) is executed multiple times, only values of the last execution can be returned. The two values can be stored by store subcommands.

/execute command also has a success count (whether or not terminates halfway). This is usually 0 or 1, but if the command split up (as perhaps with "/execute as @a -> execute") then success can be a number higher than 1. When executing it with the command block, the success count is returned to the command block, which can be checked by the conditional command block for success or be read with a redstone comparator.

There are twelve instructions (or sub-commands) for the /execute command, and each has its own special syntax, so describing syntax takes a large branching tree.

Full syntax tree
/execute . . .
  • align <axes> -> execute
  • anchored <anchor> -> execute
  • as <targets> -> execute
  • at <targets> -> execute
  • facing (<pos>|entity <targets> <anchor>) -> execute
  • in <dimension> -> execute
  • positioned (<pos>|as <targets>) -> execute
  • rotated (<rot>|as <targets>) -> execute
  • store (result|success) . . .
    • … block <targetPos> <path> (byte|short|int|long|float|double) <scale> -> execute
    • … bossbar <id> (max|value) -> execute
    • … entity <target> <path> (byte|short|int|long|float|double) <scale> -> execute
    • … score <targets> <objective> -> execute
    • … storage <target> <path> (byte|short|int|long|float|double) <scale> -> execute
  • … (if|unless) . . .
    • … block <pos> <block> -> [execute]
    • … blocks <start> <end> <destination> (all|masked) -> [execute]
    • … data . . .
      • … block <sourcePos> <path> -> [execute]
      • … entity <source> <path> -> [execute]
      • … storage <source> <path> -> [execute]
    • … entity <entities> -> [execute]
    • … predicate <predicate> -> [execute]
    • … score <target> <targetObjective> . . .
      • … (<|<=|=|>|>=) <source> <sourceObjective> -> [execute]
      • … matches <range> -> [execute]
  • run <command>
where -> execute represents the start of another subcommand.

Modify subcommands[edit]

align[edit]

Convert execution position's coordinates of specified axes to block position (rounding down, toward negative infinity.).

Syntax
align <axes> -> execute
Arguments
<axes>
Any non-repeating combination of the characters 'x', 'y', and 'z'. (For example, x, xz, zyx, or yz.)
Result
Error if the argument is not specified correctly.
Example
  • Given the position (-1.8, +2.3, +5.9), the command /execute align xz run summon zombie ~ ~ ~ summons a zombie at (-2.0, +2.3, +5.0).
  • Given (+2.4, -1.1, +3.8), using /execute align yxz run spawnpoint @p ~ ~ ~ sets the player's spawnpoint to (2, -2, 3).

anchor[edit]

Stores the distance from the feet to the eyes of the entity that is executing the command in the anchor, which is part of the command context. Default of anchor is feet.

The only places where the anchor is used is in the caret notation (^ΔT ^ΔN ^ΔB) and in the facing subcommand of the execute command.

Syntax
anchored <anchor> -> execute
Arguments
<anchor>
Must be one of feet and eyes.
Result
Error if the argument is not specified correctly.

as[edit]

Change the executor to the targeted entity/entities, but does not change position or rotation of execution. Changes the function of the @s target selector variable

Syntax
as <targets> -> execute
Arguments
<targets>
Specifies the target(s). Must be a player name, a target selector or a UUID
Permits entities other than players.
Result
Error if the argument is not specified correctly.
Terminates if <targets> fails to resolve to one or more valid entities (named players must be online).
When multiple entities are selected, next subcommand is executed once each per executor.
Example
Get data of all sheep: execute as @e[type=sheep] run data get entity @s

at[edit]

Use the position, rotation, and dimension of the target(s), but does not change the current executor. Changes the function of ~Δx ~Δy ~Δz and ^ΔT ^ΔN ^ΔB positioning.

Syntax
at <targets> -> execute
Arguments
<targets>
Specifies the target(s). Must be a player name, a target selector or a UUID
Permits entities other than players.
Result
Error if the argument is not specified correctly.
Terminates if <targets> fails to resolve to one or more valid entities (named players must be online).
When multiple entities are selected, next subcommand is executed once each per execution position.
Example
All sheep move upward 1 block: execute as @e[type=sheep] at @s run tp ~ ~1 ~
Kill yourself: execute at @e[type=sheep] run kill @s

facing[edit]

Change the execution rotation to facing either the given position or the targeted entity's/entities' eyes or feet, but does not change the current executor. Changes the function of ^ΔT ^ΔN ^ΔB positioning.

Syntax
facing (<pos>|entity <targets> <anchor>) -> execute
Arguments
<targets>
Specifies the target(s). Must be a player name, a target selector or a UUID
Permits entities other than players.
<anchor>
Must be one of feet and eyes.
<pos>
Must be in form of <x> <y> <z>. May use tilde and caret notation.
Result
Error if the argument is not specified correctly.
Terminates if <targets> fails to resolve to one or more valid entities (named players must be online).
When multiple entities are selected, next subcommand is executed once each per execution rotation.
Example
All entities move one block in the direction of (0, 64, 0) (without changing their rotation): execute as @e at @s facing 0 64 0 run tp @s ^ ^ ^1
All entities move one block in the direction of (0, 64, 0) (with changing their rotation): execute as @e at @s facing 0 64 0 run tp ^ ^ ^1
All non player entities move one space in the direction of their nearest player (without changing their orientation): execute as @e[type=!player] at @s facing entity @p eyes run tp @s ^ ^ ^1

in[edit]

Change the execution dimension to specified dimension.

Syntax
in <dimension> -> execute
Arguments
<dimension>
Must be in form of namespaced ID.
The standard dimensions in the minecraft namespace are "overworld", "the_nether", and "the_end".
Result
Error if the argument is not specified correctly.
Example
Looking for an end city in the end (can find even though players is in the overworld):execute in the_end run locate EndCity
Transport player to the nether with coordinates unchanged: execute in the_nether run teleport ~ ~ ~

positioned[edit]

Use either the given coordinates or the targeted entity's coordinates for the execution position. Changes the function of ^ΔT ^ΔN ^ΔB and ~Δx ~Δy ~Δz positioning. Does not change rotation, dimension, or executor.

Syntax
positioned <pos> -> execute
positioned as <targets> -> execute
Arguments
<targets>
Specifies the target(s). Must be a player name, a target selector or a UUID
Permits entities other than players.
<pos>
Must be in form of <x> <y> <z>. May use tilde and caret notation.
Result
Error if the argument is not specified correctly.
Terminates if <targets> fails to resolve to one or more valid entities (named players must be online).
When multiple entities are selected, next subcommand is executed once each per execution position.
Example
Look for a village near (0, 64, 0): execute positioned 0 64 0 run locate Village
Let all sheep move one block in the direction of the executor's rotation (for example, when the executor looks east, the sheep moves one block eastward; when the executor looks up, the sheep moves one block upward): execute as @e[type=sheep] positioned as @s run tp @s ^ ^ ^1

rotated[edit]

Change the execution rotation to rotating either in the given direction or the same the targeted entity is facing.

Syntax
rotated <rot> -> execute
rotated as <targets> -> execute
Arguments
<rot>
Specifies the rotation. In form of <horizontal rotation> <vertical rotation>
For the horizontal rotation, -180.0 for due north, -90.0 for due east, 0.0 for due south, 90.0 for due west, to 179.9 for just west of due north, before wrapping back around to -180.0.
For the vertical rotation, -90.0 for straight up to 90.0 for straight down.
Tilde notation can be used to specify a rotation relative to the current execution rotation.
Result
Error if the argument is not specified correctly.
Terminates if <targets> fails to resolve to one or more valid entities (named players must be online).
When multiple entities are selected, next subcommand is executed once each per execution rotation.
Example
Move every sheep 1 block toward the player closest to it: execute as @e[type=sheep] at @sORpositioned as @s rotated as @p run tp @s ^ ^ ^1

Condition subcommands[edit]

Syntax and arguments[edit]

(if|unless) block <pos> <block> -> [execute]

Compares the block at the given position to the given block ID.

(if|unless) blocks <start> <end> <destination> (all|masked) -> [execute]

Compare region between the <start> and <end> positions to the area starting at the <destination> position. The calculation of the areas as well as the (all|masked) argument work in the same way as they do in the /clone command.
  • <start>, <end>, and <destination>
    Specifies the coordinates of the two diagonal corner of source region and the coordinates of the northwest lower corner of destination region.
    Must be in form of <x> <y> <z>. May use tilde and caret notation.
  • all
    Compare all the blocks in regions.
  • masked
    Ignore the position where is air in the source region.

(if|unless) data (block <pos>|entity <target>|storage <source>) <path> -> [execute]

Check whether the targeted block, entity or storage has any data for the tag named by <path>.
  • <path>
    Specifies an NBT path to check for.

(if|unless) entity <targets> -> [execute]

Check whether one or more <targets> exist.
  • <targets>
    Specifies the target(s). Must be a player name, a target selector or a UUID
    Permits entities other than players.

(if|unless) predicate <predicate> -> [execute]

Check whether the <predicate> evaluates to a positive result.
See Predicate for more information on predicates

(if|unless) score <target> <targetObjective> (<|<=|=|>=|>) <source> <sourceObjective> -> [execute]

Check whether the target entity's score accurately relates to source entity's score, given some conditional operator.

(if|unless) score <target> <targetObjective> matches <range> -> [execute]

Check whether the target entity's score is within given range (e.g. 1, 1..5).

General arguments[edit]

<pos>
Specifies the coordinates of a block to check.
Must be in form of <x> <y> <z>. May use tilde and caret notation.
<target>
Specifies a single score holder, which can be a player name, a target selector or *(commands fails).
<targetObjective>
Specifies a scoreboard objective.

Result[edit]

Error if the argument is not specified correctly.
When not at the end of the subcommands chain, Only if the condition tests pass is the subcommand following it executed. If it is executed multiple times by multiple variables (e.g. excuetors, execution positions, execution rotations), it acts as a variable filter - Only the variable that matches the condition executes the next subcommand.
When at the end of the subcommands chain, it checks whether the condition is met and then outputs.

Example[edit]

  • Kill all players standing on a wool: execute as @a at @s if block ~ ~-1 ~ #wool run kill @s
  • Check whether your own score a and b are equal: execute if score @s a = @s b

Store subcommands[edit]

Store the success and a result value of a command somewhere.

It first records the location to store in, and then stores in the location after all the commands are executed.

Note that the return values of commands must be an integer. If a decimal, it is rounded down.

Syntax[edit]

store (result|success) block <pos> <path> (byte|short|int|long|float|double) <scale> -> execute

Saves the return value in block entity at the given position. Store as a byte, short, int, long, float, or double. If the return value is a decimal, it is rounded first and then multiplied by <scale>.

store (result|success) bossbar <id> (value|max) -> execute

Saves the return value in either the current value or the maximum value of the given bossbar.

store (result|success) entity <target> <path> (byte|short|int|long|float|double) <scale> -> execute

Use the data tag path from one targeted entity to save the return value. Store as a byte, short, int, long, float, or double. If the return value is a decimal, it is rounded first and then multiplied by <scale>.
Like the "/data" command, "/execute store <arguments>" cannot modify player NBT.

store (result|success) score <name> <objective> -> execute

Use the scoreboard under <name> and <objective> to save the return value.

store (result|success) storage <target> <path> (byte|short|int|long|float|double) <scale> -> execute

Uses the <path> within storage <target> to store the return value in. Store as a byte, short, int, long, float, or double. If the return value is a decimal, it is rounded first and then multiplied by <scale>.
If the storage does not yet exist, it gets created.

Arguments[edit]

<pos>
Specifies the coordinates of a block entity to store.
Must be in form of <x> <y> <z>. May use tilde and caret notation.
<path>
Specifies an NBT path to store return value in.
<id>
ID of the bossbar to store return value in.
<target> in entity mode
Specifies a single entity, which can be a player name, a target selector or a UUID.
<name>
Specifies a score holder, which can be a player name, a target selector or *.
<objective>
Specifies a scoreboard objective.
<target> in storage mode
Target storage container, as a namespaced ID.

Result[edit]

Error if the argument is not specified correctly.
In block and entity mode, does not store anything when the path does not exist.

run subcommand[edit]

Specifies the command to be executed, the variables of which may be modified by the subcommands used.

Syntax[edit]

run <command>

Arguments[edit]

<command>

Can be any command
Technical: Resets the command node to the root of the command dispatcher
Information on modelling commands as chat text:
  • The command dispatcher is what starts when the player begins a message with a forward-slash (/).
  • A command node is the specific word/entry the cursor is editing, either a command or an argument.
  • The root node comes before the first word in the current command.

Result[edit]

Execute this command. Fails if <command> is failure.

More examples[edit]

  • Teleport all players who have an item enchanted with Efficiency in their first hotbar slot to coordinates (0, 64, 0):
    /execute as @a if data entity @s Inventory[{Slot:0b}].tag.Enchantments[{id:"minecraft:efficiency"}] run tp @s 0 64 0
  • Create a smoke particle three blocks in front of all players:
    /execute at @a anchored eyes run particle smoke ^ ^ ^3
  • Place a saddle on pigs located within 5 blocks of the executing player, and remove saddles from pigs located over 5 blocks away from the executing player:
    /execute as @e[type=pig] at @s store success entity @s Saddle byte 1 if entity @p[distance=..5]
  • Make a player say "My feet are soaked!" in chat if they are located in a block of water:
    /execute as @a at @s if block ~ ~ ~ water run say "My feet are soaked!"
  • Make a player say "Score is reset" in chat if the score 'test' is not set, eg by doing "scoreboard players reset @s test":
    /execute as @a unless score @s test = @s test run say "Score is reset"

Bedrock Edition[edit]

Syntax[edit]

execute <origin: target> <position: x y z> <command: command>
An alternate syntax allows the command to be executed only if a specific block is detected:
execute <origin: target> <position: x y z> detect <detectPos: x y z> <block: Block> <data: int> <command: command>

Arguments[edit]

origin: target

Specifies the target to be the command's executor. Must be a player name or target selector. If more than one entity is selected, the command is run once as each of them.

position: x y z

Specifies the position from which to run the command. Coordinates specified with tilde and caret notation are relative to the target, not to the position of the command's execution.

command: command

Specifies the command to be run. Must be a valid command.

detectPos: x y z

Specifies the position of the block to check. May use tilde and caret notation to specify distances relative to position: x y z.

block: Block

Specifies the block ID that the block at detectPos, must match for the command to run. Must be a valid block ID.

data: int

Must be a valid block data for that type of block or -1 to match any block data.

Result[edit]

Fails if arguments are not specified correctly, if origin: target fails to resolve to one or more valid entities (named players must be online), if the checked block is not of the correct block id, data or state, or if the specified command fails.

On success, executes the specified command as if executed by the specified target(s), done with operator-level permission at the specified coordinate.

Examples[edit]

  • To summon lightning bolts at the positions of every zombie:
    execute @e[type=zombie] ~ ~ ~ summon lightning_bolt
  • To summon lightning bolts at the positions of every zombie standing on any type of sand:
    execute @e[type=zombie] ~ ~ ~ detect ~ ~-1 ~ minecraft:sand -1 summon lightning_bolt
  • To summon 10 creepers at the nearest player's position (only works as long as there are at least 10 entities in the loaded world):
    execute @e[c=10] ~ ~ ~ execute @p ~ ~ ~ summon creeper ~ ~ ~

History[edit]

Java Edition
1.814w07aAdded /execute.
14w08aCommands run using /execute now pass their success value back to the command block running them.
1.1116w32aAdded block state support to /execute.
1.1317w45aThe syntax of /execute has been split off.
17w45bReworked /execute store.
18w02aAdded new subcommands to /execute to allow for more control over commands.
18w05aAdded /execute store.
1.1418w43aAdded /execute (if|unless) data.
1.1519w38aAdded /execute if predicate.
Added /execute store storage.
Pocket Edition Alpha
0.16.0build 1Added /execute.
Functionality almost is equivalent to Java Edition 1.10 usage, except the entity target is optional in /execute.