Weather System

A procedural weather system with climate zones, seasonal temperatures, wind, precipitation, forecasts, and built-in weather presets across four categories.

Tip

For the complete preset reference, see Weather Presets. For the manual weather picker, see Weather Picker. For visual customization, see Weather Editor.

---

Getting started

Every bundled calendar preset includes default climate zone configurations with full weather data. Weather generation works out of the box on a bundled calendar with no manual zone setup.

To customize 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

Each zone defines:

• Seasonal temperatures: Per-season min/max with optional relative modifier syntax (5+/3-)
• Weather weights: Per-season relative probabilities for each weather preset
• Wind: Speed range and cardinal direction weights
• Daylight: Optional latitude or manual shortest/longest day overrides (see Climate Editor)
• Brightness multiplier: Per-zone scene darkness scaling
• Environment lighting: Luminosity, saturation, shadows, hue, and intensity overrides per channel (day/night), plus blend ambience toggle
• Color shift: Dawn/dusk/night hue values for time-of-day atmospheric transitions

Zone configuration is done via the Climate Editor in zone mode.

---

Season-specific climate

Each season overrides the base zone climate with custom temperature ranges and weather preset chances.

Climate layering

Climate settings use a layered approach. 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 only apply when explicitly configured in the Climate Editor:

1. Season preset override. Per-season temp min/max set in the Climate Editor 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 overrides, the season range is used. Built-in preset defaults do not filter or constrain generation.

Preset selection filtering

Presets with absolute temperature overrides that don’t overlap the season range are excluded. Presets using relative modifiers (N+/N-) 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. Configure 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

Weather includes a wind model with speed and direction.

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 Unit setting on the Weather settings tab, independent of the temperature unit.

Wind direction

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

The wind arrow indicator points in the direction the wind blows (opposite the labeled origin). HUD particles and FXMaster effects also 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, ignoring zone configuration. These include thunderstorm, blizzard, tornado, hurricane, ice storm, and monsoon.

---

Precipitation system

Weather presets can define precipitation with type and 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 ranges from trace to maximum. 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 weather independently.

The Regenerate All Weather 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, smoothing transitions. 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. Dramatic events such as tornadoes, hurricanes, and sunshowers pass quickly. Custom presets configure their own persistence in the Climate Editor.

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, making changes gradual rather than abrupt.

---

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.

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, simulating imperfect weather prediction. 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 so weather changes throughout the day rather than staying fixed from dawn to dawn. 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 for smooth overnight transitions.

HUD and tooltip display

When intraday weather is enabled, the HUD and calendar day tooltips show a per-period weather breakdown instead of a single daily condition. The per-period breakdown in tooltips is visible only to the GM and to users with the viewWeatherForecast permission. Players without forecast permission see only the aggregate daily condition.

Caution

Enabling intraday weather triggers irreversible regeneration of the forecast plan. Existing single-period forecasts are replaced with multi-period data and cannot be reverted by toggling the setting off.

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 pass a season name, e.g. /weatherprob Winter)
• Settings: Settings > Weather > Climate section > Weather Probabilities button (visible when zones are configured)
• Climate Editor: Preset Overrides tab > Weather Probabilities button (uses unsaved editor data for live preview)
• Weather Picker: Weather Probabilities button in footer on any weather picker instance

Dialog

Shows:

• 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 visualization
• Temperature range. Effective min/max for the selected zone and season

When opened from the Climate Editor, the dialog uses the editor’s in-progress data, letting you 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.
• You can query history with the /weather chat command.

---

Per-zone weather model

Each climate zone maintains independent weather state:

• Current weather: Separate current conditions per zone
• Forecast plan: Independent forecast chain per zone
• Weather history: Zone-scoped entries
• No Zone: Scenes with “No Zone” selected 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

GM overrides only clear the forecast plan for the affected zone, leaving other zones’ plans intact.

---

Scene integration

Weather syncs to the active scene’s climate zone when switching scenes. When a scene is activated:

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

Players see the correct weather for their active scene even when scenes use different climate zones.

---

Time-of-day color shifting

Climate zones define hue values for dawn, dusk, and nighttime that shift scene environment lighting based on 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:

• Dawn Hue: Environment hue at sunrise
• Dusk Hue: Environment hue at sunset
• Night Hue: Environment hue during full darkness
• Transition Duration: Minutes for the color shift transition

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 details.

---

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 via 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

Sound categories cover all weather types that have sound. 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 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 is independent of FXMaster and works without external modules. The global Enable Weather FX (FXMaster) toggle controls FXMaster scene effects only and does not affect ambient sound.

---

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 and climate zones override Foundry’s scene environment properties: hue, intensity, luminosity, saturation, and shadows per channel (day/night), plus the blend ambience toggle. 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 icon, name, and temperature
• Wind speed label and direction
• Precipitation type and intensity

---

Preset aliases

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

Aliases are zone-scoped: each calendar + zone combination can have different names for the same preset. Configure aliases 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 resolution 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 on a per-zone basis. 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, chat commands). The raw season name remains 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.