Commands/spreadplayers
Restrictions | |
---|---|
First introduced |
Teleports entities to random surface locations within an area.
Syntax[edit]
- 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[edit]
JE: <center>
: vec2
BE: x: value
: RelativeFloat and <z: value>
: RelativeFloat
- Must be a two-dimensional coordinates with floating-point number elements. Accepts tilde and caret notations.
- Specifies the center of the region to spread targets to.
JE: <spreadDistance>
: float
BE: spreadDistance: float
: float
- Must be a Single-precision floating-point format number. And it must be at least 0.0.
- Specifies the minimum distance between targets.
JE: <maxRange>
: float
BE: maxRange: float
: float
- 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>
. - 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. And it must be greater than or equal to 1.0.
- Specifies the maximum height for resulting positions.
- Must be a boolean (either
true
orfalse
). - Specifies whether to keep teams together. If
true
, targets on the same team are teleported to the same location.
JE: <targets>
: entity
BE: victim: target
: CommandSelector<Actor>
- Must be a player name, a target selector or a UUID[Java Edition only].
- Specifies the targets to spread.
Result[edit]
Command | Trigger | Java Edition | Bedrock Edition |
---|---|---|---|
any | the arguments are not specified correctly | Unparseable | Failed |
if <targets> or player: target fails to resolve to one or more entities (named players must be online) | Failed | ||
if there are too many targets to satisfy the <spreadDistance> requirement within the specified area | |||
/spreadplayers ... under ... | if there is no space under <maxHeight> to spread to. | N/A | |
any | On success | Teleports targets to random surface locations within the specified area. |
Output[edit]
Command | Edition | Situation | Success Count | /execute store success ... | /execute store result ... |
---|---|---|---|---|---|
any | Java Edition | On fail | 0 | 0 | 0 |
/spreadplayers ... true ... | On success | 1 | 1 | the number of teams the targets are on | |
/spreadplayers ... false ... | On success | 1 | 1 | the number of targeted entities | |
any | Bedrock Edition | On fail | 0 | N/A | N/A |
On success | 1 | N/A | N/A |
Note[edit]
Targets are always placed on the top block at a location (if not in under
mode), and never on lava.
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[edit]
- 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
See also[edit]
/tp
and/teleport
— different commands that teleport a single player or entity to a specific position (even underground).
History[edit]
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 . |