Commands/spreadplayers

spreadplayers

Restrictions	Operator
First introduced	Java Edition 1.6.1 (13w23a) PE 1.0.5 (PE alpha 1.0.5.0)

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>

• Bedrock Edition

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

Arguments

<center> (BE: x: value and z: value)

Specifies the center of the region to spread targets to. May use tilde and caret notation to specify coordinates relative to the command's execution.

<spreadDistance> (BE: spreadDistance: float)

Specifies the minimum distance between targets. Must be at least 0.0.

<maxRange> (BE: maxRange: 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). In Java Edition, must be at least 1.0. In Bedrock Edition, must be at least 1.0 greater than <spreadDistance>.

<maxHeight>‌^{[Java Edition only]}

Specifies the maximum height for resulting positions. Must be an integer between -2,147,483,648 through 2,147,483,647 (inclusive).

<respectTeams>‌^{[Java Edition only]}

Specifies whether to keep teams together. Must be true or false. If true, targets on the same team will be teleported to the same location.

<targets> (BE: victim: target)

Specifies the targets to spread. Must be player names, a tilde and caret notation, or a UUID‌^{[Java Edition only]}.

Permits entities other than players.

Result

Fails if the arguments are not specified correctly, if there are too many targets to satisfy the <spreadDistance> requirement within the specified area, or if there is no space under <maxHeight> to spread.

On success, teleports targets to random surface locations within the specified area. Targets will always be placed on the top block at a location, and never on lava.

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:
  • spreadplayers 0 0 200 500 true @a
• 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

Note

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.

See also

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

History

Java Edition
1.6.1		13w23a			Added /spreadplayers.
1.16		20w21a			Added an optional maxHeight argument to specify maximum height.
Pocket Edition
1.0.5		alpha 1.0.5.0			Added /spreadplayers.

Commands

View at: Template:Commands/content [edit]