Scatter Parameters | ezEdits Wiki

Last updated 2 days ago

and place multiple structures within a region. The positions that these commands choose can be customized with the parameters described on this page.

scatter first extracts all surface blocks (all non-air blocks touching air) from a region defined by -h <region>. You can filter out surfaces that do not match certain conditions using -d <directions> & -e <threshold>, and -m <mask>. On the remaining surfaces, a placement position distribution according to the given density -n <density> and uniformity -u <iterations> is calculated and structures are placed.

Scatter Region: `-h <region>`

Determines the region in which the placement positions are scattered.

Defaults to:
- Your currently selected region for //ezscatter
  - -h Active(UseOriginalPosition:true)
- or a 40x40x40 cuboid region around the clicked position for //ezbrush scatter.
  - -h Box(Dimensions:"40,40,40")

Available options:

Box (B): A cuboid region. (Named Box to have single-letter abbreviations)
Ellipsoid (E): An ellipsoidal region
Cylinder (C): A cylindrical region
- The dimensions of the first three can be set using the Dimensions (D) parameter, e.g. Box(Dimensions:"60,30,60") or B(D:"60,30,60"). It defaults to "40,40,40".
Saved (S): A selection saved using //ezsel save.
- Requires you to define the Name (N) parameter, choosing one of your saved selections.
Active (A): Your currently selected region.
- Contrary to the first three region options, these last two options have an inherent position in the world. You may choose to override their position by moving them to the player (//ezsc) or the clicked position (//ezbr sc), or use their inherent position using the UseOriginalPosition (P) parameter. The default value for the region argument for //ezsc is in fact -h Active(UseOriginalPosition:true). If you set it to false, then the command is executed with the region shifted to your player location.
By default, the center of the region is positioned at the target position. You may define an offset using the Offset (O) parameter to move it relative to its target position. The default is (0,0,0).

Examples

Ex. command: //ezbrush scatter Clipboard -h <region>

Gif going through the following options, using the brush once at the same position:

-h Box
-h Cylinder
-h Saved(Name:$triangle)
-h Saved(Name:$triangle,Offset:(0,0,10))

Whereby $triangle is just some 3-point polyhedral selection I saved with //ezsel.

Directional Filter: `-d <directions>` and `-e <threshold>`

Enables filtering out placement positions on surfaces that are facing certain directions.

The -d <directions> parameter defines the list of cardinal directions (up, down, north, east, south, west) in which the surface, on which the placement positions points are placed at, must face. If a placement position does not satisfy this condition, no structure will be placed there.

The -e <threshold> parameter defines how much the surface normal at the placement position must align with any of the directions given by -d. The higher the value the stronger the filter.

-d defaults to an empty list (nothing).

-e defaults to 0.5. Expected value range is -1 to 1.

Examples

//ezsc Clipboard S C -d <directions> -e <threshold>

-d west,up -e 0.5 (Satter points must be on a surface facing either west or up.)

-d up -e <threshold> (scatter points must be on a surface facing roughly upwards)

starts at -e -1.0 (weakest filter threshold, all shapes are placed)
pauses at -e 0.0 (half of all directions are filtered out)
and ends at -e 1.0 (strongest filter threshold, no shapes are placed anymore).

Mask Filter: `-m <mask>`

Enables filtering out placement positions that do not match a mask given by -m <mask>. Placement positions must satisfy the mask for a structure to be placed.

Examples

//ezsc Clipboard S C -m <mask> (with the clipboard being a default vanilla oak tree)

Using the following masks:

-m red (only placement positions on red wool blocks are chosen)
-m !red (only placements positions on anything but red wool blocks are chosen)
-m =y>95 (only placement positions which are above y>95 are chosen)

Density: `-n <density>`

Determines how many placements are placed, by specifying a density percentage.

The density value is a percentage. It determines what percentage of surface blocks a structure is placed on. Specifically, it determines the percentage of positions after the directional filter and the mask filter have been applied.

To be overly specific: Let N be the remaining surface blocks (e.g. the result of //count [!air]&[~air] if neither filter is used), then the final amount of structures placed is equal to N * density / 100.

The percent sign "%" is optional. 0.5 is interpreted as 0.5%.

Examples

//ezsc Clipboard C C -n <density> (with the clipboard being a default vanilla oak tree)

-n 2% (default) or -n 2 (% is optional):

-n 0.5%

-n 5%

Note when using -d or -m:

The density specifies the percentage of remaining surface blocks on which a placement is placed.

If for example, you use the mask filter to restrict the placement to a specific block which only rarely occurs within your selection, e.g. with the following region and -m sea_lantern,

Then -n 2%, the default density, implies that from all sea_lantern blocks (that touch air) only 2% are chosen as a placement position. The result of doing //ezsc Clipboard -m sea_lantern is therefore:

For cases like these, where you want to place a structure at every instance of a specific block you'd therefore use -n 100%. Doing //ezsc Clipboard -m sea_lantern -n 100% in our example results in:

Distribution Seed: `-i <seed>`

Sets the seed for the random number generator which chooses the initial random placement positions.

Defaults to -1 (random seed), meaning that the placement positions differ in each execution of the scatter command.

Uniformity: `-u <iterations>`

Determines how uniformly spread out all placement positions are. Expecting a positive integer including 0.

Defaults to 15.

The uniformity algorithm works by starting with fully random placement positions, and iteratively repelling all positions apart from one another. This parameter sets the number of repelling iterations to perform. Thus, 0 means the placement positions within your region are purely random.

Examples

//ezsc Clipboard C C -u <iterations> (with the clipboard being a default vanilla oak tree)

-u 0 (fully random distribution)
-u 2 (slightly uniform distribution)
-u 20 (very uniform distribution)

GIF starting with -u 0 and ending with -u 20:

Mask Cover Block: `-l <pattern>`

This is a niche utility option for cases in which you apply a scatter multiple times in a neighbouring region but do not want to place structures in areas where you already did scatter before. So using this flag, you can (temporarily within your workflow) overwrite all surface blocks within your region with the given block, such that any following scatter operations that overlap with already covered regions, do not place structures there because the surface blocks have been "covered".

Examples

//ezbrush scatter Clipboard -m clay

Running ezbrush scatter without the -l flag results in densely placed area wherever the clicked areas overlap, which may not be the desired result.

//ezbrush scatter Clipboard -m clay -b pink

Running ezbrush scatter with -b pink, whereby pink wool is just some random block in this case, covers the affected areas such that, combined with the -m clay mask filter subsequent brush clicks do not place any new shapes there, even when the regions overlap.

Trim outside selection: `-t`

By default scatter will determine placement positions within the currently selected region, but will place blocks outside the region if a placement position is at the border of the currently selected region. You may cut off any such blocks (prevent them from being placed) with this -t flag.

Turning on this flag is comparable to running the command with //gmask #region (for //ezscatter at least).

Examples

If this is our selected region:

Then executing the ezsc command without the flag will result in blocks potentially being placed outside the region. Only the placement/origin positions are restricted to the region.

Without -t flag:

//ezsc Cl C C -s 15,21,15 -n 0.5%

With -t flag:

//ezsc Cl C C -s 15,21,15 -n 0.5% -t