WebGL renderer: index buffer batching, increased batch size, and rename and deprecate Compositor

1. Index buffer batching — Quad rendering now uses gl.drawElements with a static index buffer instead of gl.drawArrays, pushing 4 vertices per quad instead of 6 (33% less vertex data). New IndexBuffer utility class under buffer/ with WebGL2 Uint32 / WebGL1 Uint16 support.                                                                                                                              
2. Increased batch size — Vertex batch size increased from 256 to 4096 (1024 quads), matching industry standard. Defined as a   MAX_VERTICES constant in the batcher.                                                                                                 
3. Fixed-size vertex buffer — VertexArrayBuffer no longer auto-resizes; it's allocated once at a fixed size. Removed dead resize(), length(), isEmpty() methods and simplified push().                                                                                    
4. setCompositor fast path — Early-return when the compositor and shader are already active, avoiding unnecessary flushes and binds on every draw call.                                                                                                                     
5. Naming cleanup — Renamed compositors/ → batchers/, Compositor → Batcher, QuadCompositor → QuadBatcher, PrimitiveCompositor →  PrimitiveBatcher, vertexByteSize → stride. Old names preserved as deprecated aliases in deprecated.js.
6. Tests — Expanded VertexArrayBuffer tests (22 tests) and added new IndexBuffer test suite (9 tests).

Author: obiot

packages/melonjs/CHANGELOG.md

@@ -36,6 +36,11 @@
 - WebGLRenderer: `fillPolygon` now uses `Polygon.getIndices()` cached earcut results instead of rebuilding the path each frame
 - WebGLRenderer: skip redundant `gl.uniform1i` sampler call in `QuadCompositor.addQuad()` when consecutive quads share the same texture unit
 - WebGLRenderer: replace per-frame `clone()`/`push()`/`pop()` allocations in save/restore with zero-allocation `RenderState` stacks
+- WebGLRenderer: switch quad rendering from `gl.drawArrays` (6 vertices per quad) to `gl.drawElements` with a static index buffer (4 vertices + 6 indices per quad), reducing vertex data by 33%
+- WebGLRenderer: increase vertex batch size from 256 (64 quads) to 4096 (1024 quads), reducing draw calls for sprite-heavy and tile-heavy scenes
+
+### Changed
+- WebGLRenderer: `Compositor`, `QuadCompositor`, and `PrimitiveCompositor` are now deprecated in favor of `Batcher`, `QuadBatcher`, and `PrimitiveBatcher`
 
 ## [18.0.0] (melonJS 2) - _2026-03-10_
 

packages/melonjs/src/application/settings.ts

@@ -5,7 +5,7 @@
 
 import { RendererType } from "../const";
 import Renderer from "../video/renderer";
-import Compositor from "../video/webgl/compositors/compositor";
+import { Batcher } from "../video/webgl/batchers/batcher";
 import { ScaleMethod } from "./scaleMethods";
 
 type BlendMode = "normal" | "multiply" | "lighter" | "additive" | "screen";
@@ -88,9 +88,9 @@ export type ApplicationSettings = {
 	legacy: boolean;
 
 	/**
-	 * a custom compositor class (WebGL only)
+	 * a custom batcher class (WebGL only)
 	 */
-	compositor?: Compositor | undefined;
+	compositor?: Batcher | undefined;
 } & (
 	| {
 			// the DOM parent element to hold the canvas in the HTML file

packages/melonjs/src/index.js

@@ -59,9 +59,9 @@ import Renderer from "./video/renderer.js";
 import RenderState from "./video/renderstate.js";
 import CanvasRenderTarget from "./video/rendertarget/canvasrendertarget.js";
 import { TextureAtlas } from "./video/texture/atlas.js";
-import Compositor from "./video/webgl/compositors/compositor.js";
-import PrimitiveCompositor from "./video/webgl/compositors/primitive_compositor.js";
-import QuadCompositor from "./video/webgl/compositors/quad_compositor.js";
+import { Batcher } from "./video/webgl/batchers/batcher.js";
+import PrimitiveBatcher from "./video/webgl/batchers/primitive_batcher.js";
+import QuadBatcher from "./video/webgl/batchers/quad_batcher.js";
 import GLShader from "./video/webgl/glshader.js";
 import WebGLRenderer from "./video/webgl/webgl_renderer.js";
 
@@ -103,9 +103,9 @@ export {
 	Tween,
 	QuadTree,
 	GLShader,
-	Compositor,
-	PrimitiveCompositor,
-	QuadCompositor,
+	Batcher,
+	PrimitiveBatcher,
+	QuadBatcher,
 	Renderer,
 	RenderState,
 	WebGLRenderer,

packages/melonjs/src/lang/deprecated.js

@@ -1,5 +1,8 @@
 import CanvasRenderer from "../video/canvas/canvas_renderer.js";
 import CanvasRenderTarget from "../video/rendertarget/canvasrendertarget.js";
+import { Batcher } from "../video/webgl/batchers/batcher.js";
+import PrimitiveBatcher from "../video/webgl/batchers/primitive_batcher.js";
+import QuadBatcher from "../video/webgl/batchers/quad_batcher.js";
 import WebGLRenderer from "../video/webgl/webgl_renderer.js";
 import { warning } from "./console.js";
 
@@ -53,6 +56,42 @@ WebGLRenderer.prototype.setLineWidth = function (width) {
 	this.lineWidth = width;
 };
 
+/**
+ * @deprecated since 18.2.0
+ * @see Batcher
+ */
+export class Compositor extends Batcher {
+	/** @param {any[]} args */
+	constructor(...args) {
+		warning("Compositor", "Batcher", "18.2.0");
+		super(...args);
+	}
+}
+
+/**
+ * @deprecated since 18.2.0
+ * @see PrimitiveBatcher
+ */
+export class PrimitiveCompositor extends PrimitiveBatcher {
+	/** @param {any[]} args */
+	constructor(...args) {
+		warning("PrimitiveCompositor", "PrimitiveBatcher", "18.2.0");
+		super(...args);
+	}
+}
+
+/**
+ * @deprecated since 18.2.0
+ * @see QuadBatcher
+ */
+export class QuadCompositor extends QuadBatcher {
+	/** @param {any[]} args */
+	constructor(...args) {
+		warning("QuadCompositor", "QuadBatcher", "18.2.0");
+		super(...args);
+	}
+}
+
 /**
  * @namespace Math
  * @deprecated since 18.0.0

…rc/video/webgl/compositors/compositor.js …onjs/src/video/webgl/batchers/batcher.jspackages/melonjs/src/video/webgl/compositors/compositor.js renamed to packages/melonjs/src/video/webgl/batchers/batcher.js packages/melonjs/src/video/webgl/compositors/compositor.js renamed to packages/melonjs/src/video/webgl/batchers/batcher.js

@@ -8,12 +8,22 @@ import GLShader from "../glshader.js";
  */
 
 /**
- * A base Compositor object.
+ * Maximum number of vertices per batch.
+ * At 4096 vertices (1024 quads), the vertex buffer is ~80 KB (5 floats × 4 bytes × 4096),
+ * which balances draw call reduction with safe buffer upload sizes on mobile tile-based GPUs.
+ * Within the Uint16 index limit (65,535) required for WebGL1 compatibility.
+ * @ignore
  */
-export default class Compositor {
+const MAX_VERTICES = 4096;
+
+/**
+ * A base WebGL Batcher object that manages shader programs, vertex attribute
+ * definitions, and vertex buffer batching for efficient GPU draw calls.
+ */
+export class Batcher {
 	/**
 	 * @param {WebGLRenderer} renderer - the current WebGL renderer session
-	 * @param {object} settings - additional settings to initialize this compositors
+	 * @param {object} settings - additional settings to initialize this batcher
 	 * @param {object[]} settings.attribute - an array of attributes definition
 	 * @param {string} settings.attribute.name - name of the attribute in the vertex shader
 	 * @param {number} settings.attribute.size - number of components per vertex attribute. Must be 1, 2, 3, or 4.
@@ -29,7 +39,7 @@ export default class Compositor {
 	}
 
 	/**
-	 * Initialize the compositor
+	 * Initialize the batcher
 	 * @ignore
 	 */
 	init(renderer, settings) {
@@ -43,13 +53,13 @@ export default class Compositor {
 		this.viewMatrix = renderer.currentTransform;
 
 		/**
-		 * the default shader created by this compositor
+		 * the default shader created by this batcher
 		 * @type {GLShader}
 		 */
 		this.defaultShader = undefined;
 
 		/**
-		 * the shader currently used by this compositor
+		 * the shader currently used by this batcher
 		 * @type {GLShader}
 		 */
 		this.currentShader = undefined;
@@ -63,29 +73,29 @@ export default class Compositor {
 
 		/**
 		 * an array of vertex attribute properties
-		 * @see WebGLCompositor.addAttribute
+		 * @see Batcher.addAttribute
 		 * @type {Array.<Object>}
 		 */
 		this.attributes = [];
 
 		/**
-		 * the size of a single vertex in bytes
+		 * the stride of a single vertex in bytes
 		 * (will automatically be calculated as attributes definitions are added)
-		 * @see WebGLCompositor.addAttribute
+		 * @see Batcher.addAttribute
 		 * @type {number}
 		 */
-		this.vertexByteSize = 0;
+		this.stride = 0;
 
 		/**
 		 * the size of a single vertex in floats
 		 * (will automatically be calculated as attributes definitions are added)
-		 * @see WebGLCompositor.addAttribute
+		 * @see Batcher.addAttribute
 		 * @type {number}
 		 */
 		this.vertexSize = 0;
 
 		/**
-		 * the vertex data buffer used by this compositor
+		 * the vertex data buffer used by this batcher
 		 * @type {VertexArrayBuffer}
 		 */
 		this.vertexData = null;
@@ -101,7 +111,7 @@ export default class Compositor {
 					attr.offset,
 				);
 			});
-			this.vertexData = new VertexArrayBuffer(this.vertexSize, 6);
+			this.vertexData = new VertexArrayBuffer(this.vertexSize, MAX_VERTICES);
 		} else {
 			throw new Error("attributes definition missing");
 		}
@@ -122,7 +132,7 @@ export default class Compositor {
 	}
 
 	/**
-	 * Reset compositor internal state
+	 * Reset batcher internal state
 	 * @ignore
 	 */
 	reset() {
@@ -134,7 +144,7 @@ export default class Compositor {
 	}
 
 	/**
-	 * called by the WebGL renderer when a compositor become the current one
+	 * called by the WebGL renderer when a batcher becomes the current one
 	 */
 	bind() {
 		if (this.renderer.currentProgram !== this.defaultShader.program) {
@@ -152,15 +162,15 @@ export default class Compositor {
 			this.flush();
 			shader.bind();
 			shader.setUniform("uProjectionMatrix", this.renderer.projectionMatrix);
-			shader.setVertexAttributes(this.gl, this.attributes, this.vertexByteSize);
+			shader.setVertexAttributes(this.gl, this.attributes, this.stride);
 
 			this.currentShader = shader;
 			this.renderer.currentProgram = this.currentShader.program;
 		}
 	}
 
 	/**
-	 * add vertex attribute property definition to the compositor
+	 * add vertex attribute property definition to the batcher
 	 * @param {string} name - name of the attribute in the vertex shader
 	 * @param {number} size - number of components per vertex attribute. Must be 1, 2, 3, or 4.
 	 * @param {GLenum} type - data type of each component in the array
@@ -172,30 +182,30 @@ export default class Compositor {
 
 		switch (type) {
 			case this.gl.BYTE:
-				this.vertexByteSize += size * Int8Array.BYTES_PER_ELEMENT;
+				this.stride += size * Int8Array.BYTES_PER_ELEMENT;
 				break;
 			case this.gl.UNSIGNED_BYTE:
-				this.vertexByteSize += size * Uint8Array.BYTES_PER_ELEMENT;
+				this.stride += size * Uint8Array.BYTES_PER_ELEMENT;
 				break;
 			case this.gl.SHORT:
-				this.vertexByteSize += size * Int16Array.BYTES_PER_ELEMENT;
+				this.stride += size * Int16Array.BYTES_PER_ELEMENT;
 				break;
 			case this.gl.UNSIGNED_SHORT:
-				this.vertexByteSize += size * Uint16Array.BYTES_PER_ELEMENT;
+				this.stride += size * Uint16Array.BYTES_PER_ELEMENT;
 				break;
 			case this.gl.INT:
-				this.vertexByteSize += size * Int32Array.BYTES_PER_ELEMENT;
+				this.stride += size * Int32Array.BYTES_PER_ELEMENT;
 				break;
 			case this.gl.UNSIGNED_INT:
-				this.vertexByteSize += size * Uint32Array.BYTES_PER_ELEMENT;
+				this.stride += size * Uint32Array.BYTES_PER_ELEMENT;
 				break;
 			case this.gl.FLOAT:
-				this.vertexByteSize += size * Float32Array.BYTES_PER_ELEMENT;
+				this.stride += size * Float32Array.BYTES_PER_ELEMENT;
 				break;
 			default:
 				throw new Error("Invalid GL Attribute type");
 		}
-		this.vertexSize = this.vertexByteSize / Float32Array.BYTES_PER_ELEMENT;
+		this.vertexSize = this.stride / Float32Array.BYTES_PER_ELEMENT;
 	}
 
 	/**
@@ -242,3 +252,5 @@ export default class Compositor {
 		}
 	}
 }
+
+export default Batcher;

…ebgl/compositors/primitive_compositor.js …ideo/webgl/batchers/primitive_batcher.jspackages/melonjs/src/video/webgl/compositors/primitive_compositor.js renamed to packages/melonjs/src/video/webgl/batchers/primitive_batcher.js packages/melonjs/src/video/webgl/compositors/primitive_compositor.js renamed to packages/melonjs/src/video/webgl/batchers/primitive_batcher.js

@@ -1,6 +1,6 @@
 import primitiveFragment from "./../shaders/primitive.frag";
 import primitiveVertex from "./../shaders/primitive.vert";
-import Compositor from "./compositor.js";
+import { Batcher } from "./batcher.js";
 
 /**
  * additional import for TypeScript
@@ -11,7 +11,7 @@ import Compositor from "./compositor.js";
  * A WebGL Compositor object. This class handles all of the WebGL state<br>
  * Pushes texture regions or shape geometry into WebGL buffers, automatically flushes to GPU
  */
-export default class PrimitiveCompositor extends Compositor {
+export default class PrimitiveBatcher extends Batcher {
 	/**
 	 * Initialize the compositor
 	 * @ignore