melonJS 2

A modern & lightweight HTML5 game engine

melonJS is an open-source HTML5 game engine that empowers developers to create 2D games using modern JavaScript and TypeScript. Built with ES6 classes and bundled using esbuild, it provides tree-shaking support for optimal bundle sizes.

melonJS is licensed under the MIT License and actively maintained with the help of a small team of enthusiasts at AltByte in Singapore.

Why melonJS

melonJS is designed so you can focus on making games, not on graphics plumbing.

• Canvas2D-inspired rendering API — If you've used the HTML5 Canvas, you already know melonJS. The rendering API (save, restore, translate, rotate, setColor, fillRect, ...) follows the same familiar patterns — no render graphs, no shader pipelines, no instruction sets to learn.

• True renderer abstraction — Write your game once, run it on WebGL or Canvas2D with zero code changes. The engine handles all GPU complexity behind a unified API, with automatic fallback when WebGL is not available. Designed to support future backends (WebGPU) without touching game code.

• Complete engine, minimal footprint — Physics, tilemaps, audio, input, cameras, tweens, particles, UI — a full 2D game stack in a single tree-shakeable ES module. No dependency sprawl, no library stitching.

• Tiled as a first-class citizen — Deep Tiled integration built into the core: orthogonal, isometric, hexagonal and staggered maps, animated tilesets, collision shapes, object properties, compressed formats — all parsed and rendered natively.

• Batteries included, hackable by design — Get started in minutes with minimal setup. When you need to go deeper: ES6 classes throughout, a plugin system for engine extensions, and a clean architecture that's easy to extend without fighting the framework.

About melonJS

melonJS is a fully featured game engine :

Compatibility

• Standalone library (does not rely on anything else, except a HTML5 capable browser)
• Compatible with all major browsers (Chrome, Safari, Firefox, Opera, Edge) and mobile devices

Graphics

• 2D sprite-based graphic engine
• Fast WebGL renderer for desktop and mobile devices with fallback to Canvas rendering
• Extensible batcher system for custom rendering pipelines
• High DPI resolution & Canvas advanced auto scaling
• Sprite with 9-slice scaling option, and animation management
• Built-in effects such as tinting, masking and 2D lighting
• Standard spritesheet, single and multiple Packed Textures support
• Compressed texture support (DDS, KTX, KTX2, PVR, PKM) with automatic format detection and fallback
• System & Bitmap Text
• Video sprite playback

Sound

• Web Audio support with 3D spatial audio and stereo panning based on Howler

Physics

• Polygon (SAT) based collision algorithm for accurate detection and response
• Fast Broad-phase collision detection using spatial partitioning (QuadTree)
• Collision filtering for optimized automatic collision detection
• Multiple shapes per body for complex hitboxes

Input

• Mouse and Touch device support (with mouse emulation)
• Gamepad support with button and axes binding
• Keyboard event handling with key binding system
• Device motion & accelerometer support

Camera

• Multi-camera support (split-screen, minimaps, multiple viewports)
• Camera follow with configurable deadzone and damping
• Built-in shake, fade and flash effects

UI

• Clickable, hoverable and draggable UI elements
• Drag-and-drop support
• Text buttons with built-in styling

Level Editor

• Tiled map format up to 1.12 built-in support for easy level design
  • Uncompressed and compressed Plain, Base64, CSV and JSON encoded XML tilemap loading
  • Orthogonal, Isometric, Hexagonal (both normal and staggered) and Oblique maps
  • Multiple layers (multiple background/foreground, collision and Image layers)
  • Parallax scrolling via Image layers
  • Animated and multiple Tileset support
  • Tileset transparency settings
  • Layers alpha and tinting settings
  • Rectangle, Ellipse, Polygon and Polyline objects support
  • Tiled Objects with custom properties
  • Flipped & rotated Tiles
  • Dynamic Layer and Object/Group ordering
  • Dynamic Entity loading
  • Shape based Tile collision support

Assets

• Asynchronous asset loading with progress tracking
• A fully customizable preloader
• Support for images, JSON, TMX/TSX, audio, video, binary and fonts

Core

• A state manager (to easily manage loading, menu, options, in-game state)
• Tween effects with multiple easing functions (Quadratic, Cubic, Elastic, Bounce, etc.) and Bezier/Catmull-Rom interpolation
• Transition effects
• Pooling support for object recycling
• Basic Particle System
• EventEmitter based event system
• Persistent data storage (save/load via localStorage)
• Plugin system for extending engine capabilities

Tools integration

melonJS is supporting the below tools and frameworks natively or through our official plugin(s) :

Tools integration and usage with melonJS is documented in our Wiki.

Getting Started

The fastest way to create a new game:

npm create melonjs my-game
cd my-game
npm install
npm run dev

This scaffolds a ready-to-run project with TypeScript, Vite, and the debug plugin. It also works with plain JavaScript — just rename .ts files to .js.

You can also start from the boilerplate directly, or follow the step-by-step Platformer Tutorial.

For more details, check the wiki Details & Usage guide.

Examples

• Platformer (source)
• Isometric RPG (source)
• SVG Shapes (source)
• Graphics (source)
• Hello World (source)
• Whac-A-Mole (source)
• Compressed Textures (source)
• Spine (source)

Browse all examples here

Basic Hello World Example

import * as me from "https://cdn.jsdelivr.net/npm/melonjs/+esm";

me.device.onReady(function () {
    // initialize the display canvas once the device/browser is ready
    if (!me.video.init(1218, 562, {parent : "screen", scale : "auto"})) {
        alert("Your browser does not support HTML5 canvas.");
        return;
    }

    // set a gray background color
    me.game.world.backgroundColor.parseCSS("#202020");

    // add a font text display object
    me.game.world.addChild(new me.Text(609, 281, {
        font: "Arial",
        size: 160,
        fillStyle: "#FFFFFF",
        textBaseline : "middle",
        textAlign : "center",
        text : "Hello World !"
    }));
});

Simple hello world using melonJS 2

Documentation

• Online API

Plugins

melonJS provides a plugin system allowing to extend the engine capabilities.

Here is the list of official plugins maintained by the melonJS team:

• debug-plugin - a debug panel for inspecting game objects
• tiled-inflate-plugin - enable loading and parsing of zlib, gzip and zstd compressed Tiled maps
• spine-plugin - Spine runtime integration to render Spine skeletal animations

If you wish to develop your own plugin, we also provide a plugin template to help you get started.

Installation

melonJS is distributed as a tree-shakeable ES6 module with TypeScript declarations included.

Install via npm :

npm install melonjs

Then import it in your project :

import * as me from 'melonjs';

Or use it directly via jsDelivr CDN :

<!-- load the ES6 module bundle of melonJS v18.x -->
<script type="module" src="https://cdn.jsdelivr.net/npm/melonjs@18/+esm"></script>
<!-- omit the version completely to get the latest one -->
<!-- you should NOT use this in production -->
<script type="module" src="https://cdn.jsdelivr.net/npm/melonjs/+esm"></script>

Note: the debug plugin is available separately as @melonjs/debug-plugin

Community

Join us and get help or share your projects :

• Discord
• Wiki
• FAQ

Contributing

We welcome contributions! Please read our Contributing Guide before submitting changes or new features.

Sponsors

Support the development of melonJS by becoming a sponsor. Get your logo in our README with a link to your site or become a backer and get your name in the BACKERS list. Any level of support is really appreciated and goes a long way !