FAQ

Hz-Weather Pro supports QBCore, ESX, QBX and Standalone mode. The framework is auto-detected at startup — no manual configuration needed.

Yes. Hz-Weather Pro is fully compatible with OneSync and OneSync Infinity. Weather synchronization uses GlobalState and state bags for optimal performance.

No. You must disable all other weather scripts before using Hz-Weather Pro. Having two active weather scripts will cause visual and synchronization conflicts.

Scripts to stop: vSync, qb-weathersync, cd_easytime, esx_weather, etc.

Hz-Weather Pro automatically replaces qb-weathersync and cd_easytime via the provide directive and exposes their exports for backward compatibility.

No. Hz-Weather Pro is optimized for minimal impact: 0.00 ms idle on client-side, ~0.08 ms during active events (tornado, tsunami). Server-side impact is negligible.

• ox_lib v3.0+
• oxmysql v2.0+
• PolyZone

Verify that:

1. The folder is named exactly HZ-Weather


2. The script is in your resources/ directory (e.g. resources/[standalone]/HZ-Weather/)


3. Your license is active on keymaster.fivem.net


4. You are using the same FiveM account linked to your Tebex purchase

This is normal if you're running standalone (no framework). The script will use standalone mode.

If you do have a framework, make sure es_extended or qb-core is ensured before HZ-Weather in your server.cfg.

Hz-Weather creates tables automatically on first start. If this fails:

1. Verify oxmysql is running and configured correctly


2. Check that your database user has CREATE TABLE permissions


3. As a fallback, manually import sql/install.sql

1. Download the latest version from Keymaster
2. Back up your config/ folder
3. Replace all files except config/
4. Check the Changelog for any new config parameters
5. Restart the resource: ensure HZ-Weather

1. Verify you have the ACE permission: hz_weather.admin

   add_ace group.admin hz_weather.admin allow

1. Check for conflicting resources using the same keybind
2. Try restarting the resource: ensure HZ-Weather

• Ensure the database is accessible (check oxmysql status)
• Check the F8 console for JavaScript errors
• Restart the resource to force a fresh data sync

Check these settings in config/config.lua:

• Config.DynamicWeather = true (must be enabled)


• Config.FreezeWeather = false (must not be frozen)


• Config.WeatherChangeInterval (default: 600 seconds = 10 minutes)

exports['HZ-Weather']:setZoneWeather('all', 'XMAS')
-- Or for a specific zone:
exports['HZ-Weather']:setZoneWeather('Mount Chiliad', 'XMAS')

In config/weather_types.lua, remove or disable the snow-related weather types (SNOW, SNOWLIGHT, BLIZZARD, XMAS).

Or in the season presets (config/seasons.lua), remove snow types from all weather sequences.

Increase Config.ZoneTransitionDistance in config/config.lua. The default is 800.0 meters. A higher value creates a larger blending area between zones.

You can also enable Config.WeatherInfluence.enabled = true so neighboring zones blend naturally.

1. Ensure PolyZone is started before HZ-Weather in server.cfg
2. Check the server console for database errors
3. Verify zones exist in the database (hz_weather_zones table)
4. Try creating a zone from the admin panel to test

exports['HZ-Weather']:createZone({
    name = 'my_zone',
    label = 'My Custom Zone',
    center = vector3(x, y, z),
    radius = 1500.0,
    shape = 'circle',
    priority = 1,
    weather = 'CLEAR',
})

Each season defines a weather sequence (e.g. Summer = EXTRASUNNY → CLEAR → CLOUDS → CLEARING) that cycles automatically. Seasons also control temperature ranges and wind profiles.

Three cycle modes are available:

• disabled — Manual control only (via admin panel or commands)


• auto — Rotates through 4 seasons on a timer (default: 120 minutes for full cycle)


• realtime — Maps real calendar months to seasons

1. Ensure Config.TemperatureEnabled = true
2. Check Config.TemperatureMode — 'hybrid' is recommended
3. Toggle display unit: Config.TemperatureUnit = 'C' or 'F'
4. Use /temp in chat to check the current temperature

Set Config.SyncRealWorldSeasons = true in config/config.lua. The script will map:

• December, January, February → Winter


• March, April, May → Spring


• June, July, August → Summer


• September, October, November → Autumn

1. Ensure disasters are enabled in config:

1. You need the hz_weather.admin ACE permission
2. Use the correct syntax: /tornado start, /tsunami start

Check the tornado physics settings in config/config.lua:

• Config.Tornado.ThrowVehicles = true


• Config.Tornado.ThrowPeds = true


• Config.Tornado.AffectPlayer = true

1. Verify the tsunami is in RISING phase (check /tsunami status)
2. Check Config.Tsunami.MaxWaterHeight — default is 200.0 meters
3. The warning phase lasts 30 seconds before water starts rising
4. Ensure no other script is modifying water levels

Vehicle traction is disabled by default. Enable it in config:

Config.Effects.vehicleTraction.enabled = true

Temperature notifications fire when you enter a Cold or Heat state. Since v1.1.5 two guards prevent notification spam when the temperature oscillates around a threshold:

1. 2 °C hysteresis — once in the Cold state (temp < coldThreshold), the temperature must rise to coldThreshold + 2 before you exit. Symmetric for Heat (heatThreshold − 2 to exit). Stops the overlay from flickering when the temperature hovers at the boundary.
2. 2-minute cooldown — even if hysteresis is somehow bypassed, the same notification can't re-fire within 120 s.

Thresholds:

• coldThreshold = 10 — below this = cold state activates


• heatThreshold = 30 — above this = heat state activates

Before v1.1.5 the cold / heat notification titles (Froid / Chaleur) were hardcoded strings and ignored Config.Locale. v1.1.5 added a client-side locale loader that reads config/locales/.lua on boot and localizes the titles to all 12 shipped languages (en / fr / es / de / it / ja / ko / pl / pt / ru / tr / zh).

If you updated to v1.1.5+ and the notification is still blank, either:

• Config.Locale is set to a locale file that doesn't exist → it falls back to en, you should see Cold / Heat


• You've customized the locale files and didn't add the two new keys cold_notif_title and heat_notif_title → add them with a translation for your target language

Each effect can be toggled individually in config/config.lua:

Config.Effects = {
    vehicleTraction = { enabled = false },
    reducedVisibility = { enabled = true },
    autoWipers = { enabled = true },
    autoLights = { enabled = false },
    playerEffects = { enabled = true },
    speedReduction = { enabled = false },
    ambientSounds = { enabled = true },
    syncedLightning = { enabled = true },
}

Yes! Dedicated weather apps are available for:

• LB Phone
• QS Smartphone (V3 + Pro V2)

• For QS Smartphone V3 (resource qs-smartphone) → use qs-hzweather v2.0.0+. Requires a one-line edit in qs-smartphone/config/main.lua to disable the native Weather entry (V3 doesn't allow same-id overrides). See Phone Weather Apps → QS Smartphone V3.
• For QS Smartphone Pro V2 (resource qs-smartphone-pro) → use qs-hzweather v1.x. Drop-in, no config edit. See legacy section.

QS Smartphone V2 (Pro) merged native + third-party apps into one routing table — registering a custom app under id = 'weather' cleanly replaced the native one.

QS Smartphone V3 uses two separate tables: phoneApplications (built-in apps, declared in qs-smartphone/config/main.lua) and customApps (registered at runtime via addCustomApp). The router consults phoneApplications first and the native always wins, regardless of whether a custom app with the same id exists. The V3 docs confirm this: built-in native ids cannot be removed via the API.

The fix is a one-line manual edit — comment out the native weather line in Config.PhoneApplications. Reversible. Fully documented in Phone Weather Apps → QS Smartphone V3.

If you prefer a simple iframe embed instead of the dedicated app, add this to your phone resource:

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

This works with any phone resource (lb-phone, qs-phone, HZ-Phone, etc.). See the Exports & Events page for full integration details.

You need one client Lua file in your phone resource to relay data from HZ-Weather, plus your UI code. No server file needed — lib.callback handles the round-trip.

Use the hz-weather:getMapData callback or the getForecast / getAllZoneForecasts exports to get weather data.

See the Phone Integration Guide for step-by-step instructions with code examples.

Yes. Hz-Weather Pro exposes all qb-weathersync exports and events via a compatibility layer. Scripts calling exports['qb-weathersync']:setWeather('CLEAR') will work without changes.

You can disable this layer with Config.EnableQBCompat = false if you don't need it.

Yes. Same as above — the cd_easytime compatibility layer is enabled by default. Disable with Config.EnableCDCompat = false.