Upgrading to melonJS 2.1

May 18, 2015 André Schmitz 0 Comments


With the release of melonJS 2.1, is time to conduct a upgrade to this solid version of the engine, with nice features as:

- New screen independent scaling methods
- Improved collision handling and detection
- Support for Physics Editor tool, to define entities collision shapes
- Added support for pointerenter and pointerleave events
- High-precision color transform with more accurate color effects
- Several improvements in the WebGL renderer (reached a beta quality level)
- Added support for the new Tiled 0.11 object id property
- Fixed various bugs and issues

Check the melonJS Blog for a official announcement and get the lastest version in melonJS Site.

The recommended is to migrate the current version used in the game to one immediately more recent facilitating the upgrade process (some melonJS versions have API breaks). For example, if your game uses melonJS 1.0.2, you need to update first to 1.1.0 version (check the post Upgrading to melonJS 1.1), after to 2.0.2 version (check the post Upgrading to melonJS 2.0) and finally to 2.1.3 version.

Below we will check some of the necessary changes to upgrade from melonJS 2.0.2 (previous version) to melonJS 2.1.4 (current version when writing this post). For a complete list of changes visit the melonJS Upgrade Guide.


Before the Upgrade


The melonJS 2.1 is a major release and include some breaking changes which forces you to make adjustments in your game code.

Before starting the migration, check the Upgrade Guide and the Changelog of engine and decide if the amount of work for the upgrade compensates the new features of this melonJS version!

Don't forget to always have a backup of the last game version before starting the upgrade process!


Piece of Cake


Start renaming the functions, objects and variables changed in this version, which can be easily performed via a Search and Replace (or Refactor) available in your preferred Code Editor (or IDE):

// Old Code -> New Code
spritewidth -> framewidth
spriteheight -> frameheight
me.TextureAtlas -> me.video.renderer.Texture
me.video.shader.gltexture2d() -> me.video.shader.createTexture()
The me.video.init has arguments more flexible and robust requiring three params: width, height and a list of properties for the various options (the pattern function(x, y, {settings}) for constructors signature will be applied to others melonJS functions in future):

// Before melonJS 2.1
me.video.init("screen", me.video.CANVAS, 800, 600, true, "auto", false);

// After melonJS 2.1
me.video.init(800, 600, {
    wrapper: "screen", 
    renderer: me.video.CANVAS,     
    scale: "auto", 
    scaleMethod: "fill-max",
    doubleBuffering: true,
    transparent: true
});
The new and functional scaling mode is enabled through the scaleMethod param set in me.video.init and are detailed in the melonJS Blog:

- fit (default): Letterboxed; content is scaled to design aspect ratio.
- fill-max: Canvas is resized to fit maximum design resolution; content is scaled to design aspect ratio.
- flex-width: Canvas width is resized to fit; content is scaled to design aspect ratio.
- flex-height: Canvas height is resized to fit; content is scaled to design aspect ratio.
- stretch: Canvas is resized to fit; content is scaled to screen aspect ratio.

Check also the addition of the "transparent" parameter to enable support for the new opaque canvas feature and the removal of the old maintainAspectRatio replaced by the new scaling method.

The me.sys.scalingInterpolation setting for enable or disable the anti-aliasing is avaliable now directly in the me.video.init antiAlias params:

// Before melonJS 2.1
me.sys.scalingInterpolation = true;

// After melonJS 2.1
me.video.init(800, 600, {
    wrapper: "screen", 
    renderer: me.video.CANVAS,
    doubleBuffering: true, 
    scale: "auto",      
    antiAlias: true
});


Let's Rock


In order to standardize objects constructor in melonJS, me.Sprite, me.AnimationSheet and me.ImageLayer signature have been update to follow the pattern function(x, y, {settings}):

// Before melonJS 2.1
var sprite = new me.Sprite(20, 80, me.loader.getImage("image"));
var animationSheet = new me.AnimationSheet(30, 50, image: me.loader.getImage("animationsheet"), spritewidth: 32, spriteheight: 32});

// After melonJS 2.1
var sprite = new me.Sprite(20, 80, {
   image: me.loader.getImage("image")
});

var animationSheet = new me.AnimationSheet(30, 50, {
  image: me.loader.getImage("animationsheet"),
  framewidth: 32,
  frameheight: 32
});
Most keywords and name lookups have been made case-sensitive now. This affects file names, pooling, and container child searches and may give more or less work as the patterns used in your project. To perform a case-insensitive search, you can use Javascript RegExp in container child searches:

// Before melonJS 2.1 - Get objects named "Player" or "player"
me.game.world.getChildByProp("name", "PLAYER");

// After melonJS 2.1 - Use the RegExp for Case Insensitive Search
me.game.world.getChildByProp("name", /player/i);
Lastly, remove the references to body.updateBounds() because this function is automatically called by the engine now, providing an extra facility to the developer.


Work Done


After the completion of the steps above, you must run the game performing various tests to detect possible adjustments or fixes to be made. For possible questions, use the melonJS Forum or analyze directly the source code on GitHub Repo.

The practical and functional screen scaling modes, the better support to WebGL and the easy migration proccess (if compared with the whirlwind of changes and new features introduced with melonJS versions 1.1 and 2.0), make the upgrade a good and right choice. And you can enjoy to review some "obscure" or "hackish" code, using the best practices you acquired in recent times or to implement new features in your game.

0 comentários :

Subscribe to: Post Comments ( Atom )