melonjs-lighting
/melonjs-lighting
Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness.
Original author description
Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness.
How it works
- The model: ambient darkness plus cutouts
- Soft edges: softness
- Multiple lights
- Per-pixel lighting with normal maps
- Specular highlights
- What needs a GPU backend, and what does not
- Do not combine with Camera3d
- Symptom → cause
- Related skills
SKILL.md preview
---
name: melonjs-lighting
description: "Use this skill for 2D dynamic lighting in melonJS — Light2d, ambient light on a Stage, multiple lights, and per-pixel normal-mapped sprites authored in SpriteIlluminator. Covers specular highlights via shininess, the ambient-cutout model, which parts need a GPU backend, and why Light2d does not survive a Camera3d. Triggers on: Light2d, specular, shininess, highlight, glint, lighting, ambientLight, ambientLightingColor, normalMap, SpriteIlluminator, per-pixel lighting, drawLight, torch, glow, darkness."
license: MIT
---
# 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.
```js
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:
```js
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:
```js
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**:
```js
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](https://melonjs.github.io/melonJS/examples/#/normal-map).
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.
```js
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
Versions
The database has no other skills named melonjs-lighting.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version a81a279c5a09 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100unity-2d-lighting
Unity 2D lighting — URP 2D Renderer, Light 2D types (Point/Freeform/Sprite/ Parametric/Global), Shadow Casters 2D, Sprite Mask, Renderer2DData, normal mapped sprites, blend styles. USE WHEN: setting up the URP 2D Renderer, lighting a 2D scene, adding 2D shadows, using Sprite… - 100threejs-lighting
Three.js lighting - light types, shadows, environment lighting. Use when adding lights, configuring shadows, setting up IBL, or optimizing lighting performance. - 100threejs-lighting
Three.js lighting - light types, shadows, environment lighting. Use when adding lights, configuring shadows, setting up IBL, or optimizing lighting performance. - 100threejs-lighting
Three.js lighting - light types, shadows, environment lighting. Use when adding lights, configuring shadows, setting up IBL, or optimizing lighting performance. - 100light-scene
Use when lighting or rendering a PlayCanvas scene, covering lights, ambient and environment lighting, sky, shadows, tone mapping, exposure, fog, and post-processing. - 90pixel-normals
Generate normal maps for pixel-art sprites, sprite sheets, GIFs and APNGs so 2D game art reacts to dynamic lights. Use when the user wants normal maps, 2.5D lighting, or lit sprites for Godot, Unity, Phaser, or a custom engine.