Commands/execute

From Minecraft Wiki
Jump to: navigation, search
This article is about a command that executes other commands. For the command to kill a player or other entity, see Commands/kill.
execute
Restrictions

Operator

First introduced

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

/execute executes another command but allows changing the executor, changing the position and angle it is executed at, adding preconditions, and storing its result.

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 sender(s), execution position(s), execution dimension(s), execution rotation(s) and execution anchor(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 be put 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 sender: 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> <type> <scale> -> execute
    • … bossbar <id> (max|value) -> execute
    • … entity <target> <path> <type> <scale> -> execute
    • … score <targets> <objective> -> execute
    • … storage <target> <path> <type> <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]

Updates the command's position, aligning to its current block position (an integer). Only applies along specified axes.
This is akin to flooring the coordinates – i.e. rounding them downwards. It updates the meaning of ~ ~ ~ and ^ ^ ^.
Syntax
align <axes> -> execute
Arguments
<axes>: swizzle
Any non-repeating combination of the characters 'x', 'y', and 'z'. (For example, x, xz, zyx, or yz.)
Result
Position is updated, changing by less than 1 block in any direction
Error if the argument is not specified correctly
Example
  • Given position (-1.8, +2.3, +5.9), /execute align xz changes the position of ~ ~ ~(-2, +2.3, +5).
  • Given (+2.4, -1.1, +3.8), /execute align yxz run spawnpoint @p ~ ~ ~ sets the player's spawnpoint to (2, -2, 3).

anchored[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.
Effectively recentres ^ ^ ^ on either the eyes or feet, also changing the angle the facing sub-command works off of
Syntax
anchored <anchor> -> execute
Arguments
<anchor>: entity_anchor (literally eyes or feet)
Whether to anchor the executed command to eye level or feet level
Result
^ ^ ^ positioning is recentred on either the eyes or the feet
Error if the argument is not specified correctly
Example
The effect of /tp is to move a target by placing its feet at the given position.
execute anchored eyes run tp ^ ^ ^ effectively teleports the sender's feet to where its eyes are (the execution position).
execute anchored eyes run tp ^5 ^ ^ means "place the sender's feet 5 blocks left of where its eyes are"

as[edit]

Sets the command sender to target entity, without changing position, rotation, dimension, or anchor
Syntax
as <targets> -> execute
Arguments
<targets>: entity
Target entity/entities to become the new sender.
Result
Sender is updated to target entity (which changes the meaning of @s)
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 sub-command is executed once each per sender.
Example
Get data of all sheep: execute as @e[type=sheep] run data get entity @s

at[edit]

Sets the command position, rotation, and dimension to match those of an entity/entities; does not change sender
Syntax
at <targets> -> execute
Arguments
<targets>: entity
Target entity/entities to match position, rotation, and dimension with
Result
Position, rotation, and dimension are updated to match target entity (which recentres ~ ~ ~ and ^ ^ ^ positioning)
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]

Sets the command rotation to face a given point, as viewed from its anchor (either the eyes or the feet)
Syntax
facing <pos> -> execute
facing entity <targets> <anchor> -> execute
Arguments
Option: facing <pos>
<pos>: vec3
Coordinate to rotate towards
Option: facing entity <targets> <anchor>
<targets>: entity
The target(s) to rotate towards
<anchor>: entity_anchor (literally eyes or feet)
Whether to point at the target's eyes or feet
Result
Rotation is updated to face given position or targets (which realigns ^ ^ ^ positioning)
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
Sender rotates once to the left: execute facing ^1 ^ ^ run tp ~ ~ ~
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]

Sets the command dimension
Syntax
in <dimension> -> execute
Arguments
<dimension>: dimension
Name of the new execution dimension
The standard dimensions in the minecraft namespace are "overworld", "the_nether", and "the_end".
Result
Dimension is updated
Error if the argument is not specified correctly
Example
Looking for an end city (from the overworld): execute in the_end run locate EndCity
Transposes the player into the nether, at their current coordinates: execute in the_nether run teleport ~ ~ ~

positioned[edit]

Sets the command position, without changing rotation or dimension; can match an entity's position
Syntax
positioned <pos> -> execute
positioned as <targets> -> execute
Arguments
Option: positioned <pos>
<pos>: vec3
New position
Option: positioned as <targets>
<targets>: entity
Target entity/entities to match position with
Result
Position is updated
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 sub-command is executed once each per execution position.
Examples
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 sender's rotation (for example, when the sender looks east, the sheep moves one block eastward; when the sender looks up, the sheep moves one block upward):
execute as @e[type=sheep] positioned as @s run tp @s ^ ^ ^1

rotated[edit]

Sets the command rotation; can match an entity's rotation
Syntax
rotated <rot> -> execute
rotated as <targets> -> execute
Arguments
<rot>: rotation (<yaw> <pitch>)
The desired rotation
yaw is measured clockwise in degrees from due south (the +Z direction), ranging [–180 to +180)
pitch is measured as declination from the horizon in degrees, ranging [–90 to +90] (straight up to straight down)
Tilde notation can be used to specify a rotation relative to the current execution rotation.
<targets>: entity
Target entity/entities to match rotation with
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 sub-command is executed once each per execution rotation.
Example
Move every sheep 1 block in the direction that the player closest to it is facing: execute as @e[type=sheep] at @sORpositioned as @s rotated as @p run tp @s ^ ^ ^1

Condition subcommands[edit]

The particular use of the if and unless subcommands are to restrict command execution to happen only under specified conditions. unless is a negation of if, equivalent to "if not..." The two commands have identical argument structures.

There are six different types of conditions:

  1. (if|unless) block – Tests a single real block
  2. (if|unless) blocks – Tests a real 3D rectangular volume against another
  3. (if|unless) data – Tests the data held by a real block, entity, or a storage
  4. (if|unless) entity – Tests whether an entity like the one given is real
  5. (if|unless) predicate – Tests a predicate
  6. (if|unless) score - Tests an target's score

(if|unless) block[edit]

Compares the block at a given position to a given block ID
Syntax
(if|unless) block <pos> <block> -> [execute]
Arguments
<pos>: block_pos
Position of a target block to test
<block>: block_predicate
A valid block ID (or predicate) to test for
Block ID optionally followed by block states (bounded by brackets – []) and/or data tags (bounded by braces – {})

(if|unless) blocks[edit]

Compares the blocks in two equally sized volumes
Syntax
(if|unless) blocks <start> <end> <destination> <scan mode> -> [execute]
Arguments
<start>: block_pos
<end>: block_pos
Positions of any two diagonal corners of the source volume (the comparand; the volume to compare)
<destination>: block_pos
Position of the lower northwest corner of the destination volume (the comparator; the volume to compare to)
Assumed to be of the same size as the source volume
<scan mode> : literal (all|masked)
Specifies whether all blocks in the source volume should be compared, or if air blocks should be masked/ignored

(if|unless) data[edit]

Checks whether the targeted block, entity or storage has any data for a given tag
Syntax
(if|unless) data block <pos> <path> -> [execute] – for data checking a block
(if|unless) data entity <target> <path> -> [execute] – for data checking an entity
(if|unless) data storage <source> <path> -> [execute] – for data checking [a storage?]
Arguments
Option: (if|unless) data block <pos> <path>
<pos>: block_pos
Position of the block to be tested
<path>: nbt_path
Data tag to check for
Option: (if|unless) data entity <target> <path>
<target>: entity
One single entity to be tested
<path>: nbt_path
Data tag to check for
Option: (if|unless) data storage <source> <path>
<source>: resource_location
<path>: nbt_path
Data tag to check for

(if|unless) entity[edit]

Checks whether one or more <targets> exist

Syntax
(if|unless) entity <targets> -> [execute]
Arguments
<entities>: entity
The target entity/ies to check

(if|unless) predicate[edit]

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

Syntax
(if|unless) predicate <predicate> -> [execute]
Arguments
<predicate>: resource_location[Section needs writing]

(if|unless) score[edit]

Check a score against either another score or a given range

Syntax
(if|unless) score <target> <targetObjective> (<|<=|=|>=|>) <source> <sourceObjective> -> [execute] – for comparing two scores
(if|unless) score <target> <targetObjective> matches <range> -> [execute] – for comparing one score against a range
Arguments
<target>: score_holder
A single score holder
* can be executed but fails
<targetObjective>: objective
The scoreboard objective to check under
Option: (<|<=|=|>=|>) <source> <sourceObjective>
<source>: score_holder
A second score holder to compare against
* can be executed but fails
<sourceObjective>: objective
A scoreboard objective
Option: matches <range>
<range>: int_range
Range to compare score against
Result
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. senders, 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
Kill all players standing on a wool: execute as @a at @s if block ~ ~-1 ~ #wool run kill @s
Check whether your own scores A and B are equal: execute if score @s A = @s B

Store subcommand[edit]

Store the final command's result or success value 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.

There are five different modes of storage:

  1. store (result|success) block – Store return value under one of a block's NBTs
  2. store (result|success) bossbar – Store return value as a bossbar data
  3. store (result|success) entity – Store return value under one of an entity's NBTs
  4. store (result|success) score – Store return value under a target's score on an objective
  5. store (result|success) storage – Store return value under one of a storage's NBTs

store (result|success) block[edit]

Saves the final command's return value as tag data within a block entity. 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>.
Syntax
store (result|success) block <targetPos> <path> <type> <scale> -> execute
Arguments
<targetPos>: block_pos
Position of target block
<path>: nbt_path
Location of the desired tag to hold the value in
<type> : literal (byte|short|int|long|float|double)
Desired data size/type
<scale>: double
Multiplier to apply before storing value
Result
Error if the argument is not specified correctly.
Does not store anything when the path does not exist.

store (result|success) bossbar[edit]

Saves the final command's return value in either a bossbar's current value or its maximum value
Syntax
store (result|success) bossbar <id> (value|max) -> execute
Arguments
<id>: resource_location
ID of the bossbar to target for saving
<value> : literal (value|max)
Whether to overwrite the bossbar's current value or its max value
Result
Error if the argument is not specified correctly.

store (result|success) entity[edit]

Save the final command's return value in one of an entity's data tags. 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.
Syntax
store (result|success) entity <target> <path> <type> <scale> -> execute
Arguments
<target>: entity
A single entity to store under
<path>: nbt_path
Location of the desired tag to hold the value in
<type> : literal (byte|short|int|long|float|double)
Desired data size/type
<scale>: double
Multiplier to apply before storing value
Result
Error if the argument is not specified correctly.
Does not store anything when the path does not exist.

store (result|success) score[edit]

Overrides the score held by <targets> on the given <objective> with the final command's return value.
Syntax
store (result|success) score <targets> <objective> -> execute
Arguments
<targets>: score_holder
Specifies score holder(s) whose score is to be overridden
<objective>: objective
A scoreboard objective
Result
Error if the argument is not specified correctly.

store (result|success) storage[edit]

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.
Syntax
store (result|success) storage <target> <path> <type> <scale> -> execute
Arguments
<target>: resource_location (Single word)
Target storage container, as a namespaced ID
<path>: nbt_path
Location of the desired tag to hold the value in
<type> : literal (byte|short|int|long|float|double)
Desired data type/size
<scale>: double
Multiplier to apply before storing value
Result
Error if the argument is not specified correctly


Run subcommand[edit]

The run command's single argument is the command to be executed, the variables of which may be modified by the subcommands used.

Syntax
run --><command>
Arguments
<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
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 sender. 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.