Melonjs Getting Started Agent Skill

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

The bootstrap needs await at module scope. In an ES module that is fine. If the

surrounding tooling does not allow it, wrap it:

async function main() {
    const app = new Application(800, 600, { parent: "screen" });
    await app.init();
    // …
}
void main();

Choosing a renderer

video.AUTO (the default) tries WebGPU → WebGL 2 → Canvas and uses the first

that works.

import { video } from "melonjs";

const app = new Application(800, 600, {
    parent: "screen",
    renderer: video.AUTO,      // default; or video.WEBGPU / video.WEBGL / video.CANVAS
});

Two consequences worth knowing before writing rendering code:

• Which backend you get is a runtime fact, not a build-time one. The same

code runs on a different renderer depending on the machine. Do not assume

WebGL.

• Not every feature exists on every backend. Shader effects and post effects

need a programmable pipeline and are inert on Canvas. Where a feature degrades,

the engine warns once rather than throwing — so a missing effect is a console

warning, not a crash.

Pin the renderer explicitly (video.WEBGL) only when you have a reason to. It

costs you the WebGPU path and the Canvas fallback.

The scene graph

app.world is the root Container. Everything drawn is a descendant of it.

app.world.addChild(sprite, 10);   // 10 is the z / draw order

Pass the z-order as the second argument to addChild — it is the only form

that works. renderable.z does not exist as a property, setting depth before

addChild is overwritten by autoDepth, and setting it afterwards does not

resort. See the melonjs-renderables skill for the full explanation.

Scenes

For anything beyond a single screen, use Stage subclasses and the state

manager rather than mutating app.world directly:

import { Stage, state } from "melonjs";

class PlayScreen extends Stage {
    onResetEvent() { /* build the scene */ }
    onDestroyEvent() { /* tear it down */ }
}

state.set(state.PLAY, new PlayScreen());
state.change(state.PLAY);

onResetEvent runs every time the state is entered, not once — build scene

content there, not in the constructor.

Loading assets

Assets are declared and preloaded through loader; audio needs audio.init()

with the formats you ship before any audio asset is preloaded.

import { audio, loader } from "melonjs";

loader.setOptions({ crossOrigin: "anonymous" });   // needed for remote assets
audio.init("mp3,ogg");                             // BEFORE preloading audio
await loader.preload([
    { name: "tileset", type: "image", src: "data/img/tileset.png" },
    { name: "jump",    type: "audio", src: "data/sfx/" },   // directory, not file
]);

Two ordering rules that produce confusing failures when missed:

• audio.init() must run before any audio asset is preloaded, and names the

formats you actually ship. Preloading first throws *"target audio extension(s)

should be set through me.audio.init() before calling the preloader"*.

• The audio src is a directory, not a file. The loader appends the asset

name plus each configured extension, so a full filename gives you a 404.

anchorPoint defaults to the centre

Renderable.anchorPoint is (0.5, 0.5), so pos is an object's centre, not

its top-left. Container forces (0, 0) instead.

Writing top-left math against a centred anchor puts everything half a sprite off

with no error — it is the most common source of "close but subtly wrong"

placement.

Common mistakes

| symptom | cause |

|---|---|

| blank page, nothing drawn, or a TypeError reading renderer from new Sprite / new Text | missing await app.init() |

| objects draw in the wrong order | .z/depth set instead of addChild(child, z) — .z is not even a real property |

| shader/post effect does nothing, warning in console | running on the Canvas renderer |

| audio 404s | audio asset src given as a file rather than a directory |

| scene content appears once and never resets | scene built in the constructor instead of onResetEvent |

| everything offset by half a sprite | top-left math against the centred anchorPoint default |

| a Tween or ParticleEmitter does nothing | .start() / streamParticles() never called |

| cross-origin textures fail to load | missing loader.setOptions({ crossOrigin: "anonymous" }) |

Related skills

• melonjs-20-migration — what changed in 20.x that older code and older

training data get wrong

• melonjs-renderables — custom Renderable subclasses, pointer events, post

effects and the traps in each