Getting started with melonJS

Bootstrapping a melonJS 20.x game: the Application lifecycle, the mandatory await app.init(), the world container, and what the renderer fallback means for feature availability.

Applies to: melonJS 20.x. Older major versions differ, see the melonjs-20-migration skill.

The bootstrap

Application construction is synchronous but initialisation is not. init() returns a promise and must be awaited before building any renderable, loading assets, or entering a scene.

import { Application, Text } from "melonjs";

const app = new Application(1218, 562, {
    parent: "screen",      // id of the DOM element to mount into
    scale: "auto",
    backgroundColor: "#202020",
});
await app.init();          // ← REQUIRED. Nothing below works without it.

app.world.addChild(
    new Text(609, 281, {
        font: "Arial",
        size: 160,
        fillStyle: "#FFFFFF",
        textAlign: "center",
        textBaseline: "middle",
        text: "Hello World !",
    }),
);

This is the single most common thing to get wrong. On 19.x the constructor called init(width, height, options) for you; on 20.x init() takes no arguments and calling, and awaiting, it is your job. Nothing that follows names the missing call. The constructor does build app.world, so adding a plain renderable succeeds and simply never draws, no canvas is appended and the app never subscribes to the frame tick, while constructing a Sprite or a Text throws Cannot read properties of undefined (reading 'renderer'), because the global game those two fall back on is only set once the first init() resolves. Either way app.renderer and app.viewport stay undefined and the page stays blank.

init() is asynchronous because acquiring a WebGPU device is asynchronous. There is no synchronous alternative.

Top-level await