Configuration Reference

Every setting in oxide-weather, what it does, and the value it ships with. Start with How configuration is stored — the resource saves its settings in your database, so editing the config files does not always do what you expect.

How Configuration Is Stored

This is the most important thing to understand before you change anything.

• Before the first start, oxide-weather reads its settings from the files in the shared/ folder.
• On the first start, it copies every setting from those files into a database table called oxide_settings.
• From then on, the database is the source of truth. Editing the files after the first start changes nothing, because the value already lives in the database and the database wins.

So there are two ways to work:

1. First-time setup: edit the files in shared/ before you first start the resource. Your values are imported automatically.
2. Changing a setting later: run /weather settings in game as an admin. The menu edits the database directly, live. No file editing.

Your region shapes are stored separately from settings, in the world snapshot. Once you have saved a region in /weather zones, the shapes in shared/regions_config.lua are no longer used. They are starting points for a fresh database, not a map you are locked into.

If a saved value ever turns out to be unusable, oxide-weather falls back to the value that shipped, writes a warning to the console naming the setting, and repairs the stored value.

The Settings Menu

/weather settings opens a searchable editor with two tabs, Basic and Advanced, grouped like this:

Region boundaries do not appear here. The menu shows a note pointing you at /weather zones, which is where you draw them.

Every field you have altered shows a Changed badge, and fields that only apply after a restart show a Restart required badge, so you can always see what you have changed and what is still waiting. Each field has a reset button that puts it back to the shipped value.

Which Settings Need a Restart

Most settings apply the moment you save them. Some rebuild the whole simulation and only take effect on a restart of the resource. The menu marks those clearly and tells you after you save.

Apply immediately:

Everything else needs restart oxide-weather.

shared/config.lua

The core clock and weather settings.

Time

Config.DefaultTime = {
    hour = 12,
    minute = 0
}

-- Game minutes per real minute (default: 30 = 1 real minute = 30 game minutes)
Config.TimeScale = 30

-- Real-time mirror uses UTC plus this fixed minute offset (no automatic DST).
Config.Clock = { mode = 'game', nightScale = 30, nightStart = 21, nightEnd = 6, utcOffset = 0 }

-- Start with time frozen
Config.FreezeTime = false

Weather

Config.DefaultWeather = 'CLEAR'
Config.DynamicWeather = true
Config.WeatherInterval = 15
Config.WeatherTransitionTime = 30
Config.SyncInterval = 1000
Config.ClientSyncInterval = 1000
Config.ForecastSyncInterval = 10000

Blackout

Config.Blackout = false
Config.BlackoutAffectsVehicles = true

Weather types and transitions

Config.WeatherTypes is the pool of weather the simulation may use. Remove anything you never want to see. CLEAR must stay in the list, because it is the fallback the resource falls back to if anything goes wrong.

The 15 shipped types:

CLEAR, EXTRASUNNY, CLOUDS, OVERCAST, RAIN, CLEARING, THUNDER, SMOG, FOGGY, XMAS, SNOWLIGHT, BLIZZARD, SNOW, NEUTRAL, HALLOWEEN

A transition entry looks like this. The weight numbers are relative, so a weight of 30 next to a weight of 10 is three times as likely:

Config.WeatherTransitions = {
    OVERCAST = {
        { weather = 'OVERCAST', weight = 20 },   -- stay overcast
        { weather = 'CLOUDS', weight = 25 },
        { weather = 'RAIN', weight = 30 },       -- most likely
        { weather = 'THUNDER', weight = 15 },
        { weather = 'CLEARING', weight = 10 },
    },
    -- ...one entry per weather type
}

Forecast

Config.ForecastLength = 4

Snow rendering

How snow looks. How much snow there is lives under Snow accumulation.

Config.Snow = {
    Ground = true,
    VehicleTrails = true,
    Footprints = true,
    EffectScale = 0.35,
    NightMultiplier = 0.4,
    RenderWeather = 'XMAS',
    XmasFallback = false,
    ExcludeCayo = true,
    CayoWeather = 'CLEAR',
    CayoBounds = { minX = 3000.0, maxX = 6500.0, minY = -7000.0, maxY = -3500.0 },
}

Wind

The fallback wind, used where no region supplies its own.

Config.Wind = {
    Speed = 1.0,
    Direction = 0.0,
}

Persistence

Config.Persistence = {
    Enabled = true,
    Key = 'global',
    SaveInterval = 30,
    RetryInterval = 60,
}

Trusted resources

Config.SetterResources is the list of other resources allowed to change the weather through the API. Anything not on this list can read but never write.

Config.SetterResources = {
    ['oxide-developer'] = true,
}

It ships with a single entry for an Oxide admin tool. If you do not run that resource, the entry does nothing at all. Leave it or remove it as you prefer.

To let one of your own scripts change the weather, add its exact folder name:

Config.SetterResources = {
    ['oxide-developer'] = true,
    ['my-event-script'] = true,
}

After the first start, add it in /weather settings instead: search for Trusted automation resources, add the resource with Allow weather setters on, save, then run restart oxide-weather. This list only applies after a restart.

Shared map mode

Config.MapMode chooses which map the zone editor and the radar draw on. o-link owns the artwork and calibration, so this only picks a mode.

Config.MapMode = 'inherit'

This value is saved in oxide_settings like every other setting, and applies live. Change it under Broadcast in /weather settings, or with oxide-weather:mapmode <value> from the server console (prefix it with / in game as an admin). What each mode looks like is covered by o-link's shared map documentation.

shared/regions_config.lua

Weather regions and climates.

Regional blending

Config.Regional = {
    Enabled = true,
    BlendWidth = 200.0,
    UpdateInterval = 100,
    BlendSeconds = 6.0,
    WindSmoothingSeconds = 2.0,
    MaxZones = 32,
    MaxPoints = 64,
}

Climate profiles

A climate reweights how likely each weather is. A weight of 2.0 makes that weather twice as likely there. A weight of 0.25 makes it four times less likely. Anything not listed keeps its normal chance.

Five ship by default:

Config.Climates = {
    arid = {
        label = locale("climate.arid"), defaultWeather = 'EXTRASUNNY',
        weights = { CLEAR = 2.0, EXTRASUNNY = 3.0, RAIN = 0.25, THUNDER = 0.2, FOGGY = 0.3 },
        wind = { speed = 2.5, direction = 270.0 },
    },
    -- ...
}

Starting regions

Config.Zones are the regions a fresh database starts with. Once you have saved anything in /weather zones, these are no longer read.

Six regions ship: city, sandy, paleto and cayo (priority 0), chiliad and zancudo (priority 10).

Config.Zones = {
    { id = 'city', label = locale("region.city"), climate = 'temperate', color = '#57c6c5', priority = 0,
        polygon = { points = { { x = -3200, y = -3800 }, { x = 2000, y = -3800 }, { x = 3400, y = 1200 },
                               { x = -1400, y = 1200 }, { x = -2900, y = 900 } } } },
    -- ...
}

shared/climate_config.lua

Seasons, temperature and snow accumulation.

Season handling

Config.Climate = {
    Enabled = true,
    Mode = 'game',
    DefaultSeason = 'spring',
    DaysPerSeason = { spring = 7, summer = 7, autumn = 7, winter = 7 },
    CalendarUTC = false,
    Hemisphere = 'north',
    DisplayUnit = 'F',
    -- ...
}

Season profiles

Seasons = {
    winter = { temperature = -2.0, snow = true,
        weights = { OVERCAST = 1.6, SNOW = 2.0, SNOWLIGHT = 2.0, BLIZZARD = 1.2, EXTRASUNNY = 0.3 } },
    -- ...
}

Temperature model

Shipped climate offsets: temperate 0, arid +5, coastal -2, alpine -6, marine -1.

Shipped region altitudes: city 30, sandy 45, paleto 20, chiliad 650, zancudo 20. A region without an entry, such as cayo, uses 0.

Shipped weather offsets:

The final result is clamped between -80 °C and 65 °C.

Snow accumulation

Shipped rates: XMAS 1.0, SNOW 1.0, SNOWLIGHT 0.4, BLIZZARD 1.5.

Snow = {
    Enabled = true,
    FullCoverMinutes = 30.0,
    MeltMinutesAt5C = 25.0,
    RainMeltMultiplier = 1.5,
    Rates = { XMAS = 1.0, SNOW = 1.0, SNOWLIGHT = 0.4, BLIZZARD = 1.5 },
    TrackThreshold = 0.08,
    GroundThreshold = 0.01,
    InterpolationSeconds = 5.0,
}

Holiday presets

Holidays = {
    christmas = { season = 'winter', weather = 'XMAS', snowLevel = 1.0 },
    halloween = { season = 'autumn', weather = 'HALLOWEEN', snowLevel = 0.0 },
}

These are the only two presets. You can change what each one does, but other ids are ignored. Turning one on snapshots the world first, so turning it off restores everything exactly.

shared/fronts_config.lua

Moving storms, lightning, blackouts and screen effects.

Fronts

New front defaults

Used when you spawn a front without specifying everything, and as the automatic front template.

Automatic fronts

Auto = {
    Enabled = true,
    MinMinutes = 30, MaxMinutes = 60,
    Weather = { { weather = 'RAIN', weight = 55 }, { weather = 'THUNDER', weight = 35 },
                { weather = 'FOGGY', weight = 10 } },
    Routes = {
        { coords = { x = -5000.0, y = -1000.0, z = 30.0 }, heading = 90.0 },
        { coords = { x = -5000.0, y = 2800.0, z = 45.0 }, heading = 90.0 },
        { coords = { x = -4000.0, y = 6300.0, z = 20.0 }, heading = 90.0 },
    },
},

Lightning

Scheduled blackout limits

Visibility effects

Config.Visibility = {
    Enabled = true,
    FadeSeconds = 8.0,
    MaxStrength = 0.2,
    NightMultiplier = 0.5,
    SnowMultiplier = 0.25,
    Profiles = {
        FOGGY = { modifier = 'prologue_ending_fog', strength = 0.15 },
        RAIN = { modifier = 'Yacht_Mission_ThunderRain', strength = 0.06 },
        THUNDER = { modifier = 'Yacht_Mission_ThunderRain', strength = 0.12 },
    },
}

shared/broadcast_config.lua

The public weather app, widget and alerts.

Public weather service

Config.Broadcast = {
    Enabled = true,
    Tablet = true,
    Widget = true,
    Alerts = true,
    NotificationSound = true,
    NotificationScope = 'local',
    MinimumSeverity = 2,
    LookAheadSeconds = 900,
}

Timing and limits

These control how often things refresh and how much history is kept. Changing them needs a restart.

Warning rules

Which weather deserves an alert, at what level, and what the alert says.

Config.WeatherWarnings = {
    THUNDER = { severity = 3, label = locale("alert.thunder.label"),
        advice = locale("alert.thunder.advice") },
    -- ...
}

Anything not listed never raises an alert. Remove RAIN and FOGGY if you only want alerts for serious weather.

shared/gameplay_config.lua

Shelter detection and road surfaces.

Neither of these does anything on its own. They supply data other resources read. See Features → Shelter and exposure.

Exposure

Config.Exposure = {
    Radius = 80, FreshSeconds = 30, LeaseSeconds = 5, MaxPoints = 512, ProbesPerTick = 8,
    CoveredAreas = {},
    Clothing = {},
}

Covered areas are the right fix for anywhere the automatic check gets wrong: interiors, tunnels, multi-storey car parks. Add them under Exposure in /weather settings. Each one is a shape you draw in the world, with a height range, an optional name, and an optional routing bucket if it only applies in one instance. They always beat the automatic check.

Clothing insulation maps a character model and the torso item worn to a value from 0 (no protection) to 1 (fully insulated). It ships empty. The value is decided on the server and handed to whichever resource asked, so a cold-damage script can use it. A player's game never supplies it.

Road surfaces

Config.Roads = { CellSize = 500, TickSeconds = 5, WetMinutes = 8, DryMinutes = 25,
    FreezeMinutes = 20, MeltMinutes = 15, MinX = -4500, MaxX = 7000, MinY = -7500, MaxY = 8500 }

shared/realworld_config.lua

Mirror one real place through Open-Meteo.

Real-world weather

Off by default. When it is on, your server asks Open-Meteo for the current conditions and the next two days of hourly forecast at the location you chose, and every region follows it: the weather type, the temperature, the wind and the forecast queue. Everything here applies live from the settings menu or with /weather realworld.

Config.RealWorld = {
    Enabled = false,
    Location = 'Los Angeles, US',
    PollMinutes = 15,
    SyncClock = false,
}

Open-Meteo reports a standard weather code, which maps to the closest weather type: clear and cloudy skies to EXTRASUNNY, CLEAR, CLOUDS and OVERCAST, drizzle and light rain to CLEARING, rain to RAIN, thunderstorms to THUNDER, fog to FOGGY, and snow to SNOWLIGHT, SNOW or BLIZZARD by intensity. If you removed a type from Config.WeatherTypes, the closest remaining type is used instead.

What is sent, and to whom

Your own server contacts api.open-meteo.com, or customer-api.open-meteo.com when you have set a commercial key, plus geocoding-api.open-meteo.com once for each new city name. The only things it sends are the location you configured and, on the commercial service, your key. No player data leaves the server.

The free service is for non-commercial use and allows 10,000 requests a day; one server at the default interval uses about 100. If your server needs Open-Meteo's commercial service, put your key in server.cfg and it is used automatically:

set openmeteo_api_key "your-key"

The key is read from that convar only. It is never read from a config file, never stored in the database and never sent to players.

Attribution

Open-Meteo data is licensed CC BY 4.0. The tablet weather app shows "Weather data by Open-Meteo.com" whenever the mirror is on, which is what the licence asks for. Keep that line if you customise the app.

Starting Over

If you want to wipe your settings and re-import from the files in shared/:

To also reset the world itself (time, weather, season, snow, storms and your drawn regions), delete the row in oxide_weather_state whose state_key matches your simulation key, global unless you changed it. Do this while the resource is stopped.

Next Steps