Natural Disasters

AV Weather can roll natural disasters at random across your map, or let admins trigger them on demand. A disaster takes over a zone with extreme weather (and, for tornadoes, a physical funnel), runs for a while, and then the zone returns to its normal weather cycle on its own.

Everything is configured in config/_disasters.lua. Nothing else is required — disasters reuse the same per-zone system as the rest of the script.

Disasters are server-authoritative. The server decides what happens and where; every player sees the same event in the same place. Only one disaster is ever active at a time.

How it works

Every checkInterval minutes the server rolls once:

1. It checks globalChance — the chance that any disaster happens on this roll.

2. If it hits, it picks a zone and a disaster type using the weights in Config.ZoneDisasters. A zone with bigger weights is more likely to be chosen.

3. The zone's weather is forced (e.g. THUNDER + heavy wind + fog) and normal weather generation for that zone is paused.

4. Players get a warning, then the event begins.

5. After a random duration between minDuration and maxDuration, the disaster ends and the zone resumes its normal weather.

6. A cooldown must pass before a new disaster can be rolled.

Admins can also force any disaster in any zone at any time from the weather menu or via exports — even a disaster whose weight is 0 in that zone.

---

Global settings — Config.Disasters

These control the automatic random system as a whole.

Config.Disasters = {
    enabled = true,     -- master switch for automatic disasters
    checkInterval = 15, -- every X real minutes the server rolls for a disaster
    globalChance = 10,  -- % chance, per roll, that ANY disaster happens
    cooldown = 30,      -- real minutes after one ends before a new roll
    minDuration = 5,    -- disaster length, real minutes (random min)
    maxDuration = 10,   -- disaster length, real minutes (random max)
    warnSeconds = 45,   -- seconds of warning before it hits (0 = no warning)
}

Field	Type	What it does
enabled	boolean	Turn the automatic (random) system on or off. Manual triggering still works when this is false.
checkInterval	minutes	How often the server rolls the dice.
globalChance	0–100	On each roll, the percent chance that a disaster starts at all.
cooldown	minutes	Quiet period after a disaster ends before the next roll can succeed.
minDuration / maxDuration	minutes	The event lasts a random time between these two values.
warnSeconds	seconds	Advance warning before the event actually begins. 0 = it hits instantly.

globalChance decides if a disaster happens. It does not decide which one or where — that is Config.ZoneDisasters below. Keeping the two separate lets you make disasters rare overall while still controlling their distribution.

---

Probability per zone — Config.ZoneDisasters

This table decides where a disaster lands and which type, using relative weights per zone. The keys must match your zone keys in config/_zones.lua.

Config.ZoneDisasters = {
    ['sandy'] = {
        tornado      = 45,
        hurricane    = 10,
        thunderstorm = 35,
        earthquake   = 10,
    },
    ['santos'] = {
        tornado      = 0,   -- Los Santos never gets a tornado
        hurricane    = 20,
        thunderstorm = 50,
        earthquake   = 30,
    },
    -- ... one entry per zone
}

Rules:

• Weights are relative — they do not need to add up to 100.

• A weight of 0 means "this disaster never happens here" automatically.

• A zone not listed in this table never gets an automatic disaster at all.

• Admins can still force any disaster in any zone from the menu, even one weighted 0.

Worked example

With sandy.tornado = 45 and paleto.tornado = 25, a tornado is roughly 1.8× more likely to form in Sandy Shores than in Paleto Bay (45 ÷ 25). Weights are pooled across every zone and type together, so higher numbers simply mean "more likely to be picked".

Adding a custom zone

If you added a new zone in config/_zones.lua (say vinewood), add a matching entry here so it can receive disasters:

['vinewood'] = { tornado = 0, hurricane = 15, thunderstorm = 60, earthquake = 25 },

---

Disaster types — Config.DisasterTypes

Each entry defines what a disaster is. The where/how-often lives in Config.ZoneDisasters; the behaviour and looks live here.

Shared fields

Most disasters share these:

Field	Type	What it does
label	string	Display name used in logs and the menu.
weather	string	GTA weather forced on the zone (THUNDER, RAIN, etc.). Omit for cosmetic events.
wind	number	Wind speed applied to the zone (m/s, 0–12).
fog	string	Fog preset applied to the zone (no, low, medium, high, max).
lightning	boolean	Periodic lightning flashes + thunder.
lightningInterval	{min, max}	Seconds between lightning flashes.
shake	boolean	Camera shake for players inside the zone.
shakeIntensity	number	Strength of the shake (higher = stronger).

The weather, wind and fog are applied through the normal zone system, so they sync to everyone automatically. The lightning and shake are cinematic effects that only play for players who are actually inside the affected zone.

---

Hurricane

The heaviest storm: max wind, thick fog, frequent lightning and a light, continuous camera buffeting.

["hurricane"] = {
    label = "Hurricane",
    weather = "THUNDER",
    wind = 12.0,
    fog = "high",
    lightning = true,
    lightningInterval = { 4, 9 },
    shake = true,
    shakeIntensity = 0.16,
},

Best used sparingly and in coastal zones (Paleto, Cayo).

---

Thunderstorm

A lighter storm — frequent lightning, moderate wind, low fog, and no shake. Good as a common, everyday severe-weather event.

["thunderstorm"] = {
    label = "Thunderstorm",
    weather = "THUNDER",
    wind = 7.0,
    fog = "low",
    lightning = true,
    lightningInterval = { 3, 7 },
    shake = false,
},

---

Earthquake

A cosmetic event: it does not change the weather. Instead it delivers a series of strong camera jolts, and can knock players off their feet.

["earthquake"] = {
    label = "Earthquake",
    cosmetic = true,       -- does NOT touch the weather, only shakes
    shake = true,
    shakeIntensity = 0.6,
    shakePulses = { 6, 12 }, -- number of jolts spread across the duration
    fallingProb = 50,        -- % chance, per jolt, that a walking ped ragdolls
},

Field	Type	What it does
cosmetic	boolean	Marks the event as weather-neutral. The zone keeps its normal weather.
shakePulses	{min, max}	How many jolts happen, spread evenly over the event's duration.
fallingProb	0–100	Per jolt, the chance an on-foot player is ragdolled forward. Players in vehicles are never affected.

Because the earthquake is cosmetic, it can safely overlap with whatever weather the zone already has — it never freezes or changes the forecast.

---

Tornado

The showpiece: a moving funnel that travels across the zone, sucking in nearby players, vehicles and objects. The storm weather is applied to the zone, and the funnel itself is rendered client-side with physics.

["tornado"] = {
    label = "Tornado",
    weather = "THUNDER",
    wind = 12.0,
    fog = "low",
    lightning = true,
    lightningInterval = { 5, 12 },
    shake = false,          -- proximity shake handled by the tornado module
    tornado = true,         -- THIS is what makes the funnel spawn

    -- Funnel shape & movement
    moveSpeed = 6.0,        -- m/s the funnel travels across the zone
    height = 180.0,         -- funnel height in metres
    baseRadius = 6.0,       -- radius at the ground
    topRadius = 45.0,       -- radius at the top (cone widens upward)
    rings = 6,              -- vertical particle rings (perf: keep <= 8)
    perRing = 5,            -- particles per ring (perf: keep <= 6)
    spinSpeed = 2.5,        -- radians/sec the funnel rotates
    particleDict = "scr_agencyheistb",
    particleName = "scr_env_agency3b_smoke",
    particleScale = 8.0,

    -- Distance & physics
    renderDistance = 500.0, -- draw the funnel within this distance
    pullRadius = 60.0,      -- entities inside this radius get sucked in
    pullForce = 12.0,       -- suction strength
    coreRadius = 12.0,      -- inside this you get ragdolled / thrown
},

Field	Type	What it does
tornado	boolean	Required. Set true to make the funnel spawn. Without it, the entry behaves like a normal storm.
moveSpeed	m/s	How fast the funnel wanders across the zone. It always stays inside the zone polygon.
height	metres	Total funnel height.
baseRadius / topRadius	metres	Funnel width at the ground and at the top (it widens upward into a cone).
rings	count	Vertical rings of particles. Keep ≤ 8 for performance.
perRing	count	Particles per ring. Keep ≤ 6. rings × perRing is the total particle count (30 is a good balance).
spinSpeed	rad/s	How fast the funnel visually rotates.
particleDict / particleName / particleScale	—	The particle asset and its size.
renderDistance	metres	Players only render the funnel within this distance.
pullRadius	metres	Entities inside this radius are pulled toward the funnel.
pullForce	number	Suction strength.
coreRadius	metres	Inside this inner radius, on-foot players are ragdolled and thrown.

Tune pullForce carefully. Start at 12.0 and raise it in small steps — too high launches vehicles into orbit and feels wrong. Likewise, only raise rings and perRing if your server's FPS can take it.

---

From other resources (exports)

-- Start: zone and type are optional (random/weighted if omitted).
-- Admins can force any type in any zone, even a 0-weight one.
exports['av_weather']:startDisaster('sandy', 'tornado', 8) -- zone, type, minutes

-- Random weighted disaster:
exports['av_weather']:startDisaster()

-- Stop the active disaster:
exports['av_weather']:stopDisaster()

-- Query the active disaster (returns false if none):
local active = exports['av_weather']:getActiveDisaster()
-- -> { zone = "sandy", type = "tornado", label = "Tornado" }

startDisaster returns ok, errorMessage. It fails (returns false) if a disaster is already active or the zone/type is unknown.

---

Custom warning hook

When a disaster is scheduled with warnSeconds > 0, the server calls a hook in server/editable/disasters.lua before the event begins. This is where you add your own alert — a notification, a siren sound, a UI banner, anything.

function disasterWarning(zone, zoneLabel, dtype, seconds)
    -- Called `warn` seconds before the disaster hits.
    --   zone  = zone key (e.g. "sandy")
    --   zoneLabel = zone Labe
    --   dtype = disaster type (e.g. "tornado")
    --   seconds = seconds until it hits
    -- Example: broadcast a warning to everyone
    TriggerClientEvent('av_weather:notification', -1,
        ("A %s is approaching %s!"):format(dtype, zoneLabel), 'error')
end

By default this hook only prints a debug line, so no warning is shown until you add your own. It's an editable file, so it's safe to customise.