Weather System
Weather generates procedurally from climate zones and season settings. Each zone gets its own temperature, wind, precipitation, and forecast.
Getting started
Section titled “Getting started”Every bundled calendar except Hijri ships with at least one climate zone. Hijri has no seasons or climate zones, so it draws every weather preset with equal probability until you add a zone.
To change the weather profile, open the Climate Editor and edit the bundled zone or add more zones.
Climate zones
Section titled “Climate zones”Built-in climate zone templates carry temperature ranges and weather probabilities by season.
Available templates
Section titled “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
Section titled “Zone configuration”Configure zones 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 and darkness environments
- Color shift: Dawn, dusk, and night hues for time-of-day transitions
Season-specific climate
Section titled “Season-specific climate”Each season overrides the base zone climate with its own temperature range and preset chances.
Climate layering
Section titled “Climate layering”The first matching value wins:
- Zone season override. Per-season weight and temperature overrides within a zone
- Season base. Season climate temperatures and preset weights
- Zone base. Enabled/disabled filter and base temperatures
Temperature constraint resolution
Section titled “Temperature constraint resolution”The season temperature range is the authority. Per-preset temperature constraints apply only when set in the Climate Editor:
- Season preset override. Per-season temp min/max set for a specific preset
- 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, the season range is used instead of the preset’s built-in range. Setting either bound on a preset pulls in the other bound from its built-in defaults, so a lone Temp Min override also brings in the built-in Temp Max.
Preset selection filtering
Section titled “Preset selection filtering”Presets with absolute temperature overrides that do not overlap the season range are excluded from selection. Presets using relative modifiers, or with no override at all, are never filtered by temperature.
Configuring season climate
Section titled “Configuring season climate”In Calendar Editor > Seasons tab:
- Click the edit button on a season row.
- The Climate Editor opens in season mode.
- Set the temperature range and preset chance weights.
Temperature
Section titled “Temperature”You set the display unit with the Temperature setting on the Weather settings tab.
Wind system
Section titled “Wind system”Wind speed scale
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 hazards sets the base rating, and 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. Each intraday period scores separately.
Precipitation system
Section titled “Precipitation system”Weather presets can define precipitation with a type and an intensity.
Precipitation types
Section titled “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
Section titled “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
Section titled “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
Section titled “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.
Weather inertia
Section titled “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
Section titled “Per-preset behavior”Some weather types persist longer than others: stable conditions tend to linger, dramatic events 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.
Inertia is reduced across a season boundary so the new season’s weather profile takes effect faster, and it also smooths temperature and wind transitions between the previous and new weather.
Forecast plan
Section titled “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
Section titled “How it works”- When auto-generation is enabled, the forecast plan generates on initialization and after day changes.
- The plan covers the window set by the Forecast Days setting on the Weather settings tab.
- Forecasts account for the previous day’s weather.
- Old entries are pruned automatically.
- 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. Fresh generation runs only when neither exists.
GM override behavior
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.
Each period rolls its temperature from part of the day’s range. Night runs coldest and afternoon runs warmest.
Period carry-over chance
Section titled “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
Section titled “Cross-day transitions”The evening period’s weather influences the next day’s night period.
HUD and tooltip display
Section titled “HUD and tooltip display”The HUD tooltip lists every period for anyone who can see the HUD weather indicator. MiniCal and BigCal day tooltips add the period rows only for the GM and for users with the viewWeatherForecast permission; everyone else sees only the day’s single condition, below which the period rows sit with the active period marked.
Weather Picker integration
Section titled “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
Section titled “Probability guide”Verify the weather distribution your climate zone setup produces.
Access
Section titled “Access”- Chat command:
/weatherprobor/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
Section titled “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. 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 unsaved changes.
Weather history
Section titled “Weather history”Weather is recorded in a per-zone history when it changes.
Behavior
Section titled “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 it to zero disables history recording entirely.
- Query history with the
/weatherchat 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
Section titled “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
A GM override clears the forecast plan for the affected zone only and leaves other zones’ plans intact.
Scene integration
Section titled “Scene integration”Weather syncs to the active scene’s climate zone when you switch scenes. On activation:
- The scene’s assigned climate zone is resolved.
- When weather data exists for that zone, it applies immediately, updating sound, visual effects, and the HUD.
- 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
Section titled “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
Section titled “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
Section titled “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
Section titled “Moon illumination”Moons add illumination to nighttime scenes, reducing darkness.
How it works
Section titled “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
Section titled “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
Section titled “HUD particle rendering”The HUD dome displays animated weather effects with a different visual per preset.
Available effects
Section titled “Available effects”The HUD includes an effect covering every built-in weather type, each with its own visual style, animation density and speed, special behaviors, and sky color overrides.
Wind and precipitation influence
Section titled “Wind and precipitation influence”- Wind speed affects animation direction and intensity.
- Precipitation intensity scales animation density.
Customization
Section titled “Customization”Customize HUD visuals per preset in the Weather Editor, including animation density, speed, colors, and sky appearance.
Ambient sound system
Section titled “Ambient sound system”Weather presets trigger looping ambient audio through Foundry’s environment audio context.
Categories
Section titled “Categories”See Weather Presets for the Sound column listing which presets trigger which sound loops.
Behavior
Section titled “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.
- 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 it.
Night and weather music
Section titled “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, these sections do not appear.
| 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
Section titled “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
Section titled “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
Section titled “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
Section titled “Scene ambience”Weather and climate zones affect scene lighting when ambience sync is enabled.
Darkness penalty
Section titled “Darkness penalty”Weather presets apply additive darkness adjustments. See Weather Presets for per-preset values.
Environment lighting
Section titled “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
Section titled “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
Section titled “Preset aliases”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
Section titled “Display name resolution”Display names resolve in priority order:
- Per-zone alias from the Climate Editor > Preset Overrides tab
- Name override from the Weather Editor
- Built-in localized name
This applies to the HUD, MiniCal, BigCal day cells, Weather Picker grid, and probability views.
Season aliases
Section titled “Season aliases”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
Section titled “For developers”See API Reference and Hooks.