melonJS 2

A modern & lightweight HTML5 game engine

melonJS is an open-source 2D game engine designed for indie developers — post-processing effects, custom shaders, 3D mesh support, polygon-accurate physics, modern Tiled workflows, and high performance, all packed into just over 100 KB minzipped of vanilla JS/TS with no toolchain lock-in. Built with ES6 classes and bundled with esbuild.

melonJS is licensed under the MIT License and actively maintained by the team 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
• 3D mesh rendering with OBJ/MTL model loading, perspective projection and hardware depth testing
• Built-in shader effects (Flash, Outline, Glow, Dissolve, CRT, Hologram, etc.) with multi-pass chaining via postEffects, plus custom shader support via ShaderEffect for per-sprite fragment effects (WebGL)
• Trail renderable for fading, tapering ribbons behind moving objects (speed lines, sword slashes, magic trails)
• System & Bitmap Text with built-in typewriter effect
• 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, flash, and mask-based transition effects
• Per-camera post-processing pipeline with stackable shader effects and color grading (ColorMatrix)

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

• Application class as the modern entry point with built-in pause, resume, and freeze() (hit-stop) primitives
• 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)
• 3D Mesh (source)
• 3D Mesh Material (source)
• Trail (source)
• Shader Effects (source)
• Spine (source)

Browse all examples here

---

Basic Hello World Example

import { Application, Text } from "https://cdn.jsdelivr.net/npm/melonjs/+esm";

// create a new melonJS application
const app = new Application(1218, 562, {
    parent: "screen",
    scale: "auto",
    backgroundColor: "#202020",
});

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

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

Simple hello world using melonJS

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 what you need in your project :

import { Application, Sprite, loader } from 'melonjs';

Or use it directly via jsDelivr CDN :

<!-- load the ES6 module bundle of melonJS v19.x -->
<script type="module" src="https://cdn.jsdelivr.net/npm/melonjs@19/+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 !