feat(webgl)!: WebGL 2 only renderer + Vertex Array Objects (#1509)

Phase 0 of the WebGPU groundwork: drop the WebGL 1 path and give every
batcher an immutable vertex state, so the layout description stops being
re-issued per draw and starts looking like a pipeline descriptor.

BREAKING: the WebGL renderer now requires WebGL 2.
- `video.AUTO` falls back to the Canvas renderer on WebGL-1-only devices;
  `video.WEBGL` throws there
- `preferWebGL1` setting and the `#webgl1` URL flag removed
- `device.isWebGLSupported()` probes for WebGL 2 — it now agrees with what
  renderer construction actually requests (it probed WebGL 1 before, so
  the gate and the context could disagree)
- `renderer.type` is always "WebGL2"; `renderer.WebGLVersion` deprecated
- corrections on ex-WebGL-1 configs: NPOT `repeat` genuinely tiles,
  darken/lighten use true MIN/MAX, `createPattern()` accepts NPOT
- user shaders need NO changes: GLSL ES 1.00 compiles on WebGL 2 contexts

Vertex Array Objects:
- new `WebGLVertexState` (buffer/vertexstate.js, sibling of
  WebGLIndexBuffer) owns the VAO lifecycle; its binding save/restore is
  private, so no caller can half-apply the protocol
- built from a {attributes, stride, buffer, indexBuffer} descriptor — a
  GPUVertexBufferLayout + arrayStride, so #1492 becomes a class swap
- batcher switches cost one bindVertexArray; steady-state frames issue
  zero attribute-specification calls (19 at startup, 0 per frame after)
- the attribute-leak machinery is gone: state is swapped, not disabled
- custom shaders on a built-in batcher must declare that batcher's
  attributes first, in layout order — warns once per shader on mismatch
- TMX GPU tilemap eligibility now uses `renderer.supportsShaderTileLayers`
  (a backend capability flag) instead of a WebGL-version check

Tests: 6 new specs (vertex-state units, VAO state/call-counts/recreation/
contract/adversarial, teardown), the attribute-leak spec retired and its
invariant re-expressed, 4888 passing.

Closes #1509

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JvxaXQRgQn5AoR8DNkv6Wg

Author: obiot

packages/melonjs/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [20.0.0] (melonJS 2) - _unreleased_
+
+### Changed (breaking)
+- **The WebGL renderer is now WebGL 2 only** ([#1509](https://github.com/melonjs/melonJS/issues/1509)) — the WebGL 1 fallback path is removed. `renderer: video.AUTO` falls back to the Canvas renderer on WebGL-1-only devices; `renderer: video.WEBGL` throws there. **User shaders need no changes** — `ShaderEffect` bodies and raw `GLShader` sources (GLSL ES 1.00) compile unchanged on WebGL 2 contexts.
+- `preferWebGL1` setting and the `#webgl1` URI flag are removed (`#webgl` / `#webgl2` are synonyms)
+- `device.isWebGLSupported()` now probes for a WebGL **2** context — it finally agrees with what renderer construction actually requests (the gate probed WebGL 1 before, so the two could disagree)
+- `renderer.type` is always `"WebGL2"` for the WebGL renderer; `renderer.WebGLVersion` is deprecated (always `2`)
+- behavior corrections on ex-WebGL-1 configs: `repeat` wrap now genuinely tiles non-power-of-two textures (was clamp + warning), `"darken"` / `"lighten"` blend modes use true MIN/MAX equations (were silently downgraded to `"normal"`), and `createPattern()` accepts non-power-of-two sources (threw before)
+- TMX GPU tilemap eligibility is now advertised through `renderer.supportsShaderTileLayers` (a backend capability flag) instead of a WebGL-version check
+- **each `Batcher` now owns an immutable Vertex Array Object** built at init ([#1509](https://github.com/melonjs/melonJS/issues/1509)): vertex attribute layout is frozen once built, batcher switches cost a single `bindVertexArray` (steady-state frames issue zero attribute-specification calls, measured), and `Batcher.unbind()` no longer disables attribute arrays. Custom batchers inheriting `Batcher.init()`/`bind()` need no changes. Custom shaders hosted by a built-in batcher must declare that batcher's attributes first, in layout order (ShaderEffect-generated vertex shaders already comply) — a console warning fires on mismatch. `GLShader.setVertexAttributes` is no longer called by the engine (still public)
+
+### Performance
+- **Vertex Array Objects for every batcher** ([#1509](https://github.com/melonjs/melonJS/issues/1509)) — vertex attribute layout is specified once at init rather than on every batcher switch and every mesh flush, so steady-state frames issue **zero** attribute-specification calls. How much GL traffic this saves depends on how often a scene alternates batchers: a scene that stays on one batcher saves about 2 calls per frame, one mixing sprites, meshes and primitives about 40 — in both cases well under a millisecond. The structural benefit is the larger one: attribute-state leaks between batchers become impossible by construction.
+
 ## [19.9.1] (melonJS 2) - _2026-07-28_
 
 ### Fixed

packages/melonjs/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "melonjs",
-	"version": "19.9.1",
+	"version": "20.0.0",
 	"description": "melonJS Game Engine",
 	"homepage": "http://www.melonjs.org/",
 	"type": "module",

packages/melonjs/src/application/application.ts

@@ -316,16 +316,11 @@ export default class Application {
 		} as ResolvedApplicationSettings;
 
 		// override renderer settings if &webgl or &canvas is defined in the URL
+		// (the WebGL renderer is WebGL 2 only since 20.0 — the legacy
+		// `#webgl1` flag is gone, `#webgl`/`#webgl2` are synonyms)
 		const uriFragment = getUriFragment();
-		if (
-			uriFragment.webgl === true ||
-			uriFragment.webgl1 === true ||
-			uriFragment.webgl2 === true
-		) {
+		if (uriFragment.webgl === true || uriFragment.webgl2 === true) {
 			settings.renderer = WEBGL;
-			if (uriFragment.webgl1 === true) {
-				settings.preferWebGL1 = true;
-			}
 		} else if (uriFragment.canvas === true) {
 			settings.renderer = CANVAS;
 		}
@@ -381,10 +376,11 @@ export default class Application {
 					if (!device.isWebGLSupported(this.settings)) {
 						throw new Error(
 							"Application: `renderer: video.WEBGL` was requested " +
-								"but the WebGL context could not be created in this " +
-								"environment (driver-blocklisted GPU, " +
-								"`failIfMajorPerformanceCaveat: true` on a software " +
-								"renderer, etc.). Use `video.AUTO` if Canvas " +
+								"but a WebGL 2 context could not be created in this " +
+								"environment (WebGL-1-only device, driver-blocklisted " +
+								"GPU, `failIfMajorPerformanceCaveat: true` on a " +
+								"software renderer, etc.). The WebGL renderer is " +
+								"WebGL 2 only since 20.0. Use `video.AUTO` if Canvas " +
 								"fallback is acceptable, or check " +
 								"`device.isWebGLSupported()` before construction.",
 						);

packages/melonjs/src/application/defaultApplicationSettings.ts

@@ -6,7 +6,6 @@ export const defaultApplicationSettings = {
 	renderer: AUTO,
 	scale: 1.0,
 	scaleMethod: ScaleMethods.Manual,
-	preferWebGL1: false,
 	powerPreference: "default",
 	transparent: false,
 	antiAlias: false,

packages/melonjs/src/application/settings.ts

@@ -32,20 +32,21 @@ type PhysicsType =
 	| PhysicsAdapter
 	| { adapter: PhysicsAdapter };
 
-type PowerPreference = "default" | "low-power";
+type PowerPreference = "default" | "low-power" | "high-performance";
 
 export type ApplicationSettings = {
 	/**
 	 * Renderer to use. Three built-in modes (constants from `me.video`):
 	 *
 	 * - {@link CANVAS} — HTML5 Canvas backend. No shader / mesh /
 	 *   Camera3d support.
-	 * - {@link WEBGL} — **requires WebGL**. Throws at `new Application(...)`
-	 *   time if WebGL is unavailable (driver-blocklisted GPU, perf-caveat
-	 *   failure, etc.). Use this when your scene needs Camera3d, Mesh,
-	 *   ShaderEffect, Light2d or GPU tilemap — you'd rather fail fast
-	 *   than render a stuck blank canvas.
-	 * - {@link AUTO} — try WebGL, silently fall back to Canvas if
+	 * - {@link WEBGL} — **requires WebGL 2** (the WebGL renderer is
+	 *   WebGL 2 only since 20.0). Throws at `new Application(...)`
+	 *   time if a WebGL 2 context is unavailable (WebGL-1-only device,
+	 *   driver-blocklisted GPU, perf-caveat failure, etc.). Use this when
+	 *   your scene needs Camera3d, Mesh, ShaderEffect, Light2d or GPU
+	 *   tilemap — you'd rather fail fast than render a stuck blank canvas.
+	 * - {@link AUTO} — try WebGL 2, silently fall back to Canvas if
 	 *   unavailable. Application construction always succeeds. The
 	 *   WebGL-only subsystems (Camera3d, Mesh, ShaderEffect, Light2d,
 	 *   GPU tilemap) silently stop working under the Canvas fallback —
@@ -74,14 +75,20 @@ export type ApplicationSettings = {
 	scaleTarget: HTMLElement;
 
 	/**
-	 * if true the renderer will only use WebGL 1
-	 * @default false
-	 */
-	preferWebGL1: boolean;
-
-	/**
-	 * a hint to the user agent indicating what configuration of GPU is suitable for the WebGL context. To be noted that Safari and Chrome (since version 80) both default to "low-power" to save battery life and improve the user experience on these dual-GPU machines.
-	 * @default default
+	 * A hint to the user agent about which GPU to use on multi-GPU systems
+	 * (discrete vs integrated). Browsers generally favour the low-power GPU
+	 * unless asked otherwise, to preserve battery life.
+	 *
+	 * - `"default"` — no hint; let the user agent decide.
+	 * - `"low-power"` — prefer the integrated GPU.
+	 * - `"high-performance"` — prefer the discrete GPU. Note that browsers
+	 *   only honour this for pages that handle context loss, since switching
+	 *   GPU can drop the context; melonJS registers those handlers itself,
+	 *   so the request is respected.
+	 *
+	 * The same hint (and the same values, minus `"default"`) is used by
+	 * WebGPU's adapter request, so this setting is backend-neutral.
+	 * @default "default"
 	 */
 	powerPreference: PowerPreference;
 
@@ -166,7 +173,7 @@ export type ApplicationSettings = {
 	 * When `true` (default), eligible layers render via a single quad per
 	 * tileset + a fragment shader doing per-fragment GID lookup, bypassing
 	 * the per-tile draw loop entirely. Layers that don't qualify
-	 * (Canvas/WebGL1, non-orthogonal, collection-of-image tilesets,
+	 * (Canvas renderer, non-orthogonal, collection-of-image tilesets,
 	 * tilerendersize "grid", non-zero tileoffset, oversampled beyond the
 	 * shader's overflow window) fall back to the legacy path automatically.
 	 * Set to `false` to disable globally.

packages/melonjs/src/lang/deprecated.js

@@ -21,7 +21,7 @@ export class CanvasTexture extends CanvasRenderTarget {
 	 * @param {number} width - the desired width of the canvas
 	 * @param {number} height - the desired height of the canvas
 	 * @param {object} attributes - The attributes to create both the canvas and context
-	 * @param {boolean} [attributes.context="2d"] - the context type to be created ("2d", "webgl", "webgl2")
+	 * @param {boolean} [attributes.context="2d"] - the context type to be created ("2d", "webgl" — creates a WebGL 2 context)
 	 * @param {boolean} [attributes.offscreenCanvas=false] - will create an offscreenCanvas if true instead of a standard canvas
 	 * @param {boolean} [attributes.willReadFrequently=false] - Indicates whether or not a lot of read-back operations are planned
 	 * @param {boolean} [attributes.antiAlias=false] - Whether to enable anti-aliasing, use false (default) for a pixelated effect.

packages/melonjs/src/level/tiled/TMXLayer.js

@@ -22,7 +22,7 @@ const FLIP_AD_BIT = 1 << 2;
 // the fallback so apps without any tilemap stay quiet (the prior heads-up
 // at Application init time fired regardless of whether a TMX layer was
 // ever loaded).
-let _warnedNoWebGL2Once = false;
+let _warnedNoGpuTileSupportOnce = false;
 
 /**
  * extract a 3-bit flip mask from a raw 32-bit GID (Tiled's flip bits live in
@@ -409,11 +409,11 @@ export default class TMXLayer extends Renderable {
 		// — emitted from the first TMX layer that hits it, so apps with
 		// no tilemap loaded stay quiet.
 		if (gpuAllowed) {
-			if (elig.reason === "no-webgl2-renderer") {
-				if (!_warnedNoWebGL2Once) {
-					_warnedNoWebGL2Once = true;
+			if (elig.reason === "no-gpu-renderer") {
+				if (!_warnedNoGpuTileSupportOnce) {
+					_warnedNoGpuTileSupportOnce = true;
 					console.warn(
-						"melonJS: gpuTilemap is enabled but the active renderer is not WebGL 2 — falling back to the legacy tile renderer for every tile layer",
+						"melonJS: gpuTilemap is enabled but the active renderer has no GPU tile-layer support — falling back to the legacy tile renderer for every tile layer",
 					);
 				}
 			} else {
@@ -440,8 +440,8 @@ export default class TMXLayer extends Renderable {
 		if (!gpuAllowed) {
 			return { ok: false, reason: "gpuTilemap disabled" };
 		}
-		if (!renderer || renderer.WebGLVersion !== 2) {
-			return { ok: false, reason: "no-webgl2-renderer" };
+		if (!renderer || renderer.supportsShaderTileLayers !== true) {
+			return { ok: false, reason: "no-gpu-renderer" };
 		}
 		if (this.orientation !== "orthogonal") {
 			return {

packages/melonjs/src/system/device.ts

@@ -655,10 +655,13 @@ export function isWebGLSupported(options?: {
 					failIfMajorPerformanceCaveat: options.failIfMajorPerformanceCaveat,
 				}),
 			};
+			// WebGL 2 only since 20.0 (#1509) — this gate must agree with
+			// the context actually created by the WebGL renderer (which
+			// requests "webgl2"), so AUTO falls back to Canvas exactly when
+			// renderer construction would fail
 			const _supported = !!(
-				globalThis.WebGLRenderingContext &&
-				(canvas.getContext("webgl", ctxOptions) ||
-					canvas.getContext("experimental-webgl", ctxOptions))
+				globalThis.WebGL2RenderingContext &&
+				canvas.getContext("webgl2", ctxOptions)
 			);
 			WebGLSupport = _supported ? 1 : 0;
 		} catch {

packages/melonjs/src/video/renderer.js

@@ -110,6 +110,17 @@ export default class Renderer {
 		 */
 		this.type = "Generic";
 
+		/**
+		 * Whether this renderer backend can draw TMX tile layers through a
+		 * GPU shader path (see the `gpuTilemap` application setting).
+		 * `false` here on the base/Canvas renderer; GPU backends flip it.
+		 * A capability flag rather than a version/class check so future
+		 * backends advertise support without consumers growing type checks.
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.supportsShaderTileLayers = false;
+
 		/**
 		 * The background color used to clear the main framebuffer.
 		 * Note: alpha value will be set based on the transparent property of the renderer settings.

packages/melonjs/src/video/rendertarget/canvasrendertarget.js

@@ -20,13 +20,9 @@ const defaultAttributes = {
 	stencil: true,
 	blendMode: "normal",
 	failIfMajorPerformanceCaveat: true,
-	preferWebGL1: false,
 	powerPreference: "default",
 };
 
-// WebGL version (if a gl context is created)
-let WebGLVersion;
-
 // a helper function to create the 2d/webgl context
 function createContext(canvas, attributes) {
 	let context;
@@ -50,24 +46,13 @@ function createContext(canvas, attributes) {
 			failIfMajorPerformanceCaveat: attributes.failIfMajorPerformanceCaveat,
 		};
 
-		// attempt to create a WebGL2 context unless not requested
-		if (attributes.preferWebGL1 !== true) {
-			context = canvas.getContext("webgl2", attr);
-			if (context) {
-				WebGLVersion = 2;
-			}
-		}
+		// WebGL 2 only since 20.0 (#1509) — no WebGL 1 fallback; callers
+		// (autoDetectRenderer / Application) fall back to the Canvas
+		// renderer instead when this throws
+		context = canvas.getContext("webgl2", attr);
 
-		// fallback to WebGL1
 		if (!context) {
-			WebGLVersion = 1;
-			context =
-				canvas.getContext("webgl", attr) ||
-				canvas.getContext("experimental-webgl", attr);
-		}
-
-		if (!context) {
-			throw new Error("A WebGL context could not be created.");
+			throw new Error("A WebGL 2 context could not be created.");
 		}
 	} else {
 		throw new Error("Invalid context type. Must be one of '2d' or 'webgl'");
@@ -89,8 +74,7 @@ class CanvasRenderTarget extends RenderTarget {
 	 * @param {number} width - the desired width of the canvas
 	 * @param {number} height - the desired height of the canvas
 	 * @param {object} attributes - The attributes to create both the canvas and context
-	 * @param {string} [attributes.context="2d"] - the context type to be created ("2d", "webgl")
-	 * @param {boolean} [attributes.preferWebGL1=false] - set to true for force using WebGL1 instead of WebGL2 (if supported)
+	 * @param {string} [attributes.context="2d"] - the context type to be created ("2d", "webgl" — a "webgl" request creates a WebGL 2 context)
 	 * @param {boolean} [attributes.transparent=false] - specify if the canvas contains an alpha channel
 	 * @param {boolean} [attributes.offscreenCanvas=false] - will create an offscreenCanvas if true instead of a standard canvas
 	 * @param {boolean} [attributes.willReadFrequently=false] - Indicates whether or not a lot of read-back operations are planned
@@ -120,7 +104,14 @@ class CanvasRenderTarget extends RenderTarget {
 		// create the context
 		this.context = createContext(this.canvas, this.attributes);
 
-		this.WebGLVersion = WebGLVersion;
+		if (this.attributes.context === "webgl") {
+			/**
+			 * The WebGL version of the created context.
+			 * @type {number}
+			 * @deprecated since 20.0.0 — the WebGL renderer is WebGL 2 only, this is always `2`
+			 */
+			this.WebGLVersion = 2;
+		}
 
 		// enable or disable antiAlias if specified
 		this.setAntiAlias(this.attributes.antiAlias);