melonjs 19.9.0 → 20.0.0

package/README.md

@@ -17,7 +17,7 @@ A modern & lightweight HTML5 game engine
 -------------------------------------------------------------------------------
 ![melonJS](https://melonjs.org/img/alex4-github.png)
 
-[melonJS](https://melonjs.org/) is an open-source 2.5D game engine designed for indie developers — perspective and orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects, custom shaders, 3D mesh support, polygon-accurate physics, modern Tiled workflows, and high performance. Runs on WebGL or Canvas2D with automatic fallback, tree-shakeable so you only pay for what you use, and the entire engine fits in ~150 KB minzipped of vanilla JS/TS with no toolchain lock-in. Built with ES6 classes and bundled with [esbuild](https://esbuild.github.io).
+[melonJS](https://melonjs.org/) is an open-source 2.5D game engine designed for indie developers — perspective and orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects, custom shaders, 3D mesh support, polygon-accurate physics, modern Tiled workflows, and high performance. Runs on WebGPU, WebGL 2 or Canvas2D with automatic fallback, tree-shakeable so you only pay for what you use, and the entire engine fits in ~150 KB minzipped of vanilla JS/TS with no toolchain lock-in. Built with ES6 classes and bundled with [esbuild](https://esbuild.github.io).
 
 [melonJS](https://melonjs.org/) is licensed under the [MIT License](LICENSE.md) and actively maintained by the team at AltByte in Singapore.
 
@@ -28,11 +28,11 @@ melonJS is designed so you can **focus on making games, not on graphics plumbing
 
 - **[Canvas2D-inspired rendering API](https://github.com/melonjs/melonJS/wiki/Rendering-API)** — If you've used the HTML5 Canvas, you already know melonJS. The rendering API (`save`, `restore`, `translate`, `rotate`, `setColor`, `fillRect`, ...) follows the same familiar patterns — no render graphs, no shader pipelines, no instruction sets to learn.
 
-- **True renderer abstraction** — Write your game once, run it on WebGL or Canvas2D with zero code changes. The engine handles all GPU complexity behind a unified API, with automatic fallback when WebGL is not available. Designed to support future backends (WebGPU) without touching game code.
+- **True renderer abstraction** — Write your game once, run it on WebGPU, WebGL 2 or Canvas2D with zero code changes. The engine handles all GPU complexity behind a unified API: the default `AUTO` mode tries WebGPU first at startup, falls back to WebGL 2 if that is unavailable, and ultimately to Canvas, and the entire feature set renders identically on both GPU backends.
 
 - **Complete engine, minimal footprint** — Physics, tilemaps, audio, input, cameras, tweens, particles, UI — a full game stack in a single tree-shakeable ES module. No dependency sprawl, no library stitching.
 
-- **Scenes, loaded in one call** — `level.load(name)` brings an authored scene straight into your world. [Tiled](https://www.mapeditor.org) is a first-class citizen for **2D** — orthogonal, isometric, hexagonal & staggered maps, animated tilesets, collision shapes, object properties, compressed formats, with GPU-accelerated tile rendering under WebGL 2 — and **glTF / GLB** is the equivalent for **3D scenes**: author in Blender (or any DCC tool), export a `.glb`, and the whole scene — meshes, materials, cameras, lights, and node animation — loads under a `Camera3d`, no per-mesh wiring. Animated models play back through the same animation API as a 2D `Sprite`.
+- **Scenes, loaded in one call** — `level.load(name)` brings an authored scene straight into your world. [Tiled](https://www.mapeditor.org) is a first-class citizen for **2D** — orthogonal, isometric, hexagonal & staggered maps, animated tilesets, collision shapes, object properties, compressed formats, with GPU-accelerated tile rendering on the GPU backends — and **glTF / GLB** is the equivalent for **3D scenes**: author in Blender (or any DCC tool), export a `.glb`, and the whole scene — meshes, materials, cameras, lights, and node animation — loads under a `Camera3d`, no per-mesh wiring. Animated models play back through the same animation API as a 2D `Sprite`.
 
 - **Batteries included, hackable by design** — Get started in minutes with minimal setup. When you need to go deeper: ES6 classes throughout, a plugin system for engine extensions, and a clean architecture that's easy to extend without fighting the framework.
 
@@ -46,19 +46,24 @@ Compatibility
 - Compatible with all major browsers (Chrome, Safari, Firefox, Opera, Edge) and mobile devices
 
 Graphics
-- Fast WebGL renderer for desktop and mobile devices with fallback to Canvas rendering
-- Extensible batcher system for custom rendering pipelines
+- Fast GPU renderers (WebGPU and WebGL 2) for desktop and mobile devices, with fallback to Canvas rendering
+- Since 20.0 the aging WebGL 1 path is retired and WebGL 2 is the baseline; devices offering only WebGL 1 fall back to the Canvas renderer under `AUTO`
+- Extensible batcher system for custom rendering pipelines, with backend-neutral vertex formats and draw topologies (declare a layout once, describe it to either GPU backend)
 - High DPI resolution & Canvas advanced auto scaling
 - Sprite with 9-slice scaling option and frame animation
-- Built-in effects such as tinting, masking, and CSS-style blend modes (normal, additive, multiply, screen, darken, lighten)
+- Built-in effects such as tinting, masking, and CSS-style blend modes (normal, none, additive, multiply, screen, darken, lighten)
 - Standard spritesheet, single and multiple Packed Textures support
 - Compressed texture support (DDS, KTX, KTX2, PVR, PKM) with automatic format detection and fallback
+- Hardware antialiasing (`antiAlias: true`) on both GPU backends — and it survives post-processing, since the offscreen targets a post-effect chain renders into are multisampled to match
 - Procedural noise textures: `Noise` (simplex/perlin/value/cellular, fBm / ridged / ping-pong fractal, domain warp; renderer-free and CPU-samplable for heightmaps, terrain, and spawn jitter) and `NoiseTexture2d` — bake a noise field into a sprite image, a `Gradient` color ramp, or a live-animated tangent-space normal map for lit water and surfaces; unified under a new `Texture2d` base alongside `TextureAtlas`
-- 3D mesh rendering with OBJ/MTL model loading, multi-material support, hardware depth testing, and perspective projection via `Camera3d` — ~30% faster mesh rendering with near-zero per-frame allocation (a re-drawn static mesh produces no GC garbage)
+- 3D mesh rendering with OBJ/MTL model loading, multi-material support, hardware depth testing, and perspective projection via `Camera3d` — retained-mode geometry, uploaded to the GPU once and re-drawn from there, so moving, rotating, scaling or re-tinting a mesh costs no vertex upload and no per-vertex CPU work at all
+- Mipmapped and anisotropically-filtered mesh textures on both GPU backends, so distant and grazing-angle geometry stops shimmering (opt out per mesh with `textureFilter: "nearest"` for crisp pixel-art models)
 - Lighting, in 2D and 3D:
     - **2D** — `Light2d` as a first-class `Renderable` (multiple dynamic lights, radial-gradient falloff, illumination-only mode, procedural rendering via `drawLight`), plus optional per-pixel normal-map shading on sprites for 3D-looking dynamic lights
-    - **3D** — `Light3d` directional + ambient lights, added to the world like `Light2d` (half-Lambert diffuse + ambient fill, runtime-manipulable for day/night), auto-loaded from a glTF scene's authored sun
-- Built-in shader effects (Flash, Outline, Glow, Dissolve, CRT, Hologram, etc.) with multi-pass chaining via `postEffects`, plus custom shader support via `ShaderEffect` for per-sprite fragment effects (WebGL)
+    - **3D** — `Light3d` directional, point, spot and ambient lights, added to the world like `Light2d` (half-Lambert diffuse + ambient fill, quadratic falloff and cone angles on the punctual types, runtime-manipulable for day/night), auto-loaded from a glTF scene's authored suns and lamps
+    - up to **32 simultaneous lights** on either path, with light data travelling in a uniform buffer — a static light rig costs zero GPU state changes per frame
+- Ground ("blob") shadows for 3D objects — **on by default** — so characters and props read as standing on the floor instead of hovering. An ellipse matching the caster's own footprint and rotation, shrinking and fading with height above the ground; one extra draw per object, and **one for an entire `InstancedMesh` scatter regardless of instance count**. Controllable per object, per glTF scene (`level.load(name, { castGroundShadow })`) or application-wide. Deliberately not shadow mapping: it answers "where is this standing", which is what a 2.5D scene needs
+- Built-in shader effects (Flash, Outline, Glow, Dissolve, CRT, Hologram, etc.) with multi-pass chaining via `addPostEffect()`, plus custom shader support on both GPU backends: `ShaderEffect` for per-sprite fragment effects (GLSL and/or WGSL bodies) and complete custom mesh shader programs via `mesh.shader` (a dual-language `GLShader`: GLSL pair and/or WGSL module)
 - Trail renderable for fading, tapering ribbons behind moving objects (speed lines, sword slashes, magic trails)
 - System & Bitmap Text with built-in typewriter effect
 - Video sprite playback
@@ -98,7 +103,7 @@ UI
 Scenes
 - Load a scene in one call with `level.load(name)` — 2D Tiled maps and 3D glTF scenes alike, auto-registered on preload
 - [Tiled](https://www.mapeditor.org) map format [up to 1.12](https://doc.mapeditor.org/en/stable/reference/tmx-changelog/) built-in support for easy level design
-    - **GPU-accelerated tile rendering** for orthogonal maps under WebGL 2 — each layer draws as a single quad with no per-tile loop, ~5–8× faster than the legacy CPU renderer on dense maps. Honors animated tiles, flip bits, per-layer opacity/tint/blend, and oversized bottom-aligned tiles; falls back transparently to the CPU renderer on isometric/staggered/hexagonal layers or non-WebGL-2 contexts
+    - **GPU-accelerated tile rendering** for orthogonal maps on the GPU backends (WebGL 2 and WebGPU) — each layer draws as a single quad with no per-tile loop, ~5–8× faster than the legacy CPU renderer on dense maps. Honors animated tiles, flip bits, per-layer opacity/tint/blend, and oversized bottom-aligned tiles; falls back transparently to the CPU renderer on isometric/staggered/hexagonal layers or under the Canvas renderer
     - Uncompressed and [compressed](https://github.com/melonjs/melonJS/tree/master/packages/tiled-inflate-plugin) Plain, Base64, CSV and JSON encoded XML tilemap loading
     - Orthogonal, Isometric, Hexagonal (both normal and staggered) and Oblique maps
     - Multiple layers with per-layer alpha, tinting and blend modes (multiple background/foreground, collision and Image layers)
@@ -116,7 +121,7 @@ Scenes
     - Shape based Tile collision support
 - glTF / GLB 3D scenes — load an authored 3D scene with `level.load(...)`, the same one call as a Tiled map
     - The whole scene loads at once — meshes, materials, cameras and lights — viewed under a `Camera3d`
-    - Automatically lit by the scene's directional lights (the sun set up in the authoring tool)
+    - Automatically lit by the scene's authored lights — the sun plus any point/spot lamps set up in the authoring tool, each keeping its authored name so `getChildByName("Sun")` finds it for runtime tuning
     - Textured, solid-colored, and vertex-colored materials
     - Node animation — walk/idle/sprint characters, spinning pickups, doors, lifts — played through the same `setCurrentAnimation` / `play` / `pause` / `stop` API as a 2D `Sprite`
     - `.glb` and `.gltf` files, with embedded *or* external buffers & textures
@@ -128,7 +133,7 @@ Assets
 - Support for images, JSON, TMX/TSX, glTF / GLB 3D scenes, `.aseprite` / `.ase` binary, audio, video, binary and fonts
 
 Core
-- `Application` class as the modern entry point with built-in pause, resume, and `freeze()` (hit-stop) primitives
+- `Application` class as the modern entry point — construct it, then `await app.init()` (asynchronous since 20.0, so the WebGPU device can be acquired) — with built-in pause, resume, and `freeze()` (hit-stop) primitives
 - A state manager (to easily manage loading, menu, options, in-game state)
 - Tween effects with multiple easing functions (Quadratic, Cubic, Elastic, Bounce, etc.) and Bezier/Catmull-Rom interpolation
 - Transition effects
@@ -179,9 +184,10 @@ Examples
 * [SVG Shapes](https://melonjs.github.io/melonJS/examples/#/svg-shapes) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/svgShapes))
 * [Graphics](https://melonjs.github.io/melonJS/examples/#/graphics) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/graphics))
 * [Hello World](https://melonjs.github.io/melonJS/examples/#/hello-world) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/helloWorld))
+* [Hello WebGPU](https://melonjs.github.io/melonJS/examples/#/webgpu) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/webgpu)) — the WebGPU backend in action, with the renderer negotiation surfaced on screen
 * [Whac-A-Mole](https://melonjs.github.io/melonJS/examples/#/whac-a-mole) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/whac-a-mole))
 * [Compressed Textures](https://melonjs.github.io/melonJS/examples/#/compressed-textures) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/compressedTextures))
-* [Aquarium](https://melonjs.github.io/melonJS/examples/#/aquarium) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/aquarium)) — screen-space water refraction with `renderer.toFrameTexture()`: fish swim across a seabed, then a water surface captures the live frame on the GPU and re-samples it through a scrolling `NoiseTexture2d` flow map (the Godot `hint_screen_texture` / Unity `_CameraOpaqueTexture` pattern)
+* [Aquarium](https://melonjs.github.io/melonJS/examples/#/aquarium) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/aquarium)) — screen-space water refraction with `renderer.toFrameTexture()`: fish swim across a seabed, then a water surface captures the live frame on the GPU and re-samples it through a scrolling `NoiseTexture2d` flow map (the standard screen-texture / opaque-frame-copy pattern)
 * [Heat Haze](https://melonjs.github.io/melonJS/examples/#/heat-haze) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/heatHaze)) — `renderer.toFrameTexture()` over a lit scene: normal-mapped tiles under a moving `Light2d`, distorted by a rising heat-haze that captures and ripples the lit frame
 * [3D Mesh](https://melonjs.github.io/melonJS/examples/#/mesh-3d) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3d))
 * [3D Mesh Material](https://melonjs.github.io/melonJS/examples/#/mesh-3d-material) ([source](https://github.com/melonjs/melonJS/tree/master/packages/examples/src/examples/mesh3dMaterial))
@@ -208,6 +214,9 @@ const app = new Application(1218, 562, {
     backgroundColor: "#202020",
 });
 
+// initialize it (builds the renderer and appends the canvas)
+await app.init();
+
 // set a gray background color
 app.world.backgroundColor.parseCSS("#202020");
 
@@ -223,6 +232,8 @@ app.world.addChild(new Text(609, 281, {
 ```
 > Simple hello world using melonJS
 
+> **Note:** since version 20.0, `await app.init()` is **required** after constructing the `Application`. The WebGPU backend, which `AUTO` tries first on browsers that support it, acquires its GPU device asynchronously, so initialization had to become an async step; it resolves without suspending on the WebGL and Canvas backends. On 19.x the call is optional and this example works without it.
+
 Documentation
 -------------------------------------------------------------------------------
 
@@ -235,7 +246,7 @@ melonJS provides a plugin system allowing to extend the engine capabilities.
 Here is the list of official plugins maintained by the melonJS team:
 - [debug-plugin](https://github.com/melonjs/melonJS/tree/master/packages/debug-plugin) - a debug panel for inspecting game objects
 - [tiled-inflate-plugin](https://github.com/melonjs/melonJS/tree/master/packages/tiled-inflate-plugin) - enable loading and parsing of zlib, gzip and zstd compressed [Tiled](https://www.mapeditor.org/) maps
-- [spine-plugin](https://github.com/melonjs/melonJS/tree/master/packages/spine-plugin) - [Spine](http://esotericsoftware.com) runtime integration to render Spine skeletal animations
+- [spine-plugin](https://github.com/melonjs/melonJS/tree/master/packages/spine-plugin) - [Spine](http://esotericsoftware.com) runtime integration to render Spine skeletal animations, with a dedicated batcher on each renderer (WebGPU, WebGL and Canvas)
 - [capacitor-plugin](https://github.com/melonjs/melonJS/tree/master/packages/capacitor-plugin) - bridges [Capacitor](https://capacitorjs.com/)'s native lifecycle (pause/resume, hardware back-button, orientation lock, splash) for melonJS games wrapped as iOS / Android apps
 
 If you wish to develop your own plugin, we also provide a [plugin template](https://github.com/melonjs/plugin-template) to help you get started.

package/build/application/application.d.ts

@@ -4,11 +4,14 @@ import type Renderer from "./../video/renderer.js";
 import type { ApplicationSettings, ResolvedApplicationSettings } from "./settings.ts";
 /**
  * The Application class is the main entry point for creating a melonJS game.
- * It initializes the renderer, creates the game world and viewport, registers DOM event
- * listeners (resize, orientation, scroll), and starts the game loop.
+ * The constructor resolves the given settings, creates the game world and
+ * registers DOM event listeners (resize, orientation, scroll); you **MUST**
+ * then call (and await) {@link Application#init init}, which builds the
+ * renderer, appends the canvas to the parent element, and starts the game
+ * loop — without it the application has no renderer and displays nothing.
  *
  * The Application instance provides access to the core game systems:
- * - {@link Application#renderer renderer} — the active Canvas or WebGL renderer
+ * - {@link Application#renderer renderer} — the active Canvas, WebGL or (experimental) WebGPU renderer
  * - {@link Application#world world} — the root container for all game objects
  * - {@link Application#viewport viewport} — the default camera / viewport
  *
@@ -24,6 +27,9 @@ import type { ApplicationSettings, ResolvedApplicationSettings } from "./setting
  *     renderer: 2, // AUTO
  * });
  *
+ * // build the renderer (mandatory — only suspends for WebGPU)
+ * await app.init();
+ *
  * // add objects to the world
  * app.world.addChild(new Sprite(0, 0, { image: "player" }));
  *
@@ -36,7 +42,7 @@ export default class Application {
      */
     parentElement: HTMLElement;
     /**
-     * a reference to the active Canvas or WebGL renderer
+     * a reference to the active Canvas, WebGL or (experimental) WebGPU renderer
      */
     renderer: Renderer;
     /**
@@ -99,16 +105,49 @@ export default class Application {
     private _onResize?;
     private _onOrientationChange?;
     private _onScroll?;
+    private _doResize?;
+    private _resizeObserver;
+    private _destroyed;
+    /**
+     * Simulated time advanced by one logic step, in ms — what `world.update()`
+     * receives. Fixed at `1000 / world.fps` unless `timer.interpolation` is on,
+     * in which case it follows the real frame delta.
+     *
+     * Not to be confused with {@link Application#lastUpdateDelta}, which is how
+     * long that step actually took to compute.
+     */
     updateDelta: number;
     lastUpdateStart: number | null;
-    updateAverageDelta: number;
     /**
-     * Create and initialize a new melonJS Application.
-     * This is the recommended way to start a melonJS game.
+     * Measured wall-clock cost of the most recent logic step, in ms
+     * (`performance.now()` taken either side of the world/stage update).
+     *
+     * Used by the fixed-timestep loop to avoid a spiral of death: the
+     * accumulator drains by at least this much, so a scene too heavy to
+     * simulate in real time slows down instead of locking up.
+     *
+     * Only the *last* step of a frame is recorded, so a frame that ran several
+     * catch-up steps reports less than its total update cost.
+     * Renamed from `updateAverageDelta` in 20.0.0.
+     * @since 20.0.0
+     */
+    lastUpdateDelta: number;
+    /**
+     * @deprecated since 20.0.0 — renamed to {@link Application#lastUpdateDelta}.
+     * The old name claimed an average that has not existed since 2015, when the
+     * exponential smoothing behind it was removed a day after being added.
+     */
+    get updateAverageDelta(): number;
+    set updateAverageDelta(value: number);
+    /**
+     * Create a new melonJS Application.
+     * Constructing the instance is only the first half of starting a game:
+     * you **MUST** then call (and await) {@link Application#init init} to
+     * build the renderer — an Application on which `init()` has not resolved
+     * has no `renderer`, no canvas, and cannot render anything.
      * @param width - The width of the canvas viewport
      * @param height - The height of the canvas viewport
      * @param options - The optional parameters for the application and default renderer
-     * @throws {Error} Will throw an exception if it fails to instantiate a renderer
      * @example
      * const app = new Application(1024, 768, {
      *     parent: "game-container",
@@ -116,17 +155,28 @@ export default class Application {
      *     scaleMethod: "fit",
      *     renderer: 2, // AUTO
      * });
+     * await app.init();
      */
-    constructor(width: number, height: number, options?: Partial<ApplicationSettings> & {
-        legacy?: boolean;
-    });
+    constructor(width: number, height: number, options?: Partial<ApplicationSettings>);
     /**
-     * init the game instance (create a physic world, update starting time, etc..)
-     * @param width - The width of the canvas viewport
-     * @param height - The height of the canvas viewport
-     * @param options - The optional parameters for the application and default renderer
+     * Build the renderer and everything that depends on it — the canvas
+     * (appended to the parent element), the initial resize layout, and the
+     * console banner. Reads {@link Application#settings}, resolved by the
+     * constructor; it takes no arguments of its own.
+     *
+     * **Calling and awaiting this is mandatory** — it is the second half of
+     * every Application's start-up, not an optional step. It resolves
+     * synchronously for the Canvas and WebGL backends, which acquire their
+     * context without suspending — but WebGPU cannot, and an application
+     * whose `init()` has not resolved has no `renderer`.
+     * @throws {Error} if it fails to instantiate the requested renderer
+     * (e.g. `renderer: video.WEBGL` on a device with no WebGL 2 support)
+     * @returns resolves once the application is ready to use
+     * @example
+     * const app = new Application(640, 480, { parent: "screen" });
+     * await app.init();
      */
-    init(width: number, height: number, options?: Partial<ApplicationSettings>): void;
+    init(): Promise<void>;
     /**
      * reset the game Object manager
      * destroy all current objects
@@ -210,6 +260,10 @@ export default class Application {
      * Destroy this application instance and release all associated resources.
      * Removes the canvas from the DOM, destroys the world, and unregisters
      * all event listeners.
+     *
+     * **Terminal**: a destroyed Application cannot be re-initialized —
+     * `init()` rejects afterwards (and an `init()` still in flight aborts).
+     * Construct a new Application to start again.
      * @param removeCanvas - if true, the canvas element is removed from the DOM (default: true)
      * @example
      * // clean up when done

package/build/application/application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/application/application.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/application/application.ts"],"names":[],"mappings":"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"}

package/build/application/defaultApplicationSettings.d.ts

@@ -2,11 +2,12 @@ export declare const defaultApplicationSettings: {
     renderer: 2;
     scale: number;
     scaleMethod: "manual";
-    preferWebGL1: false;
     powerPreference: "default";
     transparent: false;
     antiAlias: false;
     textureFilter: "auto";
+    maxTextures: "auto";
+    castGroundShadow: true;
     consoleHeader: true;
     blendMode: "normal";
     physic: "builtin";
@@ -15,7 +16,6 @@ export declare const defaultApplicationSettings: {
     highPrecisionShader: true;
     subPixel: false;
     verbose: false;
-    legacy: false;
     backgroundColor: string;
 };
 //# sourceMappingURL=defaultApplicationSettings.d.ts.map

package/build/application/resize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resize.d.ts","sourceRoot":"","sources":["../../src/application/resize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAkChD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CA4EhD"}
+{"version":3,"file":"resize.d.ts","sourceRoot":"","sources":["../../src/application/resize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAkChD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAyGhD"}

package/build/application/settings.d.ts

@@ -6,9 +6,9 @@ import type Camera2d from "../camera/camera2d";
 import { RendererType } from "../const";
 import { PhysicsAdapter } from "../physics/adapter";
 import Renderer from "../video/renderer";
-import { Batcher } from "../video/webgl/batchers/batcher";
+import { WebGLBatcher } from "../video/webgl/batchers/batcher.js";
 import { ScaleMethod } from "./scaleMethods";
-type BlendMode = "normal" | "multiply" | "lighter" | "additive" | "screen";
+type BlendMode = "normal" | "multiply" | "lighter" | "additive" | "screen" | "darken" | "lighten" | "exclusion" | "none";
 /**
  * How the application's physics is configured.
  *
@@ -21,23 +21,31 @@ type BlendMode = "normal" | "multiply" | "lighter" | "additive" | "screen";
 type PhysicsType = "builtin" | "none" | PhysicsAdapter | {
     adapter: PhysicsAdapter;
 };
-type PowerPreference = "default" | "low-power";
+type PowerPreference = "default" | "low-power" | "high-performance";
 export type ApplicationSettings = {
     /**
-     * Renderer to use. Three built-in modes (constants from `me.video`):
-     *
-     * - {@link CANVAS} — HTML5 Canvas backend. No shader / mesh /
-     *   Camera3d support.
-     * - {@link WEBGL} — **requires WebGL**. Throws at `new Application(...)`
-     *   time if WebGL is unavailable (driver-blocklisted GPU, perf-caveat
-     *   failure, etc.). Use this when your scene needs Camera3d, Mesh,
-     *   ShaderEffect, Light2d or GPU tilemap — you'd rather fail fast
-     *   than render a stuck blank canvas.
-     * - {@link AUTO} — try WebGL, silently fall back to Canvas if
-     *   unavailable. Application construction always succeeds. The
-     *   WebGL-only subsystems (Camera3d, Mesh, ShaderEffect, Light2d,
-     *   GPU tilemap) silently stop working under the Canvas fallback —
-     *   if your scene depends on any of those, use `WEBGL` instead.
+     * Renderer to use. Four built-in modes (constants from `me.video`):
+     *
+     * - {@link AUTO} — negotiate the best available backend:
+     *   **WebGPU → WebGL 2 → Canvas**. `await app.init()` always
+     *   resolves under AUTO; the WebGPU attempt is a full adapter/device
+     *   negotiation awaited inside `init()`, falling through to the
+     *   synchronous candidates when it rejects. Under the Canvas tail the
+     *   GPU-only subsystems (Camera3d, retained meshes, ShaderEffect,
+     *   Light2d/Light3d shading, GPU tilemap) degrade or disable — gate on
+     *   the renderer capability flags (`supportsDepthBuffer`,
+     *   `shaderLanguage`, …) if your scene depends on them.
+     * - {@link WEBGPU} — require the WebGPU backend. `app.init()`
+     *   **rejects** when no adapter/device can be acquired — it never
+     *   substitutes another backend.
+     * - {@link WEBGL} — **requires WebGL 2** (the WebGL renderer is
+     *   WebGL 2 only since 20.0). `app.init()` **rejects** if a WebGL 2
+     *   context is unavailable (WebGL-1-only device, driver-blocklisted
+     *   GPU, perf-caveat failure, etc.) — fail fast rather than render a
+     *   stuck blank canvas.
+     * - {@link CANVAS} — the HTML5 Canvas backend. No programmable
+     *   pipeline: no shaders/lighting, no Camera3d/depth path (meshes
+     *   only render on the CPU-projected 2D-camera path).
      *
      * Or pass a custom `Renderer` subclass instance for full control.
      * @default AUTO
@@ -58,13 +66,20 @@ export type ApplicationSettings = {
      */
     scaleTarget: HTMLElement;
     /**
-     * if true the renderer will only use WebGL 1
-     * @default false
-     */
-    preferWebGL1: boolean;
-    /**
-     * a hint to the user agent indicating what configuration of GPU is suitable for the WebGL context. To be noted that Safari and Chrome (since version 80) both default to "low-power" to save battery life and improve the user experience on these dual-GPU machines.
-     * @default default
+     * A hint to the user agent about which GPU to use on multi-GPU systems
+     * (discrete vs integrated). Browsers generally favour the low-power GPU
+     * unless asked otherwise, to preserve battery life.
+     *
+     * - `"default"` — no hint; let the user agent decide.
+     * - `"low-power"` — prefer the integrated GPU.
+     * - `"high-performance"` — prefer the discrete GPU. Note that browsers
+     *   only honour this for pages that handle context loss, since switching
+     *   GPU can drop the context; melonJS registers those handlers itself,
+     *   so the request is respected.
+     *
+     * The same hint (and the same values, minus `"default"`) is used by
+     * WebGPU's adapter request, so this setting is backend-neutral.
+     * @default "default"
      */
     powerPreference: PowerPreference;
     /**
@@ -73,14 +88,22 @@ export type ApplicationSettings = {
      */
     transparent: boolean;
     /**
-     * whether to enable or not video scaling interpolation
+     * whether to enable or not video scaling interpolation.
+     * On the GPU backends this drives polygon-edge antialiasing (up to
+     * 4× MSAA) — on the canvas itself, and equally through post-effect
+     * chains, whose scene capture targets are multisampled to match, so
+     * adding a camera effect never switches edge smoothing off. Texture
+     * sampling smoothness is controlled separately by `textureFilter`.
+     * Multisampled capture targets cost GPU memory (roughly 30 bytes per
+     * pixel at 4×, ~55 MB at 1080p on WebGL) — with `antiAlias: false`
+     * no multisampled storage is ever allocated.
      * @default false
      */
     antiAlias: boolean;
     /**
      * Default texture magnification/minification filter, **decoupled from
-     * `antiAlias`** (WebGL only — the 2D Canvas renderer has no per-texture
-     * filtering and ignores this).
+     * `antiAlias`** (GPU backends — WebGL and WebGPU; the 2D Canvas
+     * renderer has no per-texture filtering and ignores this).
      *
      * `antiAlias` conflates two separate concerns: polygon-edge antialiasing
      * (MSAA) *and* texture sampling smoothness. This setting separates the
@@ -111,6 +134,73 @@ export type ApplicationSettings = {
      * });
      */
     textureFilter: "auto" | "nearest" | "linear";
+    /**
+     * How many texture units the WebGL multi-texture batchers may use
+     * ([#1585](https://github.com/melonjs/melonJS/issues/1585)).
+     *
+     * A batch can draw sprites from this many distinct textures before it has
+     * to flush and start over, so a scene with more textures in flight than
+     * this loses batching sharply. The pool used to be hardcoded to 16 — the
+     * WebGL 2 spec *floor* for `MAX_TEXTURE_IMAGE_UNITS`, and roughly half
+     * what current desktop and mobile hardware reports.
+     *
+     * - `"auto"` (default) — the device's reported limit, capped at 32.
+     * - a number — that many units, clamped to what the device actually has
+     *   (asking for more than exists would fail to link the shader).
+     *
+     * Raising it costs fragment-shader compile time and register pressure,
+     * because the batcher's shader unrolls one sampler and one branch per
+     * unit. Lowering it is the escape hatch if a driver misbehaves on wide
+     * sampler ladders.
+     *
+     * **Read at initialization only** — the batchers compile their shaders
+     * against this value, so unlike `textureFilter` there is no runtime setter.
+     * WebGL only; the WebGPU backend sizes its own slot budget from its
+     * per-stage binding limits, and the Canvas renderer has no batching.
+     * @default "auto"
+     * @example
+     * // cap the pool on a device with a known-bad wide sampler ladder
+     * const app = new Application(1024, 768, {
+     *     renderer: video.WEBGL,
+     *     maxTextures: 16,
+     * });
+     */
+    maxTextures: "auto" | number;
+    /**
+     * whether 3D objects cast a soft "blob" shadow on the ground by default
+     * ([#1515](https://github.com/melonjs/melonJS/issues/1515)).
+     *
+     * A ground shadow is what stops a character or prop reading as *floating*
+     * in a 2.5D scene — it answers "where is this standing", not "where is the
+     * light". It is deliberately not a simulated shadow; see
+     * {@link Mesh#castGroundShadow}.
+     *
+     * This is the **default** for every {@link Mesh}, {@link Sprite3d} and
+     * {@link InstancedMesh}; each can override it with its own
+     * `castGroundShadow` (which wins), and {@link level.load} takes the same
+     * option for one glTF scene (which wins over this).
+     *
+     * Because it is a blanket opt-in, it skips meshes with **no vertical
+     * extent** — a flat plane lying on the floor *is* the floor, and shadowing
+     * it with itself would smear a blob across the whole ground. A per-object
+     * `castGroundShadow: true` bypasses that safeguard, being an explicit
+     * instruction.
+     *
+     * **On by default.** Requires a GPU backend *and* a {@link Camera3d}, so a
+     * 2D game is untouched whatever this says — the Canvas renderer has no
+     * depth buffer and the 2D-camera path draws none. Set it `false` to opt a
+     * 3D game out wholesale (a scene with baked lighting, or one bringing its
+     * own shadows, would otherwise get two).
+     * @default true
+     * @example
+     * // opt a 3D game out — e.g. its lighting is already baked into the models
+     * const app = new Application(1024, 768, {
+     *     cameraClass: Camera3d,
+     *     castGroundShadow: false,
+     * });
+     * await app.init();
+     */
+    castGroundShadow: boolean;
     /**
      * whether to display melonJS version and basic device information in the console
      * @default true
@@ -138,21 +228,30 @@ export type ApplicationSettings = {
      */
     physic: PhysicsType;
     /**
-     * Enable the WebGL2 procedural shader path for orthogonal tile layers.
-     * When `true` (default), eligible layers render via a single quad per
-     * tileset + a fragment shader doing per-fragment GID lookup, bypassing
-     * the per-tile draw loop entirely. Layers that don't qualify
-     * (Canvas/WebGL1, non-orthogonal, collection-of-image tilesets,
-     * tilerendersize "grid", non-zero tileoffset, oversampled beyond the
-     * shader's overflow window) fall back to the legacy path automatically.
+     * Enable the GPU procedural shader path for orthogonal tile layers
+     * (backends advertising `renderer.supportsShaderTileLayers` — WebGL 2
+     * and WebGPU). When `true` (default), eligible layers render via a
+     * single quad per tileset + a fragment shader doing per-fragment GID
+     * lookup, bypassing the per-tile draw loop entirely. Layers that
+     * don't qualify (Canvas renderer, non-orthogonal,
+     * collection-of-image tilesets, tilerendersize "grid", non-zero
+     * tileoffset, oversampled beyond the shader's overflow window) fall
+     * back to the legacy path automatically.
      * Set to `false` to disable globally.
      * @default true
      */
     gpuTilemap: boolean;
     /**
-     * if true, the renderer will fail if the browser reports a major performance caveat
-     * (e.g. software WebGL). Set to false to allow WebGL on machines with
-     * blocklisted GPU drivers or software renderers.
+     * If true, treat WebGL as unavailable when the browser warns that a
+     * context would perform dramatically worse than a native application
+     * (a software rasterizer, a blocklisted driver). Note this is stricter
+     * than the WebGL default, which is `false`.
+     *
+     * The WebGPU backend honors it too, by rejecting a fallback
+     * (software) adapter. The effect: under {@link AUTO} such a machine
+     * gets the Canvas renderer, and under {@link WEBGL} / {@link WEBGPU}
+     * `app.init()` rejects. Set to `false` to accept a software or
+     * blocklisted context instead.
      * @default true
      */
     failIfMajorPerformanceCaveat: boolean;
@@ -182,11 +281,6 @@ export type ApplicationSettings = {
      * @default false
      */
     verbose: boolean;
-    /**
-     * whether to enable legacy mode (enables deprecated `video.init()` entry point)
-     * @default false
-     */
-    legacy: boolean;
     /**
      * the CSS background color of the parent element that holds the canvas.
      * Applied during initialization to prevent a white flash before the first render.
@@ -195,14 +289,17 @@ export type ApplicationSettings = {
      */
     backgroundColor: string;
     /**
-     * a custom batcher class (WebGL only)
+     * a custom batcher class (extend the active backend's base:
+     * `WebGLBatcher` / `WebGPUBatcher`)
      * @deprecated since 18.1.0 — use `batcher` instead
      */
-    compositor?: (new (renderer: any) => Batcher) | undefined;
+    compositor?: (new (renderer: any) => WebGLBatcher) | undefined;
     /**
-     * a custom batcher class (WebGL only)
+     * a custom batcher class, riding the quad/primitive slots on either
+     * GPU backend — extend `WebGLBatcher` under WebGL, `WebGPUBatcher`
+     * under WebGPU (`addBatcher` rejects a wrong-backend class loudly)
      */
-    batcher?: (new (renderer: any) => Batcher) | undefined;
+    batcher?: (new (renderer: any) => WebGLBatcher) | undefined;
     /**
      * Default camera class instantiated for any {@link Stage} that does not
      * explicitly provide its own cameras. Set to {@link Camera3d} to opt
@@ -212,14 +309,14 @@ export type ApplicationSettings = {
      * (e.g. the loader screen) explicitly use {@link Camera2d} regardless
      * of this setting.
      *
-     * **WebGL requirement.** Camera classes whose
+     * **GPU-backend requirement.** Camera classes whose
      * `static defaultSortOn === "depth"` (Camera3d and any subclass) need
-     * the WebGL renderer — perspective projection, depth attachment and
-     * mesh draw all live in the WebGL backend. Pairing such a
-     * `cameraClass` with `renderer: video.AUTO` on a system where AUTO
-     * falls back to Canvas emits a `console.warn` at construction time
-     * and produces a non-functional render. Use `renderer: video.WEBGL`
-     * to get a hard throw instead.
+     * a renderer with a depth buffer (`renderer.supportsDepthBuffer` —
+     * WebGL 2 or WebGPU). Pairing such a `cameraClass` with
+     * `renderer: video.AUTO` on a system where AUTO falls back to Canvas
+     * emits a `console.warn` and produces a non-functional render. Pin
+     * `renderer: video.WEBGL` (or `WEBGPU`) to make `app.init()` reject
+     * instead.
      * @default Camera2d
      */
     cameraClass?: new (minX: number, minY: number, maxX: number, maxY: number) => Camera2d;

package/build/application/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/application/settings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/application/settings.ts"],"names":[],"mappings":"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"}

package/build/camera/camera2d.d.ts

@@ -7,8 +7,8 @@ import { Vector3d } from "../math/vector3d.ts";
 import { Bounds } from "./../physics/bounds.ts";
 import type Container from "./../renderable/container.js";
 import Renderable from "./../renderable/renderable.js";
+import ColorMatrixEffect from "./../video/effects/colorMatrix.js";
 import type Renderer from "./../video/renderer.js";
-import ColorMatrixEffect from "./../video/webgl/effects/colorMatrix.js";
 import type CameraEffect from "./effects/camera_effect.ts";
 /**
  * @import Entity from "./../renderable/entity/entity.js";