Skip to main content

Lights and fog

createLight wraps Three.js lights so they spawn through the same stage.add(...) pipeline as meshes. createFog owns scene fog plus optional height falloff and animated noise modulators. Add both when you want mood, readability, or shadowed outdoor scenes without hand-wiring Three.js objects in game code.

Minimal example​

website/snippets/entities/lights-and-fog.ts:

import { createLight, createFog } from '@zylem/game-lib/entity';

const sun = createLight({
  type: 'directional',
  intensity: 1.2,
  position: { x: 10, y: 20, z: 10 },
  target: { x: 0, y: 0, z: 0 },
  castShadow: true,
});

const mist = createFog({
  type: 'linear',
  color: '#9aa3ad',
  start: 15,
  end: 80,
  height: { enabled: true, level: 4, falloff: 0.25 },
});

Lights​

ZylemLightOptions is a discriminated union on type:

typeUse case
ambientFlat fill (no position)
hemisphereSky / ground gradient
directionalSun or moon; supports shadow maps
pointLocal lamp with distance falloff
spotCone spotlight with angle and penumbra

Directional and spot lights accept a target point; the entity group moves both the light and its aim object. Shadow tuning lives in LightShadowOptions (mapSize, bias, orthographic bounds for directional lights).

Access the underlying Three.js instance via ZylemLight.light when you need engine-specific tweaks.

Fog​

ZylemFogOptions controls:

  • type — 'linear' (start/end distances) or 'exp2' (density coefficient)
  • color — fog tint applied to the scene
  • height — optional ground fog (ZylemFogHeightOptions)
  • noise — optional animated density variation (ZylemFogNoiseOptions)

Fog entities attach during spawn and clean up GPU patch state on teardown.

Variations​

  • Combine a low-intensity hemisphere fill with a single shadow-casting directional key light for outdoor stages.
  • Use exp² fog for horror interiors where distance falloff should accelerate quickly.
  • Lights and fog entities have no colliders—they do not interact with physics.

Pitfalls​

  • Shadow frustum — directional shadow cameras default to a broad orthographic box; tighten shadow.left/right/top/bottom to improve texel density where gameplay happens.
  • Too many shadow casters — each casting light adds draw calls; prefer one sun plus baked or fake lighting for mobile targets.
  • Linear vs exp2 — mixing fog types on one stage is unsupported; pick one model per fog entity.

API reference​