Skip to content

How to deploy WeChat Mini Games with melonJS

Jump to bottom
Olivier Biot edited this page Apr 1, 2026 · 17 revisions

Quick How-To

The following How-To provides basic information on how to use an existing melonJS game on an already setup WeChat dev environment. For more complete tutorial on WeChat, please do refer below to the Link section.

Requirements

Introduction

The WeChat Mini Game environment is based on JavaScriptCore on iOS, and V8 on Android. These are runtime environments without BOM or DOM — there is no global document or window object. If you try to use DOM APIs to create elements like Canvas or Image, it will throw an error.

To bridge the gap between the Web and WeChat Mini Games, the WeChat team has released a weapp-adapter, with the goal to make web libraries compatible with Mini Games.

To include the adapter, download it and import it first in your project:

import './libs/weapp-adapter/index.js'

Project Structure

The folder structure is slightly different from a typical melonJS project:

├── game.js          : main entry point, equivalent to the index.html page
├── game.json        : mini game configuration
├── data/            : asset folder
└── js/
    ├── index.js     : the game "main" file
    ├── entities/
    │   ├── player.js
    │   └── enemies.js
    ├── screens/
    │   ├── play.js
    │   └── title.js
    └── libs/
        ├── weapp-adapter.js
        └── melonjs.js

ES6 Modules and melonJS

WeChat supports ES6 modules, which melonJS uses natively.

The root game.js file:

import './js/libs/weapp-adapter'
import { Application, state, loader, audio } from './js/libs/melonjs'

import { PlayScreen } from './js/screens/play.js'
import { PlayerEntity } from './js/entities/player.js'

// create a new Application instance
const app = new Application(1024, 768, {
    scale: "auto",
    scaleMethod: "stretch",
});

// initialize the audio
audio.init("mp3,ogg");

// set the play screen
state.set(state.PLAY, new PlayScreen());

// start the game
state.change(state.PLAY, true);

The game.json configuration file:

{
    "deviceOrientation": "portrait"
}

Entity definitions using ES6 classes:

import { Sprite, loader } from '../libs/melonjs'

export class PlayerEntity extends Sprite {
    constructor(x, y) {
        super(x, y, {
            image: loader.getImage("myImage"),
            framewidth: 178,
            frameheight: 140
        });
    }
}

Limitations

Some issues may be encountered when running melonJS on the WeChat Mini Game platform:

  • Audio: melonJS built-in audio may not work directly. You may need to use the Audio component provided by the weapp-adapter:
const au = new Audio('http://url/to/audio.mp3');
au.play();
au.pause();
  • Scaling mode: The basic "fit" scaling mode may not work as expected since the canvas is stretched to the full display size. Use the "fill" or "stretch" scaling mode instead.
  • Asset loading: JSON, audio and other binary files may require a full URL (relative paths may not work). Behavior might differ between the simulator and a real device.

Links

Credits

Thank you to qichuren, a web developer from Shanghai, for his help on identifying and fixing various initial issues between melonJS and WeChat.

Clone this wiki locally