2D dynamic lighting

Light2d is a world renderable that cuts through a stage's ambient darkness. The glow and the cutout work on every backend; only per-pixel normal-map shading needs a GPU one. It is 2D-only.

The model: ambient darkness plus cutouts

The Stage holds an ambient colour — a dark sheet painted over the scene after the world is drawn — and each active Light2d punches a hole in it at its visible area. The lights themselves are drawn additively on top.

class PlayScreen extends Stage {
    onResetEvent(app) {
        this.ambientLight.parseCSS("#1a1a2e");     // the darkness

        app.world.addChild(new Light2d(x, y, radiusX, radiusY, "#ffddaa", 0.9));
    }
}

The constructor is Light2d(x, y, radiusX, radiusY = radiusX, color = "#FFF", intensity = 0.7), and pos is the light's centre — its anchorPoint is (0.5, 0.5), and centerX / centerY are overridden to return pos directly. Give radiusY a different value for a stretched, elliptical light.

A Light2d added to the world registers itself with the stage's ambient overlay on activate, so you add it like any other renderable and it takes part in the lighting pass. It draws additively (blendMode = "lighter"); set light.illuminationOnly = true to suppress the visible glow while still lighting normal-mapped sprites.

Stage.ambientLight defaults to fully transparent black, and drawLighting() returns immediately while its alpha is 0 — so with no ambient colour set there is nothing to cut through and the lights just look like soft additive blobs.

Soft edges: softness

A light's hole in the darkness is hard-edged by default: full light inside its radius, full darkness outside. light.softness (0 to 1) fades it instead:

const torch = new Light2d(x, y, 220, 220, "#ffb46a", 0.4);
torch.softness = 0.8;      // lit core of 20% of the radius, then fading out

• 1 thins the darkness straight from the centre to the edge, the same falloff as the glow; in between, a fully lit core of 1 - softness of the radius.
• Hard and soft lights mix in one scene. Where lights overlap, what is left of the darkness is what each leaves, multiplied, so two half-lights make three quarters light.
• The hole is the light's size. For an opening wider than the glow (a torch whose light reaches further than its flame's halo), add a second, bigger light with illuminationOnly = true: it cuts the darkness and draws nothing.
• Up to 32 lights in view are cut by one soft pass; lights outside the view do not count. A scene with no soft light draws exactly as before.
• To keep a camera out of the darkness (a minimap showing the level lit), override drawLighting on the stage and skip that camera.
• To keep one light out of a camera, put it, or a container it is in, on a visibilityLayer the camera's cullMask leaves out: there it neither glows, nor cuts the darkness, nor lights normal-mapped sprites (see melonjs-camera-and-drawing). This is for a Light2d: a Light3d lights the meshes of every camera.

Multiple lights

Add as many as you need — the glow quads and the ambient cutouts accumulate with no fixed cap.

The normal-map pipeline is capped: lights are packed into a std140 uniform block sized for MAX_LIGHTS = 32, and anything past the 32nd is silently dropped from the per-pixel shading (it still draws its glow and punches its cutout). The cap is an allocation, not a budget — the fragment loop still runs once per pixel per live light.

Lights are positioned like any renderable, so they can follow an entity by updating pos, or be added as children of one.

Per-pixel lighting with normal maps

For sprites that respond to light direction rather than just brightness, supply a normal map alongside the diffuse texture:

await loader.preload([
    { name: "hero",     type: "image", src: "data/img/hero.png" },
    { name: "hero_n",   type: "image", src: "data/img/hero_n.png" },
]);

const hero = new Sprite(x, y, {
    image: "hero",
    normalMap: "hero_n",       // ← enables per-pixel lighting on this sprite
    framewidth: 32, frameheight: 32,
});

normalMap takes a loader key, or any image-like source (HTMLImageElement, canvas, ImageBitmap, a Texture2d). Assigning anything else — including an HTMLVideoElement, which would freeze on frame 0 — throws a TypeError.

Normal maps are typically authored in SpriteIlluminator. The sidecar pattern above — one _n image beside each diffuse image — is the simplest setup, but an atlas can carry one too: new TextureAtlas(json, image, { normalMap }) pairs a normal texture sharing the colour texture's UVs, and a Sprite built from that atlas picks it up in preference to its own settings.normalMap.

Specular highlights

A normal map gives a sprite shape: the light knows which way each texel faces, so a torch reveals bumps and crevices. shininess decides whether it also shines:

const sword = new Sprite(x, y, {
    image: "sword",
    normalMap: "sword_n",
    shininess: 64,        // 0 (the default) is matte
});

The difference is what the highlight does. Diffuse brightness depends only on the angle between the surface and the light, so a torch moving past just makes the sprite brighter. A specular highlight only appears where a texel reflects the light toward the screen, so it slides across the surface as the light moves: armour that glints as you walk by, rather than armour that is merely lit.

Low values give a broad sheen (worn metal, wet stone); high values a tight glint (polished steel, glass). It is gated on the exponent exactly as MTL Ns is on the 3D path, so 0 means matte however bright the scene, and a sprite that never sets it renders exactly as it always did.

Three things worth knowing:

• It needs a normalMap. With no surface directions there is nothing to reflect, and the sprite stays matte whatever shininess says.
• The normal map's alpha channel masks it per texel. 255 is fully reflective, 0 is dead matte, so one sprite can be a shiny blade with a matte leather grip. A normal map with no alpha detail (the usual case) shines uniformly. Note the corollary: if your normal map already uses alpha for something, that channel now also decides gloss.
• It accumulates per light. Each light contributes its own highlight in its own colour, so a sprite between a warm lamp and a cool one carries two distinct glints that move independently.

The highlight takes the light's own colour and is added on top of the lit result rather than multiplied into it, which is why a glint blows out toward white on a dark sprite instead of tinting with it.

See it running: Normal Map example.

Unlit areas of a normal-mapped sprite render pure black unless you raise Stage.ambientLightingColor (default black) — that is the base level added to every lit pixel, and it is a different knob from Stage.ambientLight.

Without a normal map a sprite is not shaded at all: it takes the unlit path on every backend, and a light changes how it looks only through its additive glow and its cutout in the ambient darkness.

What needs a GPU backend, and what does not

Less than you would expect. Light2d is renderer-agnostic: it just calls renderer.drawLight(this), and every backend implements it — the GPU backends through a shared procedural radial-falloff shader, the Canvas renderer by rasterising a cached Gradient into one shared render target and compositing it with drawImage. The hard ambient cutout pass is plain setMask + fillRect; the soft one is one shader pass on the GPU backends and an offscreen canvas on Canvas. So the lit-spot look, soft or hard, works everywhere, Canvas included.

What Canvas cannot do is per-pixel normal-map lighting: renderer.setLightUniforms() is a no-op there, and the first frame that passes a non-empty light list logs a one-shot warning. Normal-mapped sprites simply render unlit — no error.

if (app.renderer.shaderLanguage === null) {
    // Canvas fallback: lights and ambient still work, but `normalMap` is ignored
}

Do not combine with Camera3d

Camera3d extends Camera2d and therefore still runs the 2D lighting pass, but nothing in that pass is projection-aware: the ambient fill is a screen-space fillRect, the cutout is a 2D Ellipse mask, and light positions are packed as 2D world coordinates minus the camera translate. Under a perspective projection none of that lines up with what the camera actually draws.

For 3D scenes use Light3d instead — it is the counterpart for the mesh lighting path, with "directional", "ambient", "point" and "spot" types. See the melonjs-3d skill.

Symptom → cause

symptom	cause
lights added but the scene never darkens	no ambient colour set — ambientLight alpha is 0, so the pass returns early
the lit area has a hard rim	softness is 0 (the default): set it on the light
the darkness opens no wider than the glow	the hole is the light's size: add a bigger illuminationOnly light for the opening
a minimap or second camera is dark too	every camera draws the stage's darkness: override drawLighting and skip that camera
a light should show in one camera only	put it on a visibilityLayer the other camera's cullMask leaves out
sprite not shaded by a light, only glowed over	no normalMap on the sprite, or the Canvas backend is active
normal-mapped sprite is pure black where unlit	Stage.ambientLightingColor left at black
the 33rd light shades nothing	MAX_LIGHTS = 32 for the normal-map pipeline
TypeError assigning normalMap	not an image-like value (a video element is rejected outright)
lighting misaligned under a 3D camera	the 2D light pass is not projection-aware — use Light3d

Related skills

• melonjs-3d — Light3d for perspective scenes
• melonjs-sprites-and-animation — sprite settings and atlases