---

title: "Time-of-day lighting rigs" description: "Compose ambient tint, directional light, and optional environment targets." draft: false weight: 40 last_updated: 2026-07-20

Time-of-day lighting rigs

Demo code, not plugin code. Lighting rigs and directional lights ship in the demo download (demo/lighting_rigs/), not the plugin ZIP. Copy them into your project if you want them.

The plugin retains only the lighting settings data resources (TimeOfDayLightingSettings2D/3D) and template presets.

Use TimeOfDayLightingRig2D or TimeOfDayLightingRig3D when you want richer day/night presentation than color/energy on a directional light alone.

Keep TimeOfDayDirectionalLight2D / 3D as the low-level sun/moon interpolator. The rig coordinates optional targets around the same GameClock.

2D setup

1. Add a TimeOfDayDirectionalLight2D and assign its lighting_group.
2. Add a CanvasModulate for ambient darkness (or use the demo ambience node).
3. Add a TimeOfDayLightingRig2D node.
4. Assign the same GameClock used by TimeHost.
5. Point directional_light and canvas_modulate at those nodes.
6. Assign a TimeOfDayLightingSettingsGroup2D (or a shipped preset).

Gameplay lamps stay scene-owned. Add PointLight2D / occluders yourself. Enable shadow_enabled on local lights when you want readable night shadows.

Shipped 2D presets

Under templates/calendar_time/resources/lighting/ (share calendar TimeOfDay identity with the template day/night set):

• preset_simple_2d.tres — light ambient tint only.
• preset_stylized_2d.tres — warm dawn/dusk, cool night (demo default).
• preset_high_contrast_night_2d.tres — deeper night contrast.

Atmospheric overlay (2D)

Assign overlay_target to a CanvasItem (for example a full-screen ColorRect). The rig sets its modulate to the blended ambient tint. If the item uses a ShaderMaterial, the rig also writes the tint to a tint shader uniform. Declare uniform vec4 tint : source_color; in your shader. Use it for dawn haze, night desaturation, a vignette, or a sky gradient.

3D setup

1. Keep TimeOfDayDirectionalLight3D for color and energy.
2. Add a WorldEnvironment with an Environment resource.
3. Add TimeOfDayLightingRig3D.
4. Assign clock, directional_light, world_environment, and a TimeOfDayLightingSettingsGroup3D.

The rig blends background, ambient, optional fog, exposure, saturation and contrast, and sun angles. Saturation and contrast default to 1.0 (no change). They are applied through the environment's color adjustment. Set apply_fog = false on Mobile/Compatibility if fog is unsupported.

Shipped 3D presets

Under templates/calendar_time/resources/lighting/ (share calendar TimeOfDay identity with the template day/night set):

• preset_simple_3d.tres — background and ambient only, no fog.
• preset_stylized_3d.tres — fog, exposure, and sun angles (showcase look).
• preset_high_contrast_night_3d.tres — stylized plus deeper night contrast.

Lifecycle notes

• Binding before or after _ready() syncs the current projection.
• Paused and MANUAL clocks update when state is published.
• Rebind or clock = null detaches bus handlers cleanly.
• Missing optional targets are ignored (no errors).

Renderer notes

• Forward+ supports the full 3D environment set used by the showcase.
• Mobile/Compatibility may limit glow or fog. Prefer conservative defaults.
• 2D HDR and occluders are project settings, not rig requirements.