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

Skill	Load when…
melonjs-getting-started	Bootstrapping a game, new Application, await app.init(), choosing a renderer, preloading assets.
melonjs-20-migration	Code based on melonJS 19.x or earlier, or an API that "should exist" but doesn't — video.init, Entity, renderable.shader =.
melonjs-scenes-and-state	Stage subclasses, the state manager, transitions, pausing, the update loop, timers, tweens, saved data.
melonjs-renderables	Subclassing Renderable, custom draw(), draw order, anchors, floating, post effects on an object.
melonjs-sprites-and-animation	Sprite, frame animation, texture atlases (TexturePacker / Aseprite / ShoeBox), tint, flip, pooling.
melonjs-input	Keyboard actions, pointer and touch handling, drag, gamepad, virtual controls.
melonjs-physics	Collision, bodies, movement, spatial queries, and the planck / matter adapters.
melonjs-math	Vectors and matrices: what mutates, what allocates, and interpolating with lerp, slerp, damp or moveTowards.
melonjs-tilemaps	Tiled maps — TMX/TSX loading, spawning entities from objects, collision layers, isometric maps.
melonjs-audio	Sound effects, music, audio sprites, spatial audio, procedural tone and noise.
melonjs-effects-and-shaders	Post effects, custom GLSL/WGSL shaders, blend modes, colour grading, screen capture.
melonjs-3d	Anything 3D or 2.5D — Camera3d, meshes, instancing, Sprite3d billboards, Light3d, distance fog, glTF scenes.
melonjs-3d-assets	Loading glTF/GLB or OBJ models — materials, imported lights, instancing, and what is not supported.
melonjs-camera-and-drawing	Camera follow, bounds, shake and fade, coordinate conversion, and immediate-mode shape drawing.
melonjs-ui-and-text	HUDs, buttons, menus, drag-and-drop, Text and BitmapText, web fonts, panels.
melonjs-particles-and-trails	ParticleEmitter, burst versus stream, referenceSpace, and the Trail renderable.
melonjs-lighting	2D dynamic lighting — Light2d, stage ambient, normal-mapped sprites.
melonjs-deployment	Scaffolding a project, building, browser support and transpiling, native and mini-game platforms.
melonjs-loading-assets	Resource descriptors, the asset type list, base URLs, cross-origin, progress events, unloading.
melonjs-renderer-backends	A feature works on one machine but not another; choosing or pinning a backend; degrading gracefully.
melonjs-display-and-scaling	Blurry, soft or cropped output; the design resolution, how the canvas fills its page, and pixel-perfect integer scaling.
melonjs-events	The event bus, per-frame and lifecycle events, and subscribing without leaking.
melonjs-performance	Dropped frames, draw-call counts, pooling, batching, culling, baking, profiling.
melonjs-plugins	Registering the debug, Spine or Tiled-inflate plugins, physics adapters, or writing your own plugin.

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.

Package	Use when
@melonjs/planck-adapter	You want full rigid-body dynamics — stacking, joints, realistic restitution. Pass it as the Application's physic setting; the portable raycast and queryAABB calls work unchanged across adapters (querySphere and raycast3d are built-in-adapter only).
@melonjs/matter-adapter	Same, backed by matter-js. Choose one adapter per game.
@melonjs/tiled-inflate-plugin	Required to load gzip-, zlib- or zstd-compressed Tiled maps. Without it, parsing such a map throws No inflate function set.
@melonjs/spine-plugin	Skeletal animation authored in Spine, as a melonJS renderable.
@melonjs/debug-plugin	An in-game debug panel — FPS, draw counts, collision-shape and bounds overlays. Register it after app.init().
@melonjs/capacitor-plugin	Wrapping a game as a native iOS/Android app: it bridges Capacitor's lifecycle — pause/resume, the hardware back button, orientation lock, splash screen.
create-melonjs	Scaffolding a new project — start here rather than assembling a build by hand.

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.