跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

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 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add melonjs/melonJS --skill melonjs-lighting

技能说明


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.

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 s

阅读完整来源 ↗