Exports & Events

Hz-Weather Pro exposes 50+ exports and numerous events for developers to integrate weather data into their scripts.

Server Exports

All server exports are called via exports['HZ-Weather']:functionName(...).

Core

Weather & Zones

Forecast

Seasons

Temperature

Wind

Database

Bridge

Client Exports

All client exports are called via exports['HZ-Weather']:functionName(...).

Weather & Effects

Zones

Seasons

Temperature

Wind

Admin Panel

Events (Server)

Admin Events

Triggered by the admin panel (client -> server). All require the hz_weather.admin ACE permission.

Disaster Events

Forecast Events

Callbacks (lib.callback)

Sync Events

Events (Client)

Sync Events (Server -> Client)

Disaster Events (Server -> Client)

Tornado

Tsunami

Admin Panel Events (Server -> Client)

Internal Events

These are fired locally (same side) and can be listened to with AddEventHandler.

Client-Side

Server-Side

GlobalState Keys

Accessible from both client and server via GlobalState.key.

Admin Commands

Server Commands

All require hz_weather.admin ACE permission.

Client Commands

Compatibility Layer

Hz-Weather provides full backward compatibility for these resources. Scripts using their exports will work without any changes.

qb-weathersync

-- Server exports
exports['qb-weathersync']:setWeather('CLEAR')
exports['qb-weathersync']:setTime(12, 0)
exports['qb-weathersync']:setBlackout(true)
exports['qb-weathersync']:setTimeFreeze(true)
exports['qb-weathersync']:getBlackoutState()
exports['qb-weathersync']:getTimeFreezeState()
exports['qb-weathersync']:getWeatherState()
exports['qb-weathersync']:getTime()

-- Server events
TriggerServerEvent('qb-weathersync:server:setWeather', 'CLEAR')
TriggerServerEvent('qb-weathersync:server:setTime', 12, 0)
TriggerServerEvent('qb-weathersync:server:setBlackout', true)

-- Client events
RegisterNetEvent('qb-weathersync:client:DisableSync')
RegisterNetEvent('qb-weathersync:client:EnableSync')

cd\_easytime

-- Server exports
local data = exports['cd_easytime']:GetWeather()
-- Returns: { weather = 'CLEAR', blackout = false, freeze = false }

-- Client events
RegisterNetEvent('cd_easytime:PauseSync')

Integration Examples

Get weather for a zone (server)

local weather = exports['HZ-Weather']:getZoneWeather('Sandy Shores')
print('Sandy Shores weather:', weather) -- "EXTRASUNNY"

React to zone changes (client)

AddEventHandler('hz_weather:zoneChanged', function(oldZone, newZone)
    print('Entered zone:', newZone, 'from', oldZone)
end)

Get formatted temperature (client)

local tempStr = exports['HZ-Weather']:getTemperatureString('C')
print('Current temperature:', tempStr) -- "23°C"

Check player zone and temperature (server)

local zoneName = exports['HZ-Weather']:getPlayerZone(source)
local temp = exports['HZ-Weather']:getTemperature(zoneName or 'global')
TriggerClientEvent('chat:addMessage', source, {
    args = { 'Weather', 'Temperature: ' .. temp .. '°C' }
})

Special weather for a heist (server)

RegisterCommand('startHeist', function(source)
    exports['HZ-Weather']:setZoneWeather('Los Santos', 'FOGGY')
    -- Restore after 30 minutes
    SetTimeout(30  60  1000, function()
        exports['HZ-Weather']:setZoneWeather('Los Santos', 'CLEAR')
    end)
end, true)

Check if tornado is active (client)

local tornado = GlobalState.tornado
if tornado and tornado.phase == 'ACTIVE' then
    print('Tornado at', tornado.x, tornado.y, 'intensity:', tornado.intensity)
end

Listen for season changes (server)

AddEventHandler('hz_weather:seasonChanged', function(oldSeason, newSeason)
    print('Season changed:', oldSeason, '->', newSeason)
    -- Add snow decorations, seasonal items, etc.
end)

Embeddable Weather Map (iframe)

Hz-Weather Pro includes a standalone weather map page that can be embedded in any phone resource or NUI via iframe.

URL

https://cfx-nui-HZ-Weather/web/dist/map.html

What it displays

• GTA V satellite map (tile-based, pan + zoom)
• Weather emoji + zone name + temperature at each zone center
• Global weather, season, wind info
• Auto-refreshes every 30 seconds

Embed in any phone (HTML)

<iframe
  src="https://cfx-nui-HZ-Weather/web/dist/map.html"
  style="width:100%;height:100%;border:none"
  sandbox="allow-same-origin allow-scripts"
/>

Embed in React

<iframe
  src="https://cfx-nui-HZ-Weather/web/dist/map.html"
  style={{ width: '100%', height: '100%', border: 'none' }}
  sandbox="allow-same-origin allow-scripts"
/>

How it works

1. The parent page fetches weather data via NUI callback or lib.callback
2. The parent sends data to the iframe via postMessage({ type: 'hz-weather-data', payload: data })
3. map.html listens for message events and renders markers on the satellite map
4. On load, the iframe requests data from its parent via postMessage({ type: 'hz-weather-request' })

NUI Callback: getMapData

Returns JSON:

{
  "globalWeather": "CLEAR",
  "globalTemperature": 22.5,
  "season": {
    "name": "summer",
    "icon": "...",
    "label": { "en": "Summer", "fr": "Ete" }
  },
  "wind": { "speed": 15.2, "direction": 180 },
  "locale": "en",
  "temperatureUnit": "C",
  "zones": [
    {
      "name": "los_santos",
      "label": { "en": "Los Santos" },
      "center": { "x": 200, "y": -1000 },
      "weather": "CLEAR",
      "temperature": 22.5,
      "isActive": true
    }
  ]
}

Build Your Own Weather App (Phone Integration)

You can create a weather app inside any phone resource (lb-phone, qs-phone, etc.) using HZ-Weather's callback and events.

Architecture

┌─────────────┐  NUI callback  ┌─────────────┐  lib.callback  ┌────────────┐
│  Your Phone │ ──────────────► │ Your Phone  │ ──────────────► │ HZ-Weather │
│    (UI)     │ ◄────────────── │  (Client)   │ ◄────────────── │  (Server)  │
└─────────────┘  JSON response  └──────┬──────┘  JSON string    └────────────┘
                                       │
                                       │  hz_weather:zoneChanged (local event)
                                       │
                                ┌──────┴──────┐
                                │ HZ-Weather  │
                                │  (Client)   │
                                └─────────────┘

Client-side Lua (one file)

-- client/weather.lua in your phone resource

RegisterNUICallback('getWeatherData', function(_, cb)
    lib.callback('hz-weather:getMapData', false, function(jsonStr)
        if type(jsonStr) == 'string' then
            local data = json.decode(jsonStr)
            if data then
                local ok, zone = pcall(exports['HZ-Weather'].getCurrentZone, exports['HZ-Weather'])
                data.currentZone = ok and zone or nil
            end
            cb(data or { error = 'no_data' })
        else
            cb({ error = 'no_data' })
        end
    end)
end)

AddEventHandler('hz_weather:zoneChanged', function(oldZone, newZone)
    SendNUIMessage({ type = 'weather-zone-update', currentZone = newZone })
end)

UI-side (JavaScript)

async function fetchWeather() {
  const resp = await fetch('https://cfx-nui-YOUR_RESOURCE/getWeatherData', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({})
  });
  return resp.json();
}

// Listen for real-time zone changes
window.addEventListener('message', (e) => {
  if (e.data.type === 'weather-zone-update') {
    const newZone = e.data.currentZone;
    // Update your UI
  }
});

Weather type icons

const WEATHER_ICONS = {
  EXTRASUNNY: '☀️', CLEAR: '🌤️', CLOUDS: '⛅',
  OVERCAST: '☁️', RAIN: '🌧️', THUNDER: '⛈️',
  CLEARING: '🌥️', FOGGY: '🌫️', SMOG: '🌫️',
  SNOW: '❄️', SNOWLIGHT: '🌨️', BLIZZARD: '🌬️', XMAS: '🎄'
};