feat(lights): WebGL-native procedural Light2d shader (closes #1430)

[obiot]

Closes #1430.

Summary

Replace Light2d's per-light "build a radial gradient on an offscreen canvas, upload as a GL texture, drawImage every frame" pipeline with a procedural fragment shader on WebGL and a renderer-owned Gradient cache on Canvas. Light2d itself becomes pure data — no shader knowledge, no canvas allocation, no renderer reference held.

Architecture

Mirrors the drawImage API surface — same shape on both renderers, very different machinery underneath:

• Renderer.drawLight(light) — base no-op for polymorphism.
• WebGLRenderer.drawLight(light) — quads through a shared RadialGradientEffect fragment shader, routed through the standard addQuad batching path. Per-light color and intensity flow through the per-vertex tint attribute (RGB = color, A = intensity), so consecutive drawLight calls accumulate in the quad batcher and flush together: N lights = 1 program switch + 1 flush, instead of 2N + N. Lazy 1×1 white TextureAtlas as the no-op uSampler source, shared across every light. No per-light GL texture.
• CanvasRenderer.drawLight(light) — caches a small Gradient config object per Light2d in a WeakMap (rebuilt only when radii / color / intensity change), rasterizes via Gradient.toCanvas() into a single shared CanvasRenderTarget, composites with drawImage. The render target is one-per-engine, so the heavy bitmap memory stays at O(1) regardless of how many lights are active.
• Light2d.draw(renderer) collapses to one line: renderer.drawLight(this).

Falloff curve is linear (f = clamp(1 - d, 0, 1)) — matches Canvas's createRadialGradient two-stop interpolation exactly to preserve visual parity for users with calibrated scenes.

What's new

• RadialGradientEffect (src/video/webgl/effects/radialGradient.js) — generic procedural radial-gradient ShaderEffect. Constructor accepts { color, intensity }, plus setColor / setIntensity setters. Color/intensity stack from two sources multiplied together: the uColor / uIntensity uniforms (the natural API for a single-instance shader attached to a renderable) AND the per-vertex aColor tint (used by WebGLRenderer.drawLight to encode per-light state in the vertex stream so multiple lights sharing this shader batch into a single draw call).
• Light2d.setRadii(radiusX, radiusY) — fixes the latent bug where mutating radiusX/Y post-construction left the rendered light stale while getVisibleArea() (the cutout pass) tracked the new size. Named setRadii (not resize) so it doesn't shadow Renderable.resize(width, height).
• Light2d reduced to pure data — no texture field, no createGradient call, no CanvasRenderTarget import. Constructor allocates only the Color + Ellipse pool entries.

Latent bugs caught and fixed in flight

• WebGLRenderer.setBatcher stale-custom-shader leak — the previous fast path returned early when the active batcher matched and no shader was provided, so a custom shader bound by a prior call (post-effect FBO blit, etc.) could stay bound and silently render the next sprite batch through the wrong program. setBatcher now always reconciles to either the explicitly-passed shader or the batcher's defaultShader.
• QuadBatcher.blitTexture / LitQuadBatcher.blitTexture texture-unit desync — both methods called gl.activeTexture(TEXTURE0) directly without updating currentTextureUnit / boundTextures[0]. Subsequent bindTexture2D calls could short-circuit on the stale cache and bind on the wrong unit. Both now sync the cache on bind and reset on unbind.

Wins

• Zero per-light GL texture — multi-texture batching no longer fights "one slot per light".
• N consecutive lights = 1 program switch + 1 flush on WebGL — vs the original "one upload + drawImage per light".
• Sharp at any camera zoom — procedural, not bitmap.
• Reactive to property mutation — Canvas-side cache invalidates automatically on radiusX/radiusY/color/intensity change; WebGL reads live and packs into the vertex tint each call, so there's nothing to invalidate.
• Light2d is renderer-agnostic — future renderers (WebGPU, custom) just implement drawLight(light) once.

Test plan

• 86 test files / 2909 tests pass (existing 2897 + 12 new).
• pnpm build clean (lint + types + bundle).
• New tests pin: no per-light texture in Light2d constructor; Canvas cache hit / re-bake on setRadii / re-bake on color or intensity change; cache cleared on CanvasRenderer.reset(); base Renderer.drawLight polymorphism; RadialGradientEffect standalone construction in a WebGL-init describe; Canvas drawLight uses Gradient.toCanvas (transform-isolated) not toCanvasGradient (transform-anchored); WebGL drawLight drains pending sprite vertices before binding the light shader; WebGL drawLight batches consecutive lights into a single flush + single program switch; WebGL drawLight uses the per-vertex tint, never calls setColor / setIntensity per light.
• Visual: Lights example on WebGL with addPostEffect(VignetteEffect) + addPostEffect(ScanlineEffect) chain — confirmed lights render inside the camera's multi-pass post-effect FBO bracket (scanlines ride through both spotlights, vignette darkens uniformly).
• Visual: Lights example on video.CANVAS — new Gradient.toCanvas + drawImage path matches WebGL.
• Visual: Normal Map + SpriteIlluminator examples — lit pipeline still illuminates correctly; the setBatcher reconciliation does not interact badly with the lit batcher.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refactors Light2d rendering to be renderer-driven via a new Renderer.drawLight(light) API, replacing the previous per-light offscreen-canvas + GL-texture upload workflow on WebGL with a procedural fragment-shader approach while keeping a cached offscreen-canvas bake on Canvas.

Changes:

• Added Renderer.drawLight(light) (base no-op) and implemented renderer-specific drawLight paths for WebGL (procedural shader) and Canvas (WeakMap-cached gradient bake).
• Introduced Light2dEffect (a ShaderEffect subclass) and updated Light2d.draw() to delegate rendering to the renderer; added Light2d.resize(radiusX, radiusY) to keep bounds in sync with radii changes.
• Updated tests and changelog to reflect the new rendering architecture and cache behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/melonjs/src/video/renderer.js	Adds the new polymorphic drawLight(light) API as a base no-op.
packages/melonjs/src/video/webgl/webgl_renderer.js	Implements drawLight via a shared Light2dEffect and a lazily-created 1×1 white texture.
packages/melonjs/src/video/webgl/effects/light2d.js	Adds the procedural radial-falloff shader effect and its setter-based API.
packages/melonjs/src/video/canvas/canvas_renderer.js	Moves gradient baking into the renderer with a per-light WeakMap cache and invalidation logic.
packages/melonjs/src/renderable/light2d.js	Removes per-light texture allocation; delegates draw to renderer.drawLight; adds resize.
packages/melonjs/tests/lights.spec.js	Updates Light2d draw expectations and adds cache-related tests (plus intended Light2dEffect tests).
packages/melonjs/CHANGELOG.md	Documents the new rendering pipeline, new API, and Light2d.resize.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/video/webgl/webgl_renderer.js:666

• _getWhitePixel() creates and retains a WebGLTexture but there’s no corresponding cleanup on renderer reset/context restore, so the instance can hold an invalid texture handle (and leak GPU resources on normal teardown). Ensure this texture is deleted (via gl.deleteTexture) and/or _whitePixel is cleared when the renderer is reset/destroyed.

		// flush pending draws BEFORE creating/resizing FBOs,
		// since FBO construction temporarily changes GL framebuffer bindings
		this.flush();
		this.save();
		// save the current projection (not part of the render state stack)
		this._savedEffectProjection.copy(this.projectionMatrix);

		const rt = this._renderTargetPool.begin(isCamera, effects.length, w, h);
		// FBO creation/resize uses TEXTURE0 — invalidate the batcher's cache for that unit
		if (this.currentBatcher && this.currentBatcher.boundTextures) {
			delete this.currentBatcher.boundTextures[0];
		}
		rt.bind();
		this.setViewport(0, 0, w, h);
		this.disableScissor();
		this.setGlobalAlpha(1.0);
		this.setBlendMode("normal");

		if (isCamera) {
			this.clear();
		} else {
			this.clearRenderTarget();
		}

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

packages/melonjs/src/video/webgl/batchers/quad_batcher.js:233

• blitTexture() calls gl.activeTexture(gl.TEXTURE0) / gl.bindTexture(...) directly, but it does not synchronize MaterialBatcher's internal texture-unit tracking (currentTextureUnit, boundTextures, etc.). This can desync the batcher state vs. real GL state (especially after multi-texture draws) and cause subsequent texture binds to hit the wrong unit. Consider resetting/synchronizing the batcher’s texture-unit bookkeeping around the blit (e.g., set currentTextureUnit to 0 before binding and/or force it to -1 after unbinding so the next bind re-activates the correct unit).

	blitTexture(source, x, y, width, height, shader) {
		const gl = this.gl;

		this.useShader(shader);

		// bind the source texture to unit 0
		gl.activeTexture(gl.TEXTURE0);
		gl.bindTexture(gl.TEXTURE_2D, source);
		shader.setUniform("uSampler", 0);

		// push a screen-aligned quad with Y-flipped UVs, transformed by
		// the current renderer transform. `WebGLRenderer.blitEffect` resets
		// `currentTransform` to identity before calling so FBO blits are
		// unaffected; world-space callers (e.g. `drawLight`) get the
		// `preDraw` translate / scale applied automatically.
		const m = this.viewMatrix;
		const vec0 = V_ARRAY[0].set(x, y);
		const vec1 = V_ARRAY[1].set(x + width, y);
		const vec2 = V_ARRAY[2].set(x, y + height);
		const vec3 = V_ARRAY[3].set(x + width, y + height);
		if (m && !m.isIdentity()) {
			m.apply(vec0);
			m.apply(vec1);
			m.apply(vec2);
			m.apply(vec3);
		}

		const tint = 0xffffffff;
		this.vertexData.push(vec0.x, vec0.y, 0, 1, tint, 0);
		this.vertexData.push(vec1.x, vec1.y, 1, 1, tint, 0);
		this.vertexData.push(vec2.x, vec2.y, 0, 0, tint, 0);
		this.vertexData.push(vec3.x, vec3.y, 1, 0, tint, 0);

		this.flush();

		// unbind the texture to prevent feedback loop on next frame
		gl.activeTexture(gl.TEXTURE0);
		gl.bindTexture(gl.TEXTURE_2D, null);
		delete this.boundTextures[0];

		// restore the default shader (also re-enables multi-texture batching)
		this.useShader(this.defaultShader);
	}

packages/melonjs/src/video/webgl/batchers/lit_quad_batcher.js:372

• Same issue as QuadBatcher.blitTexture: this override uses gl.activeTexture(gl.TEXTURE0) / gl.bindTexture(...) directly without updating the batcher’s internal texture unit bookkeeping (currentTextureUnit, boundTextures, etc.). That can leave GL state and batcher state inconsistent and break subsequent texture binds/draws. Please synchronize/reset the batcher tracking around this blit.

	blitTexture(source, x, y, width, height, shader) {
		const gl = this.gl;

		this.useShader(shader);

		gl.activeTexture(gl.TEXTURE0);
		gl.bindTexture(gl.TEXTURE_2D, source);
		shader.setUniform("uSampler", 0);

		// transform corners through the renderer transform — see
		// `QuadBatcher.blitTexture` for the rationale (FBO callers reset
		// `currentTransform` to identity, world-space callers get the
		// translate/scale applied).
		const m = this.viewMatrix;
		const vec0 = V_ARRAY[0].set(x, y);
		const vec1 = V_ARRAY[1].set(x + width, y);
		const vec2 = V_ARRAY[2].set(x, y + height);
		const vec3 = V_ARRAY[3].set(x + width, y + height);
		if (m && !m.isIdentity()) {
			m.apply(vec0);
			m.apply(vec1);
			m.apply(vec2);
			m.apply(vec3);
		}

		const tint = 0xffffffff;
		this.vertexData.push(vec0.x, vec0.y, 0, 1, tint, 0, -1);
		this.vertexData.push(vec1.x, vec1.y, 1, 1, tint, 0, -1);
		this.vertexData.push(vec2.x, vec2.y, 0, 0, tint, 0, -1);
		this.vertexData.push(vec3.x, vec3.y, 1, 0, tint, 0, -1);

		this.flush();

		gl.activeTexture(gl.TEXTURE0);
		gl.bindTexture(gl.TEXTURE_2D, null);
		delete this.boundTextures[0];

		this.useShader(this.defaultShader);
	}

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.