lighting

Dynamic World Lighting

Use this skill when adding reusable outdoor lighting, fog, shadows, and post-processing to a 3D web game.

Pattern

Create lighting through a single world-environment module that returns a small lighting handle. The handle should contain ambient light, key directional light, shadow generator, optional sky material, optional celestial meshes, and post-processing pipeline references.

Keep setup and updates separate:

• setup creates lights, shadow settings, fog defaults, sky material, and render pipeline
• update computes time-of-day values and applies them every frame

import { Color3, DirectionalLight, HemisphericLight, Scene, ShadowGenerator, Vector3 } from '@babylonjs/core'

export interface LightingRig {
  ambient: HemisphericLight
  key: DirectionalLight
  shadows: ShadowGenerator
  weather: WeatherProfile
}

export interface WeatherProfile {
  fogBoost: number
  lightScale: number
  starScale: number
}

export function createLightingRig(scene: Scene, weather: WeatherProfile, shadowHalfSize: number): LightingRig {
  scene.fogMode = Scene.FOGMODE_EXP2
  scene.fogDensity = 0.006 + weather.fogBoost

  const ambient = new HemisphericLight('ambient-light', new Vector3(0.25, 1, 0.35), scene)
  ambient.intensity = 0.8
  ambient.specular = Color3.Black()

  const key = new DirectionalLight('main-directional-light', new Vector3(-0.3, -0.8, -0.25), scene)
  key.intensity = 1
  key.orthoLeft = -shadowHalfSize
  key.orthoRight = shadowHalfSize
  key.orthoTop = shadowHalfSize
  key.orthoBottom = -shadowHalfSize

  const shadows = new ShadowGenerator(2048, key)
  shadows.useBlurExponentialShadowMap = true
  shadows.blurKernel = 24

  return { ambient, key, shadows, weather }
}

Lighting Model

Use a hemispheric or ambient light for base readability and a directional light for sun/moon shadows. Drive both from a normalized cycle value in the range 0..1.

Typical update flow:

1. Convert elapsed time to a cycle fraction.
2. Map the fraction to an orbit angle.
3. Calculate sun altitude and direction.
4. Derive daylight and moonlight weights.
5. Lerp light colors, fog color, ambient color, and shadow darkness.
6. Move the directional light to match the active celestial source.