API Reference

local olink = exports['o-link']:olink()
local weather = olink.weather.GetWeather()

if olink.weather.GetResourceName() == 'oxide-weather' then
    local conditions = olink.weather.GetConditionsAt(coords)
end

local weather = exports['oxide-weather']:GetWeather()

-- server, from a resource listed in Config.SetterResources
local ok, reason = exports['oxide-weather']:SetWeather('THUNDER', nil)
if not ok then print(reason) end

{
    weather     = 'RAIN',                        -- the dominant weather at that point
    weights     = { RAIN = 0.7, CLOUDS = 0.3 },  -- blend of every contributing weather, sums to 1
    zone        = 'city',                        -- region id, or 'global'
    rain        = 0.7,                           -- 0-1, share of RAIN + THUNDER
    snow        = 0.0,                           -- 0-1, share of snow weathers
    raining     = true,                          -- rain >= 0.1
    wind        = { speed = 3.2, direction = 218.4 },  -- m/s, degrees
    temperature = 14.2,                          -- Celsius. nil when seasons are disabled
    snowLevel   = 0.0,                           -- 0-1 ground cover
    season      = 'autumn',                      -- nil when seasons are disabled
    blackout    = false,
}

{
    current = {
        weather     = 'OVERCAST',
        time        = { hour = 14, minute = 37 },
        zone        = 'city',
        label       = 'Los Santos',
        temperature = 12.4,        -- present when seasons are enabled
        snowLevel   = 0.0,
        season      = 'autumn',
        baseWeather = 'CLOUDS',    -- client GetWeatherData only: present when a front is overriding the region
        front       = { id, weather, strength, windStrength, phase, coords },  -- client GetWeatherData only. phase is 'weather' or 'approaching'
    },
    forecast = {
        {
            weather     = 'RAIN',
            startsIn    = 8.4,                        -- real minutes from now
            gameTime    = { hour = 18, minute = 12 }, -- in-game time it lands
            temperature = 9.8,
            season      = 'autumn',
            baseWeather = 'RAIN',   -- client GetWeatherData only
        },
        -- ...up to Config.ForecastLength entries
    },
    settings = {
        dynamicWeather   = true,
        weatherInterval  = 15,      -- real minutes
        timeScale        = 30,
        timeFrozen       = false,
        blackout         = false,
        clock            = { mode = 'game', nightScale = 30, nightStart = 21, nightEnd = 6, utcOffset = 0 },  -- global data only
        forecastRevision = 12,
        temperatureUnit  = 'F',     -- display only. Exports always return Celsius
        season           = 'autumn',
        seasonMode       = 'game',  -- 'game' | 'calendar' | 'manual' | 'holiday'
        holiday          = nil,
        clockOffset      = nil,     -- per-region clock offset in game minutes, region data only
        broadcast        = { ... }, -- the live public weather settings, global data only
        realWorld        = nil,     -- { enabled, active, stale, station, attribution } while the real-world mirror is on, global data only
    },
    wind = { speed = 3.2, direction = 218.4 },
}

{
    id         = 'front-3',
    weather    = 'THUNDER',
    coords     = { x = -5000.0, y = 2800.0, z = 45.0 },  -- where it spawned
    position   = { x = -1420.5, y = 2800.0, z = 45.0 },  -- where it is now
    heading    = 90.0,      -- compass bearing
    speed      = 12.0,      -- m/s
    radius     = 900.0,
    blendWidth = 350.0,
    windLead   = 500.0,
    windSpeed  = 6.0,
    duration   = 1200.0,    -- seconds
    fadeSeconds = 20.0,
    priority   = 0,
    age        = 184000,    -- milliseconds since spawn
}

{
    id       = 'weather-1757000000-0-4',
    zone     = 'paleto',
    region   = 'Paleto Bay',
    weather  = 'THUNDER',
    severity = 3,                    -- 1 advisory, 2 watch, 3 warning
    status   = 'active',             -- 'upcoming' | 'active' | 'ended'
    label    = 'Thunderstorm',
    title    = 'Thunderstorm warning',
    advice   = 'Lightning and heavy rain are expected...',
    message  = 'Paleto Bay · until 04:15 tomorrow. Lightning and heavy rain...',
    window   = 'until 04:15 tomorrow',
    startsIn = 0,                    -- real seconds
    endsIn   = 620,                  -- real seconds. nil means "until conditions change"
    startTime = { hour = 3, minute = 5, dayOffset = 0 },   -- in-game
    endTime   = { hour = 4, minute = 15, dayOffset = 1 },
    source   = 'front',              -- 'region' | 'forecast' | 'front' | 'scene'
    revision = 2,                    -- bumps when the alert meaningfully changes
    issuedAt = 1757000000,           -- unix seconds
    updatedAt = 1757000420,
}

local version = exports['oxide-weather']:GetApiVersion()   -- 2

if exports['oxide-weather']:IsReady() then ... end

local data = exports['oxide-weather']:GetConditionsAt(vector3(215.0, -810.0, 31.0))

local weather = exports['oxide-weather']:GetWeatherAt(coords)   -- 'THUNDER'

local wind = exports['oxide-weather']:GetWindAt(coords)
-- { speed = 3.2, direction = 218.4 }

if exports['oxide-weather']:IsRainingAt(coords) then ... end

local snowy = exports['oxide-weather']:IsSnowOnGround(coords)   -- coords optional

local celsius = exports['oxide-weather']:GetTemperatureAt(coords)   -- 12.4

local level = exports['oxide-weather']:GetSnowLevelAt(coords)   -- 0.0 to 1.0

local zone = exports['oxide-weather']:GetZoneAt(coords)   -- 'city'

local road = exports['oxide-weather']:GetRoadConditionsAt(coords)
-- { wetness = 0.42, ice = 0.0, cellSize = 500 }

local weather = exports['oxide-weather']:GetWeather()   -- 'CLEAR'

local time = exports['oxide-weather']:GetTime()   -- { hour = 14, minute = 37 }

local scale = exports['oxide-weather']:GetTimeScale()   -- 30

local frozen = exports['oxide-weather']:IsTimeFrozen()

local dark = exports['oxide-weather']:IsBlackout()

local auto = exports['oxide-weather']:IsDynamicWeather()

local minutes = exports['oxide-weather']:GetWeatherInterval()   -- 15

local forecast = exports['oxide-weather']:GetForecast()

local data = exports['oxide-weather']:GetWeatherData()          -- global
local paleto = exports['oxide-weather']:GetWeatherData('paleto') -- one region

local zones = exports['oxide-weather']:GetZones()

{
    { id = 'city', label = 'Los Santos', climate = 'temperate', color = '#57c6c5',
      enabled = true, priority = 0, blendWidth = 200.0,
      dynamicWeather = true, weatherInterval = 15,
      wind = { speed = 1.5, direction = 225.0 },
      polygon = { points = { { x = -3200, y = -3800 }, ... } } },
    -- ...
}

local weather = exports['oxide-weather']:GetZoneWeather('sandy')   -- 'EXTRASUNNY'

local forecast = exports['oxide-weather']:GetZoneForecast('sandy')

local season = exports['oxide-weather']:GetSeason()   -- 'winter'

local climate = exports['oxide-weather']:GetClimateData()
-- { season = 'winter', mode = 'game', day = 3, daysPerSeason = 7,
--   holiday = nil, temperatureUnit = 'F' }

local celsius = exports['oxide-weather']:GetTemperature()           -- global
local paleto  = exports['oxide-weather']:GetTemperature('paleto')   -- one region

local level = exports['oxide-weather']:GetSnowLevel()           -- global
local alps  = exports['oxide-weather']:GetSnowLevel('chiliad')  -- one region

local fronts = exports['oxide-weather']:GetFronts()

local dark = exports['oxide-weather']:IsZoneBlackout('paleto')

local blackouts = exports['oxide-weather']:GetBlackouts()
-- {
--   overrides = { paleto = true },
--   outages   = { { id = 'blackout-2', zone = 'city', source = 'scheduled',
--                   startsIn = 480000, endsIn = 2280000 } },   -- milliseconds
-- }

local mirror = exports['oxide-weather']:GetRealWorldWeather()
-- {
--   revision = 8, enabled = true, active = true, stale = false, exhausted = false,
--   location = 'Paris, FR', pollMinutes = 15, syncClock = false,
--   station = { name = 'Paris, Ile-de-France, France', latitude = 48.85, longitude = 2.35,
--               timezone = 'Europe/Paris', utcOffset = 7200 },
--   weather = 'RAIN', code = 63, temperature = 14.2, humidity = 81, isDay = true,
--   wind = { speed = 4.1, direction = 230 },
--   observedAt = 1789200900, fetchedAt = 1789201013, nextPollIn = 612,
--   lastError = nil, attribution = 'Weather data by Open-Meteo.com',
-- }

local alerts = exports['oxide-weather']:GetWeatherAlerts()          -- every region
local local_ = exports['oxide-weather']:GetWeatherAlerts('paleto')  -- one region

local report, reason = exports['oxide-weather']:GenerateWeazelReport(nil, { unit = 'C' })
if report then print(report.text) end

{
    headline   = 'Weazel Weather · 14:37',
    text       = 'Weazel Weather · 14:37\nLos Santos: OVERCAST 12.4°C, wind 3.2 m/s at 218\n...',
    generatedAt = 1757000000,          -- unix seconds
    gameTime   = { hour = 14, minute = 37 },
    season     = 'autumn',
    unit       = 'C',
    zones      = { 'city', 'paleto', ... },
    alerts     = { <Alert>, ... },     -- active alerts included in the text
}

local locks = exports['oxide-weather']:GetSceneLocks()
-- { { target = 'global', owner = 'admin', weather = 'THUNDER',
--     time = { hour = 3, minute = 5 }, remaining = 412.0 } }   -- seconds

local cover = exports['oxide-weather']:GetExposureAt(coords, 0)
-- { known = true, covered = false, bucket = 0, age = 4.2 }

local exposure = exports['oxide-weather']:GetPlayerExposure(source)

{
    known       = true,
    covered     = false,      -- interiors and enclosed vehicles count as covered
    wetness     = 0.63,       -- 0-1. Rises in rain, falls when dry, 1 while swimming
    insulation  = 0.0,        -- 0-1, from Config.Exposure.Clothing
    temperature = 4.1,        -- Celsius at the player's position
    conditions  = <Conditions>,
}

local snow = exports['oxide-weather']:GetSetting('Snow')

local ok, reason, pending = exports['oxide-weather']:SetSetting('WeatherTransitionTime', 0, nil)
if ok and pending == 'restart' then
    print('saved, but oxide-weather must be restarted for it to apply')
end

local ok, frontId = exports['oxide-weather']:SpawnFront({
    coords     = vector3(-1200.0, 2400.0, 30.0),  -- required
    weather    = 'THUNDER',   -- defaults to Config.Fronts.Defaults.weather
    heading    = 90.0,        -- 0-360, compass bearing
    speed      = 12.0,        -- 0-100 m/s
    radius     = 900.0,       -- 100-5000 m
    blendWidth = 350.0,       -- 1-5000 m, cannot exceed radius
    windLead   = 500.0,       -- 0-5000 m
    windSpeed  = 6.0,         -- 0-12 m/s
    duration   = 1200.0,      -- 10-7200 seconds
    fadeSeconds = 20.0,       -- 0-60, cannot exceed half the duration
    priority   = 0,           -- -1000 to 1000
}, nil)

local weather = exports['oxide-weather']:GetWeather()

local covered = exports['oxide-weather']:IsCovered()   -- current position

-- Ignore a prop you spawned, so it does not read as shelter
exports['oxide-weather']:RegisterExposureEntity(umbrellaObject)
exports['oxide-weather']:UnregisterExposureEntity(umbrellaObject)

exports['oxide-weather']:ToggleSync(false)   -- suspend weather sync for this client
exports['oxide-weather']:ToggleSync(true)    -- resume

local olink = exports['o-link']:olink()

AddEventHandler('oxide:weather:weatherChanged', function(data)
    -- data.weather  : string, the new global weather
    -- data.previous : string or nil
end)

AddEventHandler('oxide:weather:timeChanged', function(time)
    -- time.hour, time.minute
end)

AddEventHandler('oxide:weather:clockProgress', function(data)
    -- data.minutes : number, total in-game minutes advanced since the resource started
    -- data.frozen  : boolean, true while the clock is frozen or a global scene lock is held
end)

AddEventHandler('oxide:weather:freezeChanged', function(data)
    -- data.frozen : boolean
end)

AddEventHandler('oxide:weather:blackoutChanged', function(data)
    -- data.enabled : boolean, the global blackout state
end)

AddEventHandler('oxide:weather:zoneWeatherChanged', function(data)
    -- data.zone     : string, region id
    -- data.weather  : string
    -- data.previous : string or nil
end)

AddEventHandler('oxide:weather:zoneBlackoutChanged', function(data)
    -- data.zone    : string, region id
    -- data.enabled : boolean
end)

AddEventHandler('oxide:weather:seasonChanged', function(data)
    -- data.season   : string or nil
    -- data.previous : string or nil
end)

AddEventHandler('oxide:weather:frontSpawned', function(front)
    -- front : the front as spawned, with age = 0 and no position field. Use GetFronts for the live shape
end)

AddEventHandler('oxide:weather:frontRemoved', function(data)
    -- data.id     : string
    -- data.reason : string, for example 'admin' or 'expired'
end)

AddEventHandler('oxide:weather:lightningStrike', function(data)
    -- data.id                  : string, unique strike id
    -- data.front               : string, the front id that produced it
    -- data.zone                : string, region id
    -- data.coords              : { x, y, z }
    -- data.radius              : number, metres within which players see the flash
    -- data.flicker             : boolean
    -- data.flickerMilliseconds : number
end)

AddEventHandler('oxide:weather:alertsChanged', function(alerts)
    -- alerts : a list of Alert tables, most severe first
end)

AddEventHandler('oxide:weather:forecastChanged', function(forecast)
    -- forecast : the forecast list for this player's region
end)

AddEventHandler('oxide:weather:zoneChanged', function(data)
    -- data.zone     : string, the region entered
    -- data.previous : string or nil
end)

RegisterNetEvent('oxide:weather:bulletinChanged', function(packet)
    -- packet.session  : string, changes when the resource restarts
    -- packet.sequence : number, increments on every change
    -- packet.alerts   : a list of Alert tables
end)

-- client
local weather = GlobalState['oxide:weather']
local time    = GlobalState['oxide:time']

AddStateBagChangeHandler('oxide:weather', 'global', function(_, _, value)
    print('weather is now', value)
end)

-- server, in any resource
local olink = exports['o-link']:olink()

CreateThread(function()
    while true do
        Wait(30000)
        for _, id in ipairs(GetPlayers()) do
            local src = tonumber(id)
            local exposure = olink.weather.GetPlayerExposure(src)
            if exposure and exposure.known and not exposure.covered
                and exposure.temperature and exposure.temperature <= 0 then
                local protection = exposure.insulation - exposure.wetness * 0.5
                if protection < 0.5 then
                    local ped = GetPlayerPed(src)
                    SetEntityHealth(ped, math.max(101, GetEntityHealth(ped) - 5))
                end
            end
        end
    end
end)

-- server
local olink = exports['o-link']:olink()

local function GrowthMultiplier(coords)
    local conditions = olink.weather.GetConditionsAt(coords)
    if not conditions then return 1.0 end          -- weather unavailable, do not punish the player
    local multiplier = 1.0
    if conditions.raining then multiplier = multiplier * 1.15 end
    if conditions.temperature then
        if conditions.temperature <= 0 then multiplier = multiplier * 0.7
        elseif conditions.temperature >= 35 then multiplier = multiplier * 0.8 end
    end
    return multiplier
end

-- client
local olink = exports['o-link']:olink()

CreateThread(function()
    while true do
        Wait(2000)
        local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
        if vehicle ~= 0 and GetPedInVehicleSeat(vehicle, -1) == PlayerPedId() then
            local road = olink.weather.GetRoadConditionsAt(GetEntityCoords(PlayerPedId()))
            if road then
                -- slippery once the road is properly wet, or once ice has formed
                SetVehicleReduceGrip(vehicle, road.ice > 0.3 or road.wetness > 0.6)
            end
        end
    end
end)

-- server, in a news or radio resource
local olink = exports['o-link']:olink()

RegisterCommand('weatherreport', function(source)
    local report = olink.weather.GenerateWeazelReport(nil, { unit = 'C' })
    if not report then
        olink.notify.Send(source, 'The weather desk is offline.', 'error')
        return
    end
    TriggerClientEvent('chat:addMessage', -1, {
        color = { 200, 200, 255 },
        multiline = true,
        args = { 'Weazel News', report.text },
    })
end, false)

-- client
local weatherResource = exports['o-link']:olink().weather

local function BeginCutscene()
    weatherResource.ToggleSync(false)     -- oxide-weather stops touching the sky
    SetWeatherTypeNowPersist('EXTRASUNNY')
    NetworkOverrideClockTime(6, 0, 0)
end

local function EndCutscene()
    weatherResource.ToggleSync(true)      -- normal weather resumes immediately
end

-- server, from a resource listed in Config.SetterResources
exports['oxide-weather']:SetSceneLock('global', 300, nil)
-- ...run the scene...
exports['oxide-weather']:ClearSceneLock('global', nil)

-- server
AddEventHandler('olink:server:weather:alertsChanged', function(alerts)
    for _, alert in ipairs(alerts) do
        if alert.severity == 3 and alert.status == 'active' then
            print(('Severe weather in %s: %s'):format(alert.region, alert.title))
        end
    end
end)