Minecraft:Commands/spreadplayers: Difference between revisions

Latest revision as of 20:14, 9 April 2026

Example of the /spreadplayers command used on zombies. The /spreadplayers command spreads the entities in a square. This example uses 10 as the radius.

Teleports entities to random surface locations within an area. Despite its name, this command can be used to teleport any entities, not just players.

Usage

in Template:Editions, targets are always placed on the highest non-Minecraft:air block at a horizontal position. If in under mode, targets are always placed on the highest non-Minecraft:air block that is under the specified maximum height and with two air blocks above it. The horizontal coordinates are invalid if there's no such non-Minecraft:air block.

in Template:Editions, targets are always placed one block above the highest solid block at a horizonal position. If with maxHeight: value argument, targets are always placed one block above the highest solid block that is under the specified maximum height. The horizontal coordinates are invalid if there's no such solid block, or if the solid block does not have two air blocks above it.

Targets are never placed on Minecraft:lava, Minecraft:water, bubble column, or Minecraft:fire. Positions above these blocks are invalid. in Template:Editions, magma block, wither rose, Minecraft:campfire, soul campfire, sweet berry bush, nether portal, end portal, and end gateway are also invalid positions.

in Template:Editions, the entities are spread into the command's execution dimension.

in Template:Editions, the command changes an entity's position without changing dimension. But the valid position is calculated in the command's execution dimension.

If there are no valid position, or the targets are too many to satisfy the minimum distance (<spreadDistance> or spreadDistance: float) requirement within valid positions, no entities are spread.

Syntax

Java Edition

spreadplayers <center> <spreadDistance> <maxRange> <respectTeams> <targets>

Spreads players to positions on the top non-air block.

spreadplayers <center> <spreadDistance> <maxRange> under <maxHeight> <respectTeams> <targets>

Spreads players to positions under the maximum height, on the highest non-Minecraft:air block with two air blocks above it.

Bedrock Edition

spreadplayers <x: value> <z: value> <spreadDistance: float> <maxRange: float> <victim: target> [maxHeight: value]

Arguments

REDIRECT Template:Edition

Template:Rcat: <center>: vec2

REDIRECT Template:Edition

Template:Rcat: x: value: RelativeFloat and z: value: RelativeFloat

Specifies the center of the region to spread targets to.

{{#vardefine:onlyje|Template:IN,}}{{#vardefine:onlybe| Template:IN,}}{{#vardefine:je-arg|vec2}}{{#vardefine:be-arg|relativefloat}}Template:Error{{#vardefine:onlyje|}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|}}

Template:El: <spreadDistance>: float
Template:El: spreadDistance: float: float

Specifies the minimum distance between each two targets.

{{#vardefine:onlyje|Template:IN,}}{{#vardefine:onlybe| Template:IN,}}{{#vardefine:je-arg|float}}{{#vardefine:be-arg|float}}Template:Error{{#vardefine:onlyje|}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|}} And it should be at least 0.0.

Template:El: <maxRange>: float
Template:El: maxRange: float: float

Specifies the maximum distance on each horizontal axis from the center of the area to spread targets (thus, the area is square, not circular).

{{#vardefine:onlyje|Template:IN,}}{{#vardefine:onlybe| Template:IN,}}{{#vardefine:je-arg|float}}{{#vardefine:be-arg|float}}Template:Error{{#vardefine:onlyje|}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|}} in Template:Editions, it should be at least 1.0 greater than spreadDistance: float.

REDIRECT Template:Edition

Template:Rcat: <maxHeight>: integer

REDIRECT Template:Edition

Template:Rcat：maxHeight: value: RelativeFloat

Specifies the maximum height for the target positions.

in Template:Editions, {{#vardefine:onlyje|}}{{#vardefine:onlybe| Template:IN,}}{{#vardefine:je-arg|integer}}{{#vardefine:be-arg|}}Template:Error{{#vardefine:onlyje|}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|}}

in Template:Editions, {{#vardefine:onlyje|Template:IN,}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|relativefloat}}Template:Error{{#vardefine:onlyje|}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|}}

REDIRECT Template:Edition

Template:Rcat: <respectTeams>: bool

Specifies whether to keep entities on the same team together. If true, targets on the same team are teleported to the same position.

{{#vardefine:onlyje|}}{{#vardefine:onlybe| Template:IN,}}{{#vardefine:je-arg|bool}}{{#vardefine:be-arg|}}Template:Error{{#vardefine:onlyje|}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|}}

Template:El: <targets>: entity
Template:El: victim: target: CommandSelector<Actor>

Specifies the targets to spread.

{{#vardefine:onlyje|Template:IN,}}{{#vardefine:onlybe| Template:IN,}}{{#vardefine:je-arg|entity}}{{#vardefine:be-arg|entity}}Template:Error{{#vardefine:onlyje|}}{{#vardefine:onlybe|}}{{#vardefine:je-arg|}}{{#vardefine:be-arg|}}

Result

Template:Result table Template:Result table Template:Result table Template:Result table Template:Result table Template:Result table Template:Result table Template:Result table Template:Result table Template:Result table

Output

{{#vardefine:output-table-lines|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:output-table-lines|-2}}{{#vardefine:output-table-lines-now|}}{{#vardefine:command-num-now|}}{{#vardefine:command-line-now|}}{{#vardefine:commands-num|}}{{#vardefine:output-edition-num-now|}}{{#vardefine:output-edition-line-now|}}{{#vardefine:output-editions-num|}}{{#vardefine:je-outputs-dis|}}

{{#vardefine:output-table-lines|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:situation-{{#var:output-table-lines}}|On fail}}{{#vardefine:output1-{{#var:output-table-lines}}|0}}{{#vardefine:output2-{{#var:output-table-lines}}|0}}{{#vardefine:output3-{{#var:output-table-lines}}|0}}{{#vardefine:command-row-{{#var:commands-num}}|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:output-editions-num|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:output-edition-{{#var:output-editions-num}}|je}}{{#vardefine:output-edition-row-{{#var:output-editions-num}}|1}} {{#vardefine:output-table-lines|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:situation-{{#var:output-table-lines}}|On success}}{{#vardefine:output1-{{#var:output-table-lines}}|1}}{{#vardefine:output2-{{#var:output-table-lines}}|1}}{{#vardefine:output3-{{#var:output-table-lines}}|the number of teams that these targets are in}}{{#vardefine:commands-num|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:command-{{#var:commands-num}}|/spreadplayers ... true ...}}{{#vardefine:command-row-{{#var:commands-num}}|1}}{{#vardefine:output-edition-row-{{#var:output-editions-num}}|Expression error: Unrecognized punctuation character "{".}} {{#vardefine:output-table-lines|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:situation-{{#var:output-table-lines}}|On success}}{{#vardefine:output1-{{#var:output-table-lines}}|1}}{{#vardefine:output2-{{#var:output-table-lines}}|1}}{{#vardefine:output3-{{#var:output-table-lines}}|the number of targeted entities}}{{#vardefine:commands-num|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:command-{{#var:commands-num}}|/spreadplayers ... false ...}}{{#vardefine:command-row-{{#var:commands-num}}|1}}{{#vardefine:output-edition-row-{{#var:output-editions-num}}|Expression error: Unrecognized punctuation character "{".}} {{#vardefine:output-table-lines|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:situation-{{#var:output-table-lines}}|On fail}}{{#vardefine:output1-{{#var:output-table-lines}}|0}}{{#vardefine:output2-{{#var:output-table-lines}}|N/A}}{{#vardefine:output3-{{#var:output-table-lines}}|N/A}}{{#vardefine:commands-num|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:command-{{#var:commands-num}}|Any}}{{#vardefine:command-row-{{#var:commands-num}}|1}}{{#vardefine:output-editions-num|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:output-edition-{{#var:output-editions-num}}|be}}{{#vardefine:output-edition-row-{{#var:output-editions-num}}|1}} {{#vardefine:output-table-lines|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:situation-{{#var:output-table-lines}}|On success}}{{#vardefine:output1-{{#var:output-table-lines}}|1}}{{#vardefine:output2-{{#var:output-table-lines}}|N/A}}{{#vardefine:output3-{{#var:output-table-lines}}|N/A}}{{#vardefine:command-row-{{#var:commands-num}}|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:output-edition-row-{{#var:output-editions-num}}|Expression error: Unrecognized punctuation character "{".}}

{{#vardefine:output-table-lines|Expression error: Unrecognized punctuation character "{".}}{{#vardefine:output-table-lines|-2}}{{#vardefine:output-table-lines-now|}}{{#vardefine:command-num-now|}}{{#vardefine:command-line-now|}}{{#vardefine:commands-num|}}{{#vardefine:output-edition-num-now|}}{{#vardefine:output-edition-line-now|}}{{#vardefine:output-editions-num|}}{{#vardefine:je-outputs-dis|}}

Examples

in Template:Editions, to teleport all players by team to random surface locations in a 1,000×1,000-block area centered on (0,0), with a minimum distance between teams of 200 blocks:
- spreadplayers 0 0 200 500 true @aTemplate:Only
in Template:Editions, to teleport one random player from each of three teams (Red, Blue, and Green), as well as Alice and Bob, to random surface locations in a 200×200-block area centered on (0,0), with a minimum distance between players of 50 blocks:
- spreadplayers 0 0 50 100 false @r[team=Red] @r[team=Blue] @r[team=Green] Alice BobTemplate:Only

History

Template:Message box Template:Article other

Java Edition

Template:HistoryTable

Bedrock Edition

Template:HistoryTable

References

External links

Template:Cite

Navigation

All editions

Removed	placefeature

Template:El only

Debug	chase debugconfig debugmobspawning debugpath raid serverpack spawn_armor_trims warden_spawn_tracker

Removed	? achievement banip blockdata broadcast chunk entitydata home iron locatebiome replaceitem setspawn solid stats testfor testforblock testforblocks toggledownfall unban wood

Template:Els only

Template:El only

Removed

Template:El only

Removed	position videostreamaction

Template:Els only

Removed	clearfixedinv executeasself move place setfixedinvslot setfixedinvslots test transferserver

Joke

@@ Line 11: / Line 11: @@
 ==Usage==
-{{IN|java}}, targets are always placed on the highest non-[[Minecraft:air]] block at a horizontal position. If in <code>under</code> mode, targets are always placed on the highest non-[[Minecraft:air]] block that is under the specified maximum height and with two air blocks above it. The horizontal coordinates are invalid if there's no such non-[[Minecraft:air]] block.
+{{MC/In|java}}, targets are always placed on the highest non-[[Minecraft:air]] block at a horizontal position. If in <code>under</code> mode, targets are always placed on the highest non-[[Minecraft:air]] block that is under the specified maximum height and with two air blocks above it. The horizontal coordinates are invalid if there's no such non-[[Minecraft:air]] block.
-{{IN|bedrock}}, targets are always placed one block above the highest solid block at a horizonal position. If with <code>maxHeight: value</code> argument, targets are always placed one block above the highest solid block that is under the specified maximum height. The horizontal coordinates are invalid if there's no such solid block, or if the solid block does not have two air blocks above it.
+{{MC/In|bedrock}}, targets are always placed one block above the highest solid block at a horizonal position. If with <code>maxHeight: value</code> argument, targets are always placed one block above the highest solid block that is under the specified maximum height. The horizontal coordinates are invalid if there's no such solid block, or if the solid block does not have two air blocks above it.
-Targets are never placed on [[Minecraft:lava]], [[Minecraft:water]], bubble column, or [[Minecraft:fire]]. Positions above these blocks are invalid. {{IN|bedrock}}, magma block, wither rose, [[Minecraft:campfire]], soul campfire, sweet berry bush, nether portal, end portal, and end gateway are also invalid positions.
+Targets are never placed on [[Minecraft:lava]], [[Minecraft:water]], bubble column, or [[Minecraft:fire]]. Positions above these blocks are invalid. {{MC/In|bedrock}}, magma block, wither rose, [[Minecraft:campfire]], soul campfire, sweet berry bush, nether portal, end portal, and end gateway are also invalid positions.
-{{IN|java}}, the entities are spread into the command's execution dimension.
+{{MC/In|java}}, the entities are spread into the command's execution dimension.
-{{IN|bedrock}}, the command changes an entity's position without changing dimension. But the valid position is calculated in the command's execution dimension.
+{{MC/In|bedrock}}, the command changes an entity's position without changing dimension. But the valid position is calculated in the command's execution dimension.
 If there are no valid position, or the targets are too many to satisfy the minimum distance (<code><spreadDistance></code> or <code>spreadDistance: float</code>) requirement within valid positions, no entities are spread.
@@ Line 36: / Line 36: @@
 ==Arguments==
-{{el|je|short=1}}: {{argument|center|vec2}}<br>
+{{MC/El|je|short=1}}: {{MC/Argument|center|vec2}}<br>
-{{el|be|short=1}}: {{argument|be=1|x: value|RelativeFloat}} and {{argument|be=1|z: value|RelativeFloat}}
+{{MC/El|be|short=1}}: {{MC/Argument|be=1|x: value|RelativeFloat}} and {{MC/Argument|be=1|z: value|RelativeFloat}}
 : Specifies the center of the region to spread targets to.
-: {{arg desc|je=vec2|be=RelativeFloat}}
+: {{MC/Arg desc|je=vec2|be=RelativeFloat}}
-{{argument|spreadDistance|float|spreadDistance: float|float}}
+{{MC/Argument|spreadDistance|float|spreadDistance: float|float}}
 : Specifies the minimum distance between each two targets.
-: {{arg desc|je=float|be=float}} And it should be at least 0.0.
+: {{MC/Arg desc|je=float|be=float}} And it should be at least 0.0.
-{{argument|maxRange|float|maxRange: float|float}}
+{{MC/Argument|maxRange|float|maxRange: float|float}}
 : Specifies the maximum distance on each horizontal axis from the center of the area to spread targets (thus, the area is square, not circular).
-: {{arg desc|je=float|min=1.0|be=float}} {{IN|bedrock}}, it should be at least 1.0 greater than <code>spreadDistance: float</code>.
+: {{MC/Arg desc|je=float|min=1.0|be=float}} {{MC/In|bedrock}}, it should be at least 1.0 greater than <code>spreadDistance: float</code>.
-{{el|je|short=1}}: {{argument|maxHeight|integer}}
+{{MC/El|je|short=1}}: {{MC/Argument|maxHeight|integer}}
-{{el|be|short=1}}：{{argument|be=1|maxHeight: value|RelativeFloat}}
+{{MC/El|be|short=1}}：{{MC/Argument|be=1|maxHeight: value|RelativeFloat}}
 : Specifies the maximum height for the target positions.
-: {{IN|je}}, {{lcfirst:{{arg desc|je=integer}}}}
+: {{MC/In|je}}, {{lcfirst:{{MC/Arg desc|je=integer}}}}
-: {{IN|be}}, {{lcfirst:{{arg desc|be=RelativeFloat}}}}
+: {{MC/In|be}}, {{lcfirst:{{MC/Arg desc|be=RelativeFloat}}}}
-{{el|je|short=1}}: {{argument|respectTeams|bool}}
+{{MC/El|je|short=1}}: {{MC/Argument|respectTeams|bool}}
 : Specifies whether to keep entities on the same team together. If <code>true</code>, targets on the same team are teleported to the same position.
-: {{arg desc|je=bool}}
+: {{MC/Arg desc|je=bool}}
-{{argument|targets|entity|victim: target|CommandSelector<Actor>}}
+{{MC/Argument|targets|entity|victim: target|CommandSelector<Actor>}}
 : Specifies the targets to spread.
-: {{arg desc|je=entity|amount=multiple|type=entities|be=actor}}
+: {{MC/Arg desc|je=entity|amount=multiple|type=entities|be=actor}}
 ==Result==
@@ Line 79: / Line 79: @@
 == Output ==
-{{Output table}}
+{{MC/Output table}}
-{{Output table|edition=je|On fail|0|0|0}}
+{{MC/Output table|edition=je|On fail|0|0|0}}
-{{Output table|cmd=/spreadplayers ... true ...|On success|1|1|the number of teams that these targets are in}}
+{{MC/Output table|cmd=/spreadplayers ... true ...|On success|1|1|the number of teams that these targets are in}}
-{{Output table|cmd=/spreadplayers ... false ...|On success|1|1|the number of targeted entities}}
+{{MC/Output table|cmd=/spreadplayers ... false ...|On success|1|1|the number of targeted entities}}
-{{Output table|cmd=|edition=be|On fail|0}}
+{{MC/Output table|cmd=|edition=be|On fail|0}}
-{{Output table|On success|1}}
+{{MC/Output table|On success|1}}
-{{Output table}}
+{{MC/Output table}}
 ==Examples==
-* {{IN|java}}, to teleport all players by team to random surface locations in a 1,000×1,000-block area centered on (0,0), with a minimum distance between teams of 200 blocks:
+* {{MC/In|java}}, to teleport all players by team to random surface locations in a 1,000×1,000-block area centered on (0,0), with a minimum distance between teams of 200 blocks:
 ** <code>spreadplayers 0 0 200 500 true @a</code>{{only|java}}
-* {{IN|java}}, to teleport one random player from each of three teams (Red, Blue, and Green), as well as Alice and Bob, to random surface locations in a 200×200-block area centered on (0,0), with a minimum distance between players of 50 blocks:
+* {{MC/In|java}}, to teleport one random player from each of three teams (Red, Blue, and Green), as well as Alice and Bob, to random surface locations in a 200×200-block area centered on (0,0), with a minimum distance between players of 50 blocks:
 ** <code>spreadplayers 0 0 50 100 false @r[team=Red] @r[team=Blue] @r[team=Green] Alice Bob</code>{{only|java}}
 == History ==
-{{Expand section}}
+{{MC/Expand section}}
 === ''Java Edition'' ===
 {{HistoryTable
-|{{HistoryLine|java}}
+|{{MC/HistoryLine|java}}
-|{{HistoryLine||1.6.1|dev=13w23a|Added {{cmd|spreadplayers|link=none}}.}}
+|{{HistoryLine||1.6.1|dev=13w23a|Added {{MC/Cmd|spreadplayers|link=none}}.}}
-|{{HistoryLine||1.16|dev=20w21a|Added an optional <code><maxHeight></code> argument to specify maximum height.}}
+|{{MC/HistoryLine||1.16|dev=20w21a|Added an optional <code><maxHeight></code> argument to specify maximum height.}}
 |{{HistoryLine||1.19.4|dev=22w03a|Now entities are spread to the command's execution dimension.<ref>{{Bug|MC-181832|resolution=Fixed}}</ref>}}
 }}
@@ Line 107: / Line 107: @@
 === ''Bedrock Edition'' ===
 {{HistoryTable
-|{{HistoryLine|pocket}}
+|{{MC/HistoryLine|pocket}}
-|{{HistoryLine||1.0.5|dev=alpha 1.0.5.0|Added {{cmd|spreadplayers|link=none}}.}}
+|{{HistoryLine||1.0.5|dev=alpha 1.0.5.0|Added {{MC/Cmd|spreadplayers|link=none}}.}}
-|{{HistoryLine|bedrock}}
+|{{MC/HistoryLine|bedrock}}
-|{{HistoryLine||1.21.20|dev=beta 1.21.10.23|Added an optional <code>maxHeight: value</code> argument.}}
+|{{MC/HistoryLine||1.21.20|dev=beta 1.21.10.23|Added an optional <code>maxHeight: value</code> argument.}}
 }}
 ==See also==
-*{{cmd|tp}} and {{cmd|teleport}} — different commands that teleport a single player or entity to a specific position (even underground).
+*{{MC/Cmd|tp}} and {{MC/Cmd|teleport}} — different commands that teleport a single player or entity to a specific position (even underground).
 == References ==
@@ Line 125: / Line 125: @@
 == Navigation ==
-{{Navbox commands}}
+{{MC/Navbox commands}}
 de:Befehl/spreadplayers