Populators

Populators are the block rules under populators: in a season file. They put blocks such as snow, flowers or leaf litter on the ground, or swap the surface block (water to ice), in the chunks sent to players. Only players see these blocks: the server keeps its real blocks, which other plugins see, and nothing is saved.

Each key under populators is one rule, named by the key. A rule needs block or block-pool to place anything.

• A value the plugin cannot use logs a warning naming the season file, the rule and the option, and in most cases skips the rule.
• /ms reload reads the rules again, but chunks players already have keep their blocks until they are sent again, see Chunk refresh.

When rules run

A chunk gets the rules of a season when it is sent to a player and all of these hold:

• the world is in that season, or the chunk lies in a WorldGuard region whose permanent-season flag names it;
• modify-biome-on-client is true in config.yml;
• the player has not turned season colours off with /toggleseasoncolors;
• no land plugin has switched season effects off there, see Land Claims.

Rules are stored per biome-color-index, so two seasons with the same index share one set. Block replacements run on the chunk first.

Rules work on the surface of each column: the highest block that is not air, leaves, a snow layer or moss carpet. They are tried from the lowest priority up.

A plant standing on the ground is itself the surface, so a rule with scan-for: [GRASS_BLOCK] skips a column with short grass or a flower on top, and require-snowable rejects the plant.

What to place

• A pool entry without material, or with a weight that is not a number (default 1), skips the whole rule. An unknown material is left out of the pool with Unknown material in populator pool '<rule>': <material>. When no entry is left, the rule uses block, or places nothing without one.
• A REPLACE_IN_PLACE rule without scan-for replaces the surface of every column that passes its other checks.

Snow layers

layers sets how many snow layers a SNOW rule places in a column: a whole number, or a formula in quotes worked out per column. Formulas take numbers, +, -, *, /, parentheses, min(a, b), max(a, b) and three names:

The result is rounded, above 8 counts as 8, and 0 or less places no snow in that column. Without layers a snow rule places 1 layer. A value that is neither a number nor a formula skips the rule. On a block other than SNOW, layers is ignored.

The snow exists only on the players' screens, so deep snow has side effects:

• From 2 layers up, players stand on top of the snow, (layers - 1) / 8 of a block above the ground, where the server sees air.
• A player standing on 6 or more layers on open ground can count as flying and is kicked after about 4 seconds, unless allow-flight is true in server.properties.
• On a Minecraft 26.3 server, a player standing on 2 or more layers is sent the real blocks under their feet at most every 10 seconds, which takes that snow away.

Light melts snow

A rule that places SNOW skips every spot where the block light is 12 or higher, the level at which real snow layers melt.

• Only block light counts, not sunlight, and only SNOW: ice, snow blocks and every other block a rule places ignore light.
• A skipped spot does not count as placed, so the rules after it still run on that column.
• A light of level 13 or higher placed later melts the snow around it too, in worlds whose current season has a rule with block: SNOW.
• Removing a light sends nothing. The snow comes back the next time the chunk is sent.

Where to place

• scan-for, surface-blacklist, destroyable-blocks, block-pool and phase-density must be YAML lists, and phase-multipliers and noise sections with indented keys. A single value on the key's own line (scan-for: GRASS_BLOCK) is ignored without a warning, so a scan-for written that way matches every surface.
• The block above the surface is always air, leaves, a snow layer or moss carpet, so destroy-flora only does something when destroyable-blocks names one of those.

How often

Noise

A noise section gives a rule a smooth pattern across the world. Its value at a column runs from 0 to 1: the share of the ground with a lower value, whatever the other noise options are.

Snow coverage

Snow coverage is a number from 0 to 1 per column. A rule with use-snow-coverage: true places its block only where there is coverage, and a layers formula reads it as coverage. In every world, snow only shows from the phase in first-snowfall-phase on, and never in END unless that is 4.

In a world with the weather simulation

Each column keeps its own snow cover, so snow lies where it snowed. The cover changes with the weather there:

• It grows from 0 to 1 within weather.snow-cover.build-minutes while snow falls there (rain above weather.rain-precip-threshold with ground air below weather.snow-temp-threshold).
• Rain melts it within rain-melt-minutes.
• Dry air at or above the snow temperature thaws it within thaw-minutes.
• Cold air without snowfall keeps it as it is.

The times are weather minutes, see Weather.

• A partial cover puts snow on that share of the blocks, always the same ones.
• Players see the snow settle and melt as the cover changes.
• Columns with no player near keep their snow until the weather runs there again. The cover is saved with the weather in the world folder and survives a restart. It is cleared when the world reaches END and when its season changes.
• With shared weather, each server keeps and saves its own cover from the weather it receives.

In other worlds

The coverage is one number per world, kept in memory and 0 again after a restart. It is 0 before first-snowfall-phase. A chunk sent while the world has a vanilla storm (rain or snow) raises it to the ceiling of the current phase. Between storms it holds, but never above the ceiling:

• With SIMPLEX noise the columns with the highest noise are covered first. Without noise each column rolls on its own.
• The coverage is only worked out while chunks are sent. Chunks sent earlier keep their snow until they are sent again.
• With sub-seasons off the phase is always MIDDLE.

Shipped rules

The 12 small flowers are dandelion, poppy, blue orchid, allium, azure bluet, the four tulips, oxeye daisy, cornflower and lily of the valley. example.yml holds snow, ice, flora and leaf-litter rules with enabled: false.

Switching rules at runtime

The seasonpopulator mechanic changes rules while the server runs:

• action=disable;rule=<id> sets the chance of every rule with that id, in every season, to 0, and action=enable gives it back. The id is matched exactly, case included. Rules with use-snow-coverage or phase-density, such as the shipped snow and ice, do not read their chance, so disable does not stop them.
• action=refresh sends the loaded chunks within radius chunks (3 by default) of the target again, to every player in the world who has them in view.
• enable and disable live in memory only: /ms reload and a restart rebuild the rules from the files, and a rule with enabled: false cannot be enabled. Neither changes chunks already sent, so follow them with refresh.

Chunk refresh

Players see changed rules once their chunks are sent again, which happens:

• when the season or phase of the world changes. The chunks within the server's view distance of each player are sent again slowly: with view distance 10 and one player, the first after about 44 seconds and the last after about 88. Every further player in the world adds about as much again;
• with seasonpopulator{action=refresh};
• when the snow cover near a player changes, in a world with the weather simulation, see Snow coverage;
• when a bright light is placed near a player in a world with a snow rule, see Light melts snow;
• when a player loads the chunk again, by moving away and back or by logging in again.

/ms reload sends no chunks.

Breaking populator blocks

Players can break a populator block that sits in the air, such as snow, a flower or leaf litter. It disappears for them and everyone within 64 blocks, and drops what the real block would drop with the right tool. A block that replaced another one, like ice on water, cannot be broken this way.

Examples

populators:
  wildflowers:
    priority: 30
    scan-for:
      - GRASS_BLOCK
    chance: 8%
    phase-multipliers:
      START: 0.25
      EARLY: 0.5
    block-pool:
      - material: DANDELION
        weight: 3
      - material: CORNFLOWER
        weight: 1
    noise:
      type: SIMPLEX
      scale: 0.03
      threshold: 0.6

Flowers in patches over 40 percent of the grass, with an 8 percent chance per column inside them (a quarter of that in START, half in EARLY).

populators:
  drifts:
    priority: 40
    block: SNOW
    use-snow-coverage: true
    layers: "1 + 3 * noise * coverage"
    require-snowable: true
    noise:
      type: SIMPLEX
      scale: 0.01
      octaves: 3
      stretch: 2.0
      angle: 25

Drifts about twice as long as they are wide, along 25 degrees: 1 layer of fresh snow, up to 4 at full cover where the noise is highest.

populators:
  late-ice:
    priority: 5
    mode: REPLACE_IN_PLACE
    block: ICE
    scan-for:
      - WATER
    require-non-matching-neighbor: true
    phase-density: [0.0, 0.0, 1.0, 1.0, 0.5]

Water next to a shore freezes from MIDDLE on, and half of it thaws again in END.