Phone Weather Apps

Hz-Weather Pro has dedicated weather apps for LB Phone and QS Smartphone. Both apps display the same features — install the one matching your phone system.

Features

• Current weather — condition, temperature, wind speed & direction
• Interactive satellite map — zoom/pan with zone markers and live weather overlay
• Hourly forecast — scrollable forecast per zone
• Sun tracker — animated sunrise/sunset arc synced with game time
• Dynamic backgrounds — animated weather-based backgrounds (rain, snow, sun, clouds, thunder)
• Season display — current season with icon
• Wind card — speed, direction, and compass display
• Zone list — all weather zones with current conditions, clickable to view details
• Current zone indicator — shows which zone the player is currently in
• Real-time updates — auto-refreshes every 30s + instant updates on zone/temperature/season changes

Requirements

Both apps require HZ-Weather to be running on your server.

LB Phone App

QS Smartphone V3 App

Installation

LB Phone

1. Download lb-hzweather from your Keymaster
2. Place it in your server's resources/ folder
3. Add to your server.cfg:

ensure ox_lib
ensure HZ-Weather
ensure lb-phone
ensure lb-hzweather

1. Restart your server — the app appears automatically in the LB Phone app list (pre-installed by default).

QS Smartphone V3

1. Download qs-hzweather v2.0.0+ from your Keymaster
2. Place it in your server's resources/ folder
3. Disable the native Weather app. QS Smartphone V3 keeps built-in apps (phoneApplications) and custom apps (customApps) in two separate routing tables — registering a custom app with id = 'weather' does not override the native (the native always wins). Edit qs-smartphone/config/main.lua (around line 1578) and comment out the native weather entry:

Config.PhoneApplications = {
    -- { id = 'weather', label = 'Weather', icon = 'weather.webp', category = 'Information & Reading' }, -- disabled: replaced by qs-hzweather
    { id = 'calendar',   label = 'Calendar',    icon = 'calendar.webp',   category = 'Productivity & Finance' },
    -- ...
}

Leave firstPageItems = { 'weather', 'calendar' } untouched — our custom app registers under id = 'weather' so the home-screen slot is filled by our iframe.

1. Add to your server.cfg:

ensure ox_lib
ensure HZ-Weather
ensure qs-smartphone
ensure qs-hzweather

1. Restart your server. Open the phone → the Weather icon now opens our iframe.

TRUNCATE TABLE phone_metadata;
TRUNCATE TABLE phone_app_store;

QS Smartphone V2 (Pro) — legacy

For servers still running QS Smartphone Pro (V2, resource name qs-smartphone-pro), use qs-hzweather v1.x:

1. Download qs-hzweather v1.x from your Keymaster (older releases tab)
2. Place it in your server's resources/ folder
3. Add to your server.cfg:

ensure ox_lib
ensure HZ-Weather
ensure qs-smartphone-pro
ensure qs-hzweather

1. Restart your server — no config edit needed. V2 supports same-id override natively, so the app replaces the native Weather automatically.

Configuration

LB Phone

Edit config.lua in the lb-hzweather resource:

Config.Identifier = "hz-weather"    -- Unique app ID (do not change if already deployed)
Config.DefaultApp = true            -- true = pre-installed, false = downloadable from app store
Config.Name = "Weather"             -- App name shown in phone
Config.Description = "Real-time weather forecast powered by HZ-Weather"
Config.Developer = "HZ Development" -- Developer name in app store

QS Smartphone V3

No configuration file in qs-hzweather itself — registration is hardcoded for the weather id. The only edit required is the one-line comment-out in qs-smartphone/config/main.lua documented in step 3 of the install section.

How It Works

Both apps use the same data flow:

Phone UI (React) → NUI Callback → lib.callback → HZ-Weather Server → Response

The app calls lib.callback('hz-weather:getMapData') to fetch all weather data (current weather, zones, forecast, temperatures, wind, season, game time, sunrise/sunset). No server-side Lua file is needed in the app resource — lib.callback handles the client-server round-trip via ox_lib.

Real-time updates are received via client events:

• hz_weather:zoneChanged — player changed zone


• hz_weather:syncTemperatures — temperature update


• hz_weather:syncSeason — season change

QS Smartphone V3 — Technical Details

The QS V3 app is registered as a custom app (iframe-based) that visually replaces the native Weather:

• App identifier: id = 'weather' — registered via addCustomApp({ id = 'weather', ... appStoreOnly = false ... }). V3 keeps phoneApplications (native) and customApps (third-party) in two separate tables; the native always wins routing, which is why disabling the native config entry is mandatory.
• Icon: Served from our resource — ui/build/icon.svg. The native weather.webp is no longer used since the native entry is disabled.
• Iframe URL: https://cfx-nui-qs-hzweather/ui/build/index.html — loaded by QS V3's custom-app iframe component. The iframe doesn't get a sandbox attribute, allows clipboard/camera/microphone.
• NUI rendering: The app runs inside V3's iframe slot. fetchNui() POSTs to https://qs-hzweather/... (same-origin to the iframe), hitting our RegisterNUICallback handlers. The body { visibility: hidden; display: none } CSS guard is undone explicitly in useEffect (V2 relied on qs-smartphone-pro sending an app-opened postMessage to flip it — V3 doesn't).
• Bridge SDK (optional): V3 exposes QSPhoneBridge at https://cfx-nui-qs-smartphone/web/build/bridge/qs-phone-bridge.js for theme detection, toast notifications, and event communication. qs-hzweather currently doesn't use it (30 s polling is enough); future versions may integrate it for instant push.
• Widget: The home-screen weather widget is built into QS Smartphone V3 and reads its data from GTA natives independently of HZ-Weather — qs-hzweather does not control it.

Development

LB Phone App

cd lb-hzweather/ui/
npm install
npm run dev      # Hot reload on localhost:3000

Switch to dev mode in fxmanifest.lua:

ui_page "http://localhost:3000/"
-- ui_page "ui/dist/index.html"

Build for production:

npm run build

QS Smartphone V3 App

cd qs-hzweather/ui/
npm install
npm run dev      # Hot reload on localhost:5173

Build for production:

npm run build

After rebuilding, restart qs-hzweather on the server so QS V3's iframe reloads the new bundle.

Troubleshooting

LB Phone

QS Smartphone V3

QS Smartphone V2 (Pro) — legacy