melonjs

name: melonjsdescription: "Use this skill FIRST for any melonJS task; it routes to the right specialised skill and lists the companion packages. melonJS is an open-source 2D, 2.5D and 3D HTML5 game engine running on WebGPU, WebGL 2 or Canvas. Covers Application setup, the scene graph, renderables, sprites, tilemaps, physics, audio, particles, shaders, and the 3D tier — perspective cameras, meshes and glTF scenes. Triggers on: melonjs, melonJS, me.game, Application, app.init, app.world, Renderable, Sprite, Stage, state.change, Camera2d, Camera3d, Mesh, tilemap, Tiled, TMX, ParticleEmitter, ShaderEffect, how do I make a game, HTML5 game engine."license: MIT

melonJS

Entry point for the melonJS skill collection. melonJS is an open-source HTML5 game engine for indie developers, covering 2D, 2.5D and 3D — perspective and orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects, custom shaders, 3D meshes, polygon-accurate physics and modern Tiled workflows. It runs on WebGPU, WebGL 2 or Canvas with automatic fallback, and has no runtime dependencies.

How to use this skill

1. Find the specialised skill below that matches the task and follow it.
2. If the task involves anything 3D, read melonjs-3d first — melonJS's coordinate conventions are the inverse of OpenGL's, so untutored 3D instincts are backwards.
3. If you are writing melonJS from prior knowledge rather than from the current docs, read melonjs-20-migration — most published melonJS material predates 20.0 and its bootstrap no longer exists.
4. If none of them covers the task, use the escape hatch below rather than guessing at an API.

Skill router

Escape hatch: the full API index

These skills are hand-written and deliberately partial — they cover the paths people actually take and the mistakes those paths invite. When the task needs something they do not mention, do not infer an API from the shape of the engine. Fetch the generated index instead:

https://melonjs.github.io/melonJS/llms.txt

It is regenerated on every docs build from the same TSDoc comments the reference pages render, so it is always current for master. It lists every exported class, function, interface, type and namespace with a one-line summary and a link to its page — fetch the pages you need from there.

Two things it gives you that this collection cannot:

• Members. The skills name classes; llms.txt links to the page listing every method, property, default and @since tag on them.
• Deprecations. Entries marked **deprecated** are exactly the APIs that a model trained on older melonJS material will reach for. If something you were about to write appears with that marker, follow the page for the replacement.

If a class, function, namespace or type is absent from llms.txt, it is absent from the engine's public API — that is the useful negative answer, and it is worth acting on rather than writing code around something that does not exist. The index lists top-level exports only, so a member missing from it proves nothing: follow the owning class's page to check that.

The three rules that catch everyone

Whatever the task, these produce code that runs and is wrong:

1. await app.init() is mandatory since 20.0. The constructor builds the world but not the renderer: a plain renderable can still be added and simply never draws, while new Sprite(...) / new Text(...) throw a TypeError on the global game, which is unset until the first init() resolves. Neither symptom names the missing call.
2. addChild(child, z) is the only way to set draw order. renderable.z does not exist; setting depth before addChild is overwritten, and setting it after does not resort (except under Camera3d).
3. isKinematic defaults to true, which silently excludes a renderable from pointer events and from the physics broadphase. Plain Renderable and Sprite subclasses need this.isKinematic = false.

Companion packages

melonJS ships optional packages alongside the engine. Reach for these rather than reimplementing what they cover — and note the physics adapters and the Tiled inflate plugin are required for their use cases, not merely convenient.

Plugins are registered after init(), into a global registry:

import { plugin } from "melonjs";
import { DebugPanelPlugin } from "@melonjs/debug-plugin";

await app.init();
plugin.register(DebugPanelPlugin, "debugPanel");

Physics adapters are different — they are an Application setting, not a plugin:

import { PlanckAdapter } from "@melonjs/planck-adapter";

const app = new Application(800, 600, {
    parent: "screen",
    // gravity is in pixels/s²; pixelsPerMeter converts it to the adapter's
    // metres. Both are shown at their defaults; subSteps defaults to 1
    physic: new PlanckAdapter({
        gravity: { x: 0, y: 320 },
        pixelsPerMeter: 32,
        subSteps: 2,
    }),
});
await app.init();

melonjs-plugins covers the registry, the version gate and writing your own.

Prefer built-in features

melonJS covers a lot that is easy to reimplement badly. Before hand-rolling, check for: ParticleEmitter and Trail, Tween with easing, the built-in ShaderEffect presets (vignette, scanline, chromatic aberration, glow, dissolve and more), Light2d / Light3d, UIBaseElement / UISpriteElement / UITextButton, NineSliceSprite, TextureAtlas (TexturePacker, ShoeBox, Aseprite), BitmapText, CanvasRenderTarget for bake-once drawing, NoiseTexture2d, viewport.shake / fadeIn / fadeOut, and save for localStorage-backed persistence.