Night Lighting

Night lighting turns selected lights and emissive fixtures on or off based on the level time of day. Use it for street lamps, parking lots, gas stations, buildings, signs, tunnels, industrial areas, ports, and other light sources that should become active at night.

For normal authoring, place a light, tune it visually and physically, then mark it as a night light. The same behavior is stored as dynamic fields on normal level objects.

Overview

When a level is loaded, core_environment scans the scene and builds an internal registry of:

• PointLight, SpotLight, and other LightBase objects marked with nightLight
• Lights that define dayIntensity or nightIntensity
• TSStatic meshes marked with nightEmissive
• TSStatic meshes that link to lights through the child dynamic field

Every time the level time of day changes, the environment system checks whether the current time is inside the active night window. When the level enters night, registered lights are enabled, intensity-controlled lights receive their night intensity, and registered emissive meshes receive their night color. When the level returns to day, registered lights are disabled, daytime intensity values are restored where defined, and emissive meshes are darkened.

The registry is refreshed automatically when a mission starts, when the editor is deactivated, and whenever you edit night lighting fields in the Inspector.

Basic workflow

For a simple street light:

1. Place a PointLight or SpotLight near the fixture.
2. Set the light’s color, range/radius, angle, shadow setting, and physical intensity.
3. In the Inspector’s Night Lighting section, enable Night controlled.
4. Disable Enabled so the light is saved off by default during the day.
5. If the fixture mesh should glow, select its TSStatic mesh, enable Night emissive, and set Night Emissive Color in the same section.
6. Test at day, dusk, and night.
7. Save the level.

For most level work, use the Night Lighting section in the Inspector instead of editing fields manually. It exposes the same data directly on the selected light or mesh.

Time of day window

By default, night lighting uses the level’s solar night window when the TimeOfDay object has enough location and date data. In that case, night starts at the calculated local sunset and ends at the calculated local sunrise.

Levels can override the automatic solar window by setting start and end times on theLevelInfo as dynamic fields:

{"nightLightsNightStart":"0.25","nightLightsNightEnd":"0.75"}

To override the automatic solar window, select theLevelInfo in the Scene Tree. In the Inspector, scroll down to the Dynamic Fields section and add or edit nightLightsNightStart and nightLightsNightEnd as dynamic fields.

These are BeamNG TimeOfDay values from 0 to 1, not normal clock-hour fractions. In this scale:

• 0.25 maps to about 18:00.
• 0.75 maps to about 06:00.

The night window supports wrapping across midnight. A start value in the evening and an end value in the morning means the system treats both late evening and early morning as night.

If neither override field is set, the system uses the solar sunset-to-sunrise window when available. If the solar window cannot be calculated, or if only one override field is set, the missing value falls back to the fixed default of 0.25 for start and 0.75 for end.

If the start and end values are identical, automatic night lighting is disabled.

Object fields

Night lighting is stored directly on scene objects through dynamic fields. These fields are saved in items.level.json together with the rest of the level object data.

nightLight

Use nightLight on lights that should be off during the day and on at night. The light can be a PointLight, SpotLight, or another object derived from LightBase.

Most night lights should be saved with isEnabled set to false. This avoids unnecessary active lights when the level loads in daytime and lets the environment system decide when the light should be enabled.

Example:

{"name":"StreetLight_A_01","class":"SpotLight","isEnabled":false,"nightLight":"1","intensity":20000,"range":45}

dayIntensity and nightIntensity

Use these fields when a light should remain part of the scene but change brightness between day and night.

The value is written to the light’s normal intensity field. Use the engine unit for the light type:

• SpotLight: candelas
• PointLight: lumens

If only one side is defined, only that side is changed. For example, a light with nightIntensity but no dayIntensity will receive the night intensity at night, then keep its existing value during the day.

Use this for:

• Lights that should stay dim during dusk/day but become stronger at night
• Artistic fallback lighting where full on/off switching is too abrupt
• Special fixtures that need a different daytime value for visibility or readability

nightEmissive

Use nightEmissive on a TSStatic when the visible fixture should glow at night. The system changes the mesh instanceColor:

• At night, RGB is set to the night emissive color
• During the day, RGB is set to black
• Alpha is preserved

Meshes that use this workflow should support instance color and normally use useInstanceRenderData.

nightEmissiveColor

Use this when a mesh has its own explicit night color.

Both normalized and 8-bit-style values are accepted:

{"nightEmissiveColor":"0.74 0.88 1"}

{"nightEmissiveColor":"189 225 255"}

Keep this color close to the linked or nearby light color. A warm orange sodium lamp should not have a cool blue-white emissive surface unless the art intentionally calls for that contrast.

child

The child field links a TSStatic fixture mesh to one or more light object names. The environment system scans child, child1, child2, and further indexed dynamic fields and treats linked light objects as night lights.

When a mesh has linked lights, the first linked light provides the mesh’s night emissive color. This keeps the projected light and visible glowing fixture in sync. In that linked setup, the linked light color is used instead of nightEmissiveColor.

Use links for assembled fixtures where the mesh and light should behave as one authoring unit.

West Coast USA reference

West Coast USA is the best built-in reference for this system. Its night lighting is organized under:

levels/west_coast_usa/main/MissionGroup/nightlights/

Inside that group, light families are split into subfolders such as light emitters, pole lights, gas station lights, city lights, bridge lights, and port lights. This structure supports inspection, bulk edits, and debugging in a large level.

A typical HPS-style street light emitter is saved disabled and marked as a night light:

{"name":"SpotLight_1101","class":"SpotLight","__parent":"lightemitters_hps","brightness":4,"castShadows":true,"color":[1,0.30399999,0.0280000009,1],"intensity":20000,"isEnabled":false,"nightLight":"1","outerAngle":160,"range":45,"useColorTemperature":"true"}

Key fields:

• isEnabled:false: the light is not active by default
• nightLight:"1": the environment system controls it
• color: warm sodium-like light color
• intensity, range, and outerAngle: the physical and spatial light setup
• castShadows: enabled where the fixture benefits from shadows

A visible pole-light mesh can link to a light and define its emissive color:

{"class":"TSStatic","__parent":"polelightsingle","child":"SpotLight_11011175170147","instanceColor":[0.741999984,0.880999982,1,1],"nightEmissive":"1","nightEmissiveColor":"189 225 255","shapeName":"levels/west_coast_usa/art/shapes/objects/pole_light_single.dae","useInstanceRenderData":true}

Key fields:

• child: links the mesh to the light object
• nightEmissive:"1": enables night emissive switching
• nightEmissiveColor: visible glow color
• shapeName: the actual fixture mesh

Inspector Night Lighting section

The Night Lighting section is built into the World Editor Inspector window. It appears at the bottom of the Inspector when you select one or more lights or TSStatic meshes. Mixed selections of lights and meshes do not show the section.

Night lighting settings in the World Editor Inspector

The section edits the selected objects’ dynamic fields and automatically refreshes the night lighting registry after a change so it can be previewed without reloading the level.

Editing lights

When a light derived from LightBase, such as a PointLight or SpotLight, is selected, the Inspector displays:

• Night controlled (nightLight): toggles automatic day/night control.
• Day Intensity (dayIntensity): optional physical intensity applied during daytime.
• Night Intensity (nightIntensity): optional physical intensity applied during nighttime.

Editing meshes

When a TSStatic mesh is selected, the Inspector displays:

• Night emissive (nightEmissive): enables automatic nighttime emissive color switching.
• Night Emissive Color (nightEmissiveColor): sets the RGB instance color used at night.
• Linked child lights (child): links one or more light object names, separated by spaces or commas. Linked lights are registered as night lights, and the first linked light supplies the mesh’s emissive color.

Bulk editing

You can select multiple lights or meshes in the Scene Tree and edit their Night Lighting fields simultaneously in the Inspector. For example, you can select all street lamps of a certain type and toggle Night controlled on all of them at once, or set their Night Intensity together.

Saving

The editor marks changed objects dirty and refreshes the night lighting registry, but it does not replace saving the level. After editing, save the level from the World Editor and reload it once to confirm the saved data behaves correctly.

Before the World Editor saves a level, the environment system temporarily applies the daytime night-light state, then restores the previous preview state after saving. This keeps controlled lights saved disabled during the day and keeps night emissive meshes saved dark instead of baking the current night preview into the level file.

Manual authoring workflow

Advanced users can author or review night lighting directly in items.level.json.

Recommended manual workflow:

1. Group night lighting under a clear SimGroup, such as NightLighting or nightlights.
2. Keep fixture families in separate groups or item files.
3. Name lights consistently so child links are readable.
4. Save controlled lights with isEnabled:false.
5. Add nightLight:"1" to automatically controlled lights.
6. Add nightEmissive:"1" and nightEmissiveColor to fixture meshes that should glow.
7. Link fixture meshes to their light names with child where practical.
8. Reload or refresh the registry.
9. Test day, dusk, night, and dawn.

Avoid using absolute asset paths. Keep shapeName and other paths relative to the level or game filesystem.

Artist guidelines

Start from the physical lighting first:

• Use realistic color temperature and color
• Use real intensity ranges where possible
• Keep the light range/radius only as large as needed
• Avoid using bloom to compensate for weak emissive or lighting setup
• Match emissive color to light color
• Test from normal driving camera distances, not only from a close editor view

Large urban levels need restraint. Hundreds of small lights can be acceptable if most have limited range.

Advanced notes

The runtime registry stores object IDs, not names, after scanning. This means renaming a linked light requires manually updating the child field on linked meshes.

The environment system scans up to 256 indexed child fields per mesh. Multiple light names can be stored in one field separated by whitespace or commas.

The active state is binary: day or night. There is no built-in fade between states. If a fixture needs gradual artistic behavior, use dayIntensity and nightIntensity carefully or implement custom behavior outside the normal night-light registry.

The current light state can be queried from Lua through core_environment.getLightState(). It returns information such as current time, phase, whether night lights are active, and the configured night start/end values.

Troubleshooting

If a light does not turn on at night:

• Confirm the object is a PointLight, SpotLight, or LightBase object
• Confirm nightLight is set to a truthy value such as 1
• Confirm the current time is inside the night window
• Change a Night Lighting field in the Inspector to refresh the registry, or reload the level
• Check that the light is not hidden by bad placement, wrong rotation, too small range, or very low intensity

If an emissive mesh does not glow:

• Confirm the object is a TSStatic
• Confirm nightEmissive is set
• Confirm nightEmissiveColor is valid, or that a linked light has a useful color
• Confirm the mesh/material supports instance color for the intended emissive workflow
• Confirm useInstanceRenderData is enabled when required by the asset

If linked lights stop working after renaming:

• Update the mesh child field to the new light name

If changes disappear after reload:

• Save the level in the World Editor after editing
• Confirm the modified objects are marked dirty and are saved into the expected items.level.json
• Check whether the object is part of a prefab or external asset that needs its own save workflow

Related pages

• Physically Based Lighting
• Lights
• LevelInfo
• TimeOfDay
• Sky and Weather
• Sky, Atmosphere, and Night Sky