Documentación de Clima y hora del servidor

OV Clima

Control completo del clima y la hora del servidor, con panel en pantalla, clima por zonas del mapa, cielos especiales y una API para otros scripts.

Que hace

OV Clima sustituye a tu sincronizador de clima y hora (por ejemplo qb-weathersync, vSync o similares) por un sistema en el que el servidor manda y todos los jugadores ven lo mismo.

• Sincronización sin tráfico constante: el estado (clima, hora y banderas) se publica en GlobalState solo cuando cambia. Los jugadores que entran tarde lo leen al conectarse.
• Hora precisa: cada cliente compensa su latencia con el reloj del servidor y solo corrige su reloj si se desvía más de driftToleranceMin minutos de juego. Los saltos grandes de hora se mezclan suavemente.
• Hora gestionada o hora real: managed (velocidad configurable) o realtime (hora real con desfase sobre UTC).
• Clima automático guiado por un grafo de probabilidades (Config.Graph) y duraciones por clima (Config.Durations).
• Transiciones suaves entre climas, con nieve en el suelo y viento acordes al clima.
• Clima por zonas: 20 regiones del mapa (14 con nombre y 6 de relleno) con clima propio cada una.
• Cielos especiales: rojo, verde, azul y aurora.
• Efectos: apagón de luces artificiales y nieve en el suelo.
• Filtro de imagen cinematográfico configurable, que cada jugador puede desactivar para sí.
• Panel en pantalla (/climapanel) con mapa, selector de climas, control de hora, cielos, efectos y registro de cambios.
• Persistencia y auditoría: el estado se guarda en base de datos y cada cambio queda registrado (quién, qué y cuándo), con webhook de Discord opcional.
• API para otros scripts: exports de servidor y cliente, eventos y "sobrescrituras con dueño" para interiores, eventos y minijuegos. Incluye compatibilidad con los nombres de export de qb-weathersync.

Requisitos

Dependencias declaradas en el fxmanifest.lua:

• ox_lib
• oxmysql

No requiere qb-core ni ox_inventory. Usa Lua 5.4 (lua54 'yes') y una base de datos MySQL o MariaDB con oxmysql.

Importante: no debe haber otro sincronizador de clima y hora activo (qb-weathersync, vSync, cd_easytime, Renewed-Weathersync u otros). Si tu panel de administración tiene su propio sistema de clima, desactívalo.

Instalacion

1. Descarga el recurso desde el Portal de Cfx.re con la cuenta Cfx con la que lo compraste. Viene protegido con Asset Escrow de Cfx.re y solo funciona en servidores de tu cuenta.
2. Copia la carpeta ov_clima en la carpeta resources de tu servidor.
3. Detén y retira cualquier otro recurso que sincronice clima y hora.
4. Añade en server.cfg, después de ox_lib y oxmysql:

   ensure ox_lib
   ensure oxmysql
   ensure ov_clima

1. Concede los permisos ACE a tu equipo (ver "Comandos y permisos"), por ejemplo:

   add_ace group.admin ov_clima.admin allow

1. Base de datos: no hay archivo .sql. Las tablas ov_clima_state y ov_clima_audit se crean solas al arrancar.
2. Reinicia el servidor.

Protección y edición: según el fxmanifest.lua, quedan sin cifrar (escrow_ignore) shared/config.lua y toda la carpeta web/ (interfaz). El resto del código está cifrado. El recurso no lee convars del server.cfg.

Para que el filtro de imagen funcione, el recurso carga data/ov_filtros.xml como modificador de ciclo de color; no necesitas hacer nada más.

Configuracion

Se edita en shared/config.lua.

Comandos y permisos

Permisos ACE (prefijo configurable en Config.AcePrefix): ov_clima.admin (todo), o por separado ov_clima.view, ov_clima.weather, ov_clima.time, ov_clima.flags y ov_clima.sky.

/climapanel también está registrado como tecla (Ajustes > Teclas > FiveM > "Panel de clima y hora (Otra Vida)"), sin tecla asignada por defecto.

Climas disponibles: EXTRASUNNY, CLEAR, CLOUDS, OVERCAST, CLEARING, SMOG, FOGGY, RAIN, THUNDER, SNOWLIGHT, SNOW, BLIZZARD, XMAS, HALLOWEEN.

Exports del servidor (devuelven true, resultado o false, código_de_error):

GetApiVersion, GetState, GetWeather, GetTime, GetWeatherTypes, IsValidWeather, SetWeather(clima, {instant, transition, holdMinutes}), SetAutoWeather, SetTime(h, m, {instant}), SetTimeFrozen, SetTimeScale, SetBlackout, SetSnow, SetZoneWeather, ClearZones, GetZones, SetSky, SetFilter, GetFilter, RequestOverride, ReleaseOverride, ListOverrides.

Compatibilidad con qb-weathersync: setWeather, setTime, setTimeFreeze, setDynamicWeather, setBlackout y getWeatherState, y en el cliente los eventos qb-weathersync:client:DisableSync y EnableSync.

Sobrescrituras con dueño (RequestOverride): un script pide un clima, hora o bandera temporal con spec = { scope = 'global' | 'player', target, weather, transition, time = { hour, minute, frozen }, blackout, snow, priority, ttl }. Gana la de mayor prioridad; se limpian solas al terminar el ttl, al liberarlas o al detenerse el recurso que las pidió, y no alteran el estado base.

Eventos del servidor: ov_clima:weatherChanged, ov_clima:timeChanged, ov_clima:flagsChanged, ov_clima:zonesChanged. En el cliente: ov_clima:client:weatherChanged y ov_clima:client:regionChanged.

Exports del cliente: GetWeather, GetTime, PauseSync, ResumeSync (cada recurso tiene su propio pedido) e IsSyncPaused.

Como se usa

Jugadores: el clima y la hora se ven automáticamente. Con /filtro se activa o desactiva el filtro de imagen solo para uno mismo.

Equipo de administración:

1. Con el permiso adecuado, abre el panel con /climapanel.
2. Elige un clima y su transición, ajusta la hora con el control deslizante, congela la hora o cambia la velocidad del día.
3. Activa cielos especiales, apagón o nieve.
4. En el mapa, toca una zona y asígnale un clima propio; cada jugador verá el clima de la zona en la que está, y fuera de cualquier zona rige el global.
5. Los botones se bloquean si te falta el permiso correspondiente.

Para administradores

• Un clima puesto a mano se mantiene manualHoldMinutes minutos y después sigue el automático. Para fijarlo indefinidamente, pon ese valor a 0 o desactiva el automático con /climaauto off.
• En modo realtime la hora no se puede cambiar a mano; el comando devolverá un aviso.
• Las zonas y el estado se guardan en base de datos y sobreviven a los reinicios.
• Los límites de las zonas son aproximados: revísalos con el mapa del panel y ajusta Config.Regions.
• Los cielos usan modificadores de color incluidos en el juego (Config.Sky); si alguno no se encuentra, se prueba el siguiente candidato y se avisa en la consola del cliente (F8). Los cielos tiñen el ambiente pero no cambian el color de las estrellas.
• Para eventos, interiores o minijuegos, usa RequestOverride en lugar de cambiar el clima base.
• Para ver qué se cambió, consulta la tabla ov_clima_audit o el registro del panel.

Códigos de error de la API: invalid_weather, invalid_time, invalid_scale, invalid_mode, invalid_arg, invalid_scope, player_not_found, player_time_unsupported, not_found y realtime_mode.

Preguntas frecuentes

¿Es compatible con otros scripts de clima? No debe haber dos sincronizadores a la vez. OV Clima responde a los exports y eventos habituales de qb-weathersync, por lo que los scripts que los usan (por ejemplo casas o interiores) siguen funcionando.

¿Necesito qb-core? No. Solo necesita ox_lib y oxmysql.

¿Cómo hago que la hora siga la hora real? Cambia Config.Time.mode a 'realtime' y ajusta realtimeOffsetMinutes.

¿Cómo evito que llueva? Quita RAIN y THUNDER de los destinos en Config.Graph, o fija un clima a mano y desactiva el automático.

¿Cómo cambio la duración del día? Config.Time.msPerGameMinute, o SetTimeScale desde otro script.

¿Dónde veo los errores? En la consola del servidor y en la consola del cliente (F8). Puedes activar Config.Debug para más detalle.

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re y en la tienda. Conserva tu shared/config.lua al actualizar. Para soporte, usa el Discord de la tienda: [enlace de soporte].