Installation

Requirements

Dependency	Minimum Version	Link	Cost
HZ-Bridge	v1.0.0+	Hz-Scripts shop	Free
ox\_lib	v3.0.0+	overextended/ox\_lib	Free
oxmysql	v2.0.0+	overextended/oxmysql	Free
PolyZone	latest	mkafrin/PolyZone	Free

HZ-Bridge is a free shared dependency used by all Hz-Scripts. Install it once — if you already have it from another Hz-Script, no need to download it again (just keep it updated).

Hz-Weather Pro is standalone — it works with QBCore, ESX, QBX, or no framework at all. Framework detection is handled by HZ-Bridge automatically.

Step 1 — Download

After your purchase on Tebex, download the script from your FiveM Keymaster:

Log in to keymaster.fivem.net
Go to Granted Assets
Download HZ-Weather

Important: Use the same FiveM account that is linked to your Tebex license. The script is escrow-protected and requires a valid license.

Step 2 — Files

Extract the archive
Place the HZ-Weather folder in your resources directory

server/
├── resources/
│   ├── [standalone]/
│   │   ├── HZ-Weather/
│   │   │   ├── client/
│   │   │   ├── server/
│   │   │   ├── classes/
│   │   │   ├── config/
│   │   │   │   ├── config.lua
│   │   │   │   ├── seasons.lua
│   │   │   │   ├── weather_types.lua
│   │   │   │   ├── zones.lua
│   │   │   │   └── locales/
│   │   │   │       ├── en.lua
│   │   │   │       └── fr.lua
│   │   │   ├── compatibility/
│   │   │   ├── web/
│   │   │   │   └── dist/
│   │   │   ├── sql/
│   │   │   │   └── install.sql
│   │   │   └── fxmanifest.lua

The folder name must be HZ-Weather (case-sensitive on Linux servers).

Step 3 — Database

Hz-Weather uses oxmysql and creates its tables automatically on first start. No manual SQL import is required.

Tables created automatically:

Table	Purpose
`hz_weather_config`	Persistent config overrides
`hz_weather_zones`	Weather zone definitions
`hz_weather_seasons`	Season cycle state
`hz_weather_history`	Weather history log (analytics)
`hz_weather_blackout`	Blackout state

If you prefer to create the tables manually, you can import sql/install.sql — but this is optional.

Step 4 — server.cfg

Add the script to your server.cfg after your framework and dependencies:

# Dependencies (required)
ensure ox_lib
ensure oxmysql
ensure PolyZone

Framework (optional — one of these)
ensure qb-core
ensure es_extended

HZ-Bridge (before all Hz-Scripts)
ensure HZ-Bridge

Hz-Weather Pro
ensure HZ-Weather

Startup order is important! HZ-Bridge must start after your framework but before HZ-Weather. The full order is: Framework → Dependencies → HZ-Bridge → HZ-Weather.

Step 5 — Admin Permission

Hz-Weather uses an ACE permission for admin access. Add this to your server.cfg:

add_ace group.admin hz_weather.admin allow

Or grant it to a specific player:

add_ace identifier.license:xxxxxxxx hz_weather.admin allow

The permission name is configurable in config/config.lua:

Config.AdminPermission = 'hz_weather.admin'

Step 6 — Configuration

Edit the files in config/ to match your server:

File	Purpose
`config/config.lua`	Main configuration (weather, time, effects, disasters)
`config/seasons.lua`	Season cycle presets and durations
`config/zones.lua`	Default weather zone definitions
`config/locales/en.lua`	English translations
`config/locales/fr.lua`	French translations

See the Configuration page for a full breakdown of every option.

Step 7 — Compatibility

Hz-Weather replaces these resources automatically via the provide directive in fxmanifest.lua:

qb-weathersync (QBCore weather sync)
cd_easytime (CD Easy Time)

You can safely remove or stop those resources — HZ-Weather exposes the same exports and events for full backward compatibility.

vSync Compatibility

HZ-Weather includes a vSync compatibility layer that intercepts vSync:toggle, vSync:updateWeather, and vSync:requestSync events. This means scripts that depend on vSync (garages, interiors, etc.) work automatically without any code changes.

For example, garages that force CLEAR weather inside and call vSync:requestSync on exit will properly re-sync with HZ-Weather's zone weather.

Disable all other weather scripts before using Hz-Weather Pro. Having two weather scripts running will cause visual conflicts. Scripts to stop: vSync, qb-weathersync, cd_easytime, esx_weather, etc.

Step 8 — Verify

Start (or restart) your server
Connect in-game
Open the admin panel
Check the server console for:

[Hz-Weather Pro] v1.0.0 initialized — Framework: standalone
[Hz-Weather Pro] Database ready — X zones loaded

You're done! If the admin panel opens and the console shows no errors, the script is ready. Head to Configuration to customize everything.

Updating

Back up your config/ folder
Replace all files except config/
Restart the resource: ensure HZ-Weather

Your database config overrides are preserved automatically across updates.

Troubleshooting

The script won't start

Verify that:

The folder is named exactly HZ-Weather
The script is listed in your server.cfg with ensure
Your FiveM license is valid on Keymaster
HZ-Bridge is started before HZ-Weather
Dependencies (ox_lib, oxmysql, PolyZone) start before the script

Error "Framework not detected"

Framework detection is handled by HZ-Bridge. Make sure:

HZ-Bridge is ensured before HZ-Weather
Your framework (es_extended, qb-core, qbx_core) is ensured before HZ-Bridge
The resource names match exactly (case-sensitive)
If no framework is present, the script runs in standalone mode — this is expected
See HZ-Bridge Configuration if auto-detection picks the wrong framework

Admin panel doesn't open

Verify you have the ACE permission: hz_weather.admin
Check for conflicting resources using the same keybind
Try restarting the resource: ensure HZ-Weather

Weather doesn't change

Ensure Config.DynamicWeather = true
Ensure Config.FreezeWeather = false
Check if another weather resource is still running

Zones not loading

Ensure PolyZone is started before HZ-Weather
Check the server console for database errors
Verify oxmysql is running and your database connection works

Tornado / Tsunami commands not working

Ensure Config.Tornado.Enabled = true and Config.Tsunami.Enabled = true in config
You need the admin ACE permission
Use /tornado start or /tsunami start

Can't find your answer? Join our Discord and open a ticket!