feat(application): two-phase async startup + experimental WebGPU bootstrap (#1184) — 20.0.0

Breaking: starting a game is now construct + mandatory `await app.init()`.
The constructor owns everything renderer-independent (settings resolution,
game world, DOM event bridging); init() builds the renderer and everything
downstream, and is asynchronous because a WebGPU device cannot be acquired
synchronously. The exported `game` names the most recently initialized
Application — set at the END of init(), undefined before the first one.
`video.init()`, `video.renderer`, `video.createCanvas()`,
`video.getParent()` and the `legacy` setting are removed. destroy() is
terminal; a repeated init() is a warned no-op.

The experimental WebGPU backend is the first consumer of the async path:
GPUCanvasContext at construction, adapter/device negotiation + canvas
configuration in renderer.init(), and a real per-frame clear pass; every
other drawing method stays a base-class no-op. Opt-in only — AUTO never
selects it, and init() rejects when WebGPU is unavailable. Renderers
gained an argument-less async init() lifecycle hook awaited by
Application.init().

Tests and examples migrated to `const app = new Application(...);
await app.init()`; spec files no longer read the `game` global (the
singleton spec excepted). Lifecycle hardening from adversarial review:
destroy() during a pending init() aborts instead of resurrecting the app,
each backend stamps its own context type so a WEBGPU rejection can be
retried as Canvas, and the MutationObserver / GAME_RESET subscriptions
are released on destroy. New Hello WebGPU example; all 43 examples
verified via Playwright; full suite 5223 passing.

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

Author: obiot

packages/debug-plugin/src/index.js

@@ -1,4 +1,4 @@
-import { event, input, plugin, pool, timer, utils, video } from "melonjs";
+import { event, input, plugin, pool, timer, utils } from "melonjs";
 import { homepage, name, peerDependencies, version } from "../package.json";
 import Counters from "./counters.js";
 import { drawFrameGraph, drawMemGraph } from "./graphs.js";
@@ -329,7 +329,7 @@ export class DebugPanelPlugin extends plugin.BasePlugin {
 
 	/** @private */
 	_syncPosition() {
-		const rect = video.renderer.getCanvas().getBoundingClientRect();
+		const rect = this.app.renderer.getCanvas().getBoundingClientRect();
 		const s = this.panelWrap.style;
 		s.top = `${rect.top}px`;
 		s.left = `${rect.left}px`;
@@ -453,7 +453,7 @@ export class DebugPanelPlugin extends plugin.BasePlugin {
 		if (!this.options.quadtree) {
 			return;
 		}
-		const renderer = video.renderer;
+		const renderer = this.app.renderer;
 		renderer.save();
 		const { x, y } = this.app.viewport.pos;
 		renderer.translate(-x, -y);

packages/examples/src/examples/afterBurner/ExampleAfterBurner.tsx

@@ -42,7 +42,7 @@ import {
 import { GameController } from "./GameController";
 import { SkyboxStage } from "./SkyboxStage";
 
-const createGame = () => {
+const createGame = async () => {
 	// NOTE: an `unmounted` guard around the preload callback would in
 	// principle fix the "user navigates away before preload finishes"
 	// race that Copilot flagged. It can't be added cleanly today —
@@ -68,6 +68,7 @@ const createGame = () => {
 			scale: "auto",
 			cameraClass: Camera3d,
 		});
+		await app.init();
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
 		globalThis.alert(

packages/examples/src/examples/aquarium/ExampleAquarium.tsx

@@ -23,7 +23,7 @@
  */
 import { DebugPanelPlugin } from "@melonjs/debug-plugin";
 import {
-	type Application,
+	Application,
 	loader,
 	NoiseTexture2d,
 	plugin,
@@ -295,8 +295,8 @@ class PlayScreen extends Stage {
 	}
 }
 
-const createGame = () => {
-	video.init(728, 410, {
+const createGame = async () => {
+	const app = new Application(728, 410, {
 		parent: "screen",
 		// fixed internal resolution scaled to fit (keeps viewport 728×410, so
 		// full-screen renderables cover it regardless of the container size)
@@ -308,6 +308,7 @@ const createGame = () => {
 		// instead of snapping pixel-to-pixel (default floors dx/dy to integers)
 		subPixel: true,
 	});
+	await app.init();
 
 	// register the debug plugin (hidden by default; press S to toggle)
 	plugin.register(DebugPanelPlugin, "debugPanel");

packages/examples/src/examples/aseprite/ExampleAseprite.tsx

@@ -10,8 +10,9 @@ import { paladin } from "./play";
 
 export const ExampleAseprite = () => {
 	useEffect(() => {
-		if (!me.game.isInitialized) {
-			createGame();
+		// `game` is undefined until the first Application finishes init()
+		if (!me.game?.isInitialized) {
+			void createGame();
 		}
 	}, []);
 

packages/examples/src/examples/aseprite/game.ts

@@ -4,7 +4,7 @@
  * See `packages/examples/LICENSE.md` for full license + asset credits.
  */
 import { DebugPanelPlugin } from "@melonjs/debug-plugin";
-import { loader, plugin, state, video } from "melonjs";
+import { Application, loader, plugin, state } from "melonjs";
 import { PlayScreen } from "./play";
 
 const base = `${import.meta.env.BASE_URL}assets/aseprite/`;
@@ -13,9 +13,10 @@ const resources = [
 	{ name: "paladin", type: "image", src: `${base}paladin.png` },
 ];
 
-export const createGame = () => {
+export const createGame = async () => {
 	// `parent: "screen"` — see ExampleBenchmark for the rationale.
-	video.init(640, 480, { parent: "screen" });
+	const app = new Application(640, 480, { parent: "screen" });
+	await app.init();
 
 	// register the debug plugin
 	plugin.register(DebugPanelPlugin, "debugPanel");

packages/examples/src/examples/benchmark/ExampleBenchmark.tsx

@@ -5,6 +5,7 @@
  */
 import { DebugPanelPlugin } from "@melonjs/debug-plugin";
 import {
+	Application,
 	device,
 	event,
 	game,
@@ -29,10 +30,10 @@ function addFruits(numberOfFruits: number, fruitType?: string) {
 	}
 }
 
-const createGame = () => {
+const createGame = async () => {
 	// Initialize the video.
-	if (
-		!video.init(1024, 768, {
+	try {
+		const app = new Application(1024, 768, {
 			// `parent: "screen"` — without this the engine falls back to
 			// `document.body`, and on this page body has no flow content
 			// (#screen is `position: fixed`, so it's pulled out of the
@@ -44,8 +45,9 @@ const createGame = () => {
 			scaleMethod: ScaleMethods.Flex,
 			renderer: video.AUTO,
 			transparent: false,
-		})
-	) {
+		});
+		await app.init();
+	} catch {
 		alert("Your browser does not support HTML5 canvas.");
 		return;
 	}

packages/examples/src/examples/billboard/ExampleBillboard.tsx

@@ -129,7 +129,7 @@ class SkyBackdrop extends Renderable {
 	}
 }
 
-const createGame = () => {
+const createGame = async () => {
 	let app: Application;
 	try {
 		app = new Application(1024, 768, {
@@ -139,6 +139,7 @@ const createGame = () => {
 			cameraClass: Camera3dClass,
 			antiAlias: true,
 		});
+		await app.init();
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
 		globalThis.alert(

packages/examples/src/examples/blendModes/ExampleBlendModes.tsx

@@ -3,7 +3,7 @@
  * Copyright (C) 2011 - 2026 AltByte Pte Ltd — MIT License.
  * See `packages/examples/LICENSE.md` for full license + asset credits.
  */
-import { game, Renderable, Text, video } from "melonjs";
+import { Application, game, Renderable, Text, video } from "melonjs";
 import { createExampleComponent } from "../utils";
 
 const BLEND_MODES = [
@@ -27,26 +27,27 @@ const CELL_W = 180;
 const CELL_H = 170;
 const CIRCLE_R = 45;
 
-const createGame = () => {
+const createGame = async () => {
 	const rows = Math.ceil(BLEND_MODES.length / COLS);
 	const canvasW = COLS * CELL_W;
 	const HEADER_H = 40;
 	const canvasH = rows * CELL_H + HEADER_H;
 
-	if (
-		!video.init(canvasW, canvasH, {
+	try {
+		const app = new Application(canvasW, canvasH, {
 			parent: "screen",
 			renderer: video.AUTO,
 			preferWebGL1: false,
-		})
-	) {
+		});
+		await app.init();
+	} catch {
 		alert("Your browser does not support HTML5 canvas.");
 		return;
 	}
 
 	// detect which modes are actually supported by probing setBlendMode
 	// biome-ignore lint/suspicious/noExplicitAny: renderer type varies between WebGL/Canvas
-	const renderer = video.renderer as any;
+	const renderer = game.renderer as any;
 	const supported: Record<string, boolean> = {};
 	for (const mode of BLEND_MODES) {
 		const applied = renderer.setBlendMode(mode);

packages/examples/src/examples/camera3d/ExampleCamera3d.tsx

@@ -34,7 +34,7 @@ import {
 import monsterImg from "../shaderEffects/assets/monster.png";
 import { createExampleComponent } from "../utils";
 
-const createGame = () => {
+const createGame = async () => {
 	// Stash teardown work assembled inside the loader callback so the
 	// outer `createGame` can return a single cleanup function from the
 	// async preload completion.
@@ -61,6 +61,7 @@ const createGame = () => {
 		scale: "auto",
 		cameraClass: Camera3dClass,
 	});
+	await app.init();
 
 	app.world.backgroundColor.parseCSS("#0a0a14");
 	plugin.register(DebugPanelPlugin, "debugPanel");

packages/examples/src/examples/clipping/ExampleClipping.tsx

@@ -4,6 +4,7 @@
  * See `packages/examples/LICENSE.md` for full license + asset credits.
  */
 import {
+	Application,
 	Color,
 	ColorLayer,
 	Container,
@@ -204,12 +205,13 @@ class PlayScreen extends Stage {
 	}
 }
 
-const createGame = () => {
-	video.init(760, 320, {
+const createGame = async () => {
+	const app = new Application(760, 320, {
 		parent: "screen",
 		scaleMethod: "flex",
 		renderer: video.AUTO,
 	});
+	await app.init();
 
 	state.set(state.PLAY, new PlayScreen());
 	state.change(state.PLAY);