melonjs / melonjs

a fresh, modern & lightweight HTML5 game engine

melonJS 2

A fresh, modern & lightweight HTML5 game engine

melonJS 2 is a modern version of the melonJS game engine that was first released in 2011. It has been rebuilt entirely using ES6 class, inheritance and semantic, and bundled using Rollup to provide modern features such as transpiling and tree-shaking.

Note: migrating an existing project to melonJS 2 (version 10.0 and higher) will definitely break your game (ES6 semantic and inheritance, nodeJS event emitter, and no backward compatibility with deprecated legacy APIs), and you might want to read first this small step by step guide on upgrading to melonJS 2. If you are looking at the legacy version (9.x and lower) of melonJS, you can find it here under the legacy branch.

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

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
• Blazing Fast WebGL renderer for desktop and mobile devices with fallback to Canvas rendering
• High DPI resolution & Canvas advanced auto scaling
• Sprite with 9-slice scaling option, and animation management
• built-in effects such as tinting and masking
• Standard spritesheet, single and multiple Packed Textures support
• System & Bitmap Text

Sound

• Web Audio support with 3D spatial audio or stereo panning based on Howler
• fallback to Multi-channel HTML5 audio for legacy browsers

Physic

• Polygon (SAT) based collision algorithm for accurate detection and response
• Fast Broad-phase collision detection using spatial partitioning
• Collision filtering for optimized automatic collision detection

Input

• Mouse and Touch device support (with mouse emulation)
• Device motion & accelerometer support

Level Editor

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

Assets

• Asynchronous asset loading
• A fully customizable preloader

And Also

• A state manager (to easily manage loading, menu, options, in-game state)
• Tween Effects, Transition effects
• Pooling support for object recycling
• Basic Particle System
• nodeJS EventEmitter based event system

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.

Using melonJS

For your first time using melonJS, this is where you start

• melonJS: Hacking a Platformer Game

You may find it useful to skim the overview found at the wiki Details & Usage

When starting your own projects, checkout our ES6 x Vite boilerplate or the TypeScript x Vite boilerplate

Demos

A few demos of melonJS capabilities :

• Platformer Demo (source)
• Isometric Demo (source)
• Sprite Demo (source)
• Masking Demo (source) (WARNING: may potentially trigger seizures for people with photosensitive epilepsy)
• Primitive Drawing Demo (source)
• UI Demo (source)
• Tiled Map Loader Demo (source)
• Video Demo (source)

More examples are available here

---

Basic Hello World Example

import * as me from "https://esm.run/melonjs";

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 (version 10.x or higher)

Documentation

• Online API

To enable an offline version of the documentation, navigate to the settings page and enable offline storage:

Plugins

melonJS provide 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 and gzip 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.

Download melonJS

The latest builds with corresponding release note are available for direct download here.

melonJS 2 now only provides an ES6 Bundle :

build	description
melonjs.module.js	the ES6 Module (ESM) Bundle
melonjs.mjs	a tree-shakeable ES6 Module Directory
types/index.d.ts	typescript declaration files for the ES6 Module (ESM) Bundle

Note: if you need your application to be compatible with ES5, refer to our boilerplate that provides automatic transpiling to ES5.

The latest version of melonJS can be installed through NPM :

$ npm install melonjs

And then import melonjs in your project using :

$ import * as me from 'melonjs';

Or it can simply be added to your html, using jsDeliver content delivery network (CDN) :

<!-- load the ES6 module bundle of melonJS v10.0 -->
<script type="module" src="https://esm.run/[email protected]"></script>
<!-- omit the version completely to get the latest one -->
<!-- you should NOT use this in production -->
<script type="module" src="https://esm.run/melonjs"></script>

Note: starting from the 10.0.0 version, the debug plugin is no longer provided as part of the melonJS library release, and has been moved to the official boilerplate

Contributing

For most users, all you probably want is to use melonJS, and all you need then is just to download the latest built release to get started.

If you want to start to be part and contribute to the project, make sure to read our Contributing Guide before starting submitting changes or new features.

Contributors

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 !

melonjs's Issues

maps, which do not fill the screen

Hi,

Currently (0.9.2) melonJS handles maps, which do not fill the screen, by filling
the screen with the maps background color and not rendering any tiles at all.

I think these maps should be rendered centered instead. They are useful for
small rooms in RPGs.

But please output at least an error message, e.g.:

melonJS only supports screen filling maps

-- Sebastian

Add a particle management system

Would be nice to have this built-in in the engine directly !

Add JSLint into the build process for better code quality control

Although, maybe this is already fully done by the closure compiler ? ... to be investigated.

Multi Line Animation

again me :)

I haven't seen any complain but I wonder why you don't take care of multiline animation in the default constructor of course it's easy to do it in the extended part but for me it make sense to implement it diretly inside me.SpriteObject.init

i the init part :
// #sprite per row
this.spritecount = ~~(this.image.width / this.width);
if (this.image.height > this.height)
this.spritecount += this.spritecount * ((this.image.height / this.height)-1);

and in addAnimation something like that (code not tested !!):
if (frame == null) {
// by default create an animation with all sprites from row #0
for ( var i = 0; i < this.spritecount; i++) {
// compute and add the offset of each frame

                        nbpLine = this.image.width / this.width;                            
                        line = Math.floor(i / nbpLine);
                        col = Math.floor((i - line*(nbpLine))) * this.width;
                        line = line * this.height;

                        this.anim[name].frame[i] = new me.Vector2d(col, line);
                    }

Thanks for your feedback

Key events for mobile devices

Hello Olivier, thank you very much for your library, it is awsome.

Right now i am doing a game with your library, and it is intended for mobile devices, just a demo, to show that with your library can do.

Well the thing is, to simplify things, for moovement i add some arrows, and each one fires an "click" event, and inside each, i create a new event, and trigger it. The problem is that my player does not move. The event is triggered, so i think that you are using other attribute that jQuery does not write. jQuery write a normalize event, but i can add you atrributes from the "Original Event".

The question, which attribute did you watch to detect a key event?

Thanks in advance.

P.D.
The code i am using to trigger the event

$('#arrow').click(function() {
var e = jQuery.Event('keydown', {
which : 88,
keyCode : 88,
charCode : 0
});
$(document).trigger(e);
console.info('e: ', e);
});

inheritance / composition

First Im really not familliar with javascript, got several years of object modeling and C++ dev, but I'm a complete beginner in js... So excuse me if I'm completly out of bound...

Looking at your inheritance model, I feel like there are some oddities :
For example ObjectEntity extends AnimationSheet extends AnimatedSpriteObject extends SpriteObject extends Rect extends Object

I thinkk it should be something like that :
ObjectEntity is composed with AnimatedSpriteobject and entity related data
AnimatedSpriteobject extends SpriteObect and is composed with AnimationSheet
SpriteObject extends Rect
Rect extends Object

That may just sound like purist gibberish though...

Add "removeItem(name)" to me.game.HUD Object

Add "removeItem(name)" to me.game.HUD Object

[isometric] - Object position not correctly handled

In an isometric mode, the position x:0, y:0 corresponds to the first tile, which is at the top of the diamond. However, when assigning my player at this position using Tiled, melonJS places the player at the screen coordinates 0:0.

I've just started playing with Melon and Isometric stuff, so I don't know to which extend the whole coordinate system as to be changed to support isometric types of worlds. I would be happy to work on a patch for this, but have no clue where to start looking and what would be the best way to fix it. Let me know if you are actively working on isometric

Create a document to explain coding standards

In order to have every contributors to comply to the same coding conventions, it would be interesting to have a small document explaining the conversions already in use (indentation realized with tab char, no tab char inside comments, and so on).

Rewrite mouse event management

And make it fit with the me.input object

Map Size Question

Is there a limit to how large you can make your maps? Every time i try and make a map larger than about 750 sqares (25x30, 15x50, etc) it stops loading the tiles into the game. any suggestions or am i just missing a setting in my browser or something?

Level-related memory issues

1. Previous levels stay loaded in memory even when new levels are loaded - there should be an option to unload old levels, as when loading a series of large levels, the browser may potentially run out of memory and crash. (Check my fork for a quick hack that fixes this - it just deletes the previous level when a new one is loaded)

2. Large memory use of single levels in general - a level of size 400x60 for example tends to crash the browser just by itself (both firefox & chrome on a machine with 4GB memory). Could this be optimized at all?

Support for multiple tilesets

Support for multiple tileset as supported by the Tiled level editor. As of today, melonJS is only working with one graphic Tileset and one collision Tileset.

res.obj is undefined issue

I found that when I load my next level in my game. FireFox will throw a "res.obj is undefined error". The error is referencing to this code:

if (res) {
// if we collide with an enemy
if (res.obj.type == me.game.ENEMY_OBJECT) {
// check if we jumped on it
if ((res.y > 0) && ! this.jumping) {
// bounce
me.audio.play("stomp");
this.forceJump();
} else {
// let's flicker in case we touched an enemy
this.flicker(45);
}
}
}

When it throws this error it will still load the next level. I have found that by deleting out the ".obj" in the "res.obj.type" the error goes away. I just wanted to post this solution in case other people were getting the same error and were trying to resolve it. After implementing this in my code, I have not noticed any issues caused by the deletion of ".obj".

flicker broken when using requestAnimationFrame

I just realized that objects are disappearing instead of flickering when enabling requestAnimationFrame (through me.sys.useNativeAnimFrame).

Tested only under Chrome 16 as I don't have yet any other browser that support this feature.

Dirty Rectangle mechanism

This is actually in progress :)

BitmapFont ignores 'center' alignment

BitmapFont only takes into account the 'right' alignment setting. Setting 'center' shows the same behavior as left alignment.

I have created a patch for this fix that I will be emailing to the maintainer. (Unless there is a better submission process. Gerritt?)

support for screen autoresize

Implement graphics auto-resize in melonJS, and use the browser resize event, to create (full)screen size independent games.

Draw Manager dirty object bug (?)

I'm not sure about this but can you clarify the logic in drawManager's api.draw() function (core.js:847)

It loops through all dirty rectangles and, within each rectangle, draws each dirty object.

I think it should draw all objects in each dirty rectangle, whether dirty or not.

I was trying to make a game where you switch between two characters. When switching it didn't show the active character until a movement key was pressed. I guess this might also happen if an entity moved in front of another 'passive' entity ( I haven't tested that). A lot of the entities are animated because of their sprite sheets so they are updated every frame anyway.

Hope this is clear, I probably have missed something but I couldn't quite understand how it all worked.

input Mouse bug

Hello,

It seem that the mouse event registar don't take care of the viewport :

if you have a viewport at 0:0 and an object register like that :
me.input.registerMouseEvent('mousemove', this.collisionBox, changeMouse.bind(this));

the function changemouse is launched.

but if the viewport move the mousemove is not detected anymore.

version used : Git

Support for Multiple Tilesets... Implemented?

I noticed in your closed section you have "support for multiple tilesets" responded to as "done". Is this in the current build that you released with the tutorial? This does not appear to be working correctly if so.

Failed sound loading should disable sound

I have been trying to find the point in the source where it goes wrong, but I could not see through the complex forest of callbacks, yet. Am on it, though.

Anyway, the issue is that sound files do not load on my computers when I use current standard Chromium from Ubuntu (version 14). There is an exception thrown, can the load callback is not called, so the loader never sees the audio as loaded.

What I would want for is that the loader will ignore not-found resources (maybe not just sounds), fire an exception or log an error, but go on, setting the resource to null. And the audio player will simply do nothing with a null audio.

Audio is not as important as graphics, I want users to be able to play the game even though their browser has issues with the audio.

Add touch event management

With the idea of course to have melonJS working on iOS, Android, etc...

Support for BMFont

Hi it would be great if we load BMFont files for use in games. BMFont can be found at: http://www.angelcode.com/products/bmfont/. I don't know if this would help, but the Slick2D library has an importer written in Java. Slick: http://slick.cokeandcode.com/

want more object type

I want moe object types ex ENEMY_OBJECT2 ,ENEMY_OBJECT3,ENEMY_OBJECT4 .Can I insert new code to MelonJS.js or must create a new js file .

Issues in Tutorial

There are some issues I encountered in the tutorial that caused quite a few headaches.

The first one I came upon was a syntax error in the enemy Entity code. There is a >= with a space between the > and =. The typo is in the update function in the else...if.

 // manage the enemy movement
    update: function() {
        // ... code before

        if (this.alive) {
            if (this.walkLeft && this.pos.x < = this.startX) {
                this.walkLeft = false;
            } else if (!this.walkLeft && this.pos.x > = this.endX) { //******  > = should be >= ******
                this.walkLeft = true;
            }

            //... code after
    }

The next issue I came across was the lack of explanation of Objects and Entities. I think just a couple lines explaining how to add and edit an entity to the object layer would make it much easier to follow for a newcomer to the engine. I got lost here for a while and had to backtrack to figure out where I went wrong.

Thanks!

Syntax highlighting in tutorial

A suggestion for the tutorial and any other page on the website that has code is to add some kind of syntax highlighting to the page. This way it would be easier to catch code mistakes and documentation/tutorials would be much easier to follow. There are a lot of JS highlighters out there that could be used.

Using "Shake" Method?

Hi Olivier,

Firstly, thank you for this library. I love it. But my problem is that i want to use "shake" function but i cant use correctly. It's not issue. i think it is my problem :D Can you say how i can use this method? For example, when enemy touched player, i want to shake camera fastly.

Thanks,
Ilker

Add a more "standard" spritesheet format

Zwoptex, TexturePacker or any other stuff with an easy and popular format !

Add a Modal dialog box to GUI?

it would be great if we add a modal dialog box to GUI for use in games.

Forum not working anymore ?

Hello,

I have tried to post some comment since yesterday and it's not working is that normal ?

I have tried to post comment on some topic, created a new Topic but nothing appear am I missing something ?

Don't use Tile Layer to create scrolling (parallax) layers

In case it is possible, in a future version of Tiled, to create Image layer or something. With the benefit on melonJS side to decrease the TMX file size (since now, Tiled create data for each layer, that are not used by the engine).

An idea and problem

Hi there im new in melonJS and tiled but i decided to create the perfect old game named SPACE INVADERS.

Ive got stuck in several points just because im new some of them are :
Creating the objects - you might think you click and its ok but if somebody who doesnt know what to do clicks and ads an object the rectangle on theyre screen in tiled is mostly grey your´s are green i sayed no problem try without that color maybe its working and its actualy working well

the next isue where Im is to create an enemy i simply copyed the code putted into pspad saved changed a few things like spritewidth, name of the image and just tested it out my enemys are not moving theyve got inicialized in init section but they never get into the loop of update where the moves are, please help.

this is the link to my game https://rapidshare.com/files/75650859/The_Game.rar
thanks for help anyway

Falling Bug

Hi,

First, this is a great javascript engine. I ported an old platform game I made in flash. However, there is one critical bug when falling from high places. For example, when jumping from high platform the hero goes through a solid tile. My theory is this has something to do with the acceleration of the fall greater than the height of the solid tile, as I encountered this kind of bug with my flash engine from long time ago. Just hoping you could check this bug, that would be really cool.

thanks! Really nice game engine.

Wrong Tileset name causes non-descriptive error

If the name of a Tileset loaded in Tiled does not match the name of the Tileset in code then an error occurs in .drawTile. This error isn't very descriptive and took a while to figure out. It would be nice if this error was better described.

init (True) and TMX loadLevel issue

Hello,

I'm quite new with MelonJs but I show something that I didn't expect and didn't find any topic related to that point.

Inside an init function if you place this.parent(true) you should be able to use draw and update function (http://www.melonjs.org/docs/symbols/me.ScreenObject.html#init), but if you load a TMX level those function are still not activated.

Code to test :

var PlayScreen = me.ScreenObject.extend(
{
init: function()
{
//can't work with a loadlevel
this.parent(true);

},

onResetEvent: function() 
{
    me.levelDirector.loadLevel("area01");
},


update: function() 
{       
    //can't work since a loadlevel is in place
    alert("this never occur, if you comment the load level it will work without trouble");
}

});

I think this is a bug since if we want to place keyb action not on object of the TMX but inside the PlayScreen 'class' we can't do it properly.

Thanks for your feedback.

PS: MelonJS is quite interesting, thanks for your work !!

Inheritance from AnimationSheet

In entity.js:701 there is this code:

// if one single image, disable animation
if (this.image.width == spritewidth) {
   this.update = function() {
    return false;
  }
}

However if you have a derived class from this (or, for example, derived from ObjectEntity) with its own update() function, and it does only have a single image, it will be overwritten and never called, due to the the above code. I am assuming the intention was just to disable AnimationSheet's own update() function?

Ladder collision offset and standing/jumping

Hi, there seems to be an issue with ladder metatiles. I confirmed this with the alexxkidd demo. There appears to be a -x offset error with it. It leads to the character only being able to climb up when he's standing a bit more to the left of the ladder.

Also, when standing on top of a ladder then your character can't jump. I tweaked the collision rect of the character but nothing helped.

[isometric] - Collision detection not working properly

The issue is related to #51 and the fact that in an isometric world, the tile 0 is in fact not at position (0,0) on the screen. This means that when the getTile(x,y) position is invoked for collision detection, the wrong tile is returned.

I guess this could be fixed by either managing the isometric case in a different way in the getTile function, or by computing xLUT and yLUT in a different way when in an isometric level.

Collision with tiles smaller than the Hit Box

When the hit box is bigger than the size of the solid tile, in some cases the collision isn't detected: you can see what I mean in this image:

This happens because me.TiledLayer.checkCollision() only checks the top and bottom corners, ignoring what is happening on the edge of the box.

Add a "Ending" section to MelonJS Tutorial (documentation)

MelonJS Tutorial:

1- Suggestion for Minor tweeks
a) In Part 9 the tutorial it might be good to add a small sentence to note that the screen_title image needs to be added to the game resources.
b) Mention that the title screen text should be capital letters
(I'll try to do these if I figure out how to, and if its ok to)

2- New Part: Ending
It would be great to end the tutorial with an "ending", so that when the last level is over we go back to the title screen (or go to a credits screen that goes back to the title screen if you press enter).
(I dont know how to do this at this point)

3- New Section in HUD: Life (or Hit Points/Hearts)
many games have a Hit Point or Hearts or Lives count that goes down when the player character is touched by an enemy. A section describing how to do this would be great.

H/W Acceleration

Look at WebGL and/or CSS to benefits from H/W acceleration when available.
Note : last version of melonJS already support a webGL wrapper, though not fully working.

LowerCase settings

I wished to play with the param from Tiled Object and have done a pretty simple opening/closing door with animation defined within the map.

http://norb.zxq.net/melonJS/melonsample1/

It could have been more simple using just a loadclass with eval function and place directly javascript inside the TMX map.

But (here come the issue) inside the load of the TMX map there is everywhere annoying Lowercase function, is that mandatory ? because of this lowercase the eval function can't work properly (ex : addAnimation, me.input.KEY.I, ....)

I have deleted the LowerCase on function getStringAttribute and all look fine but I would appreciate that you consider this question as a general one and think if all those LowerCase are really usefull.

Level-related performance issues in Windows Chrome

I get some serious slowdowns in certain levels (that I made with Tiled) in Windows Chrome (v18 & v19). Profiling shows most CPU use in me.TMXLayer.me.TiledLayer.extend.draw. Seems to be related to a particular area of the map, regardless of what tiles are there, as I also had it happen when there were no visible tiles on screen.

Evident in levels 7 & 9 of http://adhesion.mu/games/ld23-sub (http://adhesion.mu/games/ld23-sub/data/level7.tmx, http://adhesion.mu/games/ld23-sub/data/level9.tmx)

Support Gamepads

Gamepad API http://dvcs.w3.org/hg/webevents/raw-file/default/gamepad.html
So far has been implemented in Chrome Canary on all platforms (Windows is XBox 360 controller only).
Would be really good for platform games.

Can I use mouse event ?

Can I use mouse in game ? .example click some object to remove it .If can do it,pls give some idea how to do it.

I don't know to check mouse clicked event.

Thank you

MouseClick problem

Hello,

I don't understand but there is an problem in the new way of managing the click :

            if (obj.isClickable && obj.collisionBox.containsPoint(v)) {
                    if (obj.clicked()){

This don't fire the event like on the right and bottom part of the object

test sample : http://norb.zxq.net/melonJS/sample4/

but if i place the following code it's working normally:

            if (obj.isClickable && (x >= obj.left) && (x <= obj.right) && 
                (y >= obj.top) && (y <= obj.bottom)) 

Version used : git 9.3

Anchor Point for renderables

Instead of there only being an alignment attribute available to fonts, an anchor point should be added to a base class that all objects that draw themselves may inherit from.

The anchor point allows you to specify in normalized coordinates (0.0, 1.0) what the object's set position is relative to. For example (0.5, 0.5) means that the object's position refers to where the center of the object is placed in world coordinates.

Vertical parallax scrolling

Would be nice to have :) I hacked it into my fork (Adhesion@44caf37#diff-3) but the performance kinda sucks as it's just an extension of the existing method.

Incorrect coordinates for MouseEvent if container div not top-left

It seems incorrect coordinates are given to a GUI_Object if the div containing the app isn't top-left.

For example, if the Canvas is further down the page, a MouseEvent on GUI_Object will have a Y value of -200.

This seems to explain the issue:
http://stackoverflow.com/questions/55677/how-do-i-get-the-coordinates-of-a-mouse-click-on-a-canvas-element