> For the complete documentation index, see [llms.txt](https://ccfivem.gitbook.io/ccfivem-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ccfivem.gitbook.io/ccfivem-docs/server-management/weather-and-time-cc_weather.md). # Weather & Time (cc\_weather) **CrankChaos Weather & Time**: a server-wide clock and dynamic weather with forecast, seasons, weather regions and blackouts. The state is saved and survives restarts. ## Features * Adjustable day length, faster nights, or real time with daylight saving * Weather cycle with forecast (weighted "what comes next" tables) * Seasons (normal, summer, winter) with snow tracks in winter * Temperature per weather, time of day and season (Celsius or Fahrenheit), heat haze and frost overlay * Weather regions (cities) and custom zones with a zone editor * Blackouts, manual or random * Admin weather panel with map * Commands in German and English * Pause interface for photo, cutscene or interior scripts ## Frameworks ESX Legacy, QBCore and QBox. Weather and time apply to all players, so almost nothing is needed from the framework. ## Works with * cc\_admin/00%20Overview\.md) – audit log entries; the admin menu hands weather and time over to cc\_weather * cc\_dispatch/00%20Overview\.md) – map image in the weather panel * cc\_lib/00%20Overview\.md) – shared notifications {% hint style="info" %} The program code is protected by Cfx asset escrow. `config/`, `locales/` and `shared/cc_framework.lua` stay editable. {% endhint %} ## Pages * Installation * Configuration * API * FAQ Need help? See Support. ## Installation See also the general installation guide and dependencies. ### Requirements | Resource | Required | Notes | | ------------------------------- | -------- | ------------------------------------------------- | | `oxmysql` | yes | fxmanifest dependency | | cc\_admin/00%20Overview\.md) | optional | audit log; menu hands weather/time to cc\_weather | | cc\_dispatch/00%20Overview\.md) | optional | map background in the weather panel | | cc\_lib/00%20Overview\.md) | optional | shared notifications | {% hint style="warning" %} Remove all other weather/time scripts (vSync, qb-weathersync, cd\_easytime, Renewed-Weathersync, esx\_weathersync and similar). The console warns on start if one is running. {% endhint %} ### Steps 1. Copy the folder to `resources/[crankchaos]/cc_weather`. 2. Add to `server.cfg` – after oxmysql, cc\_lib and cc\_admin, before cc\_phone: ```cfg ensure oxmysql ensure cc_lib # optional ensure cc_admin # optional ensure cc_weather ensure cc_phone # optional add_ace group.admin cc_weather.admin allow ``` ### Database No SQL import needed. The tables `cc_weather_state` and `cc_weather_areas` are created on first start. ### Permissions All commands and the weather panel require the ACE from `Config.Ace`: ```cfg add_ace group.admin cc_weather.admin allow ``` The commands also work from the server console. ## Configuration Editable files: `config/config.lua`, `config/ui.lua` (language and look), `locales/de.json`, `locales/en.json`, `shared/cc_framework.lua` (framework bridge). In the config, "minutes" means real minutes unless "game minutes" is stated. ### Permission and commands ```lua Config.Ace = 'cc_weather.admin' Config.Commands = { weather = { 'wetter', 'weather' }, time = { 'zeit', 'time' }, freezeTime = { 'zeitstopp', 'freezetime' }, freezeWeather = { 'wetterstopp', 'freezeweather' }, blackout = { 'blackout', 'stromausfall' }, forecast = { 'vorhersage', 'forecast' }, panel = { 'wetterpanel', 'weatherpanel' }, } ``` The first name is the German command, further names are aliases. An empty list disables the command. `Config.Conflicts` lists weather scripts that trigger a console warning. ### Clock ```lua Config.Time = { mode = 'game', -- 'game' = own clock, 'real' = real time dayLength = 48, -- real minutes per full game day nightSpeed = 2.0, -- night runs faster; 1.0 = off nightStart = 21, nightEnd = 6, timezone = 'Europe/Berlin', start = { hour = 9, minute = 0 }, catchUpMinutes = 5, -- larger jumps are animated catchUpMs = 2500, } ``` `timezone` accepts `'Europe/Berlin'` (and other CET zones), `'Europe/London'`, `'Europe/Lisbon'`, `'Europe/Helsinki'`, `'UTC'`, `'local'` or a fixed hour offset such as `-5`. Daylight saving is calculated for the European zones. The timezone is also used for season months and area schedules. ### Weather ```lua Config.Weather = { types = { 'EXTRASUNNY', 'CLEAR', 'NEUTRAL', ... }, start = 'CLEAR', dynamic = true, -- weather changes by itself holdOnSet = true, -- admin-set weather stays until "dynamic" duration = { min = 20, max = 45 }, durations = { THUNDER = { min = 8, max = 15 }, ... }, forecastSteps = 8, -- 6 to 12 wind = { default = { min = 0.5, max = 3.0 }, ... }, } ``` ### Weather groups and seasons `Config.Groups` defines `normal`, `summer` and `winter`, each with `start` weights and a `next` table (which weather follows which). Numbers are weights, not percentages. ```lua Config.Seasons = { enabled = true, months = { [12] = 'winter', [1] = 'winter', [2] = 'winter', [6] = 'summer', [7] = 'summer', [8] = 'summer' }, fallback = 'normal', force = nil, -- e.g. 'winter' for testing snowTracks = true, temperatureOffset = { normal = 0, summer = 6, winter = -12 }, } ``` ### Transitions ```lua Config.Transition = { wet = 15.0, -- seconds for changes involving rain/snow dry = 1.0, cycle = 45.0, -- one step of the global cycle selfHeal = true, -- restore state if another script changes it locally } ``` ### Temperature ```lua Config.Temperature = { unit = 'C', -- 'C' or 'F' (calculated in Celsius) base = { EXTRASUNNY = 29, CLEAR = 25, ... }, daily = 5, -- day/night swing in degrees heat = { enabled = true, above = 35, modifier = 'heathaze', strength = 0.55 }, frost = { enabled = true, below = -15 }, } ``` ### Blackout ```lua Config.Blackout = { vehicles = false, -- vehicle lights also off? events = { enabled = false, -- random blackouts checkEvery = 30, chance = 10, duration = { min = 3, max = 8 }, nightOnly = true, }, } ``` {% hint style="warning" %} A blackout also darkens interiors (for example MRPD). Random blackouts are therefore off by default. {% endhint %} ### Weather regions ```lua Config.Areas = { enabled = true, checkInterval = 1500, scheduleClock = 'real', -- 'real' or 'game' for area schedules maxZones = 200, maxPoints = 1024, maxSchedule = 24, cities = { { id = 'lossantos', name = 'Los Santos', color = '#3B82F6', points = { ... } }, ... }, } ``` Default cities: Los Santos, Sandy Shores, Paleto Bay, Great Chaparral. Without a panel setting each city follows the global weather. Zones drawn in the panel take priority over cities. ## Exports, Events & Commands ### Commands All commands require `cc_weather.admin` and also work from the server console. | Command | Alias | Purpose | | ------------------------------------ | ---------------- | ------------------------------------- | | `/wetter ` | `/weather` | set weather or enable the cycle | | `/zeit ` | `/time` | set time or clock mode | | `/zeitstopp [an\|aus]` | `/freezetime` | freeze / resume the clock | | `/wetterstopp [an\|aus]` | `/freezeweather` | freeze weather | | `/blackout [minutes\|aus]` | `/stromausfall` | blackout | | `/vorhersage` | `/forecast` | forecast in chat | | `/wetterpanel` | `/weatherpanel` | panel with map, areas and zone editor | ### Server exports The capitalised setters behave like the commands and are **saved**. `setGlobalWeather`, `setAreaWeather` and `freezeTime` are **temporary** and gone after a restart. | Export | Parameters | Returns | | ----------------------------------------------- | --------------------------------------------------- | -------------------------------- | | `SetWeather(weather, hold?)` | weather type or `'dynamic'` | `ok, message` | | `SetTime(hour, minute)` | hour, minute | `ok, message` | | `SetTimeMode(mode)` | `'real'` or `'game'` | `ok, message` | | `Freeze(kind, state)` | `'time'`/`'weather'`, `true`/`false`/`nil` (toggle) | `ok, message` | | `SetBlackout(state, minutes?)` | on/off/`nil`, duration | `ok, message` | | `GetState()` | – | same as `GlobalState.ccWorld` | | `GetForecast()` | – | forecast list | | `GetTemperature(areaId?)` | optional area | Celsius | | `GetAreas()` | – | all areas with mode and weather | | `getTime()` | – | `{ hour, minute, frozen, mode }` | | `setGlobalWeather(weather)` | type or `nil` (clears) | `ok, message` | | `setAreaWeather(areaId, weather, temperature?)` | area, type or `nil`, temperature | `ok, problem` | | `freezeTime(state)` | `false` = resume, otherwise freeze | `ok, message` | ```lua exports.cc_weather:SetWeather('RAIN', true) exports.cc_weather:SetTime(22, 30) exports.cc_weather:SetBlackout(true, 10) ``` ### Client exports | Export | Returns / effect | | -------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `Pause(reason?)` | cc\_weather stops touching weather/time (reason defaults to the calling resource) | | `Resume(reason?)` | server state is restored immediately | | `IsPaused()` | `boolean` | | `SetLocalWeather(weather, hour?, minute?)` / `setLocalWeather` | pauses and holds the state locally, returns `boolean` | | `ClearLocalWeather()` / `clearLocalWeather` | back to server state | | `GetWeather()` / `getWeather` | `{ weather, area, areaName, temperature, unit, paused }` | | `GetTemperature()` / `getTemperature` | temperature at the player | | `GetState()` | `GlobalState.ccWorld` | | `openPanel()` | opens the weather panel (permission checked server-side) | {% hint style="warning" %} Every script that sets weather or time locally (character creation, photo studio, interiors, instances) must call `Pause` before and `Resume` afterwards. Otherwise cc\_weather restores the sky. {% endhint %} ```lua exports.cc_weather:Pause('my_studio') SetWeatherTypeNowPersist('EXTRASUNNY') NetworkOverrideClockTime(12, 0, 0) -- ... exports.cc_weather:Resume('my_studio') ``` ### Events `cc_weather:changed` (local, subscribe with `AddEventHandler`): * Server: `(world)` on every state change * Client: `({ weather, area, areaName, temperature })` when the weather at the player changes ### State bags * `GlobalState.ccWorld` – weather, clock, blackout * `GlobalState.ccWeatherAreas` – `{ [area] = { w, t } }` weather and temperature per area ## FAQ & Troubleshooting **The sky flickers between two weathers.** Another weather script is running. Remove it; the console names it on start (`Config.Conflicts`). **My photo studio / character creator gets the wrong weather.** That script must call `exports.cc_weather:Pause()` before setting weather or time and `Resume()` afterwards. See API. **"No permission" when using `/wetter`.** Add `add_ace group.admin cc_weather.admin allow` to `server.cfg` and make sure your player is in `group.admin`. **The weather panel has no map.** The map background needs cc\_dispatch/00%20Overview\.md). **Weather set by an admin never changes.** With `Config.Weather.holdOnSet = true` the weather stays until `/wetter dynamisch` (or `SetWeather('dynamic')`). **Changes made with `setGlobalWeather` are gone after a restart.** The lowercase exports are temporary by design. Use `SetWeather` to save. **Why does a blackout darken interiors?** That is how GTA's blackout works. Random blackouts are off by default for this reason. **Area schedules use the wrong time.** They use the real server clock in `Config.Time.timezone` by default. Set `Config.Areas.scheduleClock = 'game'` or adjust the timezone. Still stuck? See Support. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://ccfivem.gitbook.io/ccfivem-docs/server-management/weather-and-time-cc_weather.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.