Command
/spreadplayers
Teleports entities to random surface positions spread out around a center point.
Syntax
| /spreadplayers <center> <spreadDistance> <maxRange> <respectTeams> <targets> |
| /spreadplayers <center> <spreadDistance> <maxRange> under <maxHeight> <respectTeams> <targets> |
Arguments
| Argument | Kind of value | What to type |
|---|---|---|
| <center> | Flat position | The X and Z coordinates of the center of the area. |
| <spreadDistance> | Decimal number | The minimum distance in blocks between positions. 0 or more. At least 0. |
| <maxRange> | Decimal number | How far from the center, in blocks along X and Z, positions may be. 1 or more. At least 1. |
| <respectTeams> | True or false | true keeps team members together at one position, false spreads every entity separately. |
| <targets> | Target selector | The entities to spread. Any entities, not only players. One or more entities. |
| <maxHeight> | Whole number | The highest Y level an entity may land at. A whole number, not below the bottom of the world. |
Details
| Permission level | 2: operators, worlds with cheats on, command blocks and functions |
| Works in | Singleplayer with cheats enabled, multiplayer servers, command blocks and functions. Needs permission level 2 (gamemasters): operators, players in a world with cheats enabled, command blocks and functions. |
| Result | Reports "Spread N entity/entities around X, Z with an average distance of D block(s) apart", or the same for teams. The number /execute store saves is the number of positions used: the number of entities, or the number of teams when teams are kept together. |
| Area | Positions are chosen inside a square around the center that reaches maxRange blocks in each direction along X and Z. |
| Spread distance | spreadDistance is the smallest distance allowed between two positions. 0 allows any spacing. |
| Where entities land | Each entity is placed on the highest block that has two blocks of Air above it, at the center of that block. The block must be solid and must not be a liquid. |
| under | under <maxHeight> limits how high the landing position may be, which is useful under a roof or in the Nether. The search for a landing block starts at that height. A value below the bottom of the world fails with "Invalid maxHeight ...; expected higher than world minimum ...". Without under, the full height of the world is used. |
| respectTeams | With true, all players of the same team are sent to the same position. Players without a team and entities that are not players share one position. With false, every entity gets its own position. |
| Failure | The game tries up to 10,000 times to find positions. If the area is too small for the spacing, it fails with "Could not spread ... (too many entities for space - try using spread of at most ...)". |
Examples
/spreadplayers 0 0 10 50 false @aSpreads all players within 50 blocks of 0, 0, at least 10 blocks apart.
/spreadplayers ~ ~ 5 20 true @aSpreads the teams around your position within 20 blocks, with each team landing together.
/spreadplayers 100 -200 0 30 false @e[type=minecraft:cow]Scatters all Cows randomly within 30 blocks of X 100, Z -200.
/spreadplayers 0 0 20 100 under 120 false @aSpreads all players within 100 blocks of 0, 0 on ground below Y 120, for example under the Nether roof.
/spreadplayers ~ ~ 3 15 under 64 true @aSpreads teams around your position within 15 blocks, only on ground below Y 64.
/spreadplayers ~ ~ 2 10 false @e[type=minecraft:sheep,distance=..30]Scatters the Sheep within 30 blocks of you over a 10-block range around you.
