Frequently Asked Questions

Olivier Biot edited this page Dec 14, 2017 · 73 revisions

Table of Contents

  1. How to optimize your game for performance
  2. How to package your game for Windows, Mac, or Linux
  3. How to access object properties or methods from another object
  4. How to enable and use the object pooling feature
  5. Handling mouse or touch events on multiple overlapping objects
  6. Using form inputs in your game
  7. Resolving collisions properly

1. How to optimize your game for performance :

  • Try a lower fps rate. Does your game really require 60fps?
  • Make sure to use a rendering method adapted to your game, enabling it per layer (layers with sparse tiles should not have the pre rendering enabled). Layers with very few tiles draw faster dynamically, because only a few small draw operations occur, instead of one giant draw operation using mostly invisible pixels (context.drawImage() is not optimized for invisible pixels).
  • Enabling double buffering could help as well to decrease the amount of draw operations (works entirely with an off-DOM canvas and it is copied to the visible canvas at the end of the rendering cycle).
  • Enabling and using Object Pooling will help reducing memory usage by reusing object and lowering the use of garbage collector.
  • Try wrapper solution like CocoonJS that provide Canvas accelerated environments on mobile devices.
  • If you use TexturePacker disable texture rotation, as it forces melonJS to apply a default rotation angle when drawing sprites and, based on how many sprites are to be displayed, can impact performance.
  • Use PNG images with alpha channel instead of the "transparent color" settings in Tiled tilesets. Even though the performance burden will occur only on load, you will notice it frequently if the map is loaded more than once while playing.
  • The game resolution is one of most important factor that influences the performance, try lowering the resolution in the call to Also it might be best to disable auto-scaling video.
  • Optimize your assets, using a Texture Atlas (like Texture Packer or Shoebox) and use fixed sized assets that are square and powers-of-2, like 512x512px, 1024x1024px, 4096x4096px or not square but powers-of-2, like 512x256px, 1024x512px, 4096x2048px (this optimize the use of GPU memory).
  • Optimize your Tiled maps, the same should be square and powers-of-2, like 512x512px, 1024x1024px, 4096x4096px or not square but powers-of-2, like 512x256px, 1024x512px, 4096x2048px (this also optimize the use of GPU memory).
  • For optimizing many entities (like characters) melonJS provides you with some useful features like culled updates (configurable with me.Renderable.alwaysUpdate - off by default, so off-screen entities do not use any additional CPU time for AI) and avoiding garbage collection stalls using entity pooling.
  • Avoid calling me.collision.check() in every entity! This function is very slow, and careful consideration should go into which entities call it. For most games, the main player should be the only entity calling this function, with other entities responding to the collisions in their own onCollision callback. Your own character's projectiles might also call it, but only if you really NEED your character to throw projectiles. If not, throw out the idea of projectiles and save a LOT of CPU time!!
  • Avoid drawing text with the me.Font class more than necessary; it is best to render the text to an off-screen canvas:, height)) only once in your entity constructor, then draw the offscreen canvas each frame.
  • There are a ton of good programming practices you can follow that will avoid unnecessary calculations. For example, it is faster to check an object property directly: if (this.last_animation === "walk") than it is to call a function that provides the same information: if (this.isCurrentAnimation("walk"))
  • Avoid Number.prototype.degToRad() and friends - use radians directly to express rotation angles. For example, a full turn is always Math.PI * 2, a half turn is Math.PI, a quarter turn is Math.PI * 0.5, etc.
  • Use the Chrome JavaScript profiler or similar to locate problem areas.

2. How to package your game for Windows, Mac, or Linux :

  • There are several solutions out-there, but one that is known to work very well with melonJS is Node-Webkit, a stand-alone chromium wrapper that will let you package and distribute your games natively for Windows, Mac, and Linux.
  • electron is newer, more frequently updated, and backed by Github for Atom.
  • brackets-shell is pretty much the same thing, made by Adobe for Brackets. This one is based on CEF, which is updated infrequently.
  • Another known solution is cross-walk that uses Chromium to provides the same HTML5 features and capabilities you would expect to find in most modern web browsers.

3. How to access object properties or methods from another object :

  • First step is to get a reference to the target object using
  • should only be called once, and the result saved to your game's global namespace.
  • For example, to get a reference to an object named "player", you should call in your onLevelLoaded callback. If your global namespace is called game like in the melonJS boilerplate, save the result there:
game.player ="player")[0];
  • The return value is an array. So when you have one player object, it will be the only element in the array.
  • Now you can access properties and methods on the "player" object through game.player:
// Get current player position
var player_pos = game.player.pos;

// call one of the player function;

4. How to enable and use the object pooling feature :

Object Pooling allows you to greatly reduce the overhead of creating entities programmatically, and it is very useful with entities that are created and destroyed often (like bullet or laser entities). By using this feature, new instances of your entity won't be created each time you need a new one (which increases memory usage and potentially slowing your game), but rather activated or pulled from the pool. When an entity is then destroyed, it is placed back into the pool to await the next request.

So, how to use this great stuff? Let's have a look first at how to manually add an new entity (here EntityLaser) to the game manager:

// Create a new laser object
var myLaser = new EntityLaser("laser", this.pos.x , this.pos.y);
// Add the laser to the game manager with z value 3, 3);

Now to use entity pooling, the first thing is to associate a unique identifier to the object's class within the entity pool. This action has to be done one time only, preferably in your main loaded function:

me.pool.register("laser", EntityLaser, true);

Here we define "laser" as the unique identifier for the EntityLaser class in the entity pool. Also note that true is used as the last parameter to actually enable the object pooling for this particular entity type.

After this is done, we are ready to create new entities as before, with a slight difference on the object instantiation itself:

// Create a new laser object
var myLaser = me.pool.pull("laser", this.pos.x, this.pos.y);
// Add the laser to the game manager with z value 3, 3);

As you can notice, we no longer directly instantiate the object but request a new instance of the entity identified by the "laser" id, which was declared to use our EntityLaser class.

One specific point of attention when using this is the object properties initialization, as you should carefully ensure that all of them are properly set/reset to their default value in the entity init method.

That's it!

5. Handling mouse or touch events on multiple overlapping objects :

For most uses, the mouse/touch listeners will work great as long as the rects are in different parts of the screen. If any of them overlap you can run into trouble quickly. One obvious example is when registering mouse/touch events for the same me.Rect on multiple objects; wanting to use is rather common.

The trouble starts when you want to release the event, because a callback isn't provided to me.input.releasePointerEvent() specifying which callback should be released. Instead, it releases all callbacks on the provided me.Rect. (Side note: This may change in a future version of melonJS.)

As an immediate workaround, consider changing your code to register the event in a single "top level" object, and then delegate the event using the super awesome minpubsub!

First, the top-level event handler should be updated to only re-publish the event:

me.input.registerPointerEvent("pointerdown",, function (event) {
    me.event.publish("pointerdown", [ event ]);

Then setup some event listeners:

this.pointerDown= me.event.subscribe("pointerdown", function (event) {
    console.log(event.pointerId, event.gameX, event.gameY); // etc ...

When you are ready to destroy the object which has an open subscription, you must unsubscribe:


And you can safely destroy the event delegator when you no longer need to handle any mouse/touch events:


6. Using form inputs in your game :

You have the option of positioning and styling the HTML elements using CSS. Using the HTML elements will take care of all kinds of corner cases for you: basic navigation features using keyboard and mouse input. Even things you necessarily don't have to think about, like focus, tab selection, copy+paste, scrolling, etc. And on Mobile, using native HTML form elements relieve you of reimplementing the virtual keyboard, since the native keyboard only appears when an HTML text element is focused!

The HTML form elements also provide pretty simple APIs to get and manipulate their values. Especially if you are already using a library like jQuery.

Here's a class that implements a text input, using jQuery to simplify the code:

game.TextInput = me.Renderable.extend({
    init : function (x, y, type, length) {
        this.$input = $('<input type="' + type + '" required>').css({
            "left" : x,
            "top" : y

        switch (type) {
        case "text":
                .attr("maxlength", length)
                .attr("pattern", "[a-zA-Z0-9_\-]+");
        case "number":
            this.$input.attr("max", length);


    destroy : function () {

The real magic comes from using CSS to position the elements as expected within the viewport:

#screen {
    position: relative;

#screen input {
    position: absolute;
    z-index: 2;

You can also style the HTML inputs with background and font-color, font styles, border styles, etc. to better match your game.

And of course you can always manipulate the HTML element contents using the jQuery element reference, eg. with this.$input.val() and so on.

7. Resolving collisions properly :

Collision detection is hard! The naïve approach to detecting collisions in a pixel-perfect manner is identical to the naïve approach of detecting collisions in a tile grid. The only difference between these cases is granularity; the area of a "solid" rectangle, and the tradeoff is how fast it can run with different granularities. As it turns out, the naïve approach is also the easiest to understand and implement.

Naïve collision detection checks for overlaps between two rectangles. That might be a sprite rectangle overlapping a tile, or a pixel overlapping another pixel; it's just a matter of granularity! This is called an AABB test, and it involves comparing the top, left, right, and bottom coordinates of both rectangles in end-end order: top<=>bottom, bottom<=>top, left<=>right, right<=>left. That's four comparisons total. It's pretty fast when the granularity is large!

With melonJS, we want the best of both worlds; the accuracy of pixel-perfect collision detection with very high performance. To achieve this, the engine uses a combination of algorithms; QuadTree, AABB tests, SAT ... in roughly that order. QuadTree allows fast lookups of nearby objects which are candidates for collisions, the AABB test further filters objects that are definitely not colliding, and SAT performs very fast pixel-perfect collisions against arbitrary polygons and circles.

But wait! Collision detection is only one part of the issue. The other part is how objects respond to collisions. Some objects are solid, so no object may pass through them. Other objects are only there to trigger events when another object touches it (but may freely move through the object). The finish line on a race course is one example of the latter; you don't want cars to run into the finish line like a brick wall. But you do want the race to end when the player's car crosses the finish line, and that is triggered by collision detection.

Collision responses aren't even that black-and-white! The Platformer Example implements platform objects that players can pass through, jump through, land on, and drop down from. Maybe you want some objects to be "squishy" instead of solid concrete... Whatever the case, these responses are all taken care of by collision handlers. In melonJS, the collision handler is me.Entity.onCollision. It's a callback that accepts two arguments: response and other, and the return value is a Boolean that informs melonJS whether the response should be applied (true) or ignored (false). response is a me.collision.ResponseObject, and other is just a reference to the other entity that is overlapping.

While melonJS does a decent job at handling collision responses by default in a sane manner, there are some things that will throw you off-guard if you are not prepared. Here's the list of collision gotchas:

  • An Entity that moves too fast will pass through solid shapes, and may be accelerated even faster if a collision occurs on the wrong side. This is the oldest open ticket: #16 A solution is described in a (now-closed) ticket, regarding the use of the Entity's range-of-motion instead of simply its AABB during the initial filtering phase: #103

  • When a moving Entity hits the corner of a solid world shape, it has a chance of "bumping" to the side instead of coming to a dead stop. The "bumping" is perpendicular to the direction of momentum as described in this forum post. It's caused by SAT choosing the "shortest depth" of the overlap for use as the collision response vector. When dealing with velocities that are high enough to penetrate into a rectangle more than the corner it clips, the "shortest depth" will be perpendicular to the momentum. It can be fixed by choosing a better heuristic than "shortest depth" in the collision handler, e.g. direction of momentum always wins over "shortest depth".

  • The "shortest depth" heuristic also causes Entities to slowly slide down slopes when gravity is enabled. This is described in detail in another forum post, along with a suggested solution that forces the collision response upward instead of left or right.

  • Collision shapes with aligned edges (like rectangles that cover adjacent tiles) can cause moving Entities to get stuck on the inner corners as the Entity slides across what should be a flat surface. This is a well-known problem where "internal edges" confuse the collision detection system because collision responses are not applied simultaneously to all overlapping shapes, but individually, one-at-a-time. The general fix is using larger collision shapes, but a second solution is provided in this forum post which describes a method of velocity limiting against the colliding axis to prevent collisions with internal edges.