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.
melonjs · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add melonjs/melonJS --skill melonjs-lightingAbout this skill
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
Light2dis 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
1thins the darkness straight from the centre to the edge, the same falloff as the glow; in between, a fully lit core of1 - softnessof 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
drawLightingon the stage and skip that camera. - To keep one light out of a camera, put it, or a container it is in, on a
visibilityLayerthe camera'scullMaskleaves out: there it neither glows, nor cuts the darkness, nor lights normal-mapped sprites (seemelonjs-camera-and-drawing). This is for aLight2d: aLight3dlights 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 s
Read the complete source ↗