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
xsound	v1.0.0+	rcore-tech/xsound	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).

xsound is required since v1.3.0 for the tsunami's 3D coastal sirens. If you trigger a tsunami without xsound running, the event still works visually but the sirens are silent (no crash). Voice phases use a separate Web Audio NUI layer and don't depend on xsound.

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
ensure xsound          # tsunami sirens (v1.3.0+)

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 delegates the admin check to HZ-Bridge, which routes it to your framework's permission system. The default permission group is admin (configurable via Config.AdminPermission in config/config.lua).

How to grant it depends on your framework:

QBCore / QBX

Add the player to the admin group via the QBCore permission system. Two options:

Option A — server.cfg (principal):

add_principal identifier.license:xxxxxxxx qbcore.admin

Option B — database:

INSERT INTO permissions (license, permission)
VALUES ('license:xxxxxxxx', 'admin');

Then /refreshcommands in the server console (or restart QBCore).

ESX

The player must be in the admin or superadmin group:

UPDATE users SET group = 'admin' WHERE identifier = 'license:xxxxxxxx';

Then reconnect to the server.

Standalone (no framework)

Classic ACE in server.cfg:

add_ace group.admin admin allow
add_principal identifier.license:xxxxxxxx group.admin

Find your FiveM license

Connect to your server in-game
In the server console, type players
Copy the value after license: from the line listing your name

The default Config.AdminPermission = 'admin' is correct for most setups. Only change it if you've intentionally created a custom permission group (e.g. weather.admin) on your framework's side.

A Tebex purchase key (tbx-...) is not your FiveM license — it only proves ownership on Keymaster. Permissions are tied to your in-game license: identifier.

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 admin permission group (see Step 5) — this is routed through your framework, not a raw ACE node on QBCore / ESX.
On QBCore, make sure you ran /refreshcommands (or restarted the server) after adding the principal / DB row.
On ESX, reconnect after updating your group in the users table.
HZ-Bridge v1.1.1+ prints the exact two lines to copy-paste in the server console when the permission check fails — check your console output.
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!