Changelog

qs-hzweather v2.0.0 — QS Smartphone V3 Compatibility

> This release is for the qs-hzweather addon resource only — the core HZ-Weather server resource is unchanged. Follow the migration steps below if you upgraded QS Smartphone to V3.

Breaking

• Target phone changed: qs-smartphone-pro → qs-smartphone. QS Smartphone V3 ships under the resource name qs-smartphone (no -pro). qs-hzweather v2.0.0 depends on it. If you're still on V2 (Pro), stay on qs-hzweather v1.x — see the legacy V2 section.
• One-line manual edit required in qs-smartphone/config/main.lua. V3 keeps native apps (phoneApplications) and custom apps (customApps) in two separate routing tables — same-id registration does not override the native (the native always wins). To make our app the only Weather, comment out { id = 'weather', label = 'Weather', icon = 'weather.webp', category = 'Information & Reading' } in Config.PhoneApplications. Reversible by uncommenting. Full instructions in Phone Weather Apps.
• addCustomApp payload shape changed for V3. The old { app, image, ui, label, job, blockedJobs, timeout, ... } is replaced by { id, label, icon, category, creator, description, age, appStoreOnly, sizeMb, iframe = { url }, custom = { enabled, sourceResource, bridge = { enabled, allowedOrigins } } }. qs-hzweather v2.0.0 already uses the new shape — no action needed unless you forked the resource.

Bug Fixes

• Iframe rendering blank white screen on V3. The V1.x bundle relied on qs-smartphone-pro flipping the body's visibility / display via an app-opened postMessage. V3 doesn't send that signal, so the page-level CSS guard (body { visibility: hidden; display: none }) was never released. App.tsx now sets document.body.style.visibility = 'visible' and display = 'block' unconditionally in the mount effect (mirrors V3's phone-custom-react starter template).
• Robust registration: tries addCustomApp first, falls back to updateCustomApp('weather', payload) if the id is already taken. The fallback path is mostly future-proofing — current V3 behaviour is that the native and custom spaces are disjoint, so the manual config edit is still required.

Improvements

• fxmanifest.lua slimmed down: removed ui_page (V3 loads our UI as an iframe under our resource's cfx-nui- origin, no top-level NUI needed) and the legacy title/description were refreshed.
• Console error line now points at the troubleshooting doc when both registration paths fail: addCustomApp failed (X) and updateCustomApp failed (Y). Check INSTALL.md step 3 (disable native weather in qs-smartphone/config/main.lua).
• INSTALL.md in the resource folder now documents V3 only, with a clear "How the override works" section and a troubleshooting table.

Upgrade Notes

• If you're still on QS Smartphone Pro V2: do not install qs-hzweather v2.0.0 — stay on v1.x.
• If you're moving to V3:

v1.1.8 — Zone Editor Circle Support + Blackout Exceptions Fix

New Features

• Circle zones in the admin panel zone editor — the in-game editor (/hzpanel → Hz-Weather → Zones) was polygon-only. New + Circle button alongside + Polygon lets admins create circle zones directly: click the map to drop the center, drag the radius slider in the inspector (50–5000 m, live preview), set name / weather / colour, save. Existing config-defined circle zones (e.g. Cayo Perico) now also render on the editor canvas — they were invisible before because the canvas only drew shapes with an explicit points[] array.

Bug Fixes

• Cayo Perico circle drawn at the wrong size on the admin map — the previous render used which ignores Mercator stretch at high latitudes. Cayo sits at game Y ≈ -5150, projected lat ≈ -87°, where 1 m on Y is ~35× larger than 1 m on X in pixel space. The circle now renders as a true projected ellipse using local px-per-meter ratios on each axis, matching what the player sees in-world. Both the editor canvas and the read-only Map view use the same logic so they always agree.
• Config.BlackoutExceptions never worked — the shipped default values (Pillbox Hospital, Mission Row PD, Sandy Shores Sheriff, Paleto Bay Sheriff) are GTA-native zone labels, but the client check compares against the current HZ-Weather zone slug (vinewood, los_santos, ...). The two namespaces never matched, so no zone ever kept its lights during a blackout. The field is now a constrained multi-select picker (new enum-multi HZ-Bridge field type), choices are the 10 HZ-Weather zone slugs from config/zones.lua, default is empty.
• Polygon-only handles (vertex drag, edge-insert click, right-click delete, cursor preview line, "drop point #N" banner) used to render for circle drafts too — they're now properly gated so a circle draft only shows its center marker + outline.

Breaking — config migration

• Config.BlackoutExceptions defaults changed from { 'Pillbox Hospital', 'Mission Row PD', 'Sandy Shores Sheriff', 'Paleto Bay Sheriff' } (broken — silently no-op) to {} (empty). If you want LS or any region to stay lit during a blackout, re-tick the corresponding HZ-Weather zones in the admin panel (or set the values directly in config/config.lua). Available slugs: paleto, mont_josiah, sandy_shores, banham_canyon, vinewood_hills, vinewood, tataviam_mountains, palomino_highlands, los_santos, cayo_perico.
• Granularity is now region-wide (selecting los_santos keeps the whole city lit, not one building). If you need per-building exceptions, run a custom client-side override against GetNameOfZone().

Improvements

• Two new client NUI callbacks (upsertZone, deleteZone) forwarding to the existing server events. Required for the new circle creation / radius edit flow in the admin panel.
• When the admin clicks À ma position while in a circle draft, the player's current coords drop directly as the center, so the only remaining step is the radius slider.

Upgrade Notes

• If you previously relied on BlackoutExceptions to keep hospitals / PDs lit, the feature was a no-op — nothing to migrate, but you'll want to set up the new region-level exceptions if you actually use blackouts.
• If you add a DB-backed zone via the editor and want it as a blackout exception, also add its slug to the choices array in bridge_schema.lua (the panel won't auto-discover DB-created zones in the multi-select yet).
• Requires HZ-Bridge v1.1.0+ for the enum-multi field type to render correctly. Older HZ-Bridge versions will fall back to a generic string input but the field will save / load fine.

v1.1.5 — Temperature Hysteresis + Client-Side Locales

Bug Fixes

• Fixed cold/heat notification spam near the threshold — when the temperature oscillated around coldThreshold (e.g. 9 °C → 7 °C → 9 °C…), the notification re-fired on every flip and the colour overlay flashed. Replaced the simple on/off flag with a 2 °C hysteresis band + a 2-minute cooldown between notifications. Once the player enters the Cold state, the temperature must rise to coldThreshold + 2 before exiting. Symmetric for Heat.
• Fixed client-side strings being stuck in French regardless of Config.Locale — the cold / heat notification titles (Froid / Chaleur) were hardcoded. Added a lightweight client-side locale loader that reads config/locales/.lua at boot and exposes a global L(key, fallback) helper. Notification titles now localize correctly in all 12 shipped languages (en / fr / es / de / it / ja / ko / pl / pt / ru / tr / zh).

Improvements

• New client script client/locale.lua — loads the resource's own translation table on boot, falls back to English if the configured locale isn't found. Reusable by any other client-side string that needs localization
• 2 new locale keys added to every shipped language: cold_notif_title, heat_notif_title
• Config.Debug = true HUD overlay now exposes coldActive / heatActive (the sticky hysteresis state) instead of the old on-fire-once flags

Upgrade Notes

• Config untouched — no migration needed
• If you've translated the locale files yourself, add these 2 keys to your custom file so the notifications aren't blank

v1.1.4 — Forecast Sync & Phone App Fixes

New Features

• Forecast transition steps — When an admin overrides a zone's weather, the forecast now generates smooth intermediate steps instead of an instant jump (e.g. EXTRASUNNY → CLEAR → CLOUDS → OVERCAST → RAIN)
• Full vSync compatibility — Garages and scripts using vSync:requestSync / vSync:updateWeather now work out of the box
• Debug overlay — Enable Config.Debug = true to display an on-screen panel showing GTA actual weather vs HZ expected, sync status, zone, transition state, temperature

Bug Fixes

• Fixed weather snapping instantly when crossing zones — transitions are now smooth everywhere with 25s fade per step
• Fixed cold/heat notification spam — one notification per state change instead of repeating
• Fixed weather flash on season/admin weather change — smooth 15s transition only
• Fixed StateBag re-applying same weather causing desync with GTA engine
• Fixed admin zone weather change not updating in Forecast tab
• Fixed sunrise/sunset hardcoded to 6:00/20:00 — now synced from Config.NightTime
• Fixed sun arc not tracking game time during night hours
• Fixed QS Smartphone Pro weather app not opening (NUI iframe rendering + resource name resolution)
• Fixed phone weather app showing 0 locations on map and zone list (isActive nil handling)

Improvements

• Smooth zone-to-zone transitions with distance-based multi-step blending
• Added 400ms debounce to prevent ghost transitions when crossing zone gaps
• Forecast updates now sent only to admins (reduced bandwidth)
• Weather sync optimized for zone players (others use GlobalState automatically)
• QS Smartphone Pro app now overrides the native Weather app — same icon, same slot, no conflict

v1.1.0 — Phone Apps & Forecast System

New Features

• Phone Weather Apps — Dedicated weather apps for LB Phone and QS Smartphone Pro with interactive satellite map, animated backgrounds, hourly forecast, sun tracker, wind & season cards
• Forecast System — Real-time weather prediction engine exposed via exports and callbacks for phone apps, HUDs, and third-party resources
• Admin Forecast Panel — New tab to view, edit, insert, and remove upcoming weather entries with live countdown and timeline
• Admin weather changes from the map now update the forecast in real-time

Bug Fixes

• Fixed weather flashes caused by double sync (StateBag + individual event) during season weather changes
• Fixed SetWeatherTypePersist snapping weather instantly instead of smooth transition
• Fixed temperature notifications ("Chaleur" / "Froid") spamming every 20 seconds — now notifies once per threshold crossing
• Fixed forecast broadcast targeting all players instead of admins only
• Fixed season weather cycle overwriting admin changes at startup (3s init guard)

Improvements

• Season weather sync now only sends individual events to players inside zones (players outside use GlobalState automatically)
• Reduced unnecessary network traffic from forecast updates
• 12 locales supported (en, fr, es, de, it, pt, ru, pl, tr, ja, ko, zh)

v1.0.0 — Initial Release

• Dynamic weather engine with 13 weather types and smooth transitions
• Unlimited weather zones with seamless blending
• Season system with 4 presets and automatic cycling
• Per-zone dynamic temperature with day/night curves
• Natural disasters: Tornado and Tsunami
• Gameplay effects (traction, visibility, player effects, lightning, blackout)
• Wind system with dynamic gusts
• Time management with multiple modes
• Admin panel (React NUI) with 6 tabs
• In-game HUD
• 50+ exports for developers
• Embeddable weather map for phone integration
• Backward compatibility with qb-weathersync and cd\_easytime
• Multi-framework support (QBCore, ESX, QBX, Standalone)
• English and French localization