Profiles

An atmosphere profile is a named set of atmosphere settings in its own file in plugins/MythicSeasons/atmosphere-profiles/. A season, a world or a skill can apply it. The rules below hold for every block of atmosphere settings, such as a profile, a season's atmosphere: block or a worlds entry.

Using a profile

A profile file does nothing until one of these places names it.

A profile changes only the settings it names, and later places in the chain still win over it.

The profile file

temperature: "+4"
humidity: "*0.5"
physics:
  auto-rate: "*0.5"
weather:
  rain-precip-threshold: 0.3
cloud-layers:
  cumulus:
    coverage: "*0.6"

Saved as atmosphere-profiles/dry-spell.yml: warmer, drier air with less rain and less cumulus.

• The name is the file name without .yml and is not case-sensitive. Use only letters, digits, - and _, so the name works in a skill line.
• Only .yml files directly in the folder count, read at startup and on /ms reload. example.yml and mars.yml are copied back at every start and reload when they are missing.
• A profile takes what a season's atmosphere: block takes. profile, worlds and transition do nothing in it and log no message, so a profile cannot name another profile.
• A file without any known setting, or with a YAML error (which the server logs), is not loaded or listed. Everything that names it reports that the file does not exist.

Value forms

These forms work for every setting a block can change, the top level of atmosphere.yml included.

• The value so far is what the earlier places of the chain left, or the built-in default. Spaces after the operator do not matter.
• Quote every operator. An unquoted *1.4 is a YAML error and the whole file is not read. An unquoted +3 or -3 is a plain number and sets the value to 3 or -3.
• Relative values stack across places: "*0.5" twice gives 0.25.
• After each place the value is moved into the setting's range without a message, and later places go on from there.
• Text that is neither a number nor a formula logs '<text>' is not a number, an operator or a formula (<reason>), ignoring, and a list or true logs expected a number, an operator like "*1.4", or a keyframe map, ignoring. The setting keeps its value. An empty text sets nothing. Only visible-from-inside in a layer file also takes true and false.
• "/0" logs division by zero, ignoring.

Keyframes

A keyframe map sets values at points of the season. Its keys are percentages (0 to 100) or phase names, and its values can take any form above except another map. The value runs in a straight line between keys and holds the first or last value outside them. The order of the keys does not matter.

A phase name is the middle of its phase. With the default thresholds START is 4.5, EARLY 13.5, MIDDLE 51, LATE 88 and END 96.

• Only a season's own atmosphere: block and its worlds blocks use that season's sub-season-thresholds. Everywhere else, profiles included, phase names use the defaults 9, 18, 84 and 92.
• Phase names are not case-sensitive. Numbers below 0 or above 100 are accepted and lie outside the season. A key that is neither a number nor a phase name logs keyframe '<key>' is neither a percentage nor a phase name (START/EARLY/MIDDLE/LATE/END), ignoring.
• A relative value in a keyframe works on the value so far, and then the two keyframes around the current point are blended.
• clouds.outflow.wind-y and physics.surface-max-humidity (-1 for automatic or off) switch halfway without blending when either keyframe around the current point is negative.
• Progress follows the calendar while the calendar is on and the world has a date. Otherwise it stays at the middle of the current phase, and keyframes do not move.

Formulas

A formula lets a setting follow the date, the time of day, the season's progress or a MythicMobs placeholder. Write it on its own ("0.5 + month / 10") or after an operator ("*(1 + 0.25 * step(6, month))"). Keyframe values, shape numbers and style variables in cloud-layers.<file name> blocks take formulas too. A formula takes numbers, +, -, *, /, parentheses and the values and functions below.

• With the calendar off, or without a date, the date values and weekday are 0 and hour follows the world's clock. weekday is also 0 when week-days is empty.
• Inside a formula, x / 0 is 0. A leading "/" whose formula gives 0 leaves the value as it is.
• Names are not case-sensitive. A - followed by a letter joins words into one name (day-of-year), so subtract with spaces: hour - day. month-1 subtracts 1.
• max-distance in a layer file has its own formula, of view-distance only, see Layer Options.

MythicMobs placeholders

A MythicMobs placeholder, angle brackets included, can stand anywhere a formula takes a number: humidity: "*<global.var.wetness>". The setting follows a change of the variable within a second.

• Placeholders are read without a caster. Global variables and other placeholders that need no mob or player work. Caster, target, skill and world variables give no number.
• <global.var.wetness|1> gives 1 until a skill sets the variable.
• While a placeholder gives no number, the settings that use it keep the value so far, and the console says so once per placeholder. Without MythicMobs no placeholder gives a number.
• On servers that share their weather, the weather follows the calendar and placeholders of the server that simulates it, and each server draws its clouds with its own.

Clouds in a block

• Layer names are not case-sensitive. A block for a layer that is not in the final clouds.layers list does nothing.
• type, color, voxel-size, max-distance, thickness, top-clearance, visible-from-inside, toggle and toggle-default only work in the layer file. In a block they log '<setting>' can only be set in the layer's own file in the cloud-layers folder, ignoring.
• A layer with a shape takes shape.<number> for the numbers that scale or move its pattern (Shapes). A layer with a style takes style.<variable>, which changes only the server look. The style itself is picked in the layer file (Styles).
• At the top level of atmosphere.yml, cloud-layers is ignored with a message: a layer's base values belong in its file.

Settings a block can change

The settings only atmosphere.yml can hold are listed on Options. In a block they are ignored with one of the messages below.

Where a block can sit

The places apply from the top of the table down. A later place wins for any setting both set.

• World names and season ids are not case-sensitive.
• Places 4, 5, 6 and 8 belong to a season. In a world whose season is disabled only 1, 2, 3, 7 and 9 apply.
• A season wins over place 3. The shipped season-adjustments set temperature and humidity for every season, which replaces a world's own. Use place 7 or 8 to win over the season.
• profile works only in place 3, where it applies as place 7, and in place 6, where it applies as place 5. Elsewhere it does nothing and logs no message.
• transition.blend-days and worlds are read in places 2 and 6, transition.blend-percent only in place 6.
• The atmosphere: block of a biome file is something else, see Weather.

atmosphere:
  profile: dry-spell
  temperature:
    START: "+2"
    MIDDLE: "+8"
    END: "+2"
  transition:
    blend-percent: 10
  worlds:
    resource_world:
      physics:
        max-wind: 20

In a season file. max-wind is in m/s, and the blend covers the last 10 percent of the season.

How the result is built

Take a world survival in the shipped winter, with temperature: 3 and profile: example under worlds.survival in atmosphere.yml:

The season adjustment replaces the world's 3, and the shipped winter block sets neither key.

Blending between seasons

Near the end of a season the whole result fades into the next season's result at progress 0, over transition.blend-days (see Options).

• Numbers fade in a straight line, and the wind direction turns the short way round. clouds.outflow.wind-y and physics.surface-max-humidity switch halfway when either side is -1.
• The cloud list switches halfway. A layer in both lists fades its settings.
• A tint fades channel by channel when both seasons set one, and switches halfway when only one does.
• Forced profiles apply to both sides.

The shipped profiles

example

A heavy, dark, windy overcast: 4 degrees colder ("-4"), 60 percent more moisture ("*1.6"), cloud and rain that form more easily (buoyancy 0.055, lapse-rate 0.055, cond-rate 1.3, auto-threshold 0.45), a day that hardly warms up (diurnal-offset -6, diurnal-amplitude 4), a stronger, steadier upper wind (speed-base 9, speed-top 38, wander-a 12) and storms that need less rain and a weaker updraft (storm-precip-threshold 0.3, storm-updraft-threshold 1.6). Every layer gets a grey-blue tint ("8A93A6"), and the cumulus is heavier and broader with a darker underside (coverage 1.8, noise-scale 140, noise-scale-y 70, shade-bottom 0.5), 40 blocks above the terrain but never above y200.

mars

Freezing, bone-dry air that never rains, with orange dust and thin ice streaks in place of the regular clouds. Its temperature: -60 is unquoted, so it replaces the season's shift. Sky and fog keep the colours of the world's biomes. The settings are on Mars layers.

• To turn a world into Mars, set profile: mars under worlds.<world> in atmosphere.yml and run /ms reload. It applies in every season and wins over the season files, except their own atmosphere.worlds.<world> blocks. The simulation has to run in that world, see Turning it on.
• The dust particles come from the pack skill MS_MarsDust, which MS_Atmosphere runs where the atmosphereprofile condition finds mars, the surface wind is at least 3 m/s and the player has season particles on. Packs installed before that skill existed need it added to skills/Atmosphere.yml by hand, see Packs.
• That condition sees the world's own profile and forced profiles, so a mars named in a season file gives no dust particles.

Checking what applies

• /ms atmosphere profiles lists the loaded profiles.
• /ms atmosphere profile [world] lists every setting some place sets, with that place, see Debugging. Settings at their default are left out. A world without a running simulation shows every setting at its default and no layers.
• The atmosphereprofile condition, <mythicseasons.atmosphereprofile> and %ms_atmosphere_profile% report the world's own profile and the forced ones, lowest priority first, or none. A profile named by a season file is in none of them.

The chain example above, before the skill runs:

Profile survival (winter 40%)
Forced: example
Cloud tint: #8A93A6
  biome-defaults.temp-scale 18 (atmosphere.yml)
  biome-defaults.temp-offset -2 (atmosphere.yml)
  biome-defaults.vapor-base 2 (atmosphere.yml)
  biome-defaults.vapor-scale 10 (atmosphere.yml)
  temperature -16 (profile example)
  humidity 0.88 (profile example)
  forcing.diurnal-amplitude 4 (profile example)

The label in brackets names the place: atmosphere.yml, world <world>, season-adjustments <season>, profile <name> (named by a season or a world), season <id>, season <id> world <world>, override <name> (a forced profile) and cloud-layers/<file name>.yml (the layer's own file). During a blend the first line ends with , <percent>% into <next season>, and a value whose two sides come from different places shows both, as <first>><second>.

Messages

Each message starts with its place (one of the labels above), then cloud-layers.<layer> inside a layer block, and the setting with @<key> where a value is at fault. Messages about values and clouds are in the sections above.