melonJS 2

A modern & lightweight HTML5 game engine

melonJS is an open-source 2.5D game engine designed for indie developers — perspective and orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects, custom shaders, 3D mesh support, polygon-accurate physics, modern Tiled workflows, and high performance. Runs on WebGL or Canvas2D with automatic fallback, tree-shakeable so you only pay for what you use, and the entire engine fits in ~150 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 game stack in a single tree-shakeable ES module. No dependency sprawl, no library stitching.

• Scenes, loaded in one call — level.load(name) brings an authored scene straight into your world. Tiled is a first-class citizen for 2D — orthogonal, isometric, hexagonal & staggered maps, animated tilesets, collision shapes, object properties, compressed formats, with GPU-accelerated tile rendering under WebGL 2 — and glTF / GLB is the equivalent for 3D scenes: author in Blender (or any DCC tool), export a .glb, and the whole scene — meshes, materials, cameras, lights, and node animation — loads under a Camera3d, no per-mesh wiring. Animated models play back through the same animation API as a 2D Sprite.

• 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 - 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 frame animation - Built-in effects such as tinting, masking, and CSS-style blend modes (normal, additive, multiply, screen, darken, lighten) - 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, multi-material support, hardware depth testing, and perspective projection via Camera3d — ~30% faster mesh rendering with near-zero per-frame allocation (a re-drawn static mesh produces no GC garbage) - Lighting, in 2D and 3D: - 2D — Light2d as a first-class Renderable (multiple dynamic lights, radial-gradient falloff, illumination-only mode, procedural rendering via drawLight), plus optional per-pixel normal-map shading on sprites for 3D-looking dynamic lights - 3D — Light3d directional + ambient lights, added to the world like Light2d (half-Lambert diffuse + ambient fill, runtime-manipulable for day/night), auto-loaded from a glTF scene's authored sun - 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 - Built-in procedural audio primitives (envelope-shaped oscillators, white/pink/brown noise) for SFX without sample assets - Direct AudioContext / master-gain accessors for custom WebAudio graphs that mix with the engine's master volume / mute

Physics - Polygon (SAT) based collision algorithm for accurate detection and response - Fast broad-phase collision detection using spatial partitioning (QuadTree in 2D, Octree in 3D, swapped automatically) - Raycast, AABB and sphere region queries with precise entry geometry, including 3D raycasts (raycast3d) - Collision lifecycle hooks on every Renderable - Collision filtering for optimized automatic collision detection - Multiple shapes per body for complex hitboxes - Pluggable PhysicsAdapter interface for custom physics via official adapters

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) - Optional perspective camera (Camera3d) with frustum culling for 2.5D / 3D-projected scenes — drop-in subclass of the default 2D camera - Camera follow with configurable deadzone and frame-rate-independent 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 - UIBaseElement / UISpriteElement containers for clickable, hoverable and holdable elements with full pointer-event wiring - Draggable / DropTarget for drag-and-drop with configurable overlap or contains-check - UITextButton text button with hover, press, and key-bind support — built on BitmapText

Scenes - Load a scene in one call with level.load(name) — 2D Tiled maps and 3D glTF scenes alike, auto-registered on preload - Tiled map format up to 1.12 built-in support for easy level design - GPU-accelerated tile rendering for orthogonal maps under WebGL 2 — each layer draws as a single quad with no per-tile loop, ~5–8× faster than the legacy CPU renderer on dense maps. Honors animated tiles, flip bits, per-layer opacity/tint/blend, and oversized bottom-aligned tiles; falls back transparently to the CPU renderer on isometric/staggered/hexagonal layers or non-WebGL-2 contexts - Uncompressed and compressed Plain, Base64, CSV and JSON encoded XML tilemap loading - Orthogonal, Isometric, Hexagonal (both normal and staggered) and Oblique maps - Multiple layers with per-layer alpha, tinting and blend modes (multiple background/foreground, collision and Image layers) - Parallax scrolling via Image layers, with parallax origin support - Animated and multiple Tileset support, tile sub-rectangles, embedded base64 images - Native .aseprite / .ase tileset images (Tiled 1.11+ qaseprite plugin workflow), with frame tags auto-mapped to per-tile animations — no PNG export step required - Tileset transparency settings - Rectangle, Ellipse, Polygon, Polyline and Capsule (round-rect) object shapes - Tiled Objects with custom properties (string, number, boolean, color, file, object, list/array and class-typed) - Per-object opacity and visibility - Concave collision polygons auto-decomposed via earcut triangulation - Flipped & rotated Tiles - Dynamic Layer and Object/Group ordering - Dynamic Entity loading via an extensible object factory registry — register custom handlers for any Tiled class name without modifying engine code - Shape based Tile collision support - glTF / GLB 3D scenes — load an authored 3D scene with level.load(...), the same one call as a Tiled map - The whole scene loads at once — meshes, materials, cameras and lights — viewed under a Camera3d - Automatically lit by the scene's directional lights (the sun set up in the authoring tool) - Textured, solid-colored, and vertex-colored materials - Node animation — walk/idle/sprint characters, spinning pickups, doors, lifts — played through the same setCurrentAnimation / play / pause / stop API as a 2D Sprite - .glb and .gltf files, with embedded or external buffers & textures - Works with any glTF authoring tool (Blender, Maya, 3ds Max, Cinema 4D, …)

Assets - Asynchronous asset loading with progress tracking - A fully customizable preloader - Support for images, JSON, TMX/TSX, glTF / GLB 3D scenes, .aseprite / .ase binary, 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 - Particle system with ParticleEmitter (emission rate, lifetime, velocity, gravity, blend modes) - 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]