ai-weathersync for developers
ai-weathersync's server exports (the qb-weathersync contract) and the GlobalState keys it publishes.
Your own scripts should not call ai-weathersync directly. Use AI Core's time and weather layer instead: lib world in TypeScript (world.setWeather, world.setTime...) or aiLib.world in Lua, documented in the lib reference. That layer works with whichever weather script the server runs, so the owner can replace ai-weathersync without breaking your script. The exports below are for scripts written for qb-weathersync and for special cases.
Exports
Every export is server side and answers under two names: exports['ai-weathersync'] and exports['qb-weathersync'] (ai-weathersync provides qb-weathersync). None of them waits. They are not typed in @aicore-fivem/shared; from TypeScript call them with lib callExport("ai-weathersync", name, ...args).
Changes made through setBlackout, setTimeFreeze and setDynamicWeather last until the owner changes that panel setting or the resource restarts.
setWeather
Changes the world's weather at once. It does not touch weather regions.
Side: Server · Waits: no
setWeather(type: string): booleanlocal ok = exports['ai-weathersync']:setWeather('RAIN')Parameters
Prop
Type
Returns
boolean: true when the weather changed. false when type is not a known weather name.
Example
import { callExport } from "@aicore-fivem/lib/server";
// A storm for an event; the panel's weather cycle continues from here.
const ok = callExport("ai-weathersync", "setWeather", "THUNDER") === true;
if (!ok) console.log("unknown weather");With Changing weather on, the next change still comes on the panel's timer, from the position of the new weather in the list (or the first entry when the new weather is not in the list).
setTime
Sets the world clock. The clock keeps running at the panel's speed from the new time.
Side: Server · Waits: no
setTime(hour: number, minute?: number): booleanlocal ok = exports['ai-weathersync']:setTime(22, 30)Parameters
Prop
Type
Returns
boolean: true when the clock was set. false when hour is not a number.
Example
import { callExport } from "@aicore-fivem/lib/server";
callExport("ai-weathersync", "setTime", 22, 30);setBlackout
Turns the blackout on or off: city lights go out, vehicle lights stay.
Side: Server · Waits: no
setBlackout(on: boolean): booleanexports['ai-weathersync']:setBlackout(true)Parameters
Prop
Type
Returns
boolean: always true.
setTimeFreeze
Stops or starts the clock at the current time.
Side: Server · Waits: no
setTimeFreeze(on: boolean): booleanexports['ai-weathersync']:setTimeFreeze(true)Parameters
Prop
Type
Returns
boolean: always true.
setDynamicWeather
Turns the automatic weather changes on or off.
Side: Server · Waits: no
setDynamicWeather(on: boolean): booleanexports['ai-weathersync']:setDynamicWeather(false)Parameters
Prop
Type
Returns
boolean: always true.
nextWeatherStage
Moves the world's weather to the next entry of the panel's list at once (back to the first after the last).
Side: Server · Waits: no
nextWeatherStage(): booleanexports['ai-weathersync']:nextWeatherStage()Returns
boolean: always true.
Getters
Each one reads the current state and does not wait.
| Export | Returns |
|---|---|
getWeatherState(): string | The world's current weather name, for example "CLEAR". Regions are not included. |
getTime(): { hour: number, minute: number } | The current game time. In Lua a table with hour and minute. |
getBlackoutState(): boolean | Whether the blackout is on (the export's value, else the panel's). |
getTimeFreezeState(): boolean | Whether the clock is stopped. |
getDynamicWeather(): boolean | Whether the weather changes by itself. |
import { callExport } from "@aicore-fivem/lib/server";
const time = callExport("ai-weathersync", "getTime") as { hour: number; minute: number };
const weather = callExport("ai-weathersync", "getWeatherState") as string;
console.log(`It is ${time.hour}:${String(time.minute).padStart(2, "0")}, weather ${weather}`);getTime answers a table ({ hour, minute }), while the original qb-weathersync answers two values (hour, minute). A Lua script written for qb-weathersync that does local h, m = exports['qb-weathersync']:getTime() gets the table in h. AI Core's own GetTime export and lib world.getTime() read both shapes and always answer { hour, minute }.
GlobalState keys
ai-weathersync publishes its state as GlobalState, written by the server only when something changes. Read them; never write them.
| Key | Value | When it changes |
|---|---|---|
ai:clock | { base: number, at: number, scale: number, frozen: boolean }: the game minute of the day (base, 0-1439) at server time at (ms, Date.now()), advancing scale game minutes per real minute, or standing still while frozen. | Panel change, setTime, setTimeFreeze. |
ai:weather | { type: string, blackout: boolean }: the world's weather and blackout. | Every weather change and setBlackout. |
ai:rweather:<regionId> | string: the current weather of one region. Removed when the region is deleted. | On the region's own timer. |
The time is not sent every minute: each client works it out from ai:clock and its own clock (offset taken once from the server).
Events
ai-weathersync has no events for other scripts. To pause the sync on a client (an interior, a cutscene), use AI Core's PauseWorldSync / ResumeWorldSync client exports or lib world.pauseSync(reason) / resumeSync(reason) (see ai-core client exports). ai-weathersync listens only to AI Core's pause.