melonjs 19.2.0 → 19.4.0

package/build/index.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - 19.2.0
+ * melonJS Game Engine - 19.4.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -750,8 +750,8 @@ var require_weak_map_basic_detection = __commonJS({
     "use strict";
     var globalThis2 = require_global_this();
     var isCallable = require_is_callable();
-    var WeakMap = globalThis2.WeakMap;
-    module.exports = isCallable(WeakMap) && /native code/.test(String(WeakMap));
+    var WeakMap2 = globalThis2.WeakMap;
+    module.exports = isCallable(WeakMap2) && /native code/.test(String(WeakMap2));
   }
 });
 
@@ -790,7 +790,7 @@ var require_internal_state = __commonJS({
     var hiddenKeys = require_hidden_keys();
     var OBJECT_ALREADY_INITIALIZED = "Object already initialized";
     var TypeError2 = globalThis2.TypeError;
-    var WeakMap = globalThis2.WeakMap;
+    var WeakMap2 = globalThis2.WeakMap;
     var set;
     var get2;
     var has2;
@@ -807,7 +807,7 @@ var require_internal_state = __commonJS({
       };
     };
     if (NATIVE_WEAK_MAP || shared.state) {
-      store = shared.state || (shared.state = new WeakMap());
+      store = shared.state || (shared.state = new WeakMap2());
       store.get = store.get;
       store.has = store.has;
       store.set = store.set;
@@ -4639,6 +4639,7 @@ var pointPool = createPool((x, y) => {
 });
 
 // src/physics/bounds.ts
+var _addFrameScratch = new Point();
 var Bounds = class _Bounds {
   _center;
   type;
@@ -4865,20 +4866,41 @@ var Bounds = class _Bounds {
     this.max.y = Math.max(this.max.y, p.y);
   }
   /**
-   * Adds the given quad coordinates to this bounds definition, multiplied by the given matrix.
+   * Expands this bounds to include the axis-aligned bounding box of
+   * the given rect's four corners, optionally transformed through `m`
+   * first. With a non-identity `m` (rotation, scale, etc.) the result
+   * is the AABB of the transformed quad, not a transformed AABB.
    * @param x0 - The left x coordinate of the quad.
    * @param y0 - The top y coordinate of the quad.
    * @param x1 - The right x coordinate of the quad.
    * @param y1 - The bottom y coordinate of the quad.
-   * @param [m] - An optional transform to apply to the given coordinates.
+   * @param [m] - An optional transform applied to each corner before inclusion.
    */
   addFrame(x0, y0, x1, y1, m) {
-    const v = pointPool.get();
+    if (m === void 0 || m.isIdentity()) {
+      const minX = Math.min(x0, x1);
+      const maxX = Math.max(x0, x1);
+      const minY = Math.min(y0, y1);
+      const maxY = Math.max(y0, y1);
+      if (minX < this.min.x) {
+        this.min.x = minX;
+      }
+      if (maxX > this.max.x) {
+        this.max.x = maxX;
+      }
+      if (minY < this.min.y) {
+        this.min.y = minY;
+      }
+      if (maxY > this.max.y) {
+        this.max.y = maxY;
+      }
+      return;
+    }
+    const v = _addFrameScratch;
     this.addPoint(v.set(x0, y0), m);
     this.addPoint(v.set(x1, y0), m);
     this.addPoint(v.set(x0, y1), m);
     this.addPoint(v.set(x1, y1), m);
-    pointPool.release(v);
   }
   contains(xOrVectorOrBounds, y) {
     let _x1;
@@ -6227,6 +6249,7 @@ var defaultApplicationSettings = {
   consoleHeader: true,
   blendMode: "normal",
   physic: "builtin",
+  gpuTilemap: true,
   failIfMajorPerformanceCaveat: true,
   highPrecisionShader: true,
   subPixel: false,
@@ -14138,10 +14161,10 @@ var Container = class _Container extends Renderable {
   draw(renderer2, viewport) {
     const bounds = this.getBounds();
     this.drawCount = 0;
-    if (this.root === false && this.clipping === true && bounds.isFinite() === true) {
-      renderer2.clipRect(bounds.left, bounds.top, bounds.width, bounds.height);
-    }
     renderer2.translate(this.pos.x, this.pos.y);
+    if (this.root === false && this.clipping === true && bounds.isFinite() === true && Number.isFinite(this.width) === true && Number.isFinite(this.height) === true) {
+      renderer2.clipRect(0, 0, this.width, this.height);
+    }
     if (this.backgroundColor.alpha > 1 / 255) {
       renderer2.clearColor(this.backgroundColor);
     }
@@ -15366,6 +15389,32 @@ var RenderState = class {
     }
     this._stackDepth = depth + 1;
   }
+  /**
+   * Inspect the scissor box that the next `restore()` would install,
+   * without mutating any state. Lets renderers detect whether a
+   * pending `restore()` will actually change the scissor (and
+   * decide, e.g., whether to flush GPU work first).
+   *
+   * Returns:
+   * - `Int32Array` (length 4) — `[x, y, width, height]` of the
+   *   saved scissor when scissor was active at the matching `save()`
+   *   call.
+   * - `null` — when the saved state had scissor disabled, or the
+   *   stack is empty. Treat this as "next scissor will be inactive".
+   *
+   * The returned array is a **live reference into the internal
+   * stack** — zero allocation on a hot path. Callers MUST treat it
+   * as read-only; mutating it corrupts subsequent `restore()` calls.
+   * @ignore
+   * @returns {Int32Array | null}
+   */
+  peekScissor() {
+    const depth = this._stackDepth - 1;
+    if (depth < 0 || !this._scissorActive[depth]) {
+      return null;
+    }
+    return this._scissorStack[depth];
+  }
   /**
    * Restore state from the stack.
    * Color, tint, transform, and scissor are restored in place.
@@ -15466,6 +15515,8 @@ var Renderer = class {
     this.maskLevel = 0;
     this.projectionMatrix = new Matrix3d();
     this.uvOffset = 0;
+    this.currentNormalMap = null;
+    this.activeLightCount = 0;
   }
   /**
    * @type {string}
@@ -15686,6 +15737,97 @@ var Renderer = class {
   setBlendMode(mode = "normal") {
     this.currentBlendMode = mode;
   }
+  /**
+   * Upload the active scene lights to the lit sprite pipeline.
+   *
+   * Called once per camera per frame by `Camera2d.draw()` (after the
+   * FBO is bound, before the world tree walk fires `Sprite.draw` for
+   * any normal-mapped sprite). The WebGL renderer overrides this to
+   * pack the lights into the lit shader's uniform buffers; the Canvas
+   * renderer cannot do per-pixel normal-map lighting and silently
+   * ignores the call. The first time a non-empty light list is passed
+   * in Canvas mode, a one-shot console warning is emitted.
+   *
+   * Stage stays renderer-agnostic by passing the raw scene data —
+   * lights iterable and ambient color — and letting the renderer
+   * decide how to encode them.
+   * @param {Iterable<object>} [lights] - active `Light2d` instances; falsy/empty no-ops
+   * @param {object} [ambient] - ambient lighting color (0..255 RGB)
+   * @param {number} [translateX=0] - world-to-screen X translate (matches `Camera2d.draw()`)
+   * @param {number} [translateY=0] - world-to-screen Y translate
+   */
+  // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars
+  setLightUniforms(lights, ambient, translateX, translateY) {
+    if (this._litPipelineWarned || !lights) {
+      return;
+    }
+    const hasAny = typeof lights.size === "number" && lights.size > 0 || typeof lights.length === "number" && lights.length > 0 || typeof lights[Symbol.iterator] === "function" && !lights[Symbol.iterator]().next().done;
+    if (hasAny) {
+      this._litPipelineWarned = true;
+      console.warn(
+        "melonJS: Light2d normal-map lighting requires the WebGL renderer; the Canvas fallback renders sprites without per-pixel lighting. Switch to `video.WEBGL` or `video.AUTO` to enable the lit pipeline."
+      );
+    }
+  }
+  /**
+   * Render a `Light2d` instance.
+   *
+   * Each renderer implements its own strategy: the WebGL renderer
+   * draws lights as quads through a shared procedural radial-falloff
+   * fragment shader (no per-light texture, color and intensity
+   * encoded in the per-vertex tint so consecutive draws batch); the
+   * Canvas renderer caches a small `Gradient` config object per
+   * light in a `WeakMap` (rebuilt only when the light's radii /
+   * color / intensity change), rasterizes it with `Gradient.toCanvas()`
+   * into a single shared `CanvasRenderTarget`, and composites the
+   * result via `drawImage`. The base implementation is a no-op so
+   * renderers without a lighting path can be polymorphically
+   * substituted.
+   *
+   * Light2d itself is renderer-agnostic — it just calls
+   * `renderer.drawLight(this)` and relies on the renderer to pick
+   * the right machinery.
+   * @param {object} light - the Light2d instance to render
+   * @see Light2d
+   */
+  // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars
+  drawLight(light) {
+  }
+  /**
+   * Draw a TMX tile layer. Default behavior:
+   *   - if `layer.canvasRenderer` is set (preRender bake), blit the cached
+   *     offscreen canvas in a single `drawImage` call;
+   *   - otherwise delegate to the layer's TMX orientation renderer for
+   *     the per-tile loop.
+   *
+   * `WebGLRenderer` overrides this to add the procedural shader fast
+   * path on top (when `layer.renderMode === "shader"`) and fall through
+   * to this base behavior for all other layers.
+   * @param {object} layer - the TMXLayer to draw
+   * @param {Rect} rect - the visible region in world coords
+   */
+  drawTileLayer(layer, rect) {
+    if (layer.canvasRenderer) {
+      const width = Math.min(rect.width, layer.width - rect.pos.x);
+      const height = Math.min(rect.height, layer.height - rect.pos.y);
+      if (width <= 0 || height <= 0) {
+        return;
+      }
+      this.drawImage(
+        layer.canvasRenderer.getCanvas(),
+        rect.pos.x,
+        rect.pos.y,
+        width,
+        height,
+        rect.pos.x,
+        rect.pos.y,
+        width,
+        height
+      );
+      return;
+    }
+    layer.getRenderer().drawTileLayer(this, layer, rect);
+  }
   /**
    * Set the current fill & stroke style color.
    * By default, or upon reset, the value is set to #000000.
@@ -16206,7 +16348,7 @@ var TextureAtlas = class {
   /**
    * @param {object|object[]} atlases - atlas information. See {@link loader.getJSON}
    * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|CompressedImage|string|OffscreenCanvas[]|HTMLImageElement[]|HTMLCanvasElement[]|string[]} [src=atlas.meta.image] - Image source
-   * @param {boolean} [cache=false] - Use true to skip caching this Texture
+   * @param {boolean|object} [options] - either a boolean (legacy `cache` flag — `false` disables `TextureCache` registration; default behavior is to cache) or an options object `{ cache?: boolean, normalMap?: HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|string }`. When `normalMap` is provided, the atlas exposes a paired normal-map texture sharing the same UVs as the color texture (used by the WebGL renderer's lit pipeline). `HTMLVideoElement` is intentionally not supported as a normal map (would freeze on frame 0 due to per-image GL texture caching).
    * @example
    * // create a texture atlas from a JSON Object
    * game.texture = new me.TextureAtlas(
@@ -16228,10 +16370,22 @@ var TextureAtlas = class {
    *         anchorPoint : new me.Vector2d(0.5, 0.5)
    *     },
    *     me.loader.getImage("spritesheet")
+   * );
+   *
+   * // SpriteIlluminator workflow: pair the color atlas with its normal map
+   * game.texture = new me.TextureAtlas(
+   *     me.loader.getJSON("scene"),
+   *     me.loader.getImage("scene"),
+   *     { normalMap: me.loader.getImage("scene_n") }
+   * );
    */
-  constructor(atlases, src, cache2) {
+  constructor(atlases, src, options) {
+    const opts = typeof options === "boolean" ? { cache: options } : options || {};
+    const cache2 = opts.cache;
+    const normalMap = opts.normalMap;
     this.format = null;
     this.sources = /* @__PURE__ */ new Map();
+    this.normalSources = /* @__PURE__ */ new Map();
     this.atlases = /* @__PURE__ */ new Map();
     this.activeAtlas = void 0;
     this._uvCache = { sx: -1, sy: -1, sw: -1, sh: -1, uvs: null };
@@ -16321,6 +16475,31 @@ var TextureAtlas = class {
         game.renderer.cache.set(source, this);
       });
     }
+    if (typeof normalMap !== "undefined" && normalMap !== null) {
+      let resolved;
+      if (typeof normalMap === "string") {
+        resolved = getImage(normalMap);
+        if (!resolved) {
+          throw new Error(
+            "TextureAtlas: normal map image '" + normalMap + "' not found"
+          );
+        }
+      } else if (typeof normalMap === "object" && typeof normalMap.width === "number" && typeof normalMap.height === "number") {
+        if (typeof normalMap.videoWidth === "number") {
+          throw new TypeError(
+            "TextureAtlas: options.normalMap does not support HTMLVideoElement (the lit pipeline caches the texture per image reference and would freeze on frame 0)"
+          );
+        }
+        resolved = normalMap;
+      } else {
+        throw new TypeError(
+          "TextureAtlas: options.normalMap must be an image-like, a loader key string, or null/undefined; got " + typeof normalMap
+        );
+      }
+      this.sources.forEach((_source, key) => {
+        this.normalSources.set(key, resolved);
+      });
+    }
   }
   /**
    * return the default or specified atlas dictionnary
@@ -16353,6 +16532,22 @@ var TextureAtlas = class {
       return this.sources.get(this.activeAtlas);
     }
   }
+  /**
+   * Return the paired normal-map texture for the given region, or `null`
+   * if no normal map was provided to this atlas. The normal map shares
+   * the same UV layout as the color texture returned by {@link TextureAtlas#getTexture}.
+   * @param {object} [region] - region name in case of multipack textures
+   * @returns {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|null}
+   */
+  getNormalTexture(region) {
+    if (this.normalSources.size === 0) {
+      return null;
+    }
+    if (typeof region === "object" && typeof region.texture === "string") {
+      return this.normalSources.get(region.texture) ?? null;
+    }
+    return this.normalSources.get(this.activeAtlas) ?? null;
+  }
   /**
    * add a region to the atlas
    * @param {string} name - region mame
@@ -16731,14 +16926,6 @@ var TextureCache = class {
    * cache the textureAltas for the given image
    */
   set(image, textureAtlas) {
-    const width = image.width || image.videoWidth;
-    const height = image.height || image.videoHeight;
-    if (this.renderer.WebGLVersion === 1 && (!isPowerOfTwo(width) || !isPowerOfTwo(height))) {
-      const src = typeof image.src !== "undefined" ? image.src : image;
-      console.warn(
-        "[Texture] " + src + " is not a POT texture (" + width + "x" + height + ")"
-      );
-    }
     return this.cache.put(image, textureAtlas);
   }
   /**
@@ -16851,6 +17038,7 @@ var CanvasRenderer = class extends Renderer {
   reset() {
     super.reset();
     this.clearColor(this.currentColor, this.settings.transparent !== true);
+    this._lightCache = void 0;
   }
   /**
    * Reset the canvas transform to identity
@@ -17044,6 +17232,59 @@ var CanvasRenderer = class extends Renderer {
     }
     context.drawImage(source, sx, sy, sw, sh, dx, dy, dw, dh);
   }
+  /**
+   * @inheritdoc
+   *
+   * Renders the light by drawing a cached radial `Gradient` via
+   * `Gradient.toCanvas()`. The Gradient instance is cached per-Light2d
+   * in a `WeakMap` and rebuilt only when the light's radii / color /
+   * intensity change. `toCanvas` itself shares a single
+   * `CanvasRenderTarget` across all gradients in the engine, so memory
+   * stays at O(1) regardless of how many lights are active.
+   *
+   * The cached Gradient is always circular (outer radius =
+   * `max(radiusX, radiusY)`) — `drawImage`'s non-uniform stretch
+   * produces the elliptical falloff for non-square lights, matching
+   * the procedural shader's behavior on WebGL.
+   * @param {object} light - the Light2d instance to render
+   */
+  drawLight(light) {
+    if (this._lightCache === void 0) {
+      this._lightCache = /* @__PURE__ */ new WeakMap();
+    }
+    let entry = this._lightCache.get(light);
+    const c = light.color;
+    if (entry === void 0 || entry.radiusX !== light.radiusX || entry.radiusY !== light.radiusY || entry.r !== c.r || entry.g !== c.g || entry.b !== c.b || entry.intensity !== light.intensity) {
+      const r = Math.max(light.radiusX, light.radiusY);
+      const gradient = this.createRadialGradient(r, r, 0, r, r, r);
+      gradient.addColorStop(0, c.toRGBA(light.intensity));
+      gradient.addColorStop(1, c.toRGBA(0));
+      entry = {
+        gradient,
+        radius: r,
+        radiusX: light.radiusX,
+        radiusY: light.radiusY,
+        r: c.r,
+        g: c.g,
+        b: c.b,
+        intensity: light.intensity
+      };
+      this._lightCache.set(light, entry);
+    }
+    const r2 = entry.radius * 2;
+    const canvas = entry.gradient.toCanvas(this, 0, 0, r2, r2);
+    this.drawImage(
+      canvas,
+      0,
+      0,
+      r2,
+      r2,
+      light.pos.x,
+      light.pos.y,
+      light.width,
+      light.height
+    );
+  }
   /**
    * Draw a pattern within the given rectangle.
    * @param {CanvasPattern} pattern - Pattern object
@@ -17778,14 +18019,15 @@ var CanvasRenderer = class extends Renderer {
       if (typeof mask !== "undefined") {
         context.beginPath();
       }
+      this._maskInvertOuterAdded = false;
     }
     if (typeof mask !== "undefined") {
       switch (mask.type) {
         // RoundRect
         case "RoundRect":
           context.roundRect(
-            mask.top,
             mask.left,
+            mask.top,
             mask.width,
             mask.height,
             mask.radius
@@ -17794,7 +18036,7 @@ var CanvasRenderer = class extends Renderer {
         // Rect or Bounds
         case "Rectangle":
         case "Bounds":
-          context.rect(mask.top, mask.left, mask.width, mask.height);
+          context.rect(mask.left, mask.top, mask.width, mask.height);
           break;
         // Polygon or Line
         case "Polygon":
@@ -17837,7 +18079,10 @@ var CanvasRenderer = class extends Renderer {
     }
     this.maskLevel++;
     if (invert === true) {
-      context.rect(0, 0, this.getCanvas().width, this.getCanvas().height);
+      if (this._maskInvertOuterAdded !== true) {
+        context.rect(0, 0, this.getCanvas().width, this.getCanvas().height);
+        this._maskInvertOuterAdded = true;
+      }
       context.clip("evenodd");
     } else {
       context.clip();
@@ -17856,6 +18101,30 @@ var CanvasRenderer = class extends Renderer {
 };
 
 // src/level/tiled/TMXTile.js
+var FLIP_H_BIT = 1 << 0;
+var FLIP_V_BIT = 1 << 1;
+var FLIP_AD_BIT = 1 << 2;
+function buildFlipTransform(transform, flipMask, width, height) {
+  const halfW = width / 2;
+  const halfH = height / 2;
+  const flippedH = (flipMask & FLIP_H_BIT) !== 0;
+  const flippedV = (flipMask & FLIP_V_BIT) !== 0;
+  const flippedAD = (flipMask & FLIP_AD_BIT) !== 0;
+  transform.identity();
+  transform.translate(halfW, halfH);
+  if (flippedAD) {
+    transform.rotate(degToRad(-90));
+    transform.scale(-1, 1);
+  }
+  if (flippedH) {
+    transform.scale(flippedAD ? 1 : -1, flippedAD ? -1 : 1);
+  }
+  if (flippedV) {
+    transform.scale(flippedAD ? -1 : 1, flippedAD ? 1 : -1);
+  }
+  transform.translate(-halfW, -halfH);
+  return transform;
+}
 var Tile = class extends Bounds {
   /**
    * @param {number} x - x index of the Tile in the map
@@ -18406,12 +18675,17 @@ function applyTMXProperties(obj, data2) {
 }
 
 // src/level/tiled/TMXLayer.js
-function initArray(rows, cols) {
-  const array = new Array(cols);
-  for (let col = 0; col < cols; col++) {
-    array[col] = new Array(rows).fill(null);
-  }
-  return array;
+var FLIP_H_BIT2 = 1 << 0;
+var FLIP_V_BIT2 = 1 << 1;
+var FLIP_AD_BIT2 = 1 << 2;
+function flipMaskFromGid(gid) {
+  return (gid & TMX_FLIP_H ? FLIP_H_BIT2 : 0) | (gid & TMX_FLIP_V ? FLIP_V_BIT2 : 0) | (gid & TMX_FLIP_AD ? FLIP_AD_BIT2 : 0);
+}
+function flipMaskFromTile(tile) {
+  return (tile.flippedX ? FLIP_H_BIT2 : 0) | (tile.flippedY ? FLIP_V_BIT2 : 0) | (tile.flippedAD ? FLIP_AD_BIT2 : 0);
+}
+function gidWithFlips(gid, flipMask) {
+  return gid | (flipMask & FLIP_H_BIT2 ? TMX_FLIP_H : 0) | (flipMask & FLIP_V_BIT2 ? TMX_FLIP_V : 0) | (flipMask & FLIP_AD_BIT2 ? TMX_FLIP_AD : 0);
 }
 function setLayerData(layer, bounds, data2) {
   let idx = 0;
@@ -18424,18 +18698,30 @@ function setLayerData(layer, bounds, data2) {
     width = bounds.cols;
     height = bounds.rows;
   }
+  const cols = layer.cols;
+  const layerData = layer.layerData;
+  const offsetX = bounds.x;
+  const offsetY = bounds.y;
+  let overflowedGid = 0;
   for (let y = 0; y < height; y++) {
     for (let x = 0; x < width; x++) {
-      const gid = data2[idx++];
-      if (gid !== 0) {
-        layer.layerData[x + bounds.x][y + bounds.y] = layer.getTileById(
-          gid,
-          x + bounds.x,
-          y + bounds.y
-        );
+      const rawGid = data2[idx++];
+      if (rawGid !== 0) {
+        const flatIdx = ((y + offsetY) * cols + (x + offsetX)) * 2;
+        const cleanGid = rawGid & TMX_CLEAR_BIT_MASK;
+        if (cleanGid > 65535 && overflowedGid === 0) {
+          overflowedGid = cleanGid;
+        }
+        layerData[flatIdx] = cleanGid;
+        layerData[flatIdx + 1] = flipMaskFromGid(rawGid);
       }
     }
   }
+  if (overflowedGid !== 0) {
+    console.warn(
+      "melonJS: TMX layer contains GID " + overflowedGid + " which exceeds the 16-bit cell capacity (max 65535). Tiles will be truncated and render incorrectly."
+    );
+  }
 }
 var TMXLayer = class extends Renderable {
   /**
@@ -18495,7 +18781,10 @@ var TMXLayer = class extends Renderable {
     }
     applyTMXProperties(this, data2);
     this.setRenderer(map.getRenderer());
-    this.layerData = initArray(this.rows, this.cols);
+    this.layerData = new Uint16Array(this.cols * this.rows * 2);
+    this.cachedTile = null;
+    this.dataVersion = 0;
+    this.renderMode = "auto";
     if (map.infinite === 0) {
       setLayerData(
         this,
@@ -18525,12 +18814,8 @@ var TMXLayer = class extends Renderable {
       }
     }
     this.isAnimated = this.animatedTilesets.length > 0;
-    if (typeof this.preRender === "undefined" && this.isAnimated === false) {
-      this.preRender = this.ancestor.getRootAncestor().preRender;
-    } else {
-      this.preRender = false;
-    }
-    if (this.preRender === true && !this.canvasRenderer) {
+    this._resolveRenderMode();
+    if (this.renderMode === "prerender" && !this.canvasRenderer) {
       this.canvasRenderer = new CanvasRenderer({
         canvas: createCanvas(this.width, this.height),
         width: this.width,
@@ -18539,8 +18824,109 @@ var TMXLayer = class extends Renderable {
       });
       this.getRenderer().drawTileLayer(this.canvasRenderer, this, this);
     }
+    this.preRender = this.renderMode === "prerender";
     this.isDirty = true;
   }
+  /**
+   * Resolve `this.renderMode` to one of "shader" / "prerender" / "perTile"
+   * based on eligibility checks and user/world hints. Emits a single
+   * `console.warn` at activation when a forced mode is ineligible, or
+   * when an auto-eligible mode falls back due to a layer feature the GPU
+   * path doesn't support (orientation, collection-of-image tileset, etc.).
+   * @ignore
+   */
+  _resolveRenderMode() {
+    const root = this.ancestor?.getRootAncestor?.();
+    const renderer2 = this.parentApp?.renderer;
+    const gpuAllowed = root?.gpuTilemap !== false;
+    const preRenderHint = typeof this.preRender === "boolean" ? this.preRender : root?.preRender;
+    const elig = this._checkShaderEligibility(renderer2, gpuAllowed);
+    const requested = this.renderMode;
+    if (requested === "shader") {
+      if (elig.ok) {
+        return;
+      }
+      console.warn(
+        `melonJS: layer "${this.name}" forced renderMode "shader" not available (${elig.reason}) \u2014 falling back to perTile`
+      );
+      this.renderMode = "perTile";
+      return;
+    }
+    if (requested === "prerender") {
+      if (this.isAnimated) {
+        console.warn(
+          `melonJS: layer "${this.name}" forced renderMode "prerender" disabled (layer has animated tiles) \u2014 falling back to perTile`
+        );
+        this.renderMode = "perTile";
+      }
+      return;
+    }
+    if (requested === "perTile") {
+      return;
+    }
+    if (elig.ok) {
+      this.renderMode = "shader";
+      return;
+    }
+    if (gpuAllowed && elig.reason !== "no-webgl2-renderer") {
+      console.warn(
+        `melonJS: layer "${this.name}" using legacy tile renderer (${elig.reason})`
+      );
+    }
+    if (preRenderHint && !this.isAnimated) {
+      this.renderMode = "prerender";
+      return;
+    }
+    this.renderMode = "perTile";
+  }
+  /**
+   * Check whether this layer is eligible for the WebGL2 shader path.
+   * @param {object} renderer
+   * @param {boolean} gpuAllowed - whether `gpuTilemap` is enabled at the world level
+   * @returns {{ok: boolean, reason?: string}}
+   * @ignore
+   */
+  _checkShaderEligibility(renderer2, gpuAllowed) {
+    if (!gpuAllowed) {
+      return { ok: false, reason: "gpuTilemap disabled" };
+    }
+    if (!renderer2 || renderer2.WebGLVersion !== 2) {
+      return { ok: false, reason: "no-webgl2-renderer" };
+    }
+    if (this.orientation !== "orthogonal") {
+      return {
+        ok: false,
+        reason: `no gpu renderer supported yet for "${this.orientation}" orientation`
+      };
+    }
+    if (!this.tilesets || this.tilesets.tilesets.length === 0) {
+      return { ok: false, reason: "no tilesets" };
+    }
+    const MAX_OVERFLOW_CELLS = 4;
+    for (const ts of this.tilesets.tilesets) {
+      if (ts.isCollection) {
+        return { ok: false, reason: "collection-of-image tileset" };
+      }
+      if (ts.tilerendersize !== "tile") {
+        return {
+          ok: false,
+          reason: `tilerendersize "${ts.tilerendersize}" not supported`
+        };
+      }
+      if (ts.tileoffset.x !== 0 || ts.tileoffset.y !== 0) {
+        return { ok: false, reason: "non-zero tileoffset" };
+      }
+      const overflowX = Math.ceil(ts.tilewidth / this.tilewidth) - 1;
+      const overflowY = Math.ceil(ts.tileheight / this.tileheight) - 1;
+      if (overflowX > MAX_OVERFLOW_CELLS || overflowY > MAX_OVERFLOW_CELLS) {
+        return {
+          ok: false,
+          reason: `tile overflow exceeds shader limit (${MAX_OVERFLOW_CELLS} cells)`
+        };
+      }
+    }
+    return { ok: true };
+  }
   // called when the layer is removed from the game world or a container
   onDeactivateEvent() {
     this.animatedTilesets = void 0;
@@ -18601,12 +18987,29 @@ var TMXLayer = class extends Renderable {
   /**
    * assign the given Tile object to the specified position
    * @param {Tile} tile - the tile object to be assigned
-   * @param {number} x - x coordinate (in world/pixels coordinates)
-   * @param {number} y - y coordinate (in world/pixels coordinates)
+   * @param {number} x - x coordinate (in tile/column coordinates)
+   * @param {number} y - y coordinate (in tile/row coordinates)
    * @returns {Tile} the tile object
    */
   setTile(tile, x, y) {
-    this.layerData[x][y] = tile;
+    if (x < 0 || x >= this.cols || y < 0 || y >= this.rows) {
+      return tile;
+    }
+    const slot = y * this.cols + x;
+    const idx = slot * 2;
+    const cleanGid = tile.tileId & TMX_CLEAR_BIT_MASK;
+    if (cleanGid > 65535 && !this._truncationWarned) {
+      this._truncationWarned = true;
+      console.warn(
+        "melonJS: setTile received GID " + cleanGid + " which exceeds the 16-bit cell capacity (max 65535). Tile will be truncated and render incorrectly."
+      );
+    }
+    this.layerData[idx] = cleanGid;
+    this.layerData[idx + 1] = flipMaskFromTile(tile);
+    if (this.cachedTile !== null) {
+      this.cachedTile[slot] = tile;
+    }
+    this.dataVersion++;
     this.isDirty = true;
     return tile;
   }
@@ -18636,12 +19039,27 @@ var TMXLayer = class extends Renderable {
   cellAt(x, y, boundsCheck) {
     const _x = ~~x;
     const _y = ~~y;
-    const renderer2 = this.getRenderer();
-    if (boundsCheck === false || _x >= 0 && _x < renderer2.cols && _y >= 0 && _y < renderer2.rows) {
-      return this.layerData[_x][_y];
-    } else {
+    if (boundsCheck !== false && (_x < 0 || _x >= this.cols || _y < 0 || _y >= this.rows)) {
       return null;
     }
+    const slot = _y * this.cols + _x;
+    const idx = slot * 2;
+    const gid = this.layerData[idx];
+    if (!gid) {
+      return null;
+    }
+    if (this.cachedTile === null) {
+      this.cachedTile = new Array(this.cols * this.rows).fill(null);
+    } else {
+      const cached = this.cachedTile[slot];
+      if (cached !== null) {
+        return cached;
+      }
+    }
+    const flipMask = this.layerData[idx + 1];
+    const tile = this.getTileById(gidWithFlips(gid, flipMask), _x, _y);
+    this.cachedTile[slot] = tile;
+    return tile;
   }
   /**
    * clear the tile at the specified position
@@ -18654,7 +19072,16 @@ var TMXLayer = class extends Renderable {
    * });
    */
   clearTile(x, y) {
-    this.layerData[x][y] = null;
+    if (x < 0 || x >= this.cols || y < 0 || y >= this.rows) {
+      return;
+    }
+    const slot = y * this.cols + x;
+    const idx = slot * 2;
+    this.layerData[idx] = 0;
+    this.layerData[idx + 1] = 0;
+    if (this.cachedTile !== null) {
+      this.cachedTile[slot] = null;
+    }
     if (this.preRender) {
       this.canvasRenderer.clearRect(
         x * this.tilewidth,
@@ -18663,6 +19090,7 @@ var TMXLayer = class extends Renderable {
         this.tileheight
       );
     }
+    this.dataVersion++;
     this.isDirty = true;
   }
   /**
@@ -18683,27 +19111,7 @@ var TMXLayer = class extends Renderable {
    * @ignore
    */
   draw(renderer2, rect) {
-    if (this.preRender) {
-      const width = Math.min(rect.width, this.width);
-      const height = Math.min(rect.height, this.height);
-      renderer2.drawImage(
-        this.canvasRenderer.getCanvas(),
-        rect.pos.x,
-        rect.pos.y,
-        // sx,sy
-        width,
-        height,
-        // sw,sh
-        rect.pos.x,
-        rect.pos.y,
-        // dx,dy
-        width,
-        height
-        // dw,dh
-      );
-    } else {
-      this.getRenderer().drawTileLayer(renderer2, this, rect);
-    }
+    renderer2.drawTileLayer(this, rect);
   }
 };
 
@@ -19067,7 +19475,7 @@ var TMXHexagonalRenderer = class extends TMXRenderer {
     return ret;
   }
   /**
-   * draw the tile map
+   * draw the tile map (legacy entry point — accepts a fully-constructed Tile)
    * @ignore
    */
   drawTile(renderer2, x, y, tmxTile) {
@@ -19081,12 +19489,27 @@ var TMXHexagonalRenderer = class extends TMXRenderer {
     );
     vector2dPool.release(point);
   }
+  /**
+   * draw a tile from raw (gid, flipMask, tileset) data — used by the hot
+   * rendering loop to bypass Tile construction
+   * @ignore
+   */
+  drawTileRaw(renderer2, x, y, gid, flipMask, tileset) {
+    const point = this.tileToPixelCoords(x, y, vector2dPool.get());
+    tileset.drawTileRaw(
+      renderer2,
+      tileset.tileoffset.x + point.x,
+      tileset.tileoffset.y + point.y + (this.tileheight - tileset.tileheight),
+      gid,
+      flipMask
+    );
+    vector2dPool.release(point);
+  }
   /**
    * draw the tile map
    * @ignore
    */
   drawTileLayer(renderer2, layer, rect) {
-    let tile;
     const startTile = this.pixelToTileCoords(
       rect.pos.x,
       rect.pos.y,
@@ -19110,6 +19533,15 @@ var TMXHexagonalRenderer = class extends TMXRenderer {
     }
     const endX = layer.cols;
     const endY = layer.rows;
+    const layerCols = layer.cols;
+    const data2 = layer.layerData;
+    const tilesets = layer.tilesets;
+    let tilesetCache = layer.tileset;
+    if (tilesetCache === null) {
+      vector2dPool.release(startTile);
+      vector2dPool.release(startPos);
+      return;
+    }
     if (this.staggerX) {
       startTile.x = Math.max(0, startTile.x);
       startTile.y = Math.max(0, startTile.y);
@@ -19123,9 +19555,22 @@ var TMXHexagonalRenderer = class extends TMXRenderer {
         rowTile.setV(startTile);
         rowPos.setV(startPos);
         for (; rowPos.x < rect.right && rowTile.x < endX; rowTile.x += 2) {
-          tile = layer.cellAt(rowTile.x, rowTile.y, false);
-          if (tile) {
-            tile.tileset.drawTile(renderer2, rowPos.x, rowPos.y, tile);
+          if (rowTile.x >= 0 && rowTile.y >= 0 && rowTile.y < layer.rows) {
+            const idx = (rowTile.y * layerCols + rowTile.x) * 2;
+            const gid = data2[idx];
+            if (gid) {
+              const flipMask = data2[idx + 1];
+              if (!tilesetCache.contains(gid)) {
+                tilesetCache = tilesets.getTilesetByGid(gid);
+              }
+              tilesetCache.drawTileRaw(
+                renderer2,
+                rowPos.x,
+                rowPos.y,
+                gid,
+                flipMask
+              );
+            }
           }
           rowPos.x += this.tilewidth + this.sidelengthx;
         }
@@ -19161,9 +19606,22 @@ var TMXHexagonalRenderer = class extends TMXRenderer {
           rowPos.x += this.columnwidth;
         }
         for (; rowPos.x < rect.right && rowTile.x < endX; rowTile.x++) {
-          tile = layer.cellAt(rowTile.x, rowTile.y, false);
-          if (tile) {
-            tile.tileset.drawTile(renderer2, rowPos.x, rowPos.y, tile);
+          if (rowTile.x >= 0 && rowTile.y >= 0 && rowTile.y < layer.rows) {
+            const idx = (rowTile.y * layerCols + rowTile.x) * 2;
+            const gid = data2[idx];
+            if (gid) {
+              const flipMask = data2[idx + 1];
+              if (!tilesetCache.contains(gid)) {
+                tilesetCache = tilesets.getTilesetByGid(gid);
+              }
+              tilesetCache.drawTileRaw(
+                renderer2,
+                rowPos.x,
+                rowPos.y,
+                gid,
+                flipMask
+              );
+            }
           }
           rowPos.x += this.tilewidth + this.sidelengthx;
         }
@@ -19246,7 +19704,7 @@ var TMXIsometricRenderer = class extends TMXRenderer {
     vector2dPool.release(isoPos);
   }
   /**
-   * draw the tile map
+   * draw the tile map (legacy entry point — accepts a fully-constructed Tile)
    * @ignore
    */
   drawTile(renderer2, x, y, tmxTile) {
@@ -19258,6 +19716,20 @@ var TMXIsometricRenderer = class extends TMXRenderer {
       tmxTile
     );
   }
+  /**
+   * draw a tile from raw (gid, flipMask, tileset) data — used by the hot
+   * rendering loop to bypass Tile construction
+   * @ignore
+   */
+  drawTileRaw(renderer2, x, y, gid, flipMask, tileset) {
+    tileset.drawTileRaw(
+      renderer2,
+      (this.cols - 1) * tileset.tilewidth + (x - y) * tileset.tilewidth >> 1,
+      -tileset.tilewidth + (x + y) * tileset.tileheight >> 2,
+      gid,
+      flipMask
+    );
+  }
   /**
    * draw the tile map
    * @ignore
@@ -19300,19 +19772,41 @@ var TMXIsometricRenderer = class extends TMXRenderer {
     }
     let shifted = inUpperHalf ^ inLeftHalf;
     const columnItr = vector2dPool.get().setV(rowItr);
+    const layerCols = layer.cols;
+    const layerRows = layer.rows;
+    const data2 = layer.layerData;
+    const tilesets = layer.tilesets;
+    let tilesetCache = tileset;
+    if (tilesetCache === null) {
+      vector2dPool.release(columnItr);
+      vector2dPool.release(rowItr);
+      vector2dPool.release(tileEnd);
+      vector2dPool.release(rectEnd);
+      vector2dPool.release(startPos);
+      return;
+    }
     for (let y = startPos.y * 2; y - this.tileheight * 2 < rectEnd.y * 2; y += this.tileheight) {
       columnItr.setV(rowItr);
       for (let x = startPos.x; x < rectEnd.x; x += this.tilewidth) {
-        const tmxTile = layer.cellAt(columnItr.x, columnItr.y);
-        if (tmxTile) {
-          tileset = tmxTile.tileset;
-          const offset = tileset.tileoffset;
-          tileset.drawTile(
-            renderer2,
-            offset.x + x,
-            offset.y + y / 2 - tileset.tileheight,
-            tmxTile
-          );
+        const cx = columnItr.x;
+        const cy = columnItr.y;
+        if (cx >= 0 && cx < layerCols && cy >= 0 && cy < layerRows) {
+          const idx = (cy * layerCols + cx) * 2;
+          const gid = data2[idx];
+          if (gid !== 0) {
+            const flipMask = data2[idx + 1];
+            if (!tilesetCache.contains(gid)) {
+              tilesetCache = tilesets.getTilesetByGid(gid);
+            }
+            const offset = tilesetCache.tileoffset;
+            tilesetCache.drawTileRaw(
+              renderer2,
+              offset.x + x,
+              offset.y + y / 2 - tilesetCache.tileheight,
+              gid,
+              flipMask
+            );
+          }
         }
         columnItr.x++;
         columnItr.y--;
@@ -19367,7 +19861,7 @@ var TMXOrthogonalRenderer = class extends TMXRenderer {
     return ret.set(x * this.tilewidth, y * this.tileheight);
   }
   /**
-   * draw the tile map
+   * draw the tile map (legacy entry point — accepts a fully-constructed Tile)
    * @ignore
    */
   drawTile(renderer2, x, y, tmxTile) {
@@ -19379,6 +19873,20 @@ var TMXOrthogonalRenderer = class extends TMXRenderer {
       tmxTile
     );
   }
+  /**
+   * draw a tile from raw (gid, flipMask, tileset) data — used by the hot
+   * rendering loop to bypass Tile construction
+   * @ignore
+   */
+  drawTileRaw(renderer2, x, y, gid, flipMask, tileset) {
+    tileset.drawTileRaw(
+      renderer2,
+      tileset.tileoffset.x + x * this.tilewidth,
+      tileset.tileoffset.y + (y + 1) * this.tileheight - tileset.tileheight,
+      gid,
+      flipMask
+    );
+  }
   /**
    * draw the tile map
    * @ignore
@@ -19416,12 +19924,27 @@ var TMXOrthogonalRenderer = class extends TMXRenderer {
       default:
         break;
     }
+    const cols = layer.cols;
+    const data2 = layer.layerData;
+    const tilesets = layer.tilesets;
+    let tilesetCache = layer.tileset;
+    if (tilesetCache === null) {
+      vector2dPool.release(start);
+      vector2dPool.release(end);
+      return;
+    }
     for (let y = start.y; y !== end.y; y += incY) {
       for (let x = start.x; x !== end.x; x += incX) {
-        const tmxTile = layer.cellAt(x, y, false);
-        if (tmxTile) {
-          this.drawTile(renderer2, x, y, tmxTile);
+        const idx = (y * cols + x) * 2;
+        const gid = data2[idx];
+        if (!gid) {
+          continue;
         }
+        const flipMask = data2[idx + 1];
+        if (!tilesetCache.contains(gid)) {
+          tilesetCache = tilesets.getTilesetByGid(gid);
+        }
+        this.drawTileRaw(renderer2, x, y, gid, flipMask, tilesetCache);
       }
     }
     vector2dPool.release(start);
@@ -19490,7 +20013,7 @@ var TMXObliqueRenderer = class extends TMXOrthogonalRenderer {
     return ret.set(px + this.shearX * py, this.shearY * px + py);
   }
   /**
-   * draw the tile map
+   * draw the tile map (legacy entry point — accepts a fully-constructed Tile)
    * @ignore
    */
   drawTile(renderer2, x, y, tmxTile) {
@@ -19499,6 +20022,16 @@ var TMXObliqueRenderer = class extends TMXOrthogonalRenderer {
     const dy = tileset.tileoffset.y + (y + 1) * this.tileheight - tileset.tileheight + this.skewY * x;
     tileset.drawTile(renderer2, dx, dy, tmxTile);
   }
+  /**
+   * draw a tile from raw (gid, flipMask, tileset) data — used by the hot
+   * rendering loop to bypass Tile construction
+   * @ignore
+   */
+  drawTileRaw(renderer2, x, y, gid, flipMask, tileset) {
+    const dx = tileset.tileoffset.x + x * this.tilewidth + this.skewX * y;
+    const dy = tileset.tileoffset.y + (y + 1) * this.tileheight - tileset.tileheight + this.skewY * x;
+    tileset.drawTileRaw(renderer2, dx, dy, gid, flipMask);
+  }
   /**
    * draw the given TMX Layer for the given area
    * @ignore
@@ -19569,12 +20102,25 @@ var TMXObliqueRenderer = class extends TMXOrthogonalRenderer {
       default:
         break;
     }
+    const cols = layer.cols;
+    const data2 = layer.layerData;
+    const tilesets = layer.tilesets;
+    let tilesetCache = layer.tileset;
+    if (tilesetCache === null) {
+      return;
+    }
     for (let y = startY; y !== endY; y += incY) {
       for (let x = startX; x !== endX; x += incX) {
-        const tmxTile = layer.cellAt(x, y, false);
-        if (tmxTile) {
-          this.drawTile(renderer2, x, y, tmxTile);
+        const idx = (y * cols + x) * 2;
+        const gid = data2[idx];
+        if (!gid) {
+          continue;
         }
+        const flipMask = data2[idx + 1];
+        if (!tilesetCache.contains(gid)) {
+          tilesetCache = tilesets.getTilesetByGid(gid);
+        }
+        this.drawTileRaw(renderer2, x, y, gid, flipMask, tilesetCache);
       }
     }
   }
@@ -19930,6 +20476,7 @@ var TMXGroup = class {
 };
 
 // src/level/tiled/TMXTileset.js
+var SCRATCH_MATRIX = new Matrix2d();
 var TMXTileset = class {
   /**
    *  @param {object} tileset - tileset data in JSON format ({@link http://docs.mapeditor.org/en/stable/reference/tmx-map-format/#tileset})
@@ -20260,6 +20807,96 @@ var TMXTileset = class {
       renderer2.restore();
     }
   }
+  /**
+   * draw a tile at the specified position from raw (gid, flipMask) data
+   *
+   * Like {@link drawTile} but bypasses the {@link Tile} object entirely:
+   * the renderer hot loop can pass the GID and flip mask straight from
+   * `layer.layerData` without ever allocating a Tile instance.
+   *
+   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+   * @param {number} dx - destination x position
+   * @param {number} dy - destination y position
+   * @param {number} gid - the tile's global id (with flip bits already stripped)
+   * @param {number} flipMask - 3-bit packed flip mask (H=1, V=2, AD=4)
+   * @ignore
+   */
+  drawTileRaw(renderer2, dx, dy, gid, flipMask) {
+    let dw, dh;
+    let tileImage;
+    if (this.isCollection) {
+      tileImage = this.imageCollection.get(gid);
+      const tileWidth = tileImage.width;
+      const tileHeight = tileImage.height;
+      if (this.tilerendersize === "grid") {
+        let scaleX = this.mapTilewidth / tileWidth;
+        let scaleY = this.mapTileheight / tileHeight;
+        if (this.fillmode === "preserve-aspect-fit") {
+          const scale2 = Math.min(scaleX, scaleY);
+          scaleX = scale2;
+          scaleY = scale2;
+        }
+        dw = tileWidth * scaleX;
+        dh = tileHeight * scaleY;
+        dy += this.tileheight - dh;
+        if (this.fillmode === "preserve-aspect-fit") {
+          dx += (this.mapTilewidth - dw) / 2;
+          dy -= (this.mapTileheight - dh) / 2;
+        }
+      } else {
+        dw = tileWidth;
+        dh = tileHeight;
+      }
+    } else {
+      dw = this._renderDw;
+      dh = this._renderDh;
+      dy += this._renderDyOffset;
+      dx += this._renderDxCenter;
+      dy += this._renderDyCenter;
+    }
+    if (flipMask !== 0) {
+      renderer2.save();
+      renderer2.translate(dx, dy);
+      renderer2.transform(
+        buildFlipTransform(
+          SCRATCH_MATRIX,
+          flipMask,
+          this.isCollection ? tileImage.width : this.tilewidth,
+          this.isCollection ? tileImage.height : this.tileheight
+        )
+      );
+      dx = dy = 0;
+    }
+    if (this.isCollection) {
+      renderer2.drawImage(
+        tileImage,
+        0,
+        0,
+        tileImage.width,
+        tileImage.height,
+        dx,
+        dy,
+        dw,
+        dh
+      );
+    } else {
+      const offset = this.atlas[this.getViewTileId(gid)].offset;
+      renderer2.drawImage(
+        this.image,
+        offset.x,
+        offset.y,
+        this.tilewidth,
+        this.tileheight,
+        dx,
+        dy,
+        dw + renderer2.uvOffset,
+        dh + renderer2.uvOffset
+      );
+    }
+    if (flipMask !== 0) {
+      renderer2.restore();
+    }
+  }
 };
 
 // src/level/tiled/TMXTilesetGroup.js
@@ -20378,6 +21015,14 @@ function readTileset(data2, mapTilewidth, mapTileheight) {
 function readObjectGroup(map, data2, z) {
   return new TMXGroup(map, data2, z);
 }
+function refreshAbsoluteBounds(container) {
+  container.forEach((child) => {
+    child.updateBounds(true);
+    if (child instanceof Container) {
+      refreshAbsoluteBounds(child);
+    }
+  });
+}
 var TMXTileMap = class {
   /**
    * @param {string} levelId - name of TMX map
@@ -20539,12 +21184,12 @@ var TMXTileMap = class {
           Math.max(levelBounds.width, width),
           Math.max(levelBounds.height, height)
         );
-        container.pos.set(
-          Math.max(0, ~~((width - levelBounds.width) / 2)),
-          Math.max(0, ~~((height - levelBounds.height) / 2)),
-          // don't change the container z position if defined
-          container.pos.z
-        );
+        const newX = Math.max(0, ~~((width - levelBounds.width) / 2));
+        const newY = Math.max(0, ~~((height - levelBounds.height) / 2));
+        if (container.pos.x !== newX || container.pos.y !== newY) {
+          container.pos.set(newX, newY, container.pos.z);
+          refreshAbsoluteBounds(container);
+        }
       };
       var _setBounds = _setBounds2;
       const app = container.getRootAncestor().app;
@@ -21354,6 +21999,7 @@ var Sprite = class extends Renderable {
    * @param {number} [settings.flipX] - flip the sprite on the horizontal axis
    * @param {number} [settings.flipY] - flip the sprite on the vertical axis
    * @param {Vector2d} [settings.anchorPoint={x:0.5, y:0.5}] - Anchor point to draw the frame at (defaults to the center of the frame).
+   * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|string} [settings.normalMap] - optional normal-map texture used for per-pixel lighting (SpriteIlluminator-style). Same layout/UVs as `settings.image`. When omitted (default), the sprite renders unlit and pays no extra cost. Ignored by the Canvas renderer. Note: `HTMLVideoElement` is intentionally not supported — normal maps encode static surface directions in RGB, and the engine caches the GL texture per image reference (a video would freeze on frame 0).
    * @example
    * // create a single sprite from a standalone image, with anchor in the center
    * let sprite = new me.Sprite(0, 0, {
@@ -21390,6 +22036,7 @@ var Sprite = class extends Renderable {
     this.offset = vector2dPool.get(0, 0);
     this.isVideo = false;
     this.source = null;
+    this._normalMap = null;
     this.anim = {};
     this.resetAnim = void 0;
     this.current = {
@@ -21463,6 +22110,25 @@ var Sprite = class extends Renderable {
         this.textureAtlas = this.source.getAtlas();
       }
     }
+    if (settings.image instanceof TextureAtlas && typeof settings.image.getNormalTexture === "function") {
+      const fromAtlas = settings.image.getNormalTexture();
+      if (fromAtlas) {
+        this.normalMap = fromAtlas;
+      }
+    }
+    if (this.normalMap === null && typeof settings.normalMap !== "undefined" && settings.normalMap !== null) {
+      if (typeof settings.normalMap === "string") {
+        const resolved = getImage(settings.normalMap);
+        if (!resolved) {
+          throw new Error(
+            "me.Sprite: '" + settings.normalMap + "' normal map image not found!"
+          );
+        }
+        this.normalMap = resolved;
+      } else {
+        this.normalMap = settings.normalMap;
+      }
+    }
     if (typeof settings.atlas !== "undefined") {
       this.textureAtlas = settings.atlas;
       this.atlasIndices = settings.atlasIndices;
@@ -21505,6 +22171,37 @@ var Sprite = class extends Renderable {
       this.setCurrentAnimation("default");
     }
   }
+  /**
+   * The optional normal-map image paired with this sprite's color
+   * texture (SpriteIlluminator workflow). When set, the WebGL
+   * renderer's lit pipeline samples this texture for per-pixel
+   * lighting using `Stage._activeLights`. `null` when unlit.
+   * Setting any non-image value (or anything without numeric
+   * `width`/`height`) throws — assign `null` to clear.
+   *
+   * Silently ignored by the Canvas renderer.
+   * @type {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|null}
+   */
+  get normalMap() {
+    return this._normalMap;
+  }
+  set normalMap(value) {
+    if (value === null || value === void 0) {
+      this._normalMap = null;
+      return;
+    }
+    if (typeof value !== "object" || typeof value.width !== "number" || typeof value.height !== "number") {
+      throw new TypeError(
+        "Sprite.normalMap must be null or an image-like object with numeric width/height (HTMLImageElement, HTMLCanvasElement, OffscreenCanvas, ImageBitmap)"
+      );
+    }
+    if (typeof value.videoWidth === "number") {
+      throw new TypeError(
+        "Sprite.normalMap does not support HTMLVideoElement (the lit pipeline caches the texture per image reference and would freeze on frame 0)"
+      );
+    }
+    this._normalMap = value;
+  }
   /**
    * return the flickering state of the object
    * @returns {boolean}
@@ -21854,9 +22551,32 @@ var Sprite = class extends Renderable {
     }
     return super.update(dt);
   }
+  /**
+   * Prepare the rendering context before drawing this sprite (automatically called by melonJS).
+   * Extends `Renderable.preDraw` to publish this sprite's `normalMap` (if any)
+   * on the renderer so the WebGL lit pipeline can pair it with the next
+   * `drawImage` call. Cleared back in `postDraw`.
+   * @param {Renderer} renderer - a renderer instance
+   */
+  preDraw(renderer2) {
+    super.preDraw(renderer2);
+    if (this._normalMap !== null) {
+      renderer2.currentNormalMap = this._normalMap;
+    }
+  }
+  /**
+   * restore the rendering context after drawing this sprite (automatically called by melonJS).
+   * @param {Renderer} renderer - a renderer instance
+   */
+  postDraw(renderer2) {
+    if (this._normalMap !== null) {
+      renderer2.currentNormalMap = null;
+    }
+    super.postDraw(renderer2);
+  }
   /**
    * draw this sprite (automatically called by melonJS)
-   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+   * @param {Renderer} renderer - a renderer instance
    * @param {Camera2d} [viewport] - the viewport to (re)draw
    */
   draw(renderer2) {
@@ -21915,6 +22635,7 @@ var Sprite = class extends Renderable {
       this.image.currentTime = 0;
     }
     this.image = void 0;
+    this._normalMap = null;
     super.destroy();
   }
 };
@@ -22108,7 +22829,7 @@ var ColorMatrix = class extends Matrix3d {
 // src/video/webgl/utils/attributes.js
 function extractAttributes(gl, shader) {
   const attributes = {};
-  const attrRx = /attribute\s+\w+\s+(\w+)/g;
+  const attrRx = /(?:^|\n)[ \t]*(?:attribute|in)[ \t]+(?:\w+[ \t]+)+(\w+)/g;
   let match;
   let i = 0;
   while (match = attrRx.exec(shader.vertex)) {
@@ -22119,10 +22840,18 @@ function extractAttributes(gl, shader) {
 
 // src/video/webgl/utils/precision.js
 function setPrecision(src, precision) {
-  if (src.substring(0, 9) !== "precision") {
-    return "precision " + precision + " float;\n" + src;
+  if (/^\s*(?:#version[^\n]*\n)?\s*precision\b/.test(src)) {
+    return src;
   }
-  return src;
+  if (src.substring(0, 8) === "#version") {
+    const inject = "\nprecision " + precision + " float;\nprecision " + precision + " int;";
+    const nl = src.indexOf("\n");
+    if (nl < 0) {
+      return src + inject;
+    }
+    return src.substring(0, nl) + inject + src.substring(nl);
+  }
+  return "precision " + precision + " float;\n" + src;
 }
 function getMaxShaderPrecision(gl, highPrecision = true) {
   if (highPrecision && gl.getShaderPrecisionFormat(gl.VERTEX_SHADER, gl.HIGH_FLOAT).precision > 0 && gl.getShaderPrecisionFormat(gl.FRAGMENT_SHADER, gl.HIGH_FLOAT).precision > 0) {
@@ -22188,17 +22917,56 @@ var fnHash = {
   ivec2: "2iv",
   ivec3: "3iv",
   ivec4: "4iv",
+  uvec2: "2uiv",
+  uvec3: "3uiv",
+  uvec4: "4uiv",
   mat2: "Matrix2fv",
   mat3: "Matrix3fv",
   mat4: "Matrix4fv",
-  sampler2D: "1i"
+  sampler2D: "1i",
+  // WebGL2 integer-typed samplers — bound to a unit just like a
+  // `sampler2D`; the GLSL `usampler2D` / `isampler2D` types let the
+  // shader read raw integer values via `texelFetch` instead of the
+  // normalized-float `texture()` path.
+  usampler2D: "1i",
+  isampler2D: "1i"
 };
+function valuesMatch(cached, val) {
+  if (cached === void 0) {
+    return false;
+  }
+  if (val !== null && typeof val === "object" && typeof val.length === "number") {
+    if (cached.length !== val.length) {
+      return false;
+    }
+    for (let i = 0; i < val.length; i++) {
+      if (cached[i] !== val[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return cached === val;
+}
+function captureValue(prev, val) {
+  if (val === null || typeof val !== "object" || typeof val.length !== "number") {
+    return val;
+  }
+  if (prev !== void 0 && typeof prev === "object" && typeof prev.length === "number" && prev.length === val.length) {
+    for (let i = 0; i < val.length; i++) {
+      prev[i] = val[i];
+    }
+    return prev;
+  }
+  return typeof val.slice === "function" ? val.slice() : Array.from(val);
+}
 function extractUniforms(gl, shader) {
   const uniforms = {};
   const uniRx = /uniform\s+(\w+)\s+(\w+)/g;
   const uniformsData = {};
   const descriptor = {};
   const locations = {};
+  const cache2 = {};
   let match;
   [shader.vertex, shader.fragment].forEach((shader2) => {
     while (match = uniRx.exec(shader2)) {
@@ -22217,6 +22985,10 @@ function extractUniforms(gl, shader) {
       set: (function(name2, type2, fn) {
         if (/^mat/.test(type2)) {
           return function(val) {
+            if (valuesMatch(cache2[name2], val)) {
+              return;
+            }
+            cache2[name2] = captureValue(cache2[name2], val);
             gl[fn](locations[name2], false, val);
           };
         } else {
@@ -22225,6 +22997,10 @@ function extractUniforms(gl, shader) {
             if (val.length && !/v$/.test(fn)) {
               fnv += "v";
             }
+            if (valuesMatch(cache2[name2], val)) {
+              return;
+            }
+            cache2[name2] = captureValue(cache2[name2], val);
             gl[fnv](locations[name2], val);
           };
         }
@@ -22343,8 +23119,6 @@ var GLShader = class {
           stride,
           element.offset
         );
-      } else {
-        gl.disableVertexAttribArray(index);
       }
     }
   }
@@ -23308,6 +24082,13 @@ var Camera2d = class extends Renderable {
     } else {
       renderer2.setProjection(this.projectionMatrix);
     }
+    const stage = state_default.current();
+    renderer2.setLightUniforms(
+      stage?._activeLights,
+      stage?.ambientLightingColor,
+      translateX,
+      translateY
+    );
     container.preDraw(r);
     if (isNonDefault) {
       const view = this.worldView;
@@ -23324,6 +24105,9 @@ var Camera2d = class extends Renderable {
     this.drawFX(renderer2);
     container.postDraw(r);
     this.postDraw(r);
+    if (stage) {
+      stage.drawLighting(renderer2, this, translateX, translateY);
+    }
     r.endPostEffect(this);
     if (this._colorMatrixEffect) {
       const idx = this.postEffects.indexOf(this._colorMatrixEffect);
@@ -23361,28 +24145,50 @@ var Stage = class {
   cameras;
   /**
    * The list of active lights in this stage.
-   * (Note: Canvas Rendering mode will only properly support one light per stage)
+   *
+   * Since 19.3.0, `Light2d` is a first-class world Renderable — the
+   * recommended pattern is to add lights directly to `app.world` (or any
+   * container, including a sprite, so the light follows it via parent
+   * transforms). The `lights` Map remains for backward compatibility:
+   * any entry added via `this.lights.set(name, light)` in
+   * `onResetEvent()` is automatically adopted into the world tree at
+   * stage reset time so it renders normally.
    * @see Light2d
    * @see Stage.ambientLight
    * @example
-   * // create a white spot light
-   * const whiteLight = new Light2d(0, 0, 140, "#fff", 0.7);
-   * // and add the light to this current stage
+   * // recommended:
+   * const whiteLight = new Light2d(100, 100, 140, 140, "#fff", 0.7);
+   * app.world.addChild(whiteLight);
+   *
+   * // legacy (still works, auto-adopted into world):
    * this.lights.set("whiteLight", whiteLight);
-   * // set a dark ambient light
+   *
    * this.ambientLight.parseCSS("#1117");
-   * // make the light follow the mouse
-   * input.registerPointerEvent("pointermove", app.viewport, (event) => {
-   *    whiteLight.centerOn(event.gameX, event.gameY);
-   * });
    */
   lights;
+  /**
+   * Internal set of active lights, auto-populated by `Light2d`'s
+   * `onActivateEvent` / `onDeactivateEvent` hooks. Used by Camera2d's
+   * ambient-overlay pass to compute the cutouts.
+   * @ignore
+   */
+  _activeLights;
   /**
    * an ambient light that will be added to the stage rendering
    * @default "#000000"
    * @see Light2d
    */
   ambientLight;
+  /**
+   * Base light level applied to every normal-mapped sprite in the
+   * lit rendering path. Unlike {@link Stage#ambientLight} (which is
+   * the dark overlay punched by each light's cutout), this color is
+   * added to every lit pixel so unlit areas don't render pure
+   * black. Defaults to black (0, 0, 0) — sprites without a
+   * `normalMap` ignore it entirely.
+   * @default "#000000"
+   */
+  ambientLightingColor;
   /**
    * The given constructor options
    */
@@ -23396,9 +24202,26 @@ var Stage = class {
   constructor(settings) {
     this.cameras = /* @__PURE__ */ new Map();
     this.lights = /* @__PURE__ */ new Map();
+    this._activeLights = /* @__PURE__ */ new Set();
     this.ambientLight = new Color(0, 0, 0, 0);
+    this.ambientLightingColor = new Color(0, 0, 0, 1);
     this.settings = Object.assign({}, default_settings, settings || {});
   }
+  /**
+   * Called by `Light2d.onActivateEvent` to register the light with the
+   * stage's ambient-overlay cutout list. Users normally don't call this.
+   * @ignore
+   */
+  _registerLight(light) {
+    this._activeLights.add(light);
+  }
+  /**
+   * Called by `Light2d.onDeactivateEvent` to deregister the light.
+   * @ignore
+   */
+  _unregisterLight(light) {
+    this._activeLights.delete(light);
+  }
   /**
    * Object reset function
    * @ignore
@@ -23419,6 +24242,13 @@ var Stage = class {
     }
     emit(STAGE_RESET, this);
     this.onResetEvent(app, ...extraArgs);
+    if (app && app.world) {
+      this.lights.forEach((light) => {
+        if (!light.ancestor) {
+          app.world.addChild(light);
+        }
+      });
+    }
   }
   /**
    * update function
@@ -23433,40 +24263,60 @@ var Stage = class {
         isDirty = true;
       }
     });
-    this.lights.forEach((light) => {
-      if (light.update()) {
-        isDirty = true;
-      }
-    });
     return isDirty;
   }
   /**
    * draw the current stage
+   *
+   * Lights are rendered as part of the world tree (they're now first-class
+   * Renderables) and the ambient overlay pass runs inside each Camera's
+   * post-effect FBO bracket via {@link Stage#drawLighting}.
    * @ignore
    * @param renderer - the renderer object to draw with
    * @param world - the world object to draw
    */
   draw(renderer2, world) {
-    const r = renderer2;
     this.cameras.forEach((camera) => {
       camera.draw(renderer2, world);
-      if (this.ambientLight.alpha !== 0) {
-        r.save();
-        this.lights.forEach((light) => {
-          r.setMask(light.getVisibleArea(), true);
-        });
-        r.setColor(this.ambientLight);
-        r.fillRect(0, 0, camera.width, camera.height);
-        r.clearMask();
-        r.restore();
-      }
-      this.lights.forEach((light) => {
-        light.preDraw(r);
-        light.draw(r);
-        light.postDraw(r);
-      });
     });
   }
+  /**
+   * Draw the stage's ambient-light overlay with cutouts for each active
+   * light. Called from each `Camera2d` inside its post-effect FBO bracket —
+   * lights themselves render via the world tree (they're standard
+   * Renderables); this pass only paints the dark fill that the lights cut
+   * holes through.
+   *
+   * Subclasses can override this method to implement custom lighting (e.g.
+   * per-pixel normal-mapped lighting via a custom shader). Called once per
+   * camera per frame.
+   * @param renderer - the active renderer
+   * @param camera - the camera currently rendering this stage
+   * @param translateX - the same world-to-screen X translate that
+   *   `Camera2d.draw()` applies to the world container (i.e.
+   *   `camera.pos.x + camera.offset.x` for the default camera, plus
+   *   the container's own offset for non-default cameras)
+   * @param translateY - the world-to-screen Y translate (see `translateX`)
+   */
+  drawLighting(renderer2, camera, translateX = camera.pos.x + camera.offset.x, translateY = camera.pos.y + camera.offset.y) {
+    if (this.ambientLight.alpha === 0) {
+      return;
+    }
+    const r = renderer2;
+    r.save();
+    const tx = translateX;
+    const ty = translateY;
+    if (tx !== 0 || ty !== 0) {
+      r.translate(-tx, -ty);
+    }
+    this._activeLights.forEach((light) => {
+      r.setMask(light.getVisibleArea(), true);
+    });
+    r.setColor(this.ambientLight);
+    r.fillRect(tx, ty, camera.width, camera.height);
+    r.clearMask();
+    r.restore();
+  }
   /**
    * destroy function
    * @ignore
@@ -23474,9 +24324,12 @@ var Stage = class {
   destroy(app) {
     this.cameras.clear();
     this.lights.forEach((light) => {
-      light.destroy();
+      if (!light.ancestor) {
+        light.destroy();
+      }
     });
     this.lights.clear();
+    this._activeLights.clear();
     this.onDestroyEvent(app);
   }
   /**
@@ -26798,13 +27651,9 @@ var ImageLayer = class extends Sprite {
     if (this.mask) {
       renderer2.setMask(this.mask);
     }
-    renderer2.drawPattern(
-      this._pattern,
-      0,
-      0,
-      viewport.width * 2,
-      viewport.height * 2
-    );
+    const drawW = this.repeatX ? viewport.width * 2 : width;
+    const drawH = this.repeatY ? viewport.height * 2 : height;
+    renderer2.drawPattern(this._pattern, 0, 0, drawW, drawH);
   }
   // called when the layer is removed from the game world or a container
   onDeactivateEvent() {
@@ -26825,64 +27674,33 @@ var ImageLayer = class extends Sprite {
 };
 
 // src/renderable/light2d.js
-function createGradient(light) {
-  const context = light.texture.context;
-  const x1 = light.texture.width / 2;
-  const y1 = light.texture.height / 2;
-  const radiusX = light.radiusX;
-  const radiusY = light.radiusY;
-  let scaleX;
-  let scaleY;
-  let invScaleX;
-  let invScaleY;
-  let gradient;
-  light.texture.clear();
-  if (radiusX >= radiusY) {
-    scaleX = 1;
-    invScaleX = 1;
-    scaleY = radiusY / radiusX;
-    invScaleY = radiusX / radiusY;
-    gradient = context.createRadialGradient(
-      x1,
-      y1 * invScaleY,
-      0,
-      x1,
-      radiusY * invScaleY,
-      radiusX
-    );
-  } else {
-    scaleY = 1;
-    invScaleY = 1;
-    scaleX = radiusX / radiusY;
-    invScaleX = radiusY / radiusX;
-    gradient = context.createRadialGradient(
-      x1 * invScaleX,
-      y1,
-      0,
-      x1 * invScaleX,
-      y1,
-      radiusY
-    );
-  }
-  gradient.addColorStop(0, light.color.toRGBA(light.intensity));
-  gradient.addColorStop(1, light.color.toRGBA(0));
-  context.fillStyle = gradient;
-  context.setTransform(scaleX, 0, 0, scaleY, 0, 0);
-  context.fillRect(
-    0,
-    0,
-    light.texture.width * invScaleX,
-    light.texture.height * invScaleY
-  );
-}
 var Light2d = class extends Renderable {
   /**
-   * @param {number} x - The horizontal position of the light.
-   * @param {number} y - The vertical position of the light.
+   * Create a 2D point light.
+   *
+   * A `Light2d` is a first-class world Renderable: add it to a container
+   * with `app.world.addChild(light)` (or any sub-container, including a
+   * `Sprite`, so the light follows the parent via its transform). On
+   * activation, the light auto-registers with the active `Stage`'s
+   * lighting set so the ambient overlay (`Stage.ambientLight`) cuts a
+   * hole at the light's visible area, and a radial gradient from the
+   * given `color` (full intensity at center → fully transparent at the
+   * radius) is composited additively on top — producing a soft spot
+   * light. Rendering happens inside each `Camera2d`'s post-effect FBO
+   * bracket so any camera shader (vignette, color-matrix, scanlines,
+   * etc.) wraps the lighting output.
+   *
+   * Set `radiusY` to a different value than `radiusX` for a stretched
+   * (elliptical) light. The `intensity` parameter scales the gradient's
+   * inner alpha; the `Stage.ambientLight` color and alpha control how
+   * dark the unlit areas are. Use `light.blendMode` to override the
+   * default additive blend if needed.
+   * @param {number} x - The horizontal position of the light's center (matches `Ellipse(x, y, w, h)` conventions).
+   * @param {number} y - The vertical position of the light's center.
    * @param {number} radiusX - The horizontal radius of the light.
    * @param {number} [radiusY=radiusX] - The vertical radius of the light.
-   * @param {Color|string} [color="#FFF"] - the color of the light
-   * @param {number} [intensity=0.7] - The intensity of the light.
+   * @param {Color|string} [color="#FFF"] - The color of the light at full intensity.
+   * @param {number} [intensity=0.7] - The peak alpha of the radial gradient at the light's center (0–1).
    */
   constructor(x, y, radiusX, radiusY = radiusX, color = "#FFF", intensity = 0.7) {
     super(x, y, radiusX * 2, radiusY * 2);
@@ -26892,32 +27710,77 @@ var Light2d = class extends Renderable {
     this.intensity = intensity;
     this.blendMode = "lighter";
     this.visibleArea = ellipsePool.get(
-      this.centerX,
-      this.centerY,
+      this.pos.x,
+      this.pos.y,
       this.width,
       this.height
     );
-    this.texture = new canvasrendertarget_default(this.width, this.height, {
-      offscreenCanvas: false
-    });
-    this.anchorPoint.set(0, 0);
-    createGradient(this);
+    this.anchorPoint.set(0.5, 0.5);
+    this.illuminationOnly = false;
+    this.lightHeight = Math.max(radiusX, radiusY) * 0.075;
+  }
+  /**
+   * the horizontal coordinate of this light's center.
+   * Overrides Rect's getter, which assumes `pos` is the bbox top-left and
+   * returns `pos.x + width/2`. Light2d uses `anchorPoint = (0.5, 0.5)`, so
+   * `pos` already IS the center.
+   * @type {number}
+   */
+  get centerX() {
+    return this.pos.x;
+  }
+  set centerX(value) {
+    this.pos.x = value;
+    this.recalc();
+    this.updateBounds();
+  }
+  /**
+   * the vertical coordinate of this light's center.
+   * @see Light2d#centerX
+   * @type {number}
+   */
+  get centerY() {
+    return this.pos.y;
+  }
+  set centerY(value) {
+    this.pos.y = value;
+    this.recalc();
+    this.updateBounds();
   }
   /**
-   * returns a geometry representing the visible area of this light
+   * Set new radii for this light.
+   *
+   * Updates `radiusX`/`radiusY` and the underlying bbox (via
+   * `Renderable.resize(width, height)`) so `getBounds()` and
+   * `getVisibleArea()` — which feed the ambient-cutout pass — track the
+   * new size. The Canvas renderer's gradient cache auto-invalidates on
+   * next draw via its property comparison; the WebGL procedural shader
+   * adapts to the new dimensions automatically.
+   *
+   * Named `setRadii` (not `resize`) so it does not shadow
+   * `Renderable.resize(width, height)` — code that operates on a
+   * generic `Renderable` and calls `.resize(w, h)` keeps working when
+   * the instance happens to be a `Light2d`.
+   * @param {number} radiusX - new horizontal radius
+   * @param {number} [radiusY=radiusX] - new vertical radius
+   */
+  setRadii(radiusX, radiusY = radiusX) {
+    this.radiusX = radiusX;
+    this.radiusY = radiusY;
+    this.resize(radiusX * 2, radiusY * 2);
+  }
+  /**
+   * returns a geometry representing the visible area of this light, in
+   * world-space coordinates (so it aligns with the rendered gradient
+   * regardless of camera scroll or container parenting).
    * @returns {Ellipse} the light visible mask
    */
   getVisibleArea() {
-    return this.visibleArea.setShape(
-      this.getBounds().centerX,
-      this.getBounds().centerY,
-      this.width,
-      this.height
-    );
+    const b = this.getBounds();
+    return this.visibleArea.setShape(b.centerX, b.centerY, b.width, b.height);
   }
   /**
    * update function
-   * @param {number} dt - time since the last update in milliseconds.
    * @returns {boolean} true if dirty
    */
   update() {
@@ -26925,25 +27788,50 @@ var Light2d = class extends Renderable {
   }
   /**
    * preDraw this Light2d (automatically called by melonJS)
-   * Note: The renderer should set the blend mode again (after drawing other Light2d objects)
-   * to ensure colors blend correctly in the CanvasRenderer.
-   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+   * @param {Renderer} renderer - a renderer instance
    */
   preDraw(renderer2) {
     super.preDraw(renderer2);
     renderer2.setBlendMode(this.blendMode);
   }
   /**
-   * draw this Light2d (automatically called by melonJS)
-   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
-   * @param {Camera2d} [viewport] - the viewport to (re)draw
+   * draw this Light2d (automatically called by melonJS).
+   *
+   * Delegates to `renderer.drawLight(this)` — each renderer picks its
+   * own implementation (procedural shader on WebGL; cached `Gradient`
+   * rasterized into a shared `CanvasRenderTarget` on Canvas). Light2d
+   * itself doesn't know which path is used.
+   * @param {Renderer} renderer - a renderer instance
    */
   draw(renderer2) {
-    renderer2.drawImage(
-      this.texture.canvas,
-      this.getBounds().x,
-      this.getBounds().y
-    );
+    if (this.illuminationOnly) {
+      return;
+    }
+    renderer2.drawLight(this);
+  }
+  /**
+   * Auto-register this light with the active Stage's lighting set when
+   * added to a container. The Stage uses that set to build the ambient
+   * overlay cutouts; rendering the light itself is handled normally as
+   * part of the world tree walk.
+   * @ignore
+   */
+  onActivateEvent() {
+    const stage = state_default.current();
+    if (stage && typeof stage._registerLight === "function") {
+      stage._registerLight(this);
+    }
+  }
+  /**
+   * Auto-deregister this light from the active Stage's lighting set when
+   * removed from a container.
+   * @ignore
+   */
+  onDeactivateEvent() {
+    const stage = state_default.current();
+    if (stage && typeof stage._unregisterLight === "function") {
+      stage._unregisterLight(this);
+    }
   }
   /**
    * Destroy function<br>
@@ -26952,9 +27840,6 @@ var Light2d = class extends Renderable {
   destroy() {
     colorPool.release(this.color);
     this.color = void 0;
-    const renderer2 = this.parentApp?.renderer ?? game.renderer;
-    this.texture.destroy(renderer2);
-    this.texture = void 0;
     ellipsePool.release(this.visibleArea);
     this.visibleArea = void 0;
     super.destroy();
@@ -27406,7 +28291,7 @@ var Trigger = class extends Renderable {
 };
 
 // src/version.ts
-var version = "19.2.0";
+var version = "19.4.0";
 
 // src/system/bootstrap.ts
 var initialized = false;
@@ -28267,10 +29152,7 @@ function enablePointerEvent() {
         if (activeEventList.indexOf(events[i]) !== -1) {
           pointerEventTarget.addEventListener(
             events[i],
-            throttle(
-              onMoveEvent,
-              throttlingInterval
-            ),
+            throttle(onMoveEvent, throttlingInterval),
             { passive: true }
             // do not preventDefault on Move events
           );
@@ -28783,7 +29665,7 @@ function testEllipseEllipse(a, ellipseA, b, ellipseB, response) {
       return testEllipsePolygon(a, ellipseA, b, ellipseB.toPolygon(), response);
     }
   }
-  const differenceV = T_VECTORS[--T_VECTORS_IDX].copy(b.pos).add(b.ancestor.getAbsolutePosition()).add(ellipseB.pos).sub(a.pos).add(a.ancestor.getAbsolutePosition()).sub(ellipseA.pos);
+  const differenceV = T_VECTORS[--T_VECTORS_IDX].copy(b.pos).add(b.ancestor.getAbsolutePosition()).add(ellipseB.pos).sub(a.pos).sub(a.ancestor.getAbsolutePosition()).sub(ellipseA.pos);
   const radiusA = ellipseA.radius;
   const radiusB = ellipseB.radius;
   const totalRadius = radiusA + radiusB;
@@ -28810,7 +29692,7 @@ function testPolygonEllipse(a, polyA, b, ellipseB, response) {
   if (ellipseB.radiusV.x !== ellipseB.radiusV.y) {
     return testPolygonPolygon(a, polyA, b, ellipseB.toPolygon(), response);
   }
-  const circlePos = T_VECTORS[--T_VECTORS_IDX].copy(b.pos).add(b.ancestor.getAbsolutePosition()).add(ellipseB.pos).sub(a.pos).add(a.ancestor.getAbsolutePosition()).sub(polyA.pos);
+  const circlePos = T_VECTORS[--T_VECTORS_IDX].copy(b.pos).add(b.ancestor.getAbsolutePosition()).add(ellipseB.pos).sub(a.pos).sub(a.ancestor.getAbsolutePosition()).sub(polyA.pos);
   const radius = ellipseB.radius;
   const radius2 = radius * radius;
   const points = polyA.points;
@@ -29436,6 +30318,7 @@ var World = class extends Container {
     this.fps = 60;
     this.gravity = new Vector2d(0, 0.98);
     this.preRender = false;
+    this.gpuTilemap = true;
     this.bodies = /* @__PURE__ */ new Set();
     this.broadphase = new QuadTree(
       this,
@@ -30008,114 +30891,92 @@ function generateJoinCircles(centers, radius) {
   return verts;
 }
 
-// src/video/webgl/shaders/mesh.frag
-var mesh_default = "uniform sampler2D uSampler;\nvarying vec4 vColor;\nvarying vec2 vRegion;\n\nvoid main(void) {\n    gl_FragColor = texture2D(uSampler, vRegion) * vColor;\n}\n";
-
-// src/video/webgl/shaders/mesh.vert
-var mesh_default2 = "// Current vertex point (3D position for mesh rendering)\nattribute vec3 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n}\n";
+// src/video/webgl/lighting/constants.ts
+var MAX_LIGHTS = 8;
 
-// src/video/buffer/vertex.js
-var VertexArrayBuffer = class {
-  constructor(vertexSize, maxVertex) {
-    this.vertexSize = vertexSize;
-    this.maxVertex = maxVertex;
-    this.vertexCount = 0;
-    this.buffer = new ArrayBuffer(
-      this.maxVertex * this.vertexSize * Float32Array.BYTES_PER_ELEMENT
-    );
-    this.bufferF32 = new Float32Array(this.buffer);
-    this.bufferU32 = new Uint32Array(this.buffer);
-  }
-  /**
-   * clear the vertex array buffer
-   * @ignore
-   */
-  clear() {
-    this.vertexCount = 0;
-  }
-  /**
-   * return true if full
-   * @ignore
-   */
-  isFull(vertex) {
-    return this.vertexCount + vertex >= this.maxVertex;
-  }
-  /**
-   * push a new vertex to the buffer
-   * @param {number} x - x position
-   * @param {number} y - y position
-   * @param {number} u - texture U coordinate
-   * @param {number} v - texture V coordinate
-   * @param {number} tint - tint color in UINT32 (argb) format
-   * @param {number} [textureId] - texture unit index for multi-texture batching
-   * @ignore
-   */
-  push(x, y, u, v, tint, textureId) {
-    const offset = this.vertexCount * this.vertexSize;
-    this.bufferF32[offset] = x;
-    this.bufferF32[offset + 1] = y;
-    this.bufferF32[offset + 2] = u;
-    this.bufferF32[offset + 3] = v;
-    this.bufferU32[offset + 4] = tint;
-    if (this.vertexSize > 5) {
-      this.bufferF32[offset + 5] = textureId || 0;
-    }
-    this.vertexCount++;
-    return this;
-  }
-  /**
-   * push a new vertex with all-float data to the buffer
-   * @param {ArrayLike<number>} data - float values for one vertex
-   * @param {number} srcOffset - start index in the source data
-   * @param {number} count - number of floats to copy (should equal vertexSize)
-   * @ignore
-   */
-  pushFloats(data2, srcOffset, count) {
-    const offset = this.vertexCount * this.vertexSize;
-    for (let i = 0; i < count; i++) {
-      this.bufferF32[offset + i] = data2[srcOffset + i];
-    }
-    this.vertexCount++;
-    return this;
-  }
-  /**
-   * push a new vertex to the buffer (mesh format: x, y, z, u, v, tint)
-   * @ignore
-   */
-  pushMesh(x, y, z, u, v, tint) {
-    const offset = this.vertexCount * this.vertexSize;
-    this.bufferF32[offset] = x;
-    this.bufferF32[offset + 1] = y;
-    this.bufferF32[offset + 2] = z;
-    this.bufferF32[offset + 3] = u;
-    this.bufferF32[offset + 4] = v;
-    this.bufferU32[offset + 5] = tint;
-    this.vertexCount++;
-    return this;
-  }
-  /**
-   * return a reference to the data in Float32 format
-   * @ignore
-   */
-  toFloat32(begin, end) {
-    if (typeof end !== "undefined") {
-      return this.bufferF32.subarray(begin, end);
+// src/video/webgl/shaders/multitexture-lit.js
+function buildSamplerSelect(varName, samplerPrefix, count, target) {
+  const lines = [];
+  for (let i = 0; i < count; i++) {
+    if (i === 0) {
+      lines.push("    if (" + varName + " < 0.5) {");
     } else {
-      return this.bufferF32;
+      lines.push("    } else if (" + varName + " < " + (i + 0.5) + ") {");
     }
+    lines.push(
+      "        " + target + " = texture2D(" + samplerPrefix + i + ", vRegion);"
+    );
   }
-  /**
-   * return a reference to the data in Uint32 format
-   * @ignore
-   */
-  toUint32(begin, end) {
-    if (typeof end !== "undefined") {
-      return this.bufferU32.subarray(begin, end);
-    } else {
-      return this.bufferU32;
-    }
+  lines.push("    } else {");
+  lines.push(
+    "        " + target + " = texture2D(" + samplerPrefix + "0, vRegion);"
+  );
+  lines.push("    }");
+  return lines;
+}
+function buildLitMultiTextureFragment(maxTextures) {
+  const count = Math.max(maxTextures, 1);
+  const lines = [];
+  for (let i = 0; i < count; i++) {
+    lines.push("uniform sampler2D uSampler" + i + ";");
   }
-};
+  for (let i = 0; i < count; i++) {
+    lines.push("uniform sampler2D uNormalSampler" + i + ";");
+  }
+  lines.push("uniform int uLightCount;");
+  lines.push("uniform vec4 uLightPos[" + MAX_LIGHTS + "];");
+  lines.push("uniform vec3 uLightColor[" + MAX_LIGHTS + "];");
+  lines.push("uniform float uLightHeight[" + MAX_LIGHTS + "];");
+  lines.push("uniform vec3 uAmbient;");
+  lines.push("varying vec4 vColor;");
+  lines.push("varying vec2 vRegion;");
+  lines.push("varying float vTextureId;");
+  lines.push("varying float vNormalTextureId;");
+  lines.push("varying vec2 vWorldPos;");
+  lines.push("");
+  lines.push("void main(void) {");
+  lines.push("    vec4 color;");
+  lines.push(...buildSamplerSelect("vTextureId", "uSampler", count, "color"));
+  lines.push("    if (vNormalTextureId < -0.5) {");
+  lines.push("        gl_FragColor = color * vColor;");
+  lines.push("        return;");
+  lines.push("    }");
+  lines.push("    vec4 normalSample;");
+  lines.push(
+    ...buildSamplerSelect(
+      "vNormalTextureId",
+      "uNormalSampler",
+      count,
+      "normalSample"
+    )
+  );
+  lines.push(
+    "    vec3 normal = normalize(normalSample.rgb * 2.0 - vec3(1.0));"
+  );
+  lines.push("    normal.y = -normal.y;");
+  lines.push("    vec3 lighting = uAmbient;");
+  lines.push("    for (int i = 0; i < " + MAX_LIGHTS + "; i++) {");
+  lines.push("        if (i >= uLightCount) break;");
+  lines.push("        vec4 lp = uLightPos[i];");
+  lines.push("        vec2 toLight = lp.xy - vWorldPos;");
+  lines.push("        float dist = length(toLight);");
+  lines.push("        float linear = max(0.0, 1.0 - dist / max(lp.z, 1.0));");
+  lines.push("        float att = linear * linear;");
+  lines.push(
+    "        vec3 lightDir = normalize(vec3(toLight, uLightHeight[i]));"
+  );
+  lines.push("        float NdotL = max(0.0, dot(normal, lightDir));");
+  lines.push("        lighting += uLightColor[i] * (lp.w * att * NdotL);");
+  lines.push("    }");
+  lines.push(
+    "    gl_FragColor = vec4(color.rgb * lighting, color.a) * vColor;"
+  );
+  lines.push("}");
+  return lines.join("\n");
+}
+
+// src/video/webgl/shaders/quad-multi-lit.vert
+var quad_multi_lit_default = "// Lit-aware vertex shader used by `LitQuadBatcher` (the SpriteIlluminator\n// path). Carries a paired `aNormalTextureId` per vertex so the fragment\n// shader knows which `uNormalSampler<n>` to read, and `vWorldPos` so the\n// lit math can compute per-fragment `lightPos - pos` deltas.\nattribute vec2 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\nattribute float aTextureId;\nattribute float aNormalTextureId;\n\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\nvarying float vTextureId;\nvarying float vNormalTextureId;\n// Pre-projection vertex position (in the renderer's pre-projection\n// space \u2014 typically camera-local for default cameras with the world\n// container's translate applied). Used by the lit fragment path to\n// compute `lightPos - fragmentPos` for each Light2d.\nvarying vec2 vWorldPos;\n\nvoid main(void) {\n    gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n    vTextureId = aTextureId;\n    vNormalTextureId = aNormalTextureId;\n    vWorldPos = aVertex;\n}\n";
 
 // src/video/buffer/index.js
 var IndexBuffer = class {
@@ -30216,6 +31077,145 @@ var WebGLIndexBuffer = class extends IndexBuffer {
   }
 };
 
+// src/video/webgl/shaders/multitexture.js
+function buildMultiTextureFragment(maxTextures) {
+  const count = Math.max(maxTextures, 1);
+  const lines = [];
+  for (let i = 0; i < count; i++) {
+    lines.push("uniform sampler2D uSampler" + i + ";");
+  }
+  lines.push("varying vec4 vColor;");
+  lines.push("varying vec2 vRegion;");
+  lines.push("varying float vTextureId;");
+  lines.push("");
+  lines.push("void main(void) {");
+  lines.push("    vec4 color;");
+  for (let i = 0; i < count; i++) {
+    if (i === 0) {
+      lines.push("    if (vTextureId < 0.5) {");
+    } else {
+      lines.push("    } else if (vTextureId < " + (i + 0.5) + ") {");
+    }
+    lines.push("        color = texture2D(uSampler" + i + ", vRegion);");
+  }
+  lines.push("    } else {");
+  lines.push("        color = texture2D(uSampler0, vRegion);");
+  lines.push("    }");
+  lines.push("    gl_FragColor = color * vColor;");
+  lines.push("}");
+  return lines.join("\n");
+}
+
+// src/video/webgl/shaders/quad-multi.vert
+var quad_multi_default = "// Current vertex point\nattribute vec2 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\nattribute float aTextureId;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\nvarying float vTextureId;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n    vTextureId = aTextureId;\n}\n";
+
+// src/video/buffer/vertex.js
+var VertexArrayBuffer = class {
+  constructor(vertexSize, maxVertex) {
+    this.vertexSize = vertexSize;
+    this.maxVertex = maxVertex;
+    this.vertexCount = 0;
+    this.buffer = new ArrayBuffer(
+      this.maxVertex * this.vertexSize * Float32Array.BYTES_PER_ELEMENT
+    );
+    this.bufferF32 = new Float32Array(this.buffer);
+    this.bufferU32 = new Uint32Array(this.buffer);
+  }
+  /**
+   * clear the vertex array buffer
+   * @ignore
+   */
+  clear() {
+    this.vertexCount = 0;
+  }
+  /**
+   * return true if full
+   * @ignore
+   */
+  isFull(vertex) {
+    return this.vertexCount + vertex >= this.maxVertex;
+  }
+  /**
+   * push a new vertex to the buffer
+   * @param {number} x - x position
+   * @param {number} y - y position
+   * @param {number} u - texture U coordinate
+   * @param {number} v - texture V coordinate
+   * @param {number} tint - tint color in UINT32 (argb) format
+   * @param {number} [textureId] - texture unit index for multi-texture batching
+   * @param {number} [normalTextureId] - paired normal-map texture unit index, or `-1` for unlit quads
+   * @ignore
+   */
+  push(x, y, u, v, tint, textureId, normalTextureId) {
+    const offset = this.vertexCount * this.vertexSize;
+    this.bufferF32[offset] = x;
+    this.bufferF32[offset + 1] = y;
+    this.bufferF32[offset + 2] = u;
+    this.bufferF32[offset + 3] = v;
+    this.bufferU32[offset + 4] = tint;
+    if (this.vertexSize > 5) {
+      this.bufferF32[offset + 5] = textureId || 0;
+      if (this.vertexSize > 6) {
+        this.bufferF32[offset + 6] = typeof normalTextureId === "number" ? normalTextureId : -1;
+      }
+    }
+    this.vertexCount++;
+    return this;
+  }
+  /**
+   * push a new vertex with all-float data to the buffer
+   * @param {ArrayLike<number>} data - float values for one vertex
+   * @param {number} srcOffset - start index in the source data
+   * @param {number} count - number of floats to copy (should equal vertexSize)
+   * @ignore
+   */
+  pushFloats(data2, srcOffset, count) {
+    const offset = this.vertexCount * this.vertexSize;
+    for (let i = 0; i < count; i++) {
+      this.bufferF32[offset + i] = data2[srcOffset + i];
+    }
+    this.vertexCount++;
+    return this;
+  }
+  /**
+   * push a new vertex to the buffer (mesh format: x, y, z, u, v, tint)
+   * @ignore
+   */
+  pushMesh(x, y, z, u, v, tint) {
+    const offset = this.vertexCount * this.vertexSize;
+    this.bufferF32[offset] = x;
+    this.bufferF32[offset + 1] = y;
+    this.bufferF32[offset + 2] = z;
+    this.bufferF32[offset + 3] = u;
+    this.bufferF32[offset + 4] = v;
+    this.bufferU32[offset + 5] = tint;
+    this.vertexCount++;
+    return this;
+  }
+  /**
+   * return a reference to the data in Float32 format
+   * @ignore
+   */
+  toFloat32(begin, end) {
+    if (typeof end !== "undefined") {
+      return this.bufferF32.subarray(begin, end);
+    } else {
+      return this.bufferF32;
+    }
+  }
+  /**
+   * return a reference to the data in Uint32 format
+   * @ignore
+   */
+  toUint32(begin, end) {
+    if (typeof end !== "undefined") {
+      return this.bufferU32.subarray(begin, end);
+    } else {
+      return this.bufferU32;
+    }
+  }
+};
+
 // src/video/webgl/batchers/batcher.js
 var DEFAULT_MAX_VERTICES = 4096;
 var Batcher = class {
@@ -30314,6 +31314,25 @@ var Batcher = class {
       this.useShader(this.defaultShader);
     }
   }
+  /**
+   * called by the WebGL renderer when this batcher is being replaced by another.
+   * Disables this batcher's vertex attribute locations so they don't leak across
+   * (otherwise stale stride/offset state can cause INVALID_OPERATION on the next draw).
+   */
+  unbind() {
+    if (this.currentShader === void 0) {
+      return;
+    }
+    const gl = this.gl;
+    for (let i = 0; i < this.attributes.length; ++i) {
+      const location = this.currentShader.getAttribLocation(
+        this.attributes[i].name
+      );
+      if (location !== -1) {
+        gl.disableVertexAttribArray(location);
+      }
+    }
+  }
   /**
    * Select the shader to use for compositing
    * @see GLShader
@@ -30322,6 +31341,9 @@ var Batcher = class {
   useShader(shader) {
     if (this.currentShader !== shader || this.renderer.currentProgram !== shader.program) {
       this.flush();
+      if (this.currentShader && this.currentShader !== shader) {
+        this.unbind();
+      }
       shader.bind();
       shader.setUniform(this.projectionUniform, this.renderer.projectionMatrix);
       shader.setVertexAttributes(this.gl, this.attributes, this.stride);
@@ -30492,8 +31514,15 @@ var MaterialBatcher = class extends Batcher {
   createTexture2D(unit, pixels = null, filter, repeat = "no-repeat", w = pixels.width, h = pixels.height, premultipliedAlpha = true, mipmap = true, texture, flush = true) {
     const gl = this.gl;
     const isPOT = isPowerOfTwo(w) && isPowerOfTwo(h);
-    const rs = repeat.search(/^repeat(-x)?$/) === 0 && (isPOT || this.renderer.WebGLVersion > 1) ? gl.REPEAT : gl.CLAMP_TO_EDGE;
-    const rt = repeat.search(/^repeat(-y)?$/) === 0 && (isPOT || this.renderer.WebGLVersion > 1) ? gl.REPEAT : gl.CLAMP_TO_EDGE;
+    const wantsRepeat = repeat !== "no-repeat";
+    const canRepeat = isPOT || this.renderer.WebGLVersion > 1;
+    const rs = repeat.search(/^repeat(-x)?$/) === 0 && canRepeat ? gl.REPEAT : gl.CLAMP_TO_EDGE;
+    const rt = repeat.search(/^repeat(-y)?$/) === 0 && canRepeat ? gl.REPEAT : gl.CLAMP_TO_EDGE;
+    if (wantsRepeat && !canRepeat) {
+      console.warn(
+        "melonJS: repeat wrap (" + repeat + ") requested on a non-power-of-two texture (" + w + "x" + h + ") under WebGL 1 \u2014 downgrading to clamp-to-edge"
+      );
+    }
     let currentTexture = texture;
     if (!currentTexture) {
       currentTexture = gl.createTexture();
@@ -30504,7 +31533,9 @@ var MaterialBatcher = class extends Batcher {
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
     gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, premultipliedAlpha);
-    if (pixels !== null && pixels.compressed === true) {
+    if (pixels !== null && typeof pixels.upload === "function") {
+      pixels.upload(gl, gl.TEXTURE_2D);
+    } else if (pixels !== null && pixels.compressed === true) {
       const mipmaps = pixels.mipmaps;
       for (let i = 0; i < mipmaps.length; i++) {
         gl.compressedTexImage2D(
@@ -30565,7 +31596,9 @@ var MaterialBatcher = class extends Batcher {
         pixels
       );
     }
-    if (isPOT && mipmap === true && (pixels === null || pixels.compressed !== true)) {
+    if (isPOT && mipmap === true && pixels !== null && pixels.compressed !== true && typeof pixels.upload !== "function") {
+      gl.generateMipmap(gl.TEXTURE_2D);
+    } else if (pixels === null && isPOT && mipmap === true) {
       gl.generateMipmap(gl.TEXTURE_2D);
     }
     return currentTexture;
@@ -30643,18 +31676,29 @@ var MaterialBatcher = class extends Batcher {
   }
   /**
    * @ignore
+   * @param {TextureAtlas|TextureResource} texture
+   * @param {number} [w] - ignored when the source has its own `width` (the
+   *   common case); kept for the legacy signature where callers passed a
+   *   destination size. Forwarded only as a last-resort default.
+   * @param {number} [h] - same as `w`.
+   * @param {boolean} [force=false]
+   * @param {boolean} [flush=true]
    */
   uploadTexture(texture, w, h, force = false, flush = true) {
     const unit = this.renderer.cache.getUnit(texture);
     const texture2D = this.boundTextures[unit];
     if (typeof texture2D === "undefined" || force) {
+      const filter = typeof texture.filter !== "undefined" ? texture.filter : this.renderer.settings.antiAlias ? this.gl.LINEAR : this.gl.NEAREST;
+      const source = texture.getTexture();
+      const texW = source.width || source.videoWidth || w;
+      const texH = source.height || source.videoHeight || h;
       this.createTexture2D(
         unit,
-        texture.getTexture(),
-        this.renderer.settings.antiAlias ? this.gl.LINEAR : this.gl.NEAREST,
+        source,
+        filter,
         texture.repeat,
-        w,
-        h,
+        texW,
+        texH,
         texture.premultipliedAlpha,
         void 0,
         texture2D,
@@ -30667,6 +31711,514 @@ var MaterialBatcher = class extends Batcher {
   }
 };
 
+// src/video/webgl/batchers/quad_batcher.js
+var V_ARRAY = [
+  new Vector2d(),
+  new Vector2d(),
+  new Vector2d(),
+  new Vector2d()
+];
+var QuadBatcher = class extends MaterialBatcher {
+  /**
+   * Initialize the compositor
+   * @ignore
+   */
+  init(renderer2) {
+    this.maxBatchTextures = Math.min(renderer2.maxTextures, 16);
+    super.init(renderer2, {
+      attributes: [
+        {
+          name: "aVertex",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 0 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aRegion",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 2 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aColor",
+          size: 4,
+          type: renderer2.gl.UNSIGNED_BYTE,
+          normalized: true,
+          offset: 4 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aTextureId",
+          size: 1,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 5 * Float32Array.BYTES_PER_ELEMENT
+        }
+      ],
+      shader: {
+        vertex: quad_multi_default,
+        fragment: buildMultiTextureFragment(this.maxBatchTextures)
+      }
+    });
+    this.bindColorSamplers();
+    this.useMultiTexture = true;
+    this.createIndexBuffer();
+  }
+  /**
+   * (Re-)create the index buffer for quad batching (4 verts + 6 indices per quad).
+   * Called from `init` and `reset` (after context loss).
+   * @ignore
+   */
+  createIndexBuffer() {
+    const maxQuads = this.vertexData.maxVertex / 4;
+    this.indexBuffer = new WebGLIndexBuffer(
+      this.gl,
+      maxQuads * 6,
+      this.renderer.WebGLVersion > 1
+    );
+    this.indexBuffer.fillQuadPattern(maxQuads);
+  }
+  /**
+   * Bind the color sampler uniforms (`uSampler0..uSamplerN-1`) to their
+   * respective texture units. Called from `init` and `reset`.
+   * @ignore
+   */
+  bindColorSamplers() {
+    for (let i = 0; i < this.maxBatchTextures; i++) {
+      this.defaultShader.setUniform("uSampler" + i, i);
+    }
+  }
+  /**
+   * Select the shader to use for compositing.
+   * Multi-texture batching is automatically enabled when the default
+   * shader is active, and disabled for custom ShaderEffect shaders.
+   * @see GLShader
+   * @see ShaderEffect
+   * @param {GLShader|ShaderEffect} shader - a reference to a GLShader or ShaderEffect instance
+   */
+  useShader(shader) {
+    super.useShader(shader);
+    this.useMultiTexture = shader === this.defaultShader;
+  }
+  /**
+   * Reset compositor internal state
+   * @ignore
+   */
+  reset() {
+    super.reset();
+    this.createIndexBuffer();
+    this.bindColorSamplers();
+    this.useMultiTexture = true;
+  }
+  /**
+   * Flush batched texture data to the GPU using indexed drawing.
+   * @param {number} [mode=gl.TRIANGLES] - the GL drawing mode
+   */
+  flush(mode = this.mode) {
+    const vertex = this.vertexData;
+    const vertexCount = vertex.vertexCount;
+    if (vertexCount > 0) {
+      const gl = this.gl;
+      const vertexSize = vertex.vertexSize;
+      this.indexBuffer.bind();
+      if (this.renderer.WebGLVersion > 1) {
+        gl.bufferData(
+          gl.ARRAY_BUFFER,
+          vertex.toFloat32(),
+          gl.STREAM_DRAW,
+          0,
+          vertexCount * vertexSize
+        );
+      } else {
+        gl.bufferData(
+          gl.ARRAY_BUFFER,
+          vertex.toFloat32(0, vertexCount * vertexSize),
+          gl.STREAM_DRAW
+        );
+      }
+      const indexCount = vertexCount / 4 * 6;
+      gl.drawElements(mode, indexCount, this.indexBuffer.type, 0);
+      vertex.clear();
+    }
+  }
+  /**
+   * Draw a screen-aligned quad with the given raw WebGL texture through the given shader.
+   * Binds the texture to unit 0, pushes 4 vertices (Y-flipped UVs), flushes,
+   * then unbinds the texture.
+   * @param {WebGLTexture} source - the raw GL texture to blit
+   * @param {number} x - destination x
+   * @param {number} y - destination y
+   * @param {number} width - destination width
+   * @param {number} height - destination height
+   * @param {GLShader|ShaderEffect} shader - the shader effect to apply
+   */
+  blitTexture(source, x, y, width, height, shader) {
+    const gl = this.gl;
+    this.useShader(shader);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, source);
+    this.currentTextureUnit = 0;
+    this.boundTextures[0] = source;
+    shader.setUniform("uSampler", 0);
+    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 = 4294967295;
+    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();
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    this.currentTextureUnit = -1;
+    delete this.boundTextures[0];
+    this.useShader(this.defaultShader);
+  }
+  /**
+   * Add a textured quad
+   * @param {TextureAtlas} texture - Source texture atlas
+   * @param {number} x - Destination x-coordinate
+   * @param {number} y - Destination y-coordinate
+   * @param {number} w - Destination width
+   * @param {number} h - Destination height
+   * @param {number} u0 - Texture UV (u0) value.
+   * @param {number} v0 - Texture UV (v0) value.
+   * @param {number} u1 - Texture UV (u1) value.
+   * @param {number} v1 - Texture UV (v1) value.
+   * @param {number} tint - tint color to be applied to the texture in UINT32 (argb) format
+   * @param {boolean} [reupload=false] - Force the texture to be reuploaded even if already bound
+   */
+  addQuad(texture, x, y, w, h, u0, v0, u1, v1, tint, reupload = false) {
+    const vertexData = this.vertexData;
+    if (vertexData.isFull(4)) {
+      this.flush();
+    }
+    let unit;
+    if (this.useMultiTexture) {
+      unit = this.uploadTexture(texture, w, h, reupload, false);
+      if (unit >= this.maxBatchTextures) {
+        this.flush();
+        this.renderer.cache.resetUnitAssignments();
+        unit = this.uploadTexture(texture, w, h, reupload, false);
+      }
+    } else {
+      unit = this.uploadTexture(texture, w, h, reupload);
+      if (unit !== this.currentSamplerUnit) {
+        this.currentShader.setUniform("uSampler", unit);
+        this.currentSamplerUnit = unit;
+      }
+    }
+    const m = this.viewMatrix;
+    const vec0 = V_ARRAY[0].set(x, y);
+    const vec1 = V_ARRAY[1].set(x + w, y);
+    const vec2 = V_ARRAY[2].set(x, y + h);
+    const vec3 = V_ARRAY[3].set(x + w, y + h);
+    if (!m.isIdentity()) {
+      m.apply(vec0);
+      m.apply(vec1);
+      m.apply(vec2);
+      m.apply(vec3);
+    }
+    const textureId = this.useMultiTexture ? unit : 0;
+    vertexData.push(vec0.x, vec0.y, u0, v0, tint, textureId);
+    vertexData.push(vec1.x, vec1.y, u1, v0, tint, textureId);
+    vertexData.push(vec2.x, vec2.y, u0, v1, tint, textureId);
+    vertexData.push(vec3.x, vec3.y, u1, v1, tint, textureId);
+  }
+};
+
+// src/video/webgl/batchers/lit_quad_batcher.js
+var LitQuadBatcher = class extends QuadBatcher {
+  /**
+   * @ignore
+   */
+  init(renderer2) {
+    const halved = Math.min(
+      Math.max(1, Math.floor(renderer2.maxTextures / 2)),
+      16
+    );
+    this.maxBatchTextures = halved;
+    Object.getPrototypeOf(QuadBatcher.prototype).init.call(this, renderer2, {
+      attributes: [
+        {
+          name: "aVertex",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 0 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aRegion",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 2 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aColor",
+          size: 4,
+          type: renderer2.gl.UNSIGNED_BYTE,
+          normalized: true,
+          offset: 4 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aTextureId",
+          size: 1,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 5 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aNormalTextureId",
+          size: 1,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 6 * Float32Array.BYTES_PER_ELEMENT
+        }
+      ],
+      shader: {
+        vertex: quad_multi_lit_default,
+        fragment: buildLitMultiTextureFragment(halved)
+      }
+    });
+    this.bindColorSamplers();
+    this.bindNormalSamplers();
+    this.createIndexBuffer();
+    this.useMultiTexture = true;
+    this.boundNormalMaps = new Array(halved).fill(null);
+    this.normalMapTextures = /* @__PURE__ */ new Map();
+    this._lightCount = 0;
+    this._maxLights = MAX_LIGHTS;
+    this.defaultShader.setUniform("uLightCount", 0);
+    this.defaultShader.setUniform("uAmbient", [0, 0, 0]);
+  }
+  /**
+   * Bind the paired normal sampler uniforms (`uNormalSampler0..N-1`)
+   * to texture units `maxBatchTextures..2*maxBatchTextures-1`. Called
+   * from `init` and `reset`.
+   * @ignore
+   */
+  bindNormalSamplers() {
+    for (let i = 0; i < this.maxBatchTextures; i++) {
+      this.defaultShader.setUniform(
+        "uNormalSampler" + i,
+        this.maxBatchTextures + i
+      );
+    }
+  }
+  /**
+   * @ignore
+   */
+  reset() {
+    super.reset();
+    this.bindNormalSamplers();
+    this.boundNormalMaps.fill(null);
+    this.normalMapTextures.clear();
+    this._lightCount = 0;
+    this.defaultShader.setUniform("uLightCount", 0);
+    this.defaultShader.setUniform("uAmbient", [0, 0, 0]);
+  }
+  /**
+   * Upload per-frame Light2d uniforms used by the lit fragment path.
+   * Called once per camera per frame (before the world tree walk).
+   * Lights past `MAX_LIGHTS` are silently ignored.
+   *
+   * Coordinates must be supplied in the same space as the renderer's
+   * pre-projection vertex coords (i.e. camera-local / FBO-local),
+   * matching `Stage.drawLighting`'s convention.
+   * @param {object} uniforms
+   * @param {Float32Array} uniforms.positions - flat array of `[x, y, radius, intensity]` per light, length = 4 * count
+   * @param {Float32Array} uniforms.colors - flat array of `[r, g, b]` per light, length = 3 * count
+   * @param {Float32Array} [uniforms.heights] - flat array of per-light height, length = MAX_LIGHTS
+   * @param {number} uniforms.count - number of lights to render (clamped to MAX_LIGHTS)
+   * @param {number[]} [uniforms.ambient] - `[r, g, b]` ambient floor (0..1 each)
+   */
+  setLightUniforms(uniforms) {
+    const shader = this.defaultShader;
+    const count = Math.min(uniforms.count | 0, this._maxLights);
+    this._lightCount = count;
+    shader.setUniform("uLightCount", count);
+    if (count > 0) {
+      shader.setUniform("uLightPos", uniforms.positions);
+      shader.setUniform("uLightColor", uniforms.colors);
+      if (uniforms.heights) {
+        shader.setUniform("uLightHeight", uniforms.heights);
+      }
+    }
+    if (uniforms.ambient) {
+      shader.setUniform("uAmbient", uniforms.ambient);
+    }
+  }
+  /**
+   * Bind a normal-map image to the given GL texture unit. Uploads on
+   * first use (via `uploadNormalMap`) and rebinds the cached
+   * `WebGLTexture` on subsequent calls. Mirrors the
+   * `bindTexture2D` / `createTexture2D` split used by `MaterialBatcher`,
+   * but for normal-map textures which live outside the color
+   * `TextureCache` (cached per-image in `normalMapTextures`).
+   * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image - normal-map source
+   * @param {number} unit - GL texture unit (already offset by `maxBatchTextures`)
+   */
+  bindNormalMap(image, unit) {
+    const cached = this.normalMapTextures.get(image);
+    if (typeof cached !== "undefined") {
+      this.bindTexture2D(cached, unit, false);
+      return;
+    }
+    this.uploadNormalMap(image, unit);
+  }
+  /**
+   * Upload a normal-map image to GL and cache the resulting `WebGLTexture`
+   * for future `bindNormalMap` calls. Not meant to be called directly —
+   * `bindNormalMap` invokes this on the first use of a given image.
+   *
+   * `premultipliedAlpha = false` — normal maps store linear-encoded
+   * surface normals; multiplying through alpha would corrupt the
+   * encoding for any non-opaque texel.
+   * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image - normal-map source
+   * @param {number} unit - GL texture unit (already offset by `maxBatchTextures`)
+   */
+  uploadNormalMap(image, unit) {
+    const gl = this.gl;
+    this.createTexture2D(
+      unit,
+      image,
+      this.renderer.settings.antiAlias ? gl.LINEAR : gl.NEAREST,
+      "no-repeat",
+      image.width,
+      image.height,
+      false,
+      void 0,
+      void 0,
+      false
+    );
+    this.normalMapTextures.set(image, this.boundTextures[unit]);
+  }
+  /**
+   * Add a textured quad with optional paired normal map.
+   * @param {TextureAtlas} texture - Source texture atlas
+   * @param {number} x - Destination x-coordinate
+   * @param {number} y - Destination y-coordinate
+   * @param {number} w - Destination width
+   * @param {number} h - Destination height
+   * @param {number} u0 - Texture UV (u0) value
+   * @param {number} v0 - Texture UV (v0) value
+   * @param {number} u1 - Texture UV (u1) value
+   * @param {number} v1 - Texture UV (v1) value
+   * @param {number} tint - tint color (UINT32 argb)
+   * @param {boolean} [reupload=false] - Force the texture to be reuploaded
+   * @param {HTMLImageElement|HTMLCanvasElement|null} [normalMap=null] - paired normal-map (SpriteIlluminator workflow)
+   */
+  addQuad(texture, x, y, w, h, u0, v0, u1, v1, tint, reupload = false, normalMap = null) {
+    const vertexData = this.vertexData;
+    if (vertexData.isFull(4)) {
+      this.flush();
+    }
+    let unit;
+    if (this.useMultiTexture) {
+      unit = this.uploadTexture(texture, w, h, reupload, false);
+      if (unit >= this.maxBatchTextures) {
+        this.flush();
+        this.renderer.cache.resetUnitAssignments();
+        this.boundNormalMaps.fill(null);
+        unit = this.uploadTexture(texture, w, h, reupload, false);
+      }
+    } else {
+      unit = this.uploadTexture(texture, w, h, reupload);
+      if (unit !== this.currentSamplerUnit) {
+        this.currentShader.setUniform("uSampler", unit);
+        this.currentSamplerUnit = unit;
+      }
+    }
+    let normalTextureId = -1;
+    if (normalMap !== null && this.useMultiTexture) {
+      const normalUnit = this.maxBatchTextures + unit;
+      const prev = this.boundNormalMaps[unit];
+      if (prev !== normalMap) {
+        if (prev !== null) {
+          this.flush();
+        }
+        this.bindNormalMap(normalMap, normalUnit);
+        this.boundNormalMaps[unit] = normalMap;
+      }
+      normalTextureId = unit;
+    }
+    const m = this.viewMatrix;
+    const vec0 = V_ARRAY[0].set(x, y);
+    const vec1 = V_ARRAY[1].set(x + w, y);
+    const vec2 = V_ARRAY[2].set(x, y + h);
+    const vec3 = V_ARRAY[3].set(x + w, y + h);
+    if (!m.isIdentity()) {
+      m.apply(vec0);
+      m.apply(vec1);
+      m.apply(vec2);
+      m.apply(vec3);
+    }
+    const textureId = this.useMultiTexture ? unit : 0;
+    vertexData.push(vec0.x, vec0.y, u0, v0, tint, textureId, normalTextureId);
+    vertexData.push(vec1.x, vec1.y, u1, v0, tint, textureId, normalTextureId);
+    vertexData.push(vec2.x, vec2.y, u0, v1, tint, textureId, normalTextureId);
+    vertexData.push(vec3.x, vec3.y, u1, v1, tint, textureId, normalTextureId);
+  }
+  /**
+   * Override `blitTexture` so the FBO blit pushes `-1` as the unlit
+   * sentinel (this batcher's vertex layout includes `aNormalTextureId`).
+   * @param {WebGLTexture} source - the raw GL texture to blit
+   * @param {number} x - destination x
+   * @param {number} y - destination y
+   * @param {number} width - destination width
+   * @param {number} height - destination height
+   * @param {GLShader|ShaderEffect} shader - the shader effect to apply
+   */
+  blitTexture(source, x, y, width, height, shader) {
+    const gl = this.gl;
+    this.useShader(shader);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, source);
+    this.currentTextureUnit = 0;
+    this.boundTextures[0] = source;
+    shader.setUniform("uSampler", 0);
+    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 = 4294967295;
+    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);
+    this.currentTextureUnit = -1;
+    delete this.boundTextures[0];
+    this.useShader(this.defaultShader);
+  }
+};
+
+// src/video/webgl/shaders/mesh.frag
+var mesh_default = "uniform sampler2D uSampler;\nvarying vec4 vColor;\nvarying vec2 vRegion;\n\nvoid main(void) {\n    gl_FragColor = texture2D(uSampler, vRegion) * vColor;\n}\n";
+
+// src/video/webgl/shaders/mesh.vert
+var mesh_default2 = "// Current vertex point (3D position for mesh rendering)\nattribute vec3 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n}\n";
+
 // src/video/webgl/batchers/mesh_batcher.js
 var _v = new Vector2d();
 var MeshBatcher = class extends MaterialBatcher {
@@ -30940,239 +32492,509 @@ var PrimitiveBatcher = class extends Batcher {
   }
 };
 
-// src/video/webgl/shaders/multitexture.js
-function buildMultiTextureFragment(maxTextures) {
-  const count = Math.max(maxTextures, 1);
-  const lines = [];
-  for (let i = 0; i < count; i++) {
-    lines.push("uniform sampler2D uSampler" + i + ";");
-  }
-  lines.push("varying vec4 vColor;");
-  lines.push("varying vec2 vRegion;");
-  lines.push("varying float vTextureId;");
-  lines.push("");
-  lines.push("void main(void) {");
-  lines.push("    vec4 color;");
-  for (let i = 0; i < count; i++) {
-    if (i === 0) {
-      lines.push("    if (vTextureId < 0.5) {");
+// src/video/webgl/effects/radialGradient.js
+var RadialGradientEffect = class extends ShaderEffect {
+  /**
+   * @param {WebGLRenderer} renderer - the current renderer instance
+   * @param {object} [options] - initial uniform values
+   * @param {Color} [options.color] - center color (0..255 RGB); defaults to white
+   * @param {number} [options.intensity=1] - peak alpha at the center (0..1+)
+   */
+  constructor(renderer2, options = {}) {
+    super(
+      renderer2,
+      `
+			uniform vec3 uColor;
+			uniform float uIntensity;
+			vec4 apply(vec4 color, vec2 uv) {
+				// recenter to [-1, 1] across the quad. The quad's own aspect
+				// ratio handles elliptical falloffs naturally \u2014 length(c) == 1
+				// lies on the inscribed ellipse in world space.
+				vec2 c = uv * 2.0 - 1.0;
+				float d = length(c);
+				// linear ramp matches Canvas createRadialGradient's two-stop output
+				float f = clamp(1.0 - d, 0.0, 1.0);
+				// 'color' is the per-vertex tint, already premultiplied by
+				// alpha in the vertex shader (vColor = vec4(aColor.bgr *
+				// aColor.a, aColor.a)). For standalone use the tint is
+				// (1,1,1,1) and the uniforms drive the look; for the Light2d
+				// batching path the uniforms stay at default and the tint
+				// carries the per-light color + intensity.
+				vec3 rgb = color.rgb * uColor * uIntensity * f;
+				float a = color.a * uIntensity * f;
+				return vec4(rgb, a);
+			}
+			`
+    );
+    this._colorBuf = new Float32Array(3);
+    const color = options.color;
+    if (color) {
+      this.setColor(color);
     } else {
-      lines.push("    } else if (vTextureId < " + (i + 0.5) + ") {");
+      this._colorBuf[0] = 1;
+      this._colorBuf[1] = 1;
+      this._colorBuf[2] = 1;
+      this.setUniform("uColor", this._colorBuf);
     }
-    lines.push("        color = texture2D(uSampler" + i + ", vRegion);");
+    this.setIntensity(options.intensity ?? 1);
   }
-  lines.push("    } else {");
-  lines.push("        color = texture2D(uSampler0, vRegion);");
-  lines.push("    }");
-  lines.push("    gl_FragColor = color * vColor;");
-  lines.push("}");
-  return lines.join("\n");
-}
-
-// src/video/webgl/shaders/quad-multi.vert
-var quad_multi_default = "// Current vertex point\nattribute vec2 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\nattribute float aTextureId;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\nvarying float vTextureId;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n    vTextureId = aTextureId;\n}\n";
-
-// src/video/webgl/batchers/quad_batcher.js
-var V_ARRAY = [
-  new Vector2d(),
-  new Vector2d(),
-  new Vector2d(),
-  new Vector2d()
-];
-var QuadBatcher = class extends MaterialBatcher {
   /**
-   * Initialize the compositor
-   * @ignore
+   * Set the center color. RGB only — alpha is ignored (the radial
+   * falloff supplies the per-pixel alpha).
+   * @param {Color} color - 0..255 RGB color
    */
-  init(renderer2) {
-    this.maxBatchTextures = Math.min(renderer2.maxTextures, 16);
-    super.init(renderer2, {
-      attributes: [
-        {
-          name: "aVertex",
-          size: 2,
-          type: renderer2.gl.FLOAT,
-          normalized: false,
-          offset: 0 * Float32Array.BYTES_PER_ELEMENT
-        },
-        {
-          name: "aRegion",
-          size: 2,
-          type: renderer2.gl.FLOAT,
-          normalized: false,
-          offset: 2 * Float32Array.BYTES_PER_ELEMENT
-        },
-        {
-          name: "aColor",
-          size: 4,
-          type: renderer2.gl.UNSIGNED_BYTE,
-          normalized: true,
-          offset: 4 * Float32Array.BYTES_PER_ELEMENT
-        },
-        {
-          name: "aTextureId",
-          size: 1,
-          type: renderer2.gl.FLOAT,
-          normalized: false,
-          offset: 5 * Float32Array.BYTES_PER_ELEMENT
-        }
-      ],
-      shader: {
-        vertex: quad_multi_default,
-        fragment: buildMultiTextureFragment(this.maxBatchTextures)
+  setColor(color) {
+    this._colorBuf[0] = color.r / 255;
+    this._colorBuf[1] = color.g / 255;
+    this._colorBuf[2] = color.b / 255;
+    this.setUniform("uColor", this._colorBuf);
+  }
+  /**
+   * Set the peak intensity. Acts as a brightness multiplier on the
+   * falloff curve; values above 1 over-saturate the center of the gradient.
+   * @param {number} intensity - 0..1+ multiplier
+   */
+  setIntensity(intensity) {
+    this.setUniform("uIntensity", intensity);
+  }
+};
+
+// src/video/webgl/lighting/pack.ts
+function createLightUniformScratch() {
+  return {
+    positions: new Float32Array(MAX_LIGHTS * 4),
+    colors: new Float32Array(MAX_LIGHTS * 3),
+    heights: new Float32Array(MAX_LIGHTS),
+    ambient: [0, 0, 0]
+  };
+}
+function packLights(lights, ambient, translateX, translateY, scratch) {
+  scratch.positions.fill(0);
+  scratch.colors.fill(0);
+  scratch.heights.fill(0);
+  let i = 0;
+  if (lights) {
+    for (const light of lights) {
+      if (i >= MAX_LIGHTS) {
+        break;
       }
-    });
-    for (let i = 0; i < this.maxBatchTextures; i++) {
-      this.defaultShader.setUniform("uSampler" + i, i);
+      const b = light.getBounds();
+      const radius = Math.max(b.width, b.height) / 2;
+      scratch.positions[i * 4 + 0] = b.centerX - translateX;
+      scratch.positions[i * 4 + 1] = b.centerY - translateY;
+      scratch.positions[i * 4 + 2] = radius;
+      scratch.positions[i * 4 + 3] = light.intensity;
+      scratch.colors[i * 3 + 0] = light.color.r / 255;
+      scratch.colors[i * 3 + 1] = light.color.g / 255;
+      scratch.colors[i * 3 + 2] = light.color.b / 255;
+      scratch.heights[i] = light.lightHeight;
+      i++;
     }
-    this.useMultiTexture = true;
-    const maxQuads = this.vertexData.maxVertex / 4;
-    this.indexBuffer = new WebGLIndexBuffer(
-      this.gl,
-      maxQuads * 6,
-      this.renderer.WebGLVersion > 1
-    );
-    this.indexBuffer.fillQuadPattern(maxQuads);
   }
+  if (ambient) {
+    scratch.ambient[0] = ambient.r / 255;
+    scratch.ambient[1] = ambient.g / 255;
+    scratch.ambient[2] = ambient.b / 255;
+  } else {
+    scratch.ambient[0] = 0;
+    scratch.ambient[1] = 0;
+    scratch.ambient[2] = 0;
+  }
+  return {
+    positions: scratch.positions,
+    colors: scratch.colors,
+    heights: scratch.heights,
+    ambient: scratch.ambient,
+    count: i
+  };
+}
+
+// src/video/texture/resource.js
+var TextureResource = class {
   /**
-   * Select the shader to use for compositing.
-   * Multi-texture batching is automatically enabled when the default
-   * shader is active, and disabled for custom ShaderEffect shaders.
-   * @see GLShader
-   * @see ShaderEffect
-   * @param {GLShader|ShaderEffect} shader - a reference to a GLShader or ShaderEffect instance
+   * @param {object} options
+   * @param {number} options.width   - pixel width of the texture
+   * @param {number} options.height  - pixel height of the texture
+   * @param {boolean} [options.premultipliedAlpha=false]
+   * @param {string}  [options.repeat="no-repeat"] - "no-repeat" | "repeat" | "repeat-x" | "repeat-y"
+   * @param {number}  [options.filter] - `gl.NEAREST` or `gl.LINEAR`; when
+   *   omitted the batcher falls back to the renderer's `antiAlias` setting
    */
-  useShader(shader) {
-    super.useShader(shader);
-    this.useMultiTexture = shader === this.defaultShader;
+  constructor({
+    width,
+    height,
+    premultipliedAlpha = false,
+    repeat = "no-repeat",
+    filter
+  } = {}) {
+    this.width = width;
+    this.height = height;
+    this.premultipliedAlpha = premultipliedAlpha;
+    this.repeat = repeat;
+    this.filter = filter;
+    this.sources = /* @__PURE__ */ new Map([["default", this]]);
+    this.activeAtlas = "default";
   }
   /**
-   * Reset compositor internal state
+   * Returns the upload "source" the batcher hands to `createTexture2D`.
+   * For a resource this is the resource itself — `createTexture2D`
+   * dispatches to `resource.upload(gl, target)`.
    * @ignore
    */
-  reset() {
-    super.reset();
-    const maxQuads = this.vertexData.maxVertex / 4;
-    this.indexBuffer = new WebGLIndexBuffer(
-      this.gl,
-      maxQuads * 6,
-      this.renderer.WebGLVersion > 1
-    );
-    this.indexBuffer.fillQuadPattern(maxQuads);
-    for (let i = 0; i < this.maxBatchTextures; i++) {
-      this.defaultShader.setUniform("uSampler" + i, i);
-    }
-    this.useMultiTexture = true;
+  getTexture() {
+    return this;
   }
   /**
-   * Flush batched texture data to the GPU using indexed drawing.
-   * @param {number} [mode=gl.TRIANGLES] - the GL drawing mode
+   * Issue the `gl.texImage2D` (or equivalent) call that uploads this
+   * resource's data into the currently-bound `TEXTURE_2D` slot.
+   * Subclasses MUST override.
+   * @abstract
+   * @param {WebGLRenderingContext|WebGL2RenderingContext} gl
+   * @param {number} target - `gl.TEXTURE_2D` (or future cube-map targets)
    */
-  flush(mode = this.mode) {
-    const vertex = this.vertexData;
-    const vertexCount = vertex.vertexCount;
-    if (vertexCount > 0) {
-      const gl = this.gl;
-      const vertexSize = vertex.vertexSize;
-      this.indexBuffer.bind();
-      if (this.renderer.WebGLVersion > 1) {
-        gl.bufferData(
-          gl.ARRAY_BUFFER,
-          vertex.toFloat32(),
-          gl.STREAM_DRAW,
-          0,
-          vertexCount * vertexSize
+  // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars
+  upload(gl, target) {
+    throw new Error("TextureResource subclasses must implement upload()");
+  }
+};
+var BufferTextureResource = class extends TextureResource {
+  /**
+   * @param {ArrayBufferView} data - the pixel data; size must be
+   *   `width * height * 4` bytes for the default RGBA / UNSIGNED_BYTE
+   *   format
+   * @param {object} options
+   * @param {number}  options.width
+   * @param {number}  options.height
+   * @param {boolean} [options.premultipliedAlpha=false]
+   * @param {string}  [options.repeat="no-repeat"]
+   * @param {number}  [options.filter]
+   * @param {"rgba8"|"rgba8ui"} [options.format="rgba8"] - storage format.
+   *   `"rgba8"` (default): normalized RGBA, sampled via `sampler2D` /
+   *   `texture()`. `"rgba8ui"`: unsigned-integer RGBA, sampled via
+   *   `usampler2D` / `texelFetch()` — requires WebGL2. Use the integer
+   *   form for raw-data lookups (GID tables, palette indices, etc.) to
+   *   skip the float-decode round trip and gain exact integer reads.
+   */
+  constructor(data2, options) {
+    super(options);
+    this.data = data2;
+    this.format = options.format || "rgba8";
+  }
+  /** @ignore */
+  upload(gl, target) {
+    if (this.format === "rgba8ui") {
+      if (typeof gl.RGBA8UI === "undefined") {
+        throw new Error(
+          'BufferTextureResource: format "rgba8ui" requires a WebGL 2 context'
         );
+      }
+      gl.texImage2D(
+        target,
+        0,
+        gl.RGBA8UI,
+        this.width,
+        this.height,
+        0,
+        gl.RGBA_INTEGER,
+        gl.UNSIGNED_BYTE,
+        this.data
+      );
+    } else {
+      gl.texImage2D(
+        target,
+        0,
+        gl.RGBA,
+        this.width,
+        this.height,
+        0,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        this.data
+      );
+    }
+  }
+};
+
+// src/video/webgl/shaders/orthogonal-tmxlayer.frag
+var orthogonal_tmxlayer_default = "#version 300 es\n\n// Fragment shader for the orthogonal TMX layer GPU renderer (WebGL2 /\n// GLSL ES 3.00).\n//\n// Per fragment the shader:\n//   1. recovers the world-pixel position from the host UV,\n//   2. walks candidate cells (geometric cell + cells whose oversized,\n//      bottom-aligned tiles could reach this fragment),\n//   3. fetches GIDs from the per-layer index texture, and\n//   4. samples the tileset atlas at the correct sub-region.\n//\n// Fast path: when the tileset has no oversized tiles (`uOverflow == (0, 0)`)\n// \u2014 the common case for grid-aligned maps \u2014 only the geometric cell can\n// hold this fragment's tile, so we skip the candidate loop entirely and\n// run a single `tryRenderCell` call. The loop branch is on a uniform\n// value, coherent across the wave, and trims 25 worst-case loop\n// iterations + their guard checks to a single inlined function call.\n//\n// Slow path: tiles drawing larger than the cell are bottom-aligned\n// vertically and left-aligned horizontally. Render order is \"right-down\":\n// later cells end up on top, so the candidate loop scans dy high\u2192low,\n// dx low\u2192high and picks the FIRST match.\n//\n// Index texture encoding (`RGBA8`, one cell per texel):\n//   R = GID low byte\n//   G = GID high byte    (combined: R | (G << 8) = 16-bit GID)\n//   B = flip mask        (bit 0 = H, bit 1 = V, bit 2 = AD)\n//   A = unused\n//\n// Animation lookup (`RGBA8`, 1 row, `tileCount` texels wide): per local\n// tile id, the CURRENT frame's local id, same R/G byte-pair encoding.\n//\n// Why `sampler2D` + float decode rather than `usampler2D`: the engine's\n// multi-texture default shader declares `uSampler0..uSamplerN-1` as\n// `sampler2D` \u2014 all of them are active for WebGL's draw-time validation.\n// A `usampler2D`-backed `RGBA8UI` texture cached at any of those units\n// (units 0..15 on a typical 16-unit fragment stage) would mismatch when\n// the default shader next draws sprites, killing every quad with\n// `GL_INVALID_OPERATION`. Staying on regular RGBA8 keeps the cache\n// path coherent \u2014 the cost is one `floor(c * 255 + 0.5)` per fetch.\n//\n// `texelFetch` is still used (vs `texture()`) for byte-exact reads \u2014\n// it bypasses interpolation, so the integer byte values come out\n// unmolested even on a normalized-float sampler.\n\n// The engine's `setPrecision` step injects precision declarations for\n// float and int after the `#version` line, using whatever precision the\n// renderer was configured with (`highPrecisionShader` setting on the\n// Application). Individual shader files don't hardcode precision so the\n// engine-wide preference applies.\n\nin vec2 vRegion;\nin vec4 vColor;\n\nuniform sampler2D uSampler;      // tileset atlas (RGBA)\nuniform sampler2D uTileIndex;    // per-layer GID index (RGBA8)\nuniform sampler2D uAnimLookup;   // per-tileset animation table (RGBA8)\n\nuniform vec2 uMapSize;\nuniform vec2 uCellSize;\nuniform vec2 uTileSize;\nuniform vec2 uOverflow;\nuniform vec2 uTilesetCols;\nuniform vec2 uInvTilesetSize;\nuniform vec4 uTilesetMargin;     // (marginX, marginY, spacingX, spacingY)\nuniform vec2 uGidRange;          // (firstgid, lastgid)\nuniform vec2 uVisibleStart;\nuniform vec2 uVisibleSize;\nuniform int  uAnimSize;          // number of entries in uAnimLookup, 0 if disabled\nuniform float uOpacity;\nuniform vec4 uTint;\n\nout vec4 fragColor;\n\nconst int MAX_OVERFLOW = 4;\n\n// Try to render the tile at cell (cx, cy) for the current fragment.\n// Returns true and writes the sampled color to `outColor` when the cell\n// contains a visible, in-range tile whose pixel covers this fragment.\n// Identical logic for both fast and slow paths \u2014 GLSL inlines this\n// trivially so there's no function-call overhead at runtime.\nbool tryRenderCell(int cx, int cy, vec2 worldPx, out vec4 outColor) {\n	int mapW = int(uMapSize.x);\n	int mapH = int(uMapSize.y);\n	if (cx < 0 || cx >= mapW || cy < 0 || cy >= mapH) {\n		return false;\n	}\n\n	// `texelFetch` skips filtering \u2014 the 8-bit channel values come back\n	// as normalized floats, decoded to byte ints below\n	vec4 cellF = texelFetch(uTileIndex, ivec2(cx, cy), 0);\n	uvec4 cell = uvec4(cellF * 255.0 + 0.5);\n	int firstGid = int(uGidRange.x);\n	int gid = int(cell.r) | (int(cell.g) << 8);\n	if (gid < firstGid || gid > int(uGidRange.y)) {\n		return false;\n	}\n\n	vec2 tileWorldOrigin = vec2(\n		float(cx) * uCellSize.x,\n		(float(cy) + 1.0) * uCellSize.y - uTileSize.y\n	);\n	vec2 inTile = (worldPx - tileWorldOrigin) / uTileSize;\n	if (inTile.x < 0.0 || inTile.x >= 1.0 || inTile.y < 0.0 || inTile.y >= 1.0) {\n		return false;\n	}\n\n	// flip mask + axis-swap trick: see TMX shader-path flip spec.\n	// AD performs a transpose; with AD set, H and V swap their effective\n	// axes (matches the legacy `buildFlipTransform`).\n	int flipMask = int(cell.b);\n	float flipH = float(flipMask & 1);\n	float flipV = float((flipMask >> 1) & 1);\n	float flipAD = float((flipMask >> 2) & 1);\n	inTile = mix(inTile, inTile.yx, flipAD);\n	float effH = mix(flipH, flipV, flipAD);\n	float effV = mix(flipV, flipH, flipAD);\n	inTile.x = mix(inTile.x, 1.0 - inTile.x, effH);\n	inTile.y = mix(inTile.y, 1.0 - inTile.y, effV);\n\n	int localId = gid - firstGid;\n\n	// animation: if the tileset has animated tiles, swap the local id for\n	// its current frame's id via the lookup texture (CPU updates the\n	// lookup in lockstep with `tileset.update(dt)`).\n	if (uAnimSize > 0) {\n		vec4 animF = texelFetch(uAnimLookup, ivec2(localId, 0), 0);\n		uvec4 animTexel = uvec4(animF * 255.0 + 0.5);\n		localId = int(animTexel.r) | (int(animTexel.g) << 8);\n	}\n\n	float row = floor(float(localId) / uTilesetCols.x);\n	float col = float(localId) - row * uTilesetCols.x;\n	vec2 tileOriginPx = uTilesetMargin.xy\n		+ vec2(col, row) * (uTileSize + uTilesetMargin.zw);\n	vec2 texelPx = tileOriginPx + inTile * uTileSize;\n	vec2 texelUV = texelPx * uInvTilesetSize;\n\n	vec4 sampled = texture(uSampler, texelUV);\n	if (sampled.a <= 0.0) {\n		return false;\n	}\n	outColor = sampled;\n	return true;\n}\n\nvoid main(void) {\n	vec2 tileCoord = uVisibleStart + vRegion * uVisibleSize;\n	vec2 geomCell = floor(tileCoord);\n	vec2 worldPx = tileCoord * uCellSize;\n\n	int gx = int(geomCell.x);\n	int gy = int(geomCell.y);\n	int overflowX = int(uOverflow.x + 0.5);\n	int overflowY = int(uOverflow.y + 0.5);\n\n	vec4 result;\n\n	// Fast path: tiles fit the cell exactly (the common case) \u2014 only the\n	// geometric cell can contain this fragment's tile.\n	if (overflowX == 0 && overflowY == 0) {\n		if (!tryRenderCell(gx, gy, worldPx, result)) {\n			discard;\n		}\n		result.a *= uOpacity;\n		fragColor = result * uTint;\n		return;\n	}\n\n	// Slow path: oversized tiles. Walk candidates dy high\u2192low, dx low\u2192high\n	// and pick the FIRST match \u2014 render order is \"right-down\" so later\n	// cells go on top.\n	bool found = false;\n	for (int idy = 0; idy <= MAX_OVERFLOW; idy++) {\n		int dy = MAX_OVERFLOW - idy;\n		if (dy > overflowY) continue;\n		for (int dx = 0; dx <= MAX_OVERFLOW; dx++) {\n			if (dx > overflowX) break;\n			if (tryRenderCell(gx - dx, gy + dy, worldPx, result)) {\n				found = true;\n				break;\n			}\n		}\n		if (found) break;\n	}\n	if (!found) discard;\n	result.a *= uOpacity;\n	fragColor = result * uTint;\n}\n";
+
+// src/video/webgl/shaders/orthogonal-tmxlayer.vert
+var orthogonal_tmxlayer_default2 = '#version 300 es\n\n// Vertex shader for the orthogonal TMX layer GPU renderer.\n//\n// Matches the quad batcher\'s vertex layout (`aVertex`, `aRegion`, `aColor`,\n// `uProjectionMatrix`) so the standard `setBatcher("quad", this.shader)` +\n// `addQuad()` flow drives it like any other quad. Same attribute names,\n// same uniforms \u2014 just expressed in GLSL ES 3.00 (`in`/`out` in place of\n// `attribute`/`varying`) so the program can pair with the 3.00 fragment\n// shader that uses `usampler2D` / `texelFetch` for integer-typed lookups.\n\nin vec2 aVertex;\nin vec2 aRegion;\nin vec4 aColor;\n\nuniform mat4 uProjectionMatrix;\n\nout vec2 vRegion;\nout vec4 vColor;\n\nvoid main(void) {\n	gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);\n	// premultiplied-alpha + bgra \u2192 rgba swap, same convention the batcher\n	// uses for its default sprite shader\n	vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n	vRegion = aRegion;\n}\n';
+
+// src/video/webgl/renderers/tmxlayer/orthogonal.js
+var DEFAULT_TINT = new Float32Array([1, 1, 1, 1]);
+var OrthogonalTMXLayerGPURenderer = class {
+  /**
+   * @param {WebGLRenderer} renderer - the WebGL renderer instance
+   */
+  constructor(renderer2) {
+    this.renderer = renderer2;
+    this.gl = renderer2.gl;
+    this.shader = new GLShader(
+      renderer2.gl,
+      orthogonal_tmxlayer_default2,
+      orthogonal_tmxlayer_default,
+      renderer2.shaderPrecision
+    );
+    this.resources = /* @__PURE__ */ new Map();
+    this.animLookups = /* @__PURE__ */ new Map();
+    this._v2 = new Float32Array(2);
+    this._v4 = new Float32Array(4);
+  }
+  /**
+   * Free every cached per-layer index texture and empty the local
+   * resource map. Called from `WebGLRenderer.reset()` (which
+   * `GAME_RESET` triggers) so each level transition starts clean.
+   * @ignore
+   */
+  reset() {
+    const batcher = this.renderer.currentBatcher;
+    const cache2 = this.renderer.cache;
+    const drop = (resource) => {
+      if (batcher !== void 0) {
+        batcher.deleteTexture2D(resource);
       } else {
-        gl.bufferData(
-          gl.ARRAY_BUFFER,
-          vertex.toFloat32(0, vertexCount * vertexSize),
-          gl.STREAM_DRAW
-        );
+        cache2.freeTextureUnit(resource);
+        cache2.delete(resource);
       }
-      const indexCount = vertexCount / 4 * 6;
-      gl.drawElements(mode, indexCount, this.indexBuffer.type, 0);
-      vertex.clear();
+    };
+    for (const resource of this.resources.values()) {
+      drop(resource);
     }
+    for (const entry of this.animLookups.values()) {
+      drop(entry.resource);
+    }
+    this.resources.clear();
+    this.animLookups.clear();
   }
   /**
-   * Draw a screen-aligned quad with the given raw WebGL texture through the given shader.
-   * Binds the texture to unit 0, pushes 4 vertices (Y-flipped UVs), flushes,
-   * then unbinds the texture.
-   * @param {WebGLTexture} source - the raw GL texture to blit
-   * @param {number} x - destination x
-   * @param {number} y - destination y
-   * @param {number} width - destination width
-   * @param {number} height - destination height
-   * @param {GLShader|ShaderEffect} shader - the shader effect to apply
+   * Write a `vec2` uniform without allocating a fresh Float32Array per
+   * call. Both components flow into the shared `_v2` scratch buffer,
+   * which `setUniform` reads synchronously and forwards to
+   * `gl.uniform2fv` — so reusing the buffer across calls is safe.
+   * @param {string} name
+   * @param {number} x
+   * @param {number} y
+   * @private
    */
-  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);
-    const tint = 4294967295;
-    this.vertexData.push(x, y, 0, 1, tint, 0);
-    this.vertexData.push(x + width, y, 1, 1, tint, 0);
-    this.vertexData.push(x, y + height, 0, 0, tint, 0);
-    this.vertexData.push(x + width, y + height, 1, 0, tint, 0);
-    this.flush();
-    gl.activeTexture(gl.TEXTURE0);
-    gl.bindTexture(gl.TEXTURE_2D, null);
-    delete this.boundTextures[0];
-    this.useShader(this.defaultShader);
+  _setV2(name, x, y) {
+    this._v2[0] = x;
+    this._v2[1] = y;
+    this.shader.setUniform(name, this._v2);
   }
   /**
-   * Add a textured quad
-   * @param {TextureAtlas} texture - Source texture atlas
-   * @param {number} x - Destination x-coordinate
-   * @param {number} y - Destination y-coordinate
-   * @param {number} w - Destination width
-   * @param {number} h - Destination height
-   * @param {number} u0 - Texture UV (u0) value.
-   * @param {number} v0 - Texture UV (v0) value.
-   * @param {number} u1 - Texture UV (u1) value.
-   * @param {number} v1 - Texture UV (v1) value.
-   * @param {number} tint - tint color to be applied to the texture in UINT32 (argb) format
-   * @param {boolean} reupload - Force the texture to be reuploaded even if already bound
+   * `vec4` counterpart to {@link _setV2}.
+   * @param {string} name
+   * @param {number} x
+   * @param {number} y
+   * @param {number} z
+   * @param {number} w
+   * @private
    */
-  addQuad(texture, x, y, w, h, u0, v0, u1, v1, tint, reupload = false) {
-    const vertexData = this.vertexData;
-    if (vertexData.isFull(4)) {
-      this.flush();
+  _setV4(name, x, y, z, w) {
+    this._v4[0] = x;
+    this._v4[1] = y;
+    this._v4[2] = z;
+    this._v4[3] = w;
+    this.shader.setUniform(name, this._v4);
+  }
+  /**
+   * Get-or-create the per-tileset animation-lookup entry. Returns
+   * `undefined` for tilesets that have no animated tiles (the shader's
+   * `uAnimEnabled` uniform is then set to 0 and the lookup texture is
+   * not bound).
+   *
+   * The entry holds a `tileCount × 1` RGBA8 `BufferTextureResource`
+   * where texel `localId` encodes the CURRENT frame's local id as
+   * `R = lo byte, G = hi byte` (same encoding as the GID index
+   * texture). Each call walks `tileset.animations` and rewrites
+   * dirty texels — `tileset.update(dt)` (driven by the layer) advances
+   * `anim.cur.tileid` independently of this renderer.
+   *
+   * @param {object} tileset
+   * @param {number} tileCount - tiles in the tileset's atlas grid
+   *   (`atlasCols * atlasRows`)
+   * @returns {{resource: BufferTextureResource, data: Uint8Array,
+   *   tileCount: number, dirty: boolean}|undefined}
+   */
+  _getOrUpdateAnimLookup(tileset, tileCount) {
+    if (!tileset.isAnimated || tileset.animations.size === 0) {
+      return void 0;
     }
-    let unit;
-    if (this.useMultiTexture) {
-      unit = this.uploadTexture(texture, w, h, reupload, false);
-      if (unit >= this.maxBatchTextures) {
-        this.flush();
-        this.renderer.cache.resetUnitAssignments();
-        unit = this.uploadTexture(texture, w, h, reupload, false);
-      }
-    } else {
-      unit = this.uploadTexture(texture, w, h, reupload);
-      if (unit !== this.currentSamplerUnit) {
-        this.currentShader.setUniform("uSampler", unit);
-        this.currentSamplerUnit = unit;
+    let entry = this.animLookups.get(tileset);
+    if (entry === void 0) {
+      const data3 = new Uint8Array(tileCount * 4);
+      for (let id = 0; id < tileCount; id++) {
+        data3[id * 4 + 0] = id & 255;
+        data3[id * 4 + 1] = id >> 8 & 255;
+      }
+      const resource = new BufferTextureResource(data3, {
+        width: tileCount,
+        height: 1,
+        premultipliedAlpha: false,
+        repeat: "no-repeat",
+        // NEAREST so the shader's `texelFetch` reads byte-exact
+        // channel values back as normalized floats
+        filter: this.gl.NEAREST,
+        format: "rgba8"
+      });
+      entry = { resource, data: data3, tileCount, dirty: false };
+      this.animLookups.set(tileset, entry);
+    }
+    const data2 = entry.data;
+    for (const [localId, anim] of tileset.animations) {
+      const off2 = localId * 4;
+      const cur = anim.cur.tileid;
+      const lo = cur & 255;
+      const hi = cur >> 8 & 255;
+      if (data2[off2] !== lo || data2[off2 + 1] !== hi) {
+        data2[off2] = lo;
+        data2[off2 + 1] = hi;
+        entry.dirty = true;
       }
     }
-    const m = this.viewMatrix;
-    const vec0 = V_ARRAY[0].set(x, y);
-    const vec1 = V_ARRAY[1].set(x + w, y);
-    const vec2 = V_ARRAY[2].set(x, y + h);
-    const vec3 = V_ARRAY[3].set(x + w, y + h);
-    if (!m.isIdentity()) {
-      m.apply(vec0);
-      m.apply(vec1);
-      m.apply(vec2);
-      m.apply(vec3);
+    return entry;
+  }
+  /**
+   * Get-or-create the per-layer index `BufferTextureResource`.
+   * @param {TMXLayer} layer
+   * @returns {BufferTextureResource}
+   */
+  _getResource(layer) {
+    let resource = this.resources.get(layer);
+    if (resource === void 0) {
+      resource = new BufferTextureResource(
+        new Uint8Array(layer.layerData.buffer),
+        {
+          width: layer.cols,
+          height: layer.rows,
+          // raw GID bytes — must NOT have alpha pre-multiplied
+          // into RGB, otherwise A=0 cells wipe their R/G/B
+          premultipliedAlpha: false,
+          repeat: "no-repeat",
+          // NEAREST so `texelFetch` returns the original byte
+          // values (as normalized floats) for the GID/flip
+          // decode below
+          filter: this.gl.NEAREST,
+          format: "rgba8"
+        }
+      );
+      resource._uploadedVersion = -1;
+      this.resources.set(layer, resource);
+    }
+    return resource;
+  }
+  /**
+   * Draw an orthogonal TMX layer through the shader path.
+   * @param {TMXLayer} layer
+   * @param {object} rect - the visible viewport rect (world coords)
+   */
+  draw(layer, rect) {
+    const renderer2 = this.renderer;
+    const tileWidth = layer.tilewidth;
+    const tileHeight = layer.tileheight;
+    const cols = layer.cols;
+    const rows = layer.rows;
+    const startTileX = Math.max(0, Math.floor(rect.pos.x / tileWidth));
+    const startTileY = Math.max(0, Math.floor(rect.pos.y / tileHeight));
+    const endTileX = Math.min(
+      cols,
+      Math.ceil((rect.pos.x + rect.width) / tileWidth)
+    );
+    const endTileY = Math.min(
+      rows,
+      Math.ceil((rect.pos.y + rect.height) / tileHeight)
+    );
+    if (endTileX <= startTileX || endTileY <= startTileY) {
+      return;
+    }
+    const worldX = startTileX * tileWidth;
+    const worldY = startTileY * tileHeight;
+    const worldW = (endTileX - startTileX) * tileWidth;
+    const worldH = (endTileY - startTileY) * tileHeight;
+    const visStartX = startTileX;
+    const visStartY = startTileY;
+    const visSizeX = endTileX - startTileX;
+    const visSizeY = endTileY - startTileY;
+    const batcher = renderer2.setBatcher("quad", this.shader);
+    const resource = this._getResource(layer);
+    const indexUnit = batcher.uploadTexture(
+      resource,
+      cols,
+      rows,
+      resource._uploadedVersion !== layer.dataVersion
+    );
+    resource._uploadedVersion = layer.dataVersion;
+    this.shader.setUniform("uTileIndex", indexUnit);
+    this._setV2("uMapSize", cols, rows);
+    this._setV2("uVisibleStart", visStartX, visStartY);
+    this._setV2("uVisibleSize", visSizeX, visSizeY);
+    this._setV2("uCellSize", tileWidth, tileHeight);
+    this.shader.setUniform("uOpacity", layer.getOpacity());
+    this.shader.setUniform(
+      "uTint",
+      layer.tint ? layer.tint.toArray() : DEFAULT_TINT
+    );
+    const tilesets = layer.tilesets.tilesets;
+    for (let i = 0; i < tilesets.length; i++) {
+      const tileset = tilesets[i];
+      if (tileset.isCollection || tileset.image === void 0) {
+        continue;
+      }
+      const tsW = tileset.tilewidth;
+      const tsH = tileset.tileheight;
+      const margin = tileset.margin;
+      const spacing = tileset.spacing;
+      const atlasW = tileset.image.width;
+      const atlasH = tileset.image.height;
+      const atlasCols = Math.max(
+        1,
+        Math.floor((atlasW - margin * 2 + spacing) / (tsW + spacing))
+      );
+      const atlasRows = Math.max(
+        1,
+        Math.floor((atlasH - margin * 2 + spacing) / (tsH + spacing))
+      );
+      const tileCount = atlasCols * atlasRows;
+      const animEntry = this._getOrUpdateAnimLookup(tileset, tileCount);
+      if (animEntry !== void 0) {
+        const animUnit = batcher.uploadTexture(
+          animEntry.resource,
+          animEntry.tileCount,
+          1,
+          animEntry.dirty
+        );
+        animEntry.dirty = false;
+        this.shader.setUniform("uAnimLookup", animUnit);
+        this.shader.setUniform("uAnimSize", animEntry.tileCount);
+      } else {
+        this.shader.setUniform("uAnimLookup", indexUnit);
+        this.shader.setUniform("uAnimSize", 0);
+      }
+      this._setV2("uTileSize", tsW, tsH);
+      this._setV2("uTilesetCols", atlasCols, atlasRows);
+      this._setV2("uInvTilesetSize", 1 / atlasW, 1 / atlasH);
+      this._setV4("uTilesetMargin", margin, margin, spacing, spacing);
+      this._setV2(
+        "uOverflow",
+        Math.max(0, Math.ceil(tsW / tileWidth) - 1),
+        Math.max(0, Math.ceil(tsH / tileHeight) - 1)
+      );
+      this._setV2("uGidRange", tileset.firstgid, tileset.lastgid);
+      batcher.addQuad(
+        tileset.texture,
+        worldX,
+        worldY,
+        worldW,
+        worldH,
+        0,
+        0,
+        1,
+        1,
+        4294967295
+      );
+      batcher.flush();
     }
-    const textureId = this.useMultiTexture ? unit : 0;
-    vertexData.push(vec0.x, vec0.y, u0, v0, tint, textureId);
-    vertexData.push(vec1.x, vec1.y, u1, v0, tint, textureId);
-    vertexData.push(vec2.x, vec2.y, u0, v1, tint, textureId);
-    vertexData.push(vec3.x, vec3.y, u1, v1, tint, textureId);
   }
 };
 
@@ -31205,6 +33027,7 @@ var WebGLRenderer = class extends Renderer {
     this._rectTriangles = Array.from({ length: 6 }, () => {
       return { x: 0, y: 0 };
     });
+    this._clipAABB = new Bounds();
     this._polyVerts = [];
     this._currentGradient = null;
     this.currentTransform = this.renderState.currentTransform;
@@ -31214,6 +33037,9 @@ var WebGLRenderer = class extends Renderer {
     this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.vertexBuffer);
     const CustomBatcher = this.settings.batcher || this.settings.compositor;
     this.addBatcher(new (CustomBatcher || QuadBatcher)(this), "quad", true);
+    if (!CustomBatcher) {
+      this.addBatcher(new LitQuadBatcher(this), "litQuad");
+    }
     this.addBatcher(new (CustomBatcher || PrimitiveBatcher)(this), "primitive");
     this.addBatcher(new MeshBatcher(this), "mesh");
     this.gl.disable(this.gl.DEPTH_TEST);
@@ -31314,6 +33140,7 @@ var WebGLRenderer = class extends Renderer {
   reset() {
     super.reset();
     this.clear();
+    this._orthogonalTMXGPURenderer?.reset();
     this.setViewport();
     if (this.gl.getParameter(this.gl.ARRAY_BUFFER_BINDING) !== this.vertexBuffer) {
       this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.vertexBuffer);
@@ -31332,6 +33159,63 @@ var WebGLRenderer = class extends Renderer {
     this.gl.disable(this.gl.SCISSOR_TEST);
     this._scissorActive = false;
     this._renderTargetPool.destroy();
+    if (this._lightShader !== void 0) {
+      this._lightShader.destroy?.();
+      this._lightShader = void 0;
+    }
+    if (this._lightAtlas !== void 0) {
+      this._lightAtlas.sources.forEach((source) => {
+        this.cache.delete?.(source);
+      });
+      this._lightAtlas = void 0;
+    }
+    if (this.isContextValid === false) {
+      this._orthogonalTMXGPURenderer = void 0;
+    }
+  }
+  /**
+   * Draw a TMX tile layer through whichever path the layer's `renderMode`
+   * resolves to. WebGL2-eligible layers (`renderMode === "shader"`) take
+   * the procedural shader path — one quad per tileset, GID lookup in a
+   * per-layer data texture. All other layers fall through to the base
+   * `Renderer.drawTileLayer` (preRender blit or per-tile loop).
+   * @param {object} layer - the TMXLayer to draw
+   * @param {object} rect - the visible region in world coords
+   */
+  drawTileLayer(layer, rect) {
+    if (layer.renderMode === "shader") {
+      const gpu = this._getTMXGPURendererFor(layer.orientation);
+      if (gpu !== void 0) {
+        gpu.draw(layer, rect);
+        return;
+      }
+    }
+    super.drawTileLayer(layer, rect);
+  }
+  /**
+   * Lazy-init the orientation-specific GPU tilemap renderer.
+   * @param {string} orientation
+   * @returns {object|undefined}
+   * @ignore
+   */
+  _getTMXGPURendererFor(orientation2) {
+    if (orientation2 === "orthogonal") {
+      if (this._orthogonalTMXGPURenderer === void 0) {
+        try {
+          this._orthogonalTMXGPURenderer = new OrthogonalTMXLayerGPURenderer(
+            this
+          );
+        } catch (err) {
+          console.warn(
+            "melonJS: GPU tilemap shader failed to compile, falling back to legacy renderer",
+            err
+          );
+          this._orthogonalTMXGPURenderer = null;
+        }
+      }
+      return this._orthogonalTMXGPURenderer || void 0;
+    }
+    return void 0;
   }
   /**
    * add a new batcher to this renderer
@@ -31359,21 +33243,21 @@ var WebGLRenderer = class extends Renderer {
     if (typeof batcher === "undefined") {
       throw new Error("Invalid Batcher");
     }
-    if (this.currentBatcher === batcher && typeof shader !== "object") {
+    const targetShader = shader != null ? shader : batcher.defaultShader;
+    if (this.currentBatcher === batcher && batcher.currentShader === targetShader) {
       return this.currentBatcher;
     }
     if (this.currentBatcher !== batcher) {
       if (this.currentBatcher !== void 0) {
         this.currentBatcher.flush();
+        this.currentBatcher.unbind();
       }
       this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.vertexBuffer);
       this.currentBatcher = batcher;
       this.currentBatcher.bind();
       this.currentBatcher.setProjection(this.projectionMatrix);
     }
-    if (typeof shader === "object") {
-      this.currentBatcher.useShader(shader);
-    }
+    this.currentBatcher.useShader(targetShader);
     return this.currentBatcher;
   }
   /**
@@ -31418,6 +33302,109 @@ var WebGLRenderer = class extends Renderer {
   flush() {
     this.currentBatcher.flush();
   }
+  /**
+   * Upload per-frame Light2d uniforms used by the lit sprite pipeline.
+   *
+   * Packs the active lights into pre-allocated scratch buffers, then
+   * forwards to `LitQuadBatcher`. Light positions are translated from
+   * world-space (where `light.getBounds().centerX/Y` lives) into the
+   * renderer's pre-projection coords by subtracting `(translateX, translateY)`,
+   * matching what `Stage.drawLighting` does for the cutout pass — so
+   * the lit fragment's `lightPos - vWorldPos` math lines up with the
+   * camera's view.
+   *
+   * Lights past `MAX_LIGHTS` (8) are silently dropped. Also caches the
+   * active light count on the renderer so `drawImage` can dispatch
+   * normal-mapped sprites to the lit batcher only when there's
+   * something to light them with.
+   * @param {Iterable<object>} [lights] - active `Light2d` instances; falsy/empty no-ops the lit pipeline
+   * @param {object} [ambient] - ambient lighting color (0..255 RGB); defaults to black
+   * @param {number} [translateX=0] - world-to-screen X translate (matches `Camera2d.draw()`)
+   * @param {number} [translateY=0] - world-to-screen Y translate
+   */
+  setLightUniforms(lights, ambient, translateX = 0, translateY = 0) {
+    if (this._lightUniformsScratch === void 0) {
+      this._lightUniformsScratch = createLightUniformScratch();
+    }
+    const u = packLights(
+      lights,
+      ambient,
+      translateX,
+      translateY,
+      this._lightUniformsScratch
+    );
+    this.activeLightCount = u.count;
+    const lit = this.batchers.get("litQuad");
+    if (lit && typeof lit.setLightUniforms === "function") {
+      lit.setLightUniforms(u);
+      if (this.currentBatcher && this.currentBatcher !== lit) {
+        const shader = this.currentBatcher.currentShader || this.currentBatcher.defaultShader;
+        if (shader) {
+          this.gl.useProgram(shader.program);
+          this.currentProgram = shader.program;
+        }
+      }
+    }
+  }
+  /**
+   * @inheritdoc
+   *
+   * Renders the light as a quad through a shared
+   * {@link RadialGradientEffect} fragment shader (procedural — no
+   * per-light texture). The shader and a shared 1×1 white-pixel atlas
+   * are lazy-allocated on first call and reused for every Light2d on
+   * this renderer. Each light's color and intensity are encoded into
+   * the per-vertex tint so consecutive `drawLight` calls accumulate
+   * into the quad batcher's buffer and flush together — N lights
+   * become 1 program switch + 1 flush instead of 2N + N.
+   * @param {object} light - the Light2d instance to render
+   */
+  drawLight(light) {
+    if (this._lightShader === void 0) {
+      this._lightShader = new RadialGradientEffect(this);
+    }
+    const batcher = this.setBatcher("quad", this._lightShader);
+    batcher.addQuad(
+      this._getLightAtlas(),
+      light.pos.x,
+      light.pos.y,
+      light.width,
+      light.height,
+      0,
+      0,
+      1,
+      1,
+      // pack the light's color (RGB) and intensity (A) into the
+      // vertex tint — the shader's `apply()` reads `color.rgb` and
+      // `color.a` as the per-light values.
+      light.color.toUint32(light.intensity)
+    );
+  }
+  /**
+   * Lazy-init a shared 1×1 white `TextureAtlas` used as the source
+   * texture for `drawLight`'s procedural shader. The shader ignores
+   * the sampled color, but `addQuad`'s vertex format includes a
+   * texture-unit attribute so we still need a real texture; sharing
+   * one across every light keeps them on the same multi-texture slot
+   * (no flush on light switch).
+   * @returns {TextureAtlas}
+   * @ignore
+   */
+  _getLightAtlas() {
+    if (this._lightAtlas === void 0) {
+      const canvas = globalThis.document ? globalThis.document.createElement("canvas") : new OffscreenCanvas(1, 1);
+      canvas.width = 1;
+      canvas.height = 1;
+      const ctx = canvas.getContext("2d");
+      ctx.fillStyle = "#fff";
+      ctx.fillRect(0, 0, 1, 1);
+      this._lightAtlas = new TextureAtlas(
+        createAtlas(1, 1, "lightWhite", "no-repeat"),
+        canvas
+      );
+    }
+    return this._lightAtlas;
+  }
   /**
    * Begin capturing rendering to an offscreen FBO for post-effect processing.
    * @param {Renderable} renderable - the renderable requesting post-effect processing
@@ -31602,19 +33589,22 @@ var WebGLRenderer = class extends Renderer {
    */
   enableScissor(x, y, width, height) {
     const gl = this.gl;
+    const canvas = this.getCanvas();
+    const aabb = this._clipAABB;
+    aabb.clear();
+    aabb.addFrame(x, y, x + width, y + height, this.currentTransform);
+    const sx = Math.floor(aabb.min.x);
+    const sy = Math.floor(aabb.min.y);
+    const sw = Math.ceil(aabb.max.x - sx);
+    const sh = Math.ceil(aabb.max.y - sy);
     this.flush();
     gl.enable(gl.SCISSOR_TEST);
     this._scissorActive = true;
-    gl.scissor(
-      x + this.currentTransform.tx,
-      this.getCanvas().height - height - y - this.currentTransform.ty,
-      width,
-      height
-    );
-    this.currentScissor[0] = x;
-    this.currentScissor[1] = y;
-    this.currentScissor[2] = width;
-    this.currentScissor[3] = height;
+    gl.scissor(sx, canvas.height - sh - sy, sw, sh);
+    this.currentScissor[0] = sx;
+    this.currentScissor[1] = sy;
+    this.currentScissor[2] = sw;
+    this.currentScissor[3] = sh;
   }
   /**
    * Disable the scissor test, allowing rendering to the full viewport.
@@ -31721,27 +33711,45 @@ var WebGLRenderer = class extends Renderer {
       dx |= 0;
       dy |= 0;
     }
-    this.setBatcher("quad");
+    const useLit = this.batchers.has("litQuad") && this.activeLightCount > 0 && this.currentNormalMap !== null;
+    this.setBatcher(useLit ? "litQuad" : "quad");
     const shader = this.customShader;
-    if (typeof shader === "object") {
+    if (shader != null) {
       this.currentBatcher.useShader(shader);
     }
     const reupload = typeof image.videoWidth !== "undefined";
     const texture = this.cache.get(image);
     const uvs = texture.getUVs(sx, sy, sw, sh);
-    this.currentBatcher.addQuad(
-      texture,
-      dx,
-      dy,
-      dw,
-      dh,
-      uvs[0],
-      uvs[1],
-      uvs[2],
-      uvs[3],
-      this.currentTint.toUint32(this.getGlobalAlpha()),
-      reupload
-    );
+    if (useLit) {
+      this.currentBatcher.addQuad(
+        texture,
+        dx,
+        dy,
+        dw,
+        dh,
+        uvs[0],
+        uvs[1],
+        uvs[2],
+        uvs[3],
+        this.currentTint.toUint32(this.getGlobalAlpha()),
+        reupload,
+        this.currentNormalMap
+      );
+    } else {
+      this.currentBatcher.addQuad(
+        texture,
+        dx,
+        dy,
+        dw,
+        dh,
+        uvs[0],
+        uvs[1],
+        uvs[2],
+        uvs[3],
+        this.currentTint.toUint32(this.getGlobalAlpha()),
+        reupload
+      );
+    }
     if (typeof shader === "object") {
       this.currentBatcher.useShader(this.currentBatcher.defaultShader);
     }
@@ -31781,7 +33789,7 @@ var WebGLRenderer = class extends Renderer {
   drawMesh(mesh) {
     const gl = this.gl;
     this.setBatcher("mesh");
-    if (typeof this.customShader === "object") {
+    if (this.customShader != null) {
       this.currentBatcher.useShader(this.customShader);
     }
     gl.enable(gl.DEPTH_TEST);
@@ -31806,7 +33814,7 @@ var WebGLRenderer = class extends Renderer {
     gl.enable(gl.BLEND);
     gl.disable(gl.DEPTH_TEST);
     gl.depthMask(false);
-    if (typeof this.customShader === "object") {
+    if (this.customShader != null) {
       this.currentBatcher.useShader(this.currentBatcher.defaultShader);
     }
   }
@@ -32041,23 +34049,33 @@ var WebGLRenderer = class extends Renderer {
    */
   restore() {
     const canvas = this.getCanvas();
+    const peek = this.renderState.peekScissor();
+    const cur = this.currentScissor;
+    const curActive = this._scissorActive === true;
+    const willBeActive = peek !== null;
+    const scissorChanging = curActive !== willBeActive || willBeActive && (cur[0] !== peek[0] || cur[1] !== peek[1] || cur[2] !== peek[2] || cur[3] !== peek[3]);
+    if (scissorChanging) {
+      this.flush();
+    }
     const result = this.renderState.restore(canvas.width, canvas.height);
     if (result !== null) {
       this.setBlendMode(result.blendMode);
-      if (result.scissorActive) {
+      if (scissorChanging) {
         const gl = this.gl;
-        const s = this.currentScissor;
-        gl.enable(gl.SCISSOR_TEST);
-        this._scissorActive = true;
-        gl.scissor(
-          s[0] + this.currentTransform.tx,
-          canvas.height - s[3] - s[1] - this.currentTransform.ty,
-          s[2],
-          s[3]
-        );
-      } else {
-        this.gl.disable(this.gl.SCISSOR_TEST);
-        this._scissorActive = false;
+        if (result.scissorActive) {
+          const next = this.currentScissor;
+          gl.enable(gl.SCISSOR_TEST);
+          this._scissorActive = true;
+          gl.scissor(
+            next[0],
+            canvas.height - next[3] - next[1],
+            next[2],
+            next[3]
+          );
+        } else {
+          gl.disable(gl.SCISSOR_TEST);
+          this._scissorActive = false;
+        }
       }
     }
     this._currentGradient = this.renderState.currentGradient;
@@ -32726,31 +34744,42 @@ var WebGLRenderer = class extends Renderer {
   clipRect(x, y, width, height) {
     const canvas = this.getCanvas();
     const gl = this.gl;
-    if (x !== 0 || y !== 0 || width !== canvas.width || height !== canvas.height) {
-      const currentScissor = this.currentScissor;
+    const m = this.currentTransform;
+    if (!Number.isFinite(m.tx) || !Number.isFinite(m.ty)) {
       if (this._scissorActive) {
-        if (currentScissor[0] === x && currentScissor[1] === y && currentScissor[2] === width && currentScissor[3] === height) {
-          return;
-        }
+        this.flush();
+        gl.disable(gl.SCISSOR_TEST);
+        this._scissorActive = false;
       }
-      this.flush();
-      gl.enable(this.gl.SCISSOR_TEST);
-      this._scissorActive = true;
-      gl.scissor(
-        // scissor does not account for currentTransform, so manually adjust
-        x + this.currentTransform.tx,
-        canvas.height - height - y - this.currentTransform.ty,
-        width,
-        height
-      );
-      currentScissor[0] = x;
-      currentScissor[1] = y;
-      currentScissor[2] = width;
-      currentScissor[3] = height;
-    } else {
-      gl.disable(gl.SCISSOR_TEST);
-      this._scissorActive = false;
+      return;
+    }
+    const aabb = this._clipAABB;
+    aabb.clear();
+    aabb.addFrame(x, y, x + width, y + height, m);
+    const sx = Math.floor(aabb.min.x);
+    const sy = Math.floor(aabb.min.y);
+    const sw = Math.ceil(aabb.max.x - sx);
+    const sh = Math.ceil(aabb.max.y - sy);
+    if (sx <= 0 && sy <= 0 && sx + sw >= canvas.width && sy + sh >= canvas.height) {
+      if (this._scissorActive) {
+        this.flush();
+        gl.disable(gl.SCISSOR_TEST);
+        this._scissorActive = false;
+      }
+      return;
+    }
+    const cs = this.currentScissor;
+    if (this._scissorActive && cs[0] === sx && cs[1] === sy && cs[2] === sw && cs[3] === sh) {
+      return;
     }
+    this.flush();
+    gl.enable(gl.SCISSOR_TEST);
+    this._scissorActive = true;
+    gl.scissor(sx, canvas.height - sh - sy, sw, sh);
+    cs[0] = sx;
+    cs[1] = sy;
+    cs[2] = sw;
+    cs[3] = sh;
   }
   /**
    * A mask limits rendering elements to the shape and position of the given mask object.
@@ -32769,15 +34798,16 @@ var WebGLRenderer = class extends Renderer {
     }
     this.maskLevel++;
     gl.colorMask(false, false, false, false);
-    gl.stencilFunc(gl.EQUAL, this.maskLevel, 1);
-    gl.stencilOp(gl.REPLACE, gl.REPLACE, gl.REPLACE);
+    gl.stencilMask(255);
+    gl.stencilFunc(gl.ALWAYS, 0, 255);
+    gl.stencilOp(gl.KEEP, gl.KEEP, gl.INCR);
     this.fill(mask);
     this.flush();
     gl.colorMask(true, true, true, true);
     if (invert === true) {
-      gl.stencilFunc(gl.EQUAL, this.maskLevel + 1, 1);
+      gl.stencilFunc(gl.EQUAL, 0, 255);
     } else {
-      gl.stencilFunc(gl.NOTEQUAL, this.maskLevel + 1, 1);
+      gl.stencilFunc(gl.EQUAL, this.maskLevel, 255);
     }
     gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
   }
@@ -33108,6 +35138,14 @@ var Application = class {
     this.world = new World(0, 0, this.settings.width, this.settings.height);
     this.world.app = this;
     this.world.physic = this.settings.physic;
+    this.world.gpuTilemap = this.settings.gpuTilemap;
+    if (this.settings.gpuTilemap && // duck-type rather than `instanceof WebGLRenderer` to avoid a
+    // runtime import; only the WebGL renderer carries `WebGLVersion`
+    this.renderer.WebGLVersion !== 2) {
+      console.warn(
+        "melonJS: gpuTilemap is enabled but the active renderer is not WebGL 2 \u2014 falling back to the legacy tile renderer for every tile layer"
+      );
+    }
     this.lastUpdate = globalThis.performance.now();
     if (!this.isInitialized) {
       on(STATE_CHANGE, this.repaint, this);
@@ -33129,9 +35167,7 @@ var Application = class {
   reset() {
     const current = state_default.get();
     if (typeof current !== "undefined") {
-      this.viewport = current.cameras.get(
-        "default"
-      );
+      this.viewport = current.cameras.get("default");
     }
     emit(GAME_RESET);
     this.updateFrameRate();