Minecraft:Commands/spreadplayers

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 Minecraft:entities to random surface locations within an area. Despite its name, this command can be used to teleport any entities, not just players.

Usage

Template:IN, 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.

Template:IN, 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, Minecraft:bubble column, or Minecraft:fire. Positions above these blocks are invalid. Template:IN, Minecraft:magma block, Minecraft:wither rose, Minecraft:campfire, Minecraft:soul campfire, Minecraft:sweet berry bush, nether portal, end portal, and end gateway are also invalid positions.

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

Template:IN, 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

Template:El: Template:Argument
Template:El: Template:Argument and Template:Argument

Specifies the center of the region to spread targets to.

Template:Arg desc

Template:Argument

Specifies the minimum distance between each two targets.

Template:Arg desc And it should be at least 0.0.

Template:Argument

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

Template:Arg desc Template:IN, it should be at least 1.0 greater than spreadDistance: float.

Template:El: Template:Argument

Template:El：Template:Argument

Specifies the maximum height for the target positions.

Template:IN, Template:Arg desc

Template:El: Template:Argument

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

Template:Arg desc

Template:Argument

Specifies the targets to spread.

Template:Arg desc

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

Template:Output table Template:Output table Template:Output table Template:Output table Template:Output table Template:Output table Template:Output table

Examples

Template:IN, to teleport all Minecraft: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
Template:IN, 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