> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementlabs.net/llms.txt
> Use this file to discover all available pages before exploring further.

# World

> Control the colour grade, time of day, weather and detail distance of the world under the map.

`configs/map-world.jsonc` controls how the world looks under the map. The map shows the real world,
so the same scene can be dark, foggy or half-hidden by cloud depending on the time and weather.
These settings hold it steady and readable.

Everything here applies only while the menu is open, and is undone when it closes. A
[view](https://docs.elementlabs.net/products/3d-pause-menu/reference/views.md) can change any of it for the map it draws. Silencing
the game's audio and blurring the map behind a panel are menu-wide and set in
[Menu](https://docs.elementlabs.net/products/3d-pause-menu/configuration/menu.md).

## Settings

### Colour grade

| Key | Default | Meaning |
| - | - | - |
| `timecycle` | `"element_map"` | The colour grade applied to the world. `element_map` is the menu's own grade: it sets the light, the colours and the brightness itself instead of adjusting the weather underneath, so the map looks the same on an unmodded game and with a graphics mod such as NaturalVision, and is as bright from the highest altitude as from the street. Any of the game's own grade names is accepted too, and is used as the player's game defines it. |
| `timecycleStrength` | `1.0` | How strongly it is applied, from `0.0` (none) to `1.0` (full). |
| `alwaysMidday` | `true` | Whether `element_map` lights the map as a clear midday whatever the time and the weather. Set to `false`, it follows the time of day and the weather instead: the map is dark at night, with the city's lights on, and dims at dawn and dusk. It has no effect on any other grade. |

With `alwaysMidday` on, `element_map` is a clear midday whatever the time and the weather are:
`time.hour` only moves the sun and its shadows, and the weather no longer changes the light. With
it off, the map keeps the rest of `element_map`, so it still looks the same with a graphics mod and
from every altitude, and the brightness follows the clock. Another grade, such as `default`,
follows the player's game entirely, so a graphics mod changes how the map looks and its brightness
varies with altitude.

### Time and weather

| Key | Default | Meaning |
| - | - | - |
| `time.lock` | `true` | Whether the time of day is held fixed while the menu is open. |
| `time.hour` | `12` | The hour it is held at, from `0` to `23`. Midday keeps the whole map lit. |
| `weather.lock` | `true` | Whether the weather is held fixed while the menu is open. |
| `weather.type` | `"EXTRASUNNY"` | The weather it is held at, by the game's own name: `CLEAR`, `CLOUDS`, `OVERCAST`, `RAIN`, `FOGGY` and so on. |

The time and the weather are held only for the player looking at the map, and handed back when the
menu closes: the clock where it stood when the menu opened, and the weather whatever a time and
weather script set in the meantime. A script of that kind keeps working while the menu is open; its
changes show once the menu closes.

None of this is put on at once. While the camera flies up, the clock runs from the world's time to
`time.hour` by the shorter way round and the grade fades in; while it flies back down, the same
happens in reverse. How long that takes is the camera's own `open.duration` and `close.duration`, in
[Camera](https://docs.elementlabs.net/products/3d-pause-menu/configuration/map-camera.md). The weather and the clouds are the
exceptions. The game has no gradual change for a weather held this way, so rain stops the moment the
map opens, and the clouds go at once and come back when the menu has closed.

With `time.lock` off, the map shows whatever the time is. That changes the light only with
`alwaysMidday` off or with another grade; with `element_map` and `alwaysMidday` on, the map is
midday at any hour.

### What is hidden

| Key | Default | Meaning |
| - | - | - |
| `hideClouds` | `true` | Whether the cloud layer is hidden. Cloud sits between a high camera and the ground, so leaving it visible obscures the map. |
| `hideFog` | `true` | Whether distance fog and haze are removed. They are what make far parts of the map grey out or darken, and how much there is depends on the weather and on any graphics mod. |
| `hideWorld` | `true` | Whether every ped and vehicle is hidden, other than you, the vehicle you are in, whoever is in it with you and what it tows. The scene is then the city alone. Set it to `false` for a view that is meant to watch the world. |

Clouds and fog come back when the menu closes, so a player who had them before opening it has them
again after. `hideWorld` only affects this client: other players still see you and your vehicle
while you are in the menu. Someone who gets into your vehicle comes into sight, and goes out of it
again when they get out. A player who leaves any other vehicle stays hidden; they can show for a
quarter of a second before the map hides them again. Everything comes back the moment the map
starts closing, including a fade a server had set on a player.

### Detail distance

The map is drawn from the streamed world, so how much of it is loaded decides how complete it looks.

| Key | Default | Meaning |
| - | - | - |
| `lodScale` | `3.0` | The ceiling on detail distance while the map is open. |
| `lodScaleNear` | `3.0` | The detail distance used when the camera is low, where buildings must be recognisable. |
| `lodScaleFar` | `1.0` | The detail distance used when the camera is high, where individual buildings do not matter. |

The value in use moves between `lodScaleNear` and `lodScaleFar` as altitude changes, and never
exceeds `lodScale`.

### Population budget

While the map is open the menu takes the ped and vehicle population budgets to `0`, so memory goes
to the world the camera is flying over. The game cannot be asked what they were, so the menu puts
back the values set here when it closes.

| Key | Default | Meaning |
| - | - | - |
| `populationBudget.ped` | `3` | The ped population budget restored on close, from `0` to `3`. `3` is the game's own default. |
| `populationBudget.vehicle` | `3` | The vehicle population budget restored on close, from `0` to `3`. `3` is the game's own default. |

Change these only if another resource on your server calls `SetPedPopulationBudget` or
`SetVehiclePopulationBudget`, and set them to the values it uses.

## What closing gives back

Closing the menu leaves the game as it found it. A colour grade another resource had on the world
comes back with its strength, and so does an extra grade. The expanded radar is left up if it was
up. A ped or vehicle another resource had made translucent is translucent again.

A resource that changes the grade while the menu is open keeps what it set: the menu only puts
back a grade that is still its own.

Two things cannot be read from the game and are reset instead: the streaming focus goes back to
the player, and the population budgets go to the values above.

## Example

Night held instead of midday, and lower detail for weaker machines:

```jsonc theme={null}
{
  "namespace": "map-world",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "alwaysMidday": false,
    "time": {
      "hour": 22
    },
    "lodScaleNear": 2.0,
    "lodScale": 2.0
  }
}
```

Leaving the world exactly as it is in game:

```jsonc theme={null}
{
  "namespace": "map-world",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "timecycleStrength": 0.0,
    "time": {
      "lock": false
    },
    "weather": {
      "lock": false
    },
    "hideClouds": false,
    "hideFog": false
  }
}
```

## Applying changes

```text theme={null}
restart element_3d_pausemenu
```

## Limits

| Key | Stay within | Why |
| - | - | - |
| `lodScale`, `lodScaleNear`, `lodScaleFar` | Roughly `1.0` to `4.0` | Detail distance is the single largest cost of having the map open. Raising these values loads far more of the world and can cost frames on weaker machines. Below `1.0` the map looks unfinished, with buildings missing. |
| `timecycleStrength` | `0.0` to `1.0` | Outside that range the result is not predictable. |
| `time.hour` | `0` to `23` | Outside that range the hour is not a valid time of day. |
| `weather.type` | An existing weather name | A name the game does not have leaves the weather as it is. There is no error, so check the result in game. |
| `timecycle` | An existing grade name | A name the game does not have leaves the world ungraded. There is no error, so check the result in game. |
| `populationBudget.ped`, `populationBudget.vehicle` | `0` to `3` | The game has four levels. A value outside them is brought to the nearest one. |

## Related

* [Configuration](https://docs.elementlabs.net/products/3d-pause-menu/configuration/index.md)
* [Camera](https://docs.elementlabs.net/products/3d-pause-menu/configuration/map-camera.md): the altitude range the detail settings respond to
* [Views](https://docs.elementlabs.net/products/3d-pause-menu/reference/views.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.