ai-weathersync para desenvolvedores
Os exports do servidor do ai-weathersync (o contrato do qb-weathersync) e as chaves de GlobalState que ele publica.
Seus próprios scripts não devem chamar o ai-weathersync diretamente. Use a camada de hora e clima do AI Core no lugar: o world da lib em TypeScript (world.setWeather, world.setTime...) ou aiLib.world em Lua, documentados na referência da lib. Essa camada funciona com qualquer script de clima que o servidor rode, então o dono pode substituir o ai-weathersync sem quebrar seu script. Os exports abaixo são para scripts escritos para o qb-weathersync e para casos especiais.
Exports
Todo export é do lado do servidor e responde com dois nomes: exports['ai-weathersync'] e exports['qb-weathersync'] (o ai-weathersync faz provide de qb-weathersync). Nenhum deles espera. Eles não são tipados em @aicore-fivem/shared; a partir do TypeScript chame-os com o callExport("ai-weathersync", name, ...args) da lib.
As mudanças feitas por setBlackout, setTimeFreeze e setDynamicWeather duram até o dono mudar aquela configuração do painel ou o recurso reiniciar.
setWeather
Muda o clima do mundo na hora. Não mexe nas regiões de clima.
Lado: Servidor · Espera: não
setWeather(type: string): booleanlocal ok = exports['ai-weathersync']:setWeather('RAIN')Parâmetros
Prop
Type
Retorno
boolean: true quando o clima mudou. false quando type não é um nome de clima conhecido.
Exemplo
import { callExport } from "@aicore-fivem/lib/server";
// Uma tempestade para um evento; o ciclo de clima do painel continua a partir daqui.
const ok = callExport("ai-weathersync", "setWeather", "THUNDER") === true;
if (!ok) console.log("unknown weather");Com Changing weather ligado, a próxima mudança ainda vem no timer do painel, a partir da posição do novo clima na lista (ou da primeira entrada quando o novo clima não está na lista).
setTime
Acerta o relógio do mundo. O relógio continua andando na velocidade do painel a partir da nova hora.
Lado: Servidor · Espera: não
setTime(hour: number, minute?: number): booleanlocal ok = exports['ai-weathersync']:setTime(22, 30)Parâmetros
Prop
Type
Retorno
boolean: true quando o relógio foi acertado. false quando hour não é um número.
Exemplo
import { callExport } from "@aicore-fivem/lib/server";
callExport("ai-weathersync", "setTime", 22, 30);setBlackout
Liga ou desliga o apagão: as luzes da cidade se apagam, as luzes dos veículos continuam.
Lado: Servidor · Espera: não
setBlackout(on: boolean): booleanexports['ai-weathersync']:setBlackout(true)Parâmetros
Prop
Type
Retorno
boolean: sempre true.
setTimeFreeze
Para ou inicia o relógio na hora atual.
Lado: Servidor · Espera: não
setTimeFreeze(on: boolean): booleanexports['ai-weathersync']:setTimeFreeze(true)Parâmetros
Prop
Type
Retorno
boolean: sempre true.
setDynamicWeather
Liga ou desliga as mudanças automáticas de clima.
Lado: Servidor · Espera: não
setDynamicWeather(on: boolean): booleanexports['ai-weathersync']:setDynamicWeather(false)Parâmetros
Prop
Type
Retorno
boolean: sempre true.
nextWeatherStage
Passa o clima do mundo para a próxima entrada da lista do painel na hora (de volta à primeira depois da última).
Lado: Servidor · Espera: não
nextWeatherStage(): booleanexports['ai-weathersync']:nextWeatherStage()Retorno
boolean: sempre true.
Getters
Cada um lê o estado atual e não espera.
| Export | Retorno |
|---|---|
getWeatherState(): string | O nome do clima atual do mundo, por exemplo "CLEAR". As regiões não estão incluídas. |
getTime(): { hour: number, minute: number } | A hora atual do jogo. Em Lua, uma tabela com hour e minute. |
getBlackoutState(): boolean | Se o apagão está ligado (o valor do export, senão o do painel). |
getTimeFreezeState(): boolean | Se o relógio está parado. |
getDynamicWeather(): boolean | Se o clima muda sozinho. |
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 uma tabela ({ hour, minute }), enquanto o qb-weathersync original responde dois valores (hour, minute). Um script Lua escrito para o qb-weathersync que faz local h, m = exports['qb-weathersync']:getTime() recebe a tabela em h. O próprio export GetTime do AI Core e o world.getTime() da lib leem os dois formatos e sempre respondem { hour, minute }.
Chaves de GlobalState
O ai-weathersync publica seu estado como GlobalState, escrito pelo servidor só quando algo muda. Leia-as; nunca as escreva.
| Chave | Valor | Quando muda |
|---|---|---|
ai:clock | { base: number, at: number, scale: number, frozen: boolean }: o minuto do jogo no dia (base, 0-1439) no horário do servidor at (ms, Date.now()), avançando scale minutos de jogo por minuto real, ou parado enquanto frozen. | Mudança no painel, setTime, setTimeFreeze. |
ai:weather | { type: string, blackout: boolean }: o clima e o apagão do mundo. | Toda mudança de clima e setBlackout. |
ai:rweather:<regionId> | string: o clima atual de uma região. Removida quando a região é apagada. | No timer próprio da região. |
A hora não é enviada a cada minuto: cada cliente a calcula a partir de ai:clock e do próprio relógio (com uma diferença tirada uma vez do servidor).
Eventos
O ai-weathersync não tem eventos para outros scripts. Para pausar a sincronização em um cliente (um interior, uma cutscene), use os exports de cliente PauseWorldSync / ResumeWorldSync do AI Core ou o world.pauseSync(reason) / resumeSync(reason) da lib (veja os exports do cliente do ai-core). O ai-weathersync escuta só a pausa do AI Core.