Melonjs Plugins Agent Skill

Plugins and adapters

Two different mechanisms

This trips people up, so it is worth stating first:

| | how it is installed |

|---|---|

| Plugins | plugin.register(Class, name?, ...args) — after await app.init() |

| Physics adapters | an Application setting (physic:), before init() |

// the adapter is chosen at construction …
const app = new Application(800, 600, {
    parent: "screen",
    physic: new PlanckAdapter({ gravity, pixelsPerMeter }),
});

// … the plugin is registered once the renderer exists
await app.init();
plugin.register(DebugPanelPlugin, "debugPanel");

register in detail

plugin.register(PluginClass, "name", ...constructorArgs);
plugin.cache.name;              // the instance
plugin.get(PluginClass);        // by class — or by registered name string

• The name is optional — it falls back to the class name.
• The registry is global, not per-application. It is a module-level object,

so registering the same name twice throws plugin <name> already registered.

A plugin *instance* does hold an app reference, but it defaults to game —

whichever Application most recently finished init(), since that is where

game is assigned. On a multi-application page, pass the app explicitly

through the constructor args:

plugin.register(DebugPanelPlugin, "debugPanel", input.KEY.S, myApp).

• BasePlugin.version is a floor, not an identity. It declares the

*minimum melonJS version the plugin needs*, and register throws

Plugin version mismatch, expected: <floor>, got: <engine> when the running

engine is older. That gate is the real enforcement — a peer-dependency range

only warns at install time, and not at all for CDN or pre-bundled use. If you

see that error, upgrade the engine or pin an older plugin. The check runs

*after* the instance is constructed, so a plugin whose constructor has side

effects will already have run them when it throws.

Register after await app.init(): a plugin binds to an Application and reads

renderer and frame state that does not exist before init.

The official plugins

@melonjs/debug-plugin

An in-game panel — frame time, draw and object counts — plus toggles for

hitbox/bounding-box overlays, velocity vectors and quadtree visualisation. The

first thing to reach for when something is slow or a collision is not landing

where you expect.

import { DebugPanelPlugin } from "@melonjs/debug-plugin";
plugin.register(DebugPanelPlugin, "debugPanel");   // default toggle key: S

@melonjs/tiled-inflate-plugin

Required, not optional, for Tiled maps using gzip, zlib or zstd layer

compression. It installs the inflate hook TMXUtils calls; without it a

compressed .tmx fails to parse — a map that opens fine in Tiled and refuses to

load in melonJS is nearly always this.

import { TiledInflatePlugin } from "@melonjs/tiled-inflate-plugin";
plugin.register(TiledInflatePlugin);

@melonjs/spine-plugin

Spine 4.x skeletal animation as a melonJS renderable, on all three backends.

This is the answer for deforming animated characters — glTF import does not read

vertex skinning. It also registers a Tiled object class, so Spine skeletons can

be placed from a map.

@melonjs/capacitor-plugin

Bridges Capacitor's native lifecycle and hardware-back events into the engine:

import { CapacitorPlugin } from "@melonjs/capacitor-plugin";
plugin.register(CapacitorPlugin, "capacitor", options);
// plugin.cache.capacitor.teardown()  — detach every listener

It also exports helpers usable on their own: onBackButton, bindStageBack,

lockOrientation / unlockOrientation, hideSplash. See melonjs-deployment

for the wider packaging picture.

Physics adapters

@melonjs/planck-adapter and @melonjs/matter-adapter swap the physics world

wholesale. Pick one per game. The portable surface — the declarative

renderable.bodyDef, world.adapter.queryAABB(rect) and

world.adapter.raycast(from, to) — works unchanged across the built-in world and

both adapters, so entity code does not have to branch.

Two queries are not portable: querySphere and raycast3d exist only on the

built-in adapter (planck and matter are 2D-only and deliberately omit them).

queryAABB is the one region query every adapter must implement, so call the

others optionally — app.world.adapter.querySphere?.(center, radius). For rays

there is a real flag: app.world.adapter.capabilities.raycasts3d.

Behaviour genuinely differs: velocity units, force magnitudes and where a body's

position is measured from all change. See melonjs-physics.

Writing your own

There is no init() lifecycle hook — the constructor is where setup goes,

and register instantiates it for you.

import { plugin, event } from "melonjs";

class MyPlugin extends plugin.BasePlugin {
    constructor(app = undefined) {
        super(app);              // stores it as this.app
        this.version = "20.0.0"; // MINIMUM engine version this needs
        event.on(event.GAME_UPDATE, () => { /* … */ });
    }
}

plugin.register(MyPlugin, "myPlugin");

this.version defaults to the running engine version, which means it always

passes — set it deliberately to the oldest version you actually support.

To wrap an existing engine method, plugin.patch keeps the original reachable

as this._patched():

plugin.patch(app, "update", function (time) {
    const result = this._patched(time);
    return result;
});

patch takes a class *or* an instance: given a constructor it patches the

prototype (that is how the debug plugin decorates Renderable.postDraw), given a

plain object it patches that object. this._patched is only bound for the

synchronous duration of your replacement — it is set before the call and nulled

straight after — so call it inline, never after an await.

plugin.patch(Renderable, "postDraw", function (renderer) {
    this._patched(renderer);
    // draw an overlay on top of every renderable
});

A plugin is the right shape when you need to augment engine classes or hook the

engine lifecycle globally. For anything that is just game code, a Renderable

or a Stage is simpler and easier to test.

Symptom → cause

| symptom | cause |

|---|---|

| plugin <name> already registered | the registry is global; registered twice, often across hot reloads |

| Plugin version mismatch | the plugin's version floor is above the running engine |

| Plugin should extend the BasePlugin Class ! | the class does not extend plugin.BasePlugin |

| the panel reports another app's numbers | app defaulted to game, the last Application to finish init() |

| world.adapter.querySphere is not a function | built-in adapter only; planck and matter are 2D-only |

| a Tiled map opens in Tiled but not melonJS | compressed layers, tiled-inflate plugin missing |

| plugin setup never runs | setup written in an init() method — there is no such hook |

| plugin.register for an adapter does nothing | adapters are a construction setting, not a plugin |

| physics behaves differently after adding an adapter | expected — units and force scales differ; re-tune |

Related skills

• melonjs-physics — the adapters and their behavioural differences
• melonjs-tilemaps — where the inflate plugin becomes mandatory
• melonjs-performance — using the debug panel to measure
• melonjs-deployment — Capacitor and native packaging
• melonjs-3d-assets — why skeletal characters go through Spine