Atmosphere and lighting

7.1 Purpose

Define how the overall look of a level is established using time of day, sky, fog/atmosphere and local lights.

7.2 Core concepts

Time of day, sky, clouds, fog, and lighting are controlled by level objects in the Scene Tree. A normal outdoor setup uses:

• TimeOfDay for the clock, location, date, and optional sky profile
• ScatterSky for atmospheric and celestial sky rendering
• CloudLayer for cloud appearance and transmittance
• LevelInfo for fog density, atmosphere height, and visible distance

Local PointLight and SpotLight objects provide night and area illumination.

7.3 Requirements and considerations

Choose a default time-of-day setup that preserves road and terrain readability while driving and validate visibility and contrast at multiple times of day.

Keep local light counts conservative, especially in dense urban or forested areas.

Ensure key routes remain readable at dusk and night with minimal discomfort (glare, excessive darkness).

7.4 Fog and atmosphere

Use fog to support depth cues without washing out mid-tones. The current sky pipeline derives sky and fog color from the atmosphere.

Keep color temperature consistent with the chosen sky and terrain palette.

The main LevelInfo parameters are:

• fogDensity: amount of fog
• fogAtmosphereHeight: vertical extent of the fog atmosphere
• visibleDistance: maximum scene visibility distance

Use TimeOfDay, ScatterSky, and a sky profile for atmosphere and celestial art direction. See Sky and Weather for the current setup.

7.5 Local lighting

Prefer targeted point/spot lights for points of interest and road furniture (intersections, tunnels).

Avoid heavy overlaps; set ranges and intensities suitable for driving speeds and sight distances.

Create local lights through Create Object > Environment, then select PointLight or SpotLight.

Creating a Point or Spot Light from the toolbar

Point Light

Point lights emit in all directions and use radius as their effective range.

Point Light parameters in the Inspector

Important fields:

• isEnabled: enables or disables the light
• color: light color; use the editor’s color-temperature controls when possible
• intensity: physical light intensity
• intensityUnit: unit such as lumens (lm) or candelas (cd)
• castShadows: enables or disables shadows
• radius: effective range for a point light
• range, innerAngle, and outerAngle: range and cone shape for a spotlight

Since update 0.39, local lights use physically based inverse-squared falloff. Use intensity and intensityUnit for new lights; brightness is retained only for legacy compatibility.

Point lights OFF

Point lights ON

Spot light OFF

Spot light ON

7.6 Night lighting

Lights and emissive fixtures that should activate at night can be configured in the Inspector’s Night Lighting section. Tune one representative fixture first, then reuse it for similar lights.

See Night Lighting for nightLight, day/night intensity, emissive fixture, and time-window setup.

7.7 PostFX

PostFX are applied after the scene is rendered and shape the final image. Set up physically meaningful lights, emissive materials, exposure, and tone mapping first, then use PostFX for final presentation.

The stable modding paths are custom color-correction ramps and Lua extensions that adjust existing PostFX objects. Creating custom fullscreen effects is an advanced workflow. See Post Process Effects for supported approaches.

7.8 Performance guidance

Budget the number of active dynamic lights in dense scenes. Overlapping lights and shadow-casting lights increase rendering cost.

Enable shadows only where they materially improve the scene, and test representative dense areas at night.

7.9 Data locations

Sky, time-of-day, fog, clouds, and lights are scene objects saved in items.level.json files beneath the level’s main/ scene tree. The Template level stores its main environment group under:

main/MissionGroup/level_objects/sky_and_sun/items.level.json

The exact grouping can vary, but the objects remain part of the main/ scene tree rather than separate environment configuration files.

See also: Sky and Weather , TimeOfDay , LevelInfo , Lights , Night Lighting .

7.10 Common issues

Excessive fog or contrast can lead to “milky” or overly dark and unrealistic scenes.

Color casts should be controlled with real values or it can conflict with the terrain, vegetation and the overall look and feel of the map.

Too many local lights can cause frame drops or harsh overlaps.

7.11 Validation criteria

• Day and night profiles remain readable while driving at speed.
• Fog adds depth without degrading contrast.
• PostFX and lights maintain stable performance in dressed areas.