Weather System

Weather generates procedurally from climate zones and season settings. Each zone gets its own temperature, wind, precipitation, and forecast.

Tip

For the preset reference, see Weather Presets. To set weather by hand, see Weather Picker. For visual customization, see Weather Editor.

---

Getting started

Almost every bundled calendar ships with at least one climate zone already configured, so weather generation works out of the box with no manual zone setup. The Hijri calendar is the exception: it defines no seasons and no climate zones. Until you add a zone in the Climate Editor it draws every weather preset with equal probability across a fixed fallback temperature range.

To change the weather profile, open the Climate Editor and edit the bundled zone or add more zones.

---

Climate zones

Built-in climate zone templates carry temperature ranges and weather probabilities by season.

Available templates

ID	Zone	Temp Range °C	Temp Range °F
arctic	Arctic	-45 to 8	-49 to 46
subarctic	Subarctic	-35 to 18	-31 to 64
temperate	Temperate	-5 to 30	23 to 86
subtropical	Subtropical	5 to 35	41 to 95
tropical	Tropical	22 to 35	72 to 95
arid	Arid	5 to 48	41 to 118
polar	Polar	-50 to 10	-58 to 50

Zone configuration

Zones are configured in the Climate Editor in zone mode. Each zone defines:

• Seasonal temperatures: Per-season min/max, with a relative modifier syntax (5+/3-)
• Weather weights: Per-season relative probabilities for each weather preset
• Wind: Speed range and cardinal direction weights
• Daylight: Latitude or manual overrides (see Climate Editor)
• Brightness multiplier: Per-zone scene darkness scaling
• Environment lighting: Hue and saturation overrides for the base environment and the darkness environment
• Color shift: Dawn, dusk, and night hues for time-of-day transitions

---

Season-specific climate

Each season overrides the base zone climate with its own temperature range and preset chances.

Climate layering

The first matching value wins:

1. Zone season override. Per-season weight and temperature overrides within a zone
2. Season base. Season climate temperatures and preset weights
3. Zone base. Enabled/disabled filter and base temperatures

graph TD
    A["<b>Request</b><br/><i>Given a Season and Zone,<br/>resolve the active climate</i>"] --> B{"<b>Layer 1</b><br/>Zone has a per-season<br/>override for this season?"}
    B -->|Yes| C["<b>Zone Season Override</b><br/><i>Most specific: this zone<br/>in this season</i>"]
    B -->|No| D{"<b>Layer 2</b><br/>Season defines its own<br/>base climate?"}
    D -->|Yes| E["<b>Season Base</b><br/><i>Season-wide defaults<br/>across all zones</i>"]
    D -->|No| F["<b>Layer 3: Zone Base</b><br/><i>Zone-wide fallback<br/>used when no season<br/>data is set</i>"]
    C --> G["<b>Resolved Climate</b><br/><i>Preset weights +<br/>temperature range<br/>feed weather generation</i>"]
    E --> G
    F --> G

    classDef request fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    classDef decision fill:#fff8e1,stroke:#f9a825,stroke-width:2px,color:#5d4037
    classDef layer1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef layer2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef layer3 fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#880e4f
    classDef result fill:#e0f2f1,stroke:#00695c,stroke-width:3px,color:#004d40

    class A request
    class B,D decision
    class C layer1
    class E layer2
    class F layer3
    class G result

Temperature constraint resolution

The season temperature range is the authority. Per-preset temperature constraints apply only when set in the Climate Editor:

1. Season preset override. Per-season temp min/max set for a specific preset
2. Zone preset override. Zone-level temp min/max override for the preset

Absolute overrides are intersected with the season range. Relative modifiers (N+/N-) resolve directly and can extend past the season bounds.

With no override on a preset, its built-in temperature range is ignored and the season range is used. Setting either bound on a preset activates the other bound from its built-in defaults, so a lone Temp Min override also brings in the preset’s built-in Temp Max.

Preset selection filtering

Presets with absolute temperature overrides that do not overlap the season range are excluded. Presets using relative modifiers bypass this filter. Presets without overrides are never filtered by temperature.

Configuring season climate

In Calendar Editor > Seasons tab:

1. Click the edit button on a season row.
2. The Climate Editor opens in season mode.
3. Set the temperature range and preset chance weights.

---

Temperature

Note

Temperature is stored in Celsius internally regardless of display preference.

You set the display unit with the Temperature setting on the Weather settings tab.

---

Wind system

Wind speed scale

Tier	Label	kph	mph
0	Calm	≤5	≤3
1	Light	≤20	≤12
2	Moderate	≤40	≤25
3	Strong	≤60	≤37
4	Severe	≤90	≤56
5	Extreme	>90	>56

You set the wind speed unit with the Wind Speed setting on the Weather settings tab, independent of the temperature unit.

Wind direction

Wind direction uses meteorological convention: the labeled direction is where the wind comes from. A North wind originates from the north and blows southward.

The wind arrow indicator points the way the wind blows, opposite the labeled origin. HUD particles and FXMaster effects move in the blowing direction.

Zone wind configuration

Zones can define:

• Speed range: Min/max speed tier constraining generated wind
• Direction weights: Proportional weights per compass direction for prevailing winds

Forced wind

Some presets lock their wind speed and direction to preset values and ignore zone configuration: thunderstorm, blizzard, tornado, hurricane, ice storm, and monsoon.

---

Severity

Every weather state carries a hazard severity rating derived from its wind speed, precipitation intensity, temperature extremity, and darkness penalty. The worst of those four hazards sets the base rating. Each additional hazard present raises it further.

The rating maps onto six named bands.

Band	Meaning
None	No hazard worth calling out
Light	A mild condition
Moderate	A noticeable condition
Heavy	A demanding condition
Severe	A dangerous condition
Extreme	The top of the scale, several hazards at once

The band name appears in weather tooltips whenever the rating is above None, and in the Weather Picker detail panel as you edit the fields.

Severity is derived when weather is read rather than stored, and each intraday period scores separately.

---

Precipitation system

Weather presets can define precipitation with a type and an intensity.

Precipitation types

Type	Used By
Drizzle	Drizzle, Fog
Rain	Rain, Sunshower, Thunderstorm, Tornado, Hurricane, Monsoon, Veilfall, Acid Rain, Blood Rain
Snow	Snow, Blizzard, Permafrost Surge
Sleet	Sleet
Hail	Hail, Ice Storm

Intensity

Intensity runs from none to torrential. The Weather Picker names the band as you drag the slider. Tooltips report it as a rate in millimeters or inches per hour, following the Precipitation setting on the Weather settings tab. During generation, intensity varies slightly from the preset’s base value.

---

Weather generation

Weather generates from the climate zone’s presets and season settings, with variation in temperature and wind. Enabled preset weights determine which weather is most likely. Inertia smooths transitions.

Auto-generation

When you enable Auto-Generate Weather, weather regenerates on day change for the GM only. Each zone generates independently.

The Regenerate Forecast button on the Weather settings tab clears and rebuilds the forecast for all climate zones after a confirmation dialog. Each use produces fresh weather: new presets, temperatures, and wind.

---

Weather inertia

Weather inertia favors the current weather when generating new conditions. You tune it with the Weather Inertia setting on the Weather settings tab.

• Low values make each day generate independently.
• High values strongly favor the current weather.

Per-preset behavior

Some weather types persist longer than others. Stable conditions such as clear skies, overcast, fog, rain, and snow tend to linger, while dramatic events such as tornadoes, hurricanes, and sunshowers pass quickly. Each preset row in the Climate Editor > Preset Overrides tab has an Inertia field that scales the global setting for that preset in the selected zone and season. Left blank, the preset’s built-in weight applies.

Season boundary

When a season boundary is crossed, inertia is reduced so the new season’s weather profile takes effect faster.

Value blending

Inertia also smooths temperature and wind transitions between the previous and new weather.

---

Forecast plan

Future weather is pre-generated and stored as a forecast plan: upcoming weather for each zone over a configurable window.

How it works

1. When auto-generation is enabled, the forecast plan generates on initialization and after day changes.
2. The plan covers the window set by the Forecast Days setting on the Weather settings tab.
3. Forecasts account for the previous day’s weather to produce coherent patterns.
4. Old entries are pruned automatically.
5. Each calendar keeps its own forecast plan. Switching the active calendar swaps to that calendar’s plan.

The plan is also where the day’s real weather comes from. When the day changes, each zone takes the plan entry stored for the new date. A history entry for that date is used next, and fresh generation runs only when neither exists.

GM override behavior

When a GM sets weather through the Weather Picker and the GM Override Affects Forecast setting is enabled, the forecast plan for the affected zone clears and regenerates from the new weather state.

---

Forecast variance

Forecast variance adds uncertainty to the forecasts players see. You tune it with the Forecast Accuracy setting on the Weather settings tab.

• High accuracy makes the forecast match reality.
• Low accuracy heavily randomizes the forecast.

How variance works

• Temperature: Forecasts may show temperatures slightly off from the actual plan, with closer days more accurate.
• Preset swapping: Distant forecasts have a chance to show a different weather type from the same category, restricted to presets valid for the current season and climate zone.
• GM always accurate: A GM always sees the true forecast plan without variance.

---

Intraday weather

Intraday weather splits each day into four periods, each generating its own weather. You enable it per world with the Intraday Weather setting on the Weather settings tab.

Periods

Period	Changes At
Night	Midnight
Morning	Sunrise
Afternoon	Midday
Evening	Sunset

Period boundaries come from the calendar’s sunrise, midday, and sunset times, which depend on the active climate zone’s daylight configuration. Weather changes when the world clock crosses a period boundary.

Period carry-over chance

The Period Carry-Over Chance setting on the Weather settings tab controls how often a period keeps the previous period’s weather instead of generating new conditions.

• A low value makes every period generate independently.
• A high value makes weather carry over from the previous period.

Cross-day transitions

The evening period’s weather influences the next day’s night period.

HUD and tooltip display

The HUD tooltip lists every period for anyone who can see the HUD weather indicator. In MiniCal and BigCal day tooltips the period rows are added only for the GM and for users with the viewWeatherForecast permission; everyone else sees the day’s single condition. In both cases the period rows sit below the current condition rather than replacing it, and the active period is marked.

Caution

Enabling intraday weather triggers irreversible regeneration. The world weather seed is re-rolled, the current weather in every zone is replaced, and the forecast plan is rebuilt with multi-period data. Toggling the setting back off does not restore what was there.

Weather Picker integration

The Weather Picker shows period selector tabs when intraday weather is enabled. A GM can set weather for individual periods rather than the whole day.

---

Probability guide

Verify the weather distribution your climate zone setup produces.

Access

• Chat command: /weatherprob or /wp, optionally followed by a season name
• Settings: Settings > Weather > Climate section > Weather Probabilities button (visible when zones are configured)
• Climate Editor: Preset Overrides tab > Weather Probabilities button
• Weather Picker: Weather Probabilities button in the footer

Dialog

• Zone selector. Compare probabilities across zones. A No Zone option is always appended. The selector is disabled only when no zones are configured.
• Season selector. Switch between seasons to see how weights change.
• Probability table. Each enabled weather preset with its weight, percentage, and a colored bar.
• Temperature range. Effective min/max for the selected zone and season.

Hovering a row’s weight shows the season base weight, the zone override, and the effective result, and hovering its percentage shows the weight against the total. When the selected zone and season enable no presets, the table is replaced by a notice.

Opened from the Climate Editor, the dialog uses the editor’s in-progress data, so you can preview changes before saving.

---

Weather history

Weather is recorded in a per-zone history when it changes.

Behavior

• History is recorded whenever weather is set, whether auto-generated or manual.
• On time jumps that skip multiple days, history is backfilled for the skipped dates.
• History is pruned to the window set by the Weather History Days setting on the Weather settings tab.
• Setting the window to zero disables history recording. No entries are written, past dates show no weather, and skipped days are not backfilled.
• You can query history with the /weather chat command.
• A weather text enricher pinned to a past date reads its value from history.
• History is stored per calendar. Switching the active calendar shows that calendar’s own history and leaves the other calendars’ entries untouched.

---

Per-zone weather model

Each climate zone keeps independent weather state:

• Current weather: Separate current conditions per zone
• Forecast plan: Independent forecast chain per zone, within the active calendar
• Weather history: Zone-scoped entries within the active calendar
• No Zone: Scenes set to No Zone disable zone-based weather for that scene

Batched day change

When the day changes, all zones generate weather in a single batched operation.

Zone-scoped plan clearing

A GM override clears the forecast plan for the affected zone only and leaves other zones’ plans intact.

---

Scene integration

Weather syncs to the active scene’s climate zone when you switch scenes. On activation:

1. The scene’s assigned climate zone is resolved.
2. When weather data exists for that zone, it applies immediately, updating sound, visual effects, and the HUD.
3. When no weather data exists and Auto-Generate Weather is enabled, new weather is generated for the zone on the spot.

---

Time-of-day color shifting

Climate zones define hue values for dawn, dusk, and night that shift scene environment lighting by time of day.

Phases

Phase	Description
Night	Full night hue applied
Dawn	Transitions from night hue to daytime over the configured duration
Day	No color shift (uses zone/weather base lighting)
Dusk	Transitions from daytime to dusk hue over the configured duration
Night	Dusk hue transitions to night hue

Configuration

Per-zone in the Climate Editor > Environment tab, under Color Shift. Each zone sets a Dawn, Dusk, and Night hue plus a transition duration in minutes.

Dawn and dusk apply a tint; midday applies none. Enable color shifting globally with the Sync Scene Ambience with Time of Day setting on the Canvas settings tab.

---

Moon illumination

Moons add illumination to nighttime scenes, reducing darkness.

How it works

• Each moon has a maximum brightness set in Calendar Editor > Moons tab.
• Illumination follows phase, brightest at full moon and dark at new moon.
• Multiple moons combine their illumination, capped to prevent over-bright nights.
• Moon color tinting applies colored light based on the moon’s configured color.

Effect on darkness

Moon illumination reduces the nighttime darkness value. Enable it with the Moon Illumination setting on the Canvas settings tab. See Moon Phases for configuration.

---

HUD particle rendering

The HUD dome displays animated weather effects with a different visual per preset.

Available effects

The HUD provides 38 effects covering all built-in weather types. Each effect defines a visual style, animation density and speed, special behaviors such as flash, tumble, and vortex, and sky color overrides.

Wind and precipitation influence

• Wind speed affects animation direction and intensity.
• Precipitation intensity scales animation density.

Customization

Customize HUD visuals per preset in the Weather Editor, including animation density, speed, colors, and sky appearance.

---

Ambient sound system

Weather presets trigger looping ambient audio through Foundry’s environment audio context.

Categories

See Weather Presets for the Sound column listing which presets trigger which sound loops.

Behavior

• Sounds crossfade when weather changes.
• Ambient sound is gated by the Sound Effects setting on the Weather settings tab. Disabling it stops all weather sounds.
• The Sound Volume slider controls volume.
• A per-scene Disable Weather Sound flag suppresses sound on a specific scene without affecting visual effects.
• Core Suppress Weather region behaviors lower the ambient sound while a token the user controls or owns is inside the region, restoring it on exit. The Suppression Muffle slider sets the fraction of volume kept inside the region.
• You can customize sound assignments per preset in the Weather Editor.
• Ambient sound works without external modules. The Enable Weather FX toggle controls FXMaster scene effects only and does not affect ambient sound.
• Ambient sound is separate from music. With VGMusic active, the scene weather also selects a playlist.

---

Night and weather music

With VGMusic active, Calendaria adds four sections to the Scene music configuration: Night, Rain, Snow, and Storm. You drag a playlist onto one of these the same way you assign Area Music and Combat Music. Without VGMusic installed nothing is registered, and Calendaria’s weather and darkness behave the same.

Section	Plays when
Night	The active scene is between sunset and sunrise
Rain	The scene weather precipitates rain or drizzle
Snow	The scene weather precipitates snow or sleet
Storm	The scene weather reaches the Severe band, or precipitates hail

A storm classification wins over the precipitation type, so severe rain plays the Storm playlist rather than the Rain playlist.

Which playlist wins

Combat music outranks every Calendaria section, a weather section outranks the Night section, and any Calendaria section outranks the scene’s Area Music. A scene with no matching Calendaria section falls back to its Area Music.

Night and darkness sync

The Night section follows the same scene opt-out as darkness sync. A scene with Sync Darkness with Time set to Disabled plays no night music. Sunrise and sunset are read per climate zone, so a scene with a Climate Zone Override switches at that zone’s times. See Scene Ambience.

When the playlist re-evaluates

The selection is re-checked at sunrise, at sunset, when the date or time changes, when the weather changes, and when a scene becomes active. The track changes only when the resolved section changes, so a weather roll that stays within the same section leaves the music playing.

---

Scene ambience

Weather and climate zones affect scene lighting when ambience sync is enabled.

Darkness penalty

Weather presets apply additive darkness adjustments. See Weather Presets for per-preset values.

Environment lighting

Weather presets override Foundry’s scene environment properties for both the base and darkness channels: hue, intensity, luminosity, saturation, shadows, and the ambience cycle toggle. Climate zones override hue and saturation only. Weather takes precedence, with zone values as fallback. When nothing overrides, the scene’s existing environment settings are kept.

Weather tooltips

Weather tooltips throughout the UI (HUD, MiniCal, BigCal, calendar day cells) display:

• Weather name, followed by the preset description when one is set
• Temperature
• Wind band, direction, and speed in the configured unit
• Precipitation type and rate
• Severity band, when the rating is above None

---

Preset aliases

You can rename any weather preset per zone. Aliases appear everywhere the preset name is displayed.

Aliases are zone-scoped: each calendar and zone combination can have different names for the same preset. Configure them in the Climate Editor > Preset Overrides tab.

Display name resolution

Display names resolve in priority order:

1. Per-zone alias from the Climate Editor > Preset Overrides tab
2. Name override from the Weather Editor
3. Built-in localized name

This applies to the HUD, MiniCal, BigCal day cells, Weather Picker grid, and probability views.

---

Season aliases

You can override the displayed name, abbreviation, icon, and color of any season per zone. Configure aliases in the Climate Editor > Weather tab on the zone temperature row pencil button.

Aliases are zone-scoped and apply only to display surfaces: HUD, calendar UI, chronicle, cinematic keyframes, text enrichers, format tokens, and chat commands. The raw season name stays the key for per-season temperature and preset overrides, so renaming a season for a zone does not break its seasonOverrides mapping.

---

For developers

See API Reference and Hooks.