Minecraft Wiki

The Minecraft Wiki is no longer considered as official by Microsoft and therefore several changes are required to be made, including to the wiki's logo. Please read this announcement for more information.

READ MORE

Minecraft Wiki
Advertisement
spreadplayers
Permission level
required

2‌[JE only]
1‌[BE only]

Restrictions

Cheat only‌[BE only]

Teleports entities to random surface locations within an area.

Syntax[]

  • Java Edition
spreadplayers <center> <spreadDistance> <maxRange> <respectTeams> <targets>
spreadplayers <center> <spreadDistance> <maxRange> under <maxHeight> <respectTeams> <targets>
Spreads players to resulting position under the maximum height.
  • Bedrock Edition
spreadplayers <x: value> <z: value> <spreadDistance: float> <maxRange: float> <victim: target>

Arguments[]

JE: <center>: vec2
BE: x: value: RelativeFloat and z: value: RelativeFloat

Specifies the center of the region to spread targets to.
Must be a two-dimensional coordinates with floating-point number elements. Accepts tilde and caret notations.

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

Specifies the minimum distance between targets.
Must be a Single-precision floating-point format number. And it must be at least 0.0.

JE<maxRange>: float
BE: 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).
Must be a Single-precision floating-point format number. In Java Edition, it must be greater than or equal to 1.0. In Bedrock Edition, it must be at least 1.0 greater than <spreadDistance>.

JE: <maxHeight>: integer

Specifies the maximum height for resulting positions.
Must be a Single-precision floating-point format number. And it must be greater than or equal to 1.0.

JE: <respectTeams>: bool

Specifies whether to keep teams together. If true, targets on the same team are teleported to the same location.
Must be a boolean (either true or false).

JE<targets>: entity
BE: victim: target: CommandSelector<Actor>

Specifies the targets to spread.
Must be a player name, a target selector or a UUID[Java Edition only].

Result[]

CommandTriggerJava EditionBedrock Edition
anythe arguments are not specified correctly Unparseable Failed
<targets> or player: target fails to resolve to one or more entities (named players must be online) Failed
there are too many targets to satisfy the <spreadDistance> requirement within the specified area
/spreadplayers ... under ...there is no enough space under <maxHeight> to spread to N/A
anyOn successTeleports targets to random surface locations within the specified area.

Output[]

CommandEditionSituationSuccess Count/execute store success .../execute store result ...
anyJava EditionOn fail000
/spreadplayers ... true ...On success11the number of teams that these targets are in
/spreadplayers ... false ...On success11the number of targeted entities
anyBedrock EditionOn fail0N/AN/A
On success1N/AN/A

Note[]

Targets are always placed on the top non-air block (whether it's solid or not) at a location (if not in under mode), and never on lava, water, bubble column, or fire.

The /spreadplayers command does not have a uniform distribution over the surface. It has a Gaussian distribution as the positions closer to the position set in the command have a higher chance of having an entity on them. This effect is very subtle and is not visible for short radius but can be a problem if you want a uniform random generation. This problem does not occur for the @r selector and dispensers.

Examples[]

  • 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:
  • 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 Bob[Java Edition only]

See also[]

  • /tp and /teleport — different commands that teleport a single player or entity to a specific position (even underground).

History[]

Jigsaw Block (top texture) JE2 BE2.png
This section needs expansion. 
You can help by expanding it.
Java Edition
1.6.113w23aAdded /spreadplayers.
1.1620w21aAdded an optional maxHeight argument to specify maximum height.
Pocket Edition
1.0.5alpha 1.0.5.0Added /spreadplayers.
Advertisement