Skip to main content

Lighting

Manage map lighting from the server and add temporary client-only spots for local effects. Lighting is rendered by the engine with CanvasEngine presets. You do not need to import NightAmbient or SpriteShadows in your map components.

Shared Types

Lighting types are exported by @rpgjs/common:

Initial Map Lighting

Set initial lighting in @MapData() or in a map entry inside your server module:

Day Night Cycle

The DayNightCycle preset of CanvasEngine color grades the scene by the hour of the day (blue moonlight, pink dawn, neutral day, golden hour, purple dusk) and lights the light spots of the map when it is dark. Enable it on the map and describe the lights with spots:
  • halo (0 to 1): glow of the light in the air.
  • schedule ([on, off]): hours the light is on. Without it, the light follows the darkness.
  • While dayNight is enabled, the ambient darkness overlay is not drawn.
Where does the hour come from? Register the Time Manager module with lighting: { dayNight: true }: the server owns the hour and every player sees the same one. The time, speed and paused keys of dayNight are ignored then. Without the Time Manager, the map has its own local clock (the same on every client, but not synchronized by the server): dayNight.time (start hour, 18.5 is 18:30), dayNight.speed (game minutes per real second) and dayNight.paused. To keep a map out of the cycle, set dayNight: { enabled: false } on that map.

Runtime API (Server)

RpgMap exposes:
  • map.getLighting(): LightingState | null
  • map.setLighting(next: LightingState | null, options?: { sync?: boolean })
  • map.patchLighting(patch: Partial<LightingState>, options?: { sync?: boolean })
  • map.clearLighting(options?: { sync?: boolean })
  • map.setDay(options?: { sync?: boolean })
  • map.setNight(options?: { sync?: boolean })
  • map.transitionLighting(toLighting, options?: { duration?: number, easing?: 'linear' | 'easeInOut' })
Example:
When sync is not false, lighting is broadcast to players in the map.

Runtime API (Client)

RpgClientMap exposes local light spot helpers:
  • sceneMap.addLightSpot(id, spot)
  • sceneMap.patchLightSpot(id, partialSpot)
  • sceneMap.removeLightSpot(id)
  • sceneMap.clearLightSpots()
Client spots are not synchronized. They are useful for player torches, spells, cursor effects, or cutscenes.
Local spots are merged with synchronized map spots for rendering and are cleared when the client changes map. Spots do not make the map night by themselves; NightAmbient is rendered only when synchronized lighting provides an ambient darkness value greater than 0, for example through map.setNight() or map.setLighting({ ambient: { darkness: ... } }). Ambient lighting fields map to CanvasEngine NightAmbient props: darkness and darkColor become the darkness overlay, while fogColor, fogRadius, fogSoftness, and fogOpacity configure the haze overlay.

Shadows

Shadows are opt-in: set lighting.shadows.enabled: true together with lighting.sun to get sun-driven shadows. Neither an active sun nor a light spot turns shadows on by itself. Once enabled, the engine automatically marks character sprites as shadow casters and derives default shadow sizing from the sprite bounds and hitbox.
When shadows are enabled, map light spots affect them even when the map is not in night mode. Sun shadows are rendered as a directional ambient source, so sprite, character, and Studio element shadows keep the same projection across the map instead of changing with distance. Spot lights are still passed as point lights to SpriteShadows for character shadows, so nearby torches or element lightSpot entries can pull character shadows opposite to the local source according to intensity, radius, and shadowWeight. Studio element shadows keep the sun angle whenever an active sun exists, which keeps trees and props visually aligned across the map. ambientLight overrides the derived sun direction; set it to null or { enabled: false } to disable that directional baseline. In Studio maps, an element with a lightSpot is automatically registered as a local light spot, then used by NightAmbient when night is active and by shadows whenever the spot exists. For sun-driven shadows, the default sun behaves like a directional top-left light so sprite shadows project toward the bottom-right with minimal distance variation. Studio v2 rerenders element shadows when map lighting changes. Studio elements use cached Pixi shadow textures projected from the element sprite silhouette and clipped around the bottom of the hitbox, so the cast shadow follows the object shape instead of a generic blurred circle. The projected tail is tuned shorter than a low-sun cast shadow and the contact occlusion is anchored from the opaque pixels at the base of the sprite, including a compressed footprint from the sprite base with a small overlap behind the sprite so trunks and props stay visually attached to the ground without a large circular blob. Studio v2 renders terrain wall shadows as cached Pixi sprites generated from the bottom of each wall face, with a solid contact base and a softer projected tail. These wall shadows do not use SpriteShadows, so large wall shapes do not become dynamic shadow casters. Studio elements receive automatic sun shadows even when generated map data has hasShadow: false.