Features

Everything oxide-weather does, in plain terms, with the numbers it ships with. For every setting and its allowed range, see Configuration.

How It All Fits Together

The server decides the weather and the time. Every player's game is told what to show. Nothing is decided on a player's computer, so everyone sees the same sky at the same moment.

On top of that single source of truth sit the optional layers:

Each layer can be switched off on its own if you want something simpler. Turn regions off and the whole map shares one weather. Turn seasons off and there is no temperature or snow build-up. Turn fronts off and storms no longer travel.

The Clock

One clock, everywhere

Time is held on the server and pushed to every player. Freeze it, jump it, or speed it up, and everyone changes at once.

Each player's game runs the clock at the server's speed between updates and is only corrected if it drifts, so shadows and lighting move smoothly instead of stepping.

Two ways to run it

The real-time mirror uses a fixed offset. It does not shift itself for daylight saving, so if you want that you change the offset twice a year, or let the real-world weather mirror keep it in step for you.

Day and night at different speeds

By default, one real minute is 30 game minutes, so a full day takes 48 real minutes.

You can run night faster than day. The night window is 21:00 to 06:00 by default, and it can have its own speed. Setting the day to 30 and the night to 120 gives you a long day and a night that is over in a few minutes.

Forecast countdowns understand this. If a weather change is due in "18 real minutes", that number already accounts for the night running at a different speed.

Freezing time

/weather freeze stops the clock for everyone. /weather freeze off starts it again. The weather queue keeps running while time is frozen, so the sky still changes.

Regional time offsets

From the admin panel you can give a single region its own clock offset. Useful for a set piece where one part of the map is meant to look like a different time of day. Resetting the offset puts that region back on the main clock, and setting the global time clears every offset at once.

Weather Regions

What a region is

A region is a shape drawn on the map with a weather climate attached. Six ship by default:

Climates

A climate is a set of weight multipliers that reweight how likely each weather is in that region. Five ship by default:

A climate also carries a wind speed and direction, and can carry a completely different transition pattern of its own if you want one region to behave nothing like the rest of the map.

Priority and blending

Regions can overlap. Priority decides who wins: the higher number takes the location. Mount Chiliad and Fort Zancudo sit at priority 10, and Los Santos, Sandy Shores, Paleto Bay and Cayo Perico at 0. Anywhere no region covers, such as open ocean, uses the global weather.

Where two regions of the same priority meet, their weather blends across a soft edge, 200 metres wide by default. Drive from Los Santos into Sandy Shores in the rain and the rain thins out over that distance instead of snapping off.

Crossing a boundary blends the visuals over about 6 seconds, and the wind eases over about 2 seconds, so nothing pops.

Per-region control

Every region has its own:

• current weather
• forecast queue
• automatic weather on or off
• change interval
• wind
• blend width
• colour on the map
• enabled switch

You can hold Paleto Bay in a permanent storm while the rest of the map cycles normally.

Automatic Weather and the Forecast

How the weather picks itself

Weather does not jump at random. Each weather type has a list of what it can turn into next, with a weight on each. Overcast, for example, is far more likely to turn into rain than back into clear sky. That is what makes the sky feel like it is going somewhere.

Fifteen weather types are available:

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

You can remove any of them from the pool except CLEAR, which always stays available as a fallback.

The change interval

By default the weather changes every 15 real minutes. Each region counts down separately.

The forecast queue

The next 4 weather changes are decided in advance and published as a forecast. That is what feeds the weather app, the radar, the alerts and the /weather forecast command. Because the queue is decided ahead of time, a warning can be issued before the storm arrives rather than as it lands.

The transition changes smoothly over 30 seconds by default, rather than snapping.

Winter transitions

There is a second, smaller set of transitions that only adds snow-bound routes (clouds turning into light snow, overcast into snow). With seasons on, those edges are added automatically in whichever seasons allow snow, and stripped out of the ones that do not. With seasons off, you can fold them into the base pattern with a single toggle.

Real-World Weather

Instead of picking weather from the transition table, the whole map can mirror a real city. Turn it on from /weather settings or with /weather realworld <city>, and your server starts asking Open-Meteo, a free weather service, what the sky looks like there.

What follows the real world

• The weather type. Rain in the real city is rain in every region, changing on the real hour with the same smooth transition as any other change.
• The temperature. The real reading replaces the modelled one, still cooling with altitude, so Mount Chiliad stays colder than the beach. Snow builds up and melts from it.
• The wind. Speed and direction come from the real place.
• The forecast. The next hours of the real forecast fill the queue, so the weather app, the alerts, the radar and the Weazel report all describe what is actually coming.

Moving fronts pause while the mirror is on. Scene locks and the holiday presets still win: a Christmas preset takes over, and the mirror picks up again when you end it.

What stays yours

The clock, the seasons, the blackouts, the regions and the shelter checks all work exactly as before. The game clock keeps its own speed unless you turn on the clock mirror, which follows the location's local time and daylight saving too.

The weather, forecast and front controls are read-only while the mirror runs. Anything you change in the settings menu for the automatic weather is stored and comes back the moment you turn the mirror off.

When the internet is not there

The server keeps the last two days of hourly forecast it received. If updates stop, the sky keeps following that cached forecast and the app marks the data as overdue. Only if the cache runs out entirely does the normal automatic weather resume from wherever the sky was, and the mirror takes over again with the next good update. A restart does not need the internet either: the cached forecast is saved with the world.

Updates come every 15 minutes by default and never more often than every 5. Failed requests are retried gently, starting a minute later and backing off. See Configuration → Real-world weather for what is sent and for the attribution the data licence asks for.

Seasons

Three ways to run seasons

In game mode each season is 7 in-game days long by default, so a full year takes 28 in-game days. /weather season tells you which season you are in and which day of it.

Calendar mode can follow UTC or your server machine's own clock, and can be flipped to the southern hemisphere so December is summer.

Season profiles

Each season carries a baseline temperature, whether snow is allowed, and its own weather weights:

When a season does not allow snow, snowy weather is removed from the pool entirely, and anything already snowing clears up.

Holiday presets

Two presets ship: Christmas and Halloween.

Turning a preset on takes a snapshot of the world first. Turning it off puts everything back exactly as it was, including each region's forecast queue and how long was left on its timer. While a preset is running, weather controls are locked and moving fronts are paused, so nothing can knock the scene out of shape.

Toggle them with /weather christmas and /weather halloween, or from the admin panel.

Temperature

Temperature is a real number for any point on the map, not a label. It is worked out from:

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

Temperature is shown in °F by default. Change it to °C under Climate in the settings menu. Other resources always receive Celsius regardless of the display setting, so nothing gets confused.

Moving fronts adjust the temperature too. Standing under a thunderstorm cell reads colder than the region around it.

Snow

Snow that accumulates

Snow is not a switch. It is a level from 0 to 1 per region, and per point on the map.

Different snow weathers lay snow at different rates: SNOW and XMAS at full rate, SNOWLIGHT at 40%, BLIZZARD at 150%.

Melting depends on how far above freezing it is. At +1 °C the ground stays white for a long time. At +15 °C it is gone quickly.

What snow looks like

• Ground cover, vehicle tracks and footprints can each be switched off on their own.
• The falling-snow effect is scaled to 35% of full strength by default, because the game's own full-strength snow is very heavy.
• At night that is scaled down again to 40%, easing in through dawn and dusk so it does not jump.
• All snow weathers render with the XMAS look by default, which avoids the heavy ground mist the other snow types use. The simulation, forecast and exports still report the real weather.
• If XMAS causes problems on your map or with your players' game builds, you can substitute SNOW, SNOWLIGHT or BLIZZARD for it. The server still reports XMAS.

Cayo Perico

Snow is excluded from Cayo Perico by default. Anyone inside the island's bounds sees clear weather instead of snow, reads a snow level of zero, and gets the tropical temperature baseline. You can move the bounds or turn the exclusion off.

Moving Weather Fronts

A front is a storm cell that travels across the map. It is not a region, and it does not care about region boundaries.

Each front has:

Inside the core the front's weather takes over completely. Across the soft edge it blends with whatever the region underneath is doing. Ahead of the front the wind picks up before the cloud arrives.

Up to 8 fronts can be active at once.

Automatic fronts

Left alone, a new front spawns every 30 to 60 real minutes from one of three starting points off the west coast, heading east across the map. The weather it brings is picked from a weighted mix: rain 55%, thunder 35%, fog 10%.

If seasons are on, snow fronts only spawn in a season that allows snow.

Spawning one yourself

/weather front spawn drops a front at your feet with the defaults, and takes optional arguments for weather, bearing, speed, radius, lifetime and a specific X/Y position. /weather front list shows what is active with a countdown, and /weather front remove <id> clears one. The admin panel's Fronts tab does the same with a map. See Admin Tools → /weather front.

Lightning and Power Cuts

Lightning

While a thunder front is active, or a region is under thunder, lightning strikes every 35 to 70 seconds. Players within 2500 m of the strike see the flash.

Lightning can also flicker the street lights for 400 milliseconds near the strike, which reads as a power surge.

Blackouts

Three kinds:

Vehicle lights can be included or excluded from a blackout.

Lightning can also cause one. Each thunder strike has a 20% chance of knocking out power in the affected region for 120 seconds, provided the front is covering enough of it.

Up to 64 outages can be scheduled at once, up to 24 hours long, up to 7 days ahead.

Manage them all with /weather blackout, or from the admin panel's Power tab.

Visibility Effects

Rain, thunder and fog can carry a subtle screen filter on top of the game's own weather, to sell heavy conditions. Three profiles ship: a light fog wash for FOGGY, and a storm filter for RAIN and THUNDER at two different strengths.

Two things keep it out of your way:

• The effect is capped at 20% strength, halved at night, and cut to a quarter as snow blends in.
• It only takes the screen filter slot when that slot is free. If any other resource has claimed it, oxide-weather backs off and never clears or adjusts a filter it does not own.

If a filter is missing from a player's game, it is noted once and skipped rather than retried forever.

The Public Weather Service

This is the player-facing side: a forecast your players can actually look at.

The weather app

If you run oxide-tablet, players get a Weather app with three pages:

Players install the app themselves from the tablet.

The home-screen widget

A Weather widget in three sizes:

Tapping it opens the app.

Severe weather alerts

Alerts are worked out automatically from each region's forecast queue and from any storm front heading its way. They come in three levels:

Each rule carries a short title and a line of advice, and both are yours to rewrite.

Two rules make them read like real weather alerts:

• Something happening now is issued at its full level. Something forecast for later is capped at a watch, and is promoted to a warning when it actually starts.
• Alerts carry a time window ("today 14:20 to 16:05", "until 03:40 tomorrow") worked out from the in-game clock, including day rollover.

By default players are notified about watches and warnings in their own region, up to 15 real minutes ahead. You can widen that to advisories, to all regions, or to warnings only.

Notifications arrive on the tablet with a sound, and repeated samples of the same alert do not re-notify. A watch turning into a warning does.

The radar

The radar shows regions coloured by their conditions and every active storm cell, with its heading, its size and where it will be. Its look-ahead is bounded by whichever comes first: your alert look-ahead, the radar horizon setting, or the end of the known forecast queue. It never draws a future it has not actually decided.

The admin panel has the same radar on its own tab.

The Weazel News report

oxide-weather can produce a written weather bulletin on demand: a headline with the in-game time, a line per region with conditions, temperature and wind, an outlook line with the upcoming changes, and every active alert.

There is no command for it. It is there for other resources to pull, so a news script, a radio script or a newspaper job can print a real weather segment. See GenerateWeazelReport.

The Admin Panel

/weather on its own opens a full-screen panel with a map of your regions. Click a region to control it, or stay on Global to control everything at once.

The panel refreshes itself every two seconds while it is open, so two admins working at once see each other's changes. See Admin Tools → The admin panel.

The Zone Editor

/weather zones opens a map where you build your own weather regions.

• Draw a region on the map, or by walking the shape in the world. The editor hands over to the in-world drawing tool, you place the corners, and the shape comes back into the map.
• Edit the name, colour, climate, priority, blend width, whether automatic weather runs there and how often it changes.
• Enable or disable a region without deleting it.
• Delete a region you no longer want.

Limits: up to 32 regions, up to 64 corners each, and shapes may not cross over themselves.

Your saved regions replace the ones that ship. The ones in the config file are starting points, not a map you are stuck with.

Changes apply live. Nobody has to reconnect. See Admin Tools → The zone editor.

Scene Locks

A scene lock freezes the world for a photo, a cutscene or a staged event.

• /weather lock global 300 freezes weather, time, wind, blackout state and snow cover for everyone, for 5 minutes.
• /weather lock 42 300 freezes it for player 42 only. Everyone else carries on as normal.
• /weather unlock global or /weather unlock 42 releases it early.

A lock lasts between 1 and 7200 seconds and releases itself when it expires, so a forgotten lock cannot strand your server.

While a global lock is held, weather controls are refused with a clear message, and moving fronts are paused so they do not skip ahead. Time inside the hold does not count towards weather timers, so nothing snaps forward when you release it.

Locks are also released automatically when the player they apply to disconnects, or when the resource that requested one stops.

Shelter and Exposure

oxide-weather can answer the question "is this spot under cover?" for other resources. It does not do anything with that answer on its own. It supplies the data, and other resources decide what it means.

How cover is worked out

Three sources, in order:

1. Areas you drew. Shapes you mark as covered in the settings menu always win. Use these for interiors, tunnels, car parks and anything the game's own geometry gets wrong. Each one has a height range, and can be limited to a single routing bucket.
2. A look upward. For anywhere else, the server asks a nearby player's game to fire a probe straight up from that point. If it hits something, the point is covered. Results stay valid for 30 seconds.
3. The player's own situation. For a player specifically, being inside an interior counts as covered, and so does sitting in a vehicle that is not a boat, a bike, a cycle, or a convertible with the roof down.

Only points somebody has actually asked about are checked, up to 512 of them, at 8 checks per second, and only from players within 80 metres.

Wetness

For each player, the resource also tracks how wet they are. Standing in the rain uncovered takes about a minute to soak through. Drying off takes about five minutes. Swimming soaks you instantly.

Clothing insulation

You can map a clothing item to an insulation value from 0 to 1, keyed by character model and the torso item worn. That value is handed to whatever resource asked, so a warm jacket can matter for cold damage. It ships empty. Insulation is decided on the server, never sent up by a player's game.

Turning it off

There is no on/off switch, because it costs nothing when nothing is asking. Checks only happen for points another resource requests. If no resource is asking about shelter, no checks run.

Road Conditions

The map is covered by a grid of 500 metre cells, updated every 5 seconds. Each cell tracks two numbers from 0 to 1:

Like shelter, oxide-weather only supplies these numbers. Turning them into grip loss is the job of a vehicle resource that reads them.

/weather inspect prints the wetness and ice at your position, so you can see it working.

The grid saves with the rest of the world, so a restart does not dry every road instantly.

Saving and Restarts

The whole world is written to your database:

• the clock, the weather and the forecast queue, globally and per region
• your region shapes and settings
• the season and how far through it you are
• snow cover per region
• active storms, blackouts and schedules
• road wetness and ice

A checkpoint is written every 30 seconds and immediately after any change. On a clean stop, a final checkpoint is written. If the database is briefly unavailable, the write is retried every 60 seconds and nothing is lost in the meantime.

Restart the resource and the world picks up where it left off.

If two servers share one database, give each one its own simulation key so they do not overwrite each other.

Working with Other Resources

Other resources can read the weather in two ways:

• Through o-link. The weather namespace exposes conditions, forecasts, temperature, snow, fronts, shelter and road data. This is the recommended path, because a script written against it keeps working if you ever swap weather resources.
• Directly. oxide-weather also publishes its own exports.

Anything that changes the weather is locked down. A resource must be named in the trusted list before it may set anything, and a request that carries a player must also pass the admin check. Everything else is read-only.

Live values are also published as server state that any script can read without calling anything, including the current weather, time, season, forecast, snow cover and active storms.

Full details, with copy-paste examples, are in the API Reference.

Next Steps