ai-weathersync para desarrolladores
Los exports de servidor de ai-weathersync (el contrato de qb-weathersync) y las claves de GlobalState que publica.
Tus propios scripts no deberían llamar directamente a ai-weathersync. Usa en su lugar la capa de hora y clima de AI Core: world de la lib en TypeScript (world.setWeather, world.setTime...) o aiLib.world en Lua, documentados en la referencia de la lib. Esa capa funciona con el script de clima que use el servidor, así que el dueño puede reemplazar ai-weathersync sin romper tu script. Los exports de abajo son para scripts escritos para qb-weathersync y para casos especiales.
Exports
Cada export es de servidor y responde bajo dos nombres: exports['ai-weathersync'] y exports['qb-weathersync'] (ai-weathersync hace provide de qb-weathersync). Ninguno espera. No están tipados en @aicore-fivem/shared; desde TypeScript llámalos con callExport("ai-weathersync", name, ...args) de la lib.
Los cambios hechos con setBlackout, setTimeFreeze y setDynamicWeather duran hasta que el dueño cambia ese ajuste del panel o se reinicia el recurso.
setWeather
Cambia al momento el clima del mundo. No toca las regiones de clima.
Lado: Servidor · Espera: no
setWeather(type: string): booleanlocal ok = exports['ai-weathersync']:setWeather('RAIN')Parámetros
Prop
Type
Devuelve
boolean: true cuando el clima cambió. false cuando type no es un nombre de clima conocido.
Ejemplo
import { callExport } from "@aicore-fivem/lib/server";
// Una tormenta para un evento; el ciclo de clima del panel continúa desde aquí.
const ok = callExport("ai-weathersync", "setWeather", "THUNDER") === true;
if (!ok) console.log("unknown weather");Con Changing weather activado, el siguiente cambio sigue llegando con el temporizador del panel, desde la posición del nuevo clima en la lista (o la primera entrada cuando el nuevo clima no está en la lista).
setTime
Fija el reloj del mundo. El reloj sigue avanzando a la velocidad del panel desde la nueva hora.
Lado: Servidor · Espera: no
setTime(hour: number, minute?: number): booleanlocal ok = exports['ai-weathersync']:setTime(22, 30)Parámetros
Prop
Type
Devuelve
boolean: true cuando se fijó el reloj. false cuando hour no es un número.
Ejemplo
import { callExport } from "@aicore-fivem/lib/server";
callExport("ai-weathersync", "setTime", 22, 30);setBlackout
Activa o desactiva el apagón: las luces de la ciudad se apagan, las de los vehículos se quedan.
Lado: Servidor · Espera: no
setBlackout(on: boolean): booleanexports['ai-weathersync']:setBlackout(true)Parámetros
Prop
Type
Devuelve
boolean: siempre true.
setTimeFreeze
Detiene o pone en marcha el reloj en la hora actual.
Lado: Servidor · Espera: no
setTimeFreeze(on: boolean): booleanexports['ai-weathersync']:setTimeFreeze(true)Parámetros
Prop
Type
Devuelve
boolean: siempre true.
setDynamicWeather
Activa o desactiva los cambios automáticos de clima.
Lado: Servidor · Espera: no
setDynamicWeather(on: boolean): booleanexports['ai-weathersync']:setDynamicWeather(false)Parámetros
Prop
Type
Devuelve
boolean: siempre true.
nextWeatherStage
Pasa al momento el clima del mundo a la siguiente entrada de la lista del panel (vuelve a la primera después de la última).
Lado: Servidor · Espera: no
nextWeatherStage(): booleanexports['ai-weathersync']:nextWeatherStage()Devuelve
boolean: siempre true.
Getters
Cada uno lee el estado actual y no espera.
| Export | Devuelve |
|---|---|
getWeatherState(): string | El nombre del clima actual del mundo, por ejemplo "CLEAR". Las regiones no se incluyen. |
getTime(): { hour: number, minute: number } | La hora actual del juego. En Lua, una tabla con hour y minute. |
getBlackoutState(): boolean | Si el apagón está activado (el valor del export, si no el del panel). |
getTimeFreezeState(): boolean | Si el reloj está detenido. |
getDynamicWeather(): boolean | Si el clima cambia solo. |
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 responde una tabla ({ hour, minute }), mientras que el qb-weathersync original responde dos valores (hour, minute). Un script Lua escrito para qb-weathersync que hace local h, m = exports['qb-weathersync']:getTime() recibe la tabla en h. El export propio GetTime de AI Core y world.getTime() de la lib leen las dos formas y siempre responden { hour, minute }.
Claves de GlobalState
ai-weathersync publica su estado como GlobalState, que el servidor solo escribe cuando algo cambia. Léelas; nunca las escribas.
| Clave | Valor | Cuándo cambia |
|---|---|---|
ai:clock | { base: number, at: number, scale: number, frozen: boolean }: el minuto de juego del día (base, 0-1439) en la hora del servidor at (ms, Date.now()), avanzando scale minutos de juego por minuto real, o detenido mientras frozen. | Cambio en el panel, setTime, setTimeFreeze. |
ai:weather | { type: string, blackout: boolean }: el clima y el apagón del mundo. | Cada cambio de clima y setBlackout. |
ai:rweather:<regionId> | string: el clima actual de una región. Se quita cuando se borra la región. | Con el temporizador propio de la región. |
La hora no se envía cada minuto: cada cliente la calcula a partir de ai:clock y su propio reloj (el desfase se toma una vez del servidor).
Eventos
ai-weathersync no tiene eventos para otros scripts. Para pausar la sincronización en un cliente (un interior, una cinemática), usa los exports de cliente PauseWorldSync / ResumeWorldSync de AI Core o world.pauseSync(reason) / resumeSync(reason) de la lib (mira los exports de cliente de ai-core). ai-weathersync solo escucha la pausa de AI Core.