Skip to content
Skills Library
Programming · Tool integration

melonjs-plugins

/melonjs-plugins

Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered.

Repository
melonjs ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered.

Original author description

Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered.

How it works

  1. Two different mechanisms
  2. register in detail
  3. The official plugins
  4. Physics adapters
  5. Writing your own
  6. Symptom → cause
  7. Related skills
Original SKILL.md headings · 187 lines, 1,076 words
SKILL.md preview
---
name: melonjs-plugins
description: "Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, Capacitor packaging — or when writing your own plugin. Covers plugin.register and its version gate, plugin.cache, plugin.patch, and why physics adapters are not plugins. Triggers on: plugin, plugin.register, plugin.cache, plugin.get, plugin.patch, BasePlugin, debug-plugin, DebugPanelPlugin, SpinePlugin, TiledInflatePlugin, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered."
license: MIT
---

# 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()` |

```js
// 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

```js
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.

```js
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.

```js
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:

```js
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.

```js
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()`:

```js
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`.

```js
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

Versions

The database has no other skills named melonjs-plugins.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 183b19eb2169 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100melonjs-tilemaps
    Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers. Covers registerTiledObjectClass and the pool.register name contract, camera bounds,…
  • 100melonjs-deployment
    Use this skill when packaging, shipping or scaffolding a melonJS game — starting a project with create-melonjs, building for the web, wrapping as a native app with Capacitor or Cordova, publishing to WeChat Mini Games or Facebook Instant Games, browser support and transpiling.…
  • 100neko-plugin
    Work on N.E.K.O plugins end to end. Use when the user asks to create, modify, review, run, debug, inspect, document, validate, package, or reason about N.E.K.O plugins, plugin.toml, plugin SDK usage, plugin UI surfaces, plugin CLI tooling, plugin runtime behavior, or plugin system contracts.
  • 100capacitor-plugin-development
    Guides the agent through creating and maintaining Capacitor plugins from scratch. Covers scaffolding a new plugin project, designing the TypeScript API, implementing native iOS (Swift) and Android (Java/Kotlin) bridges, implementing the web layer, defining TypeScript type…
  • 100pytest-plugins
    Use when pytest plugin ecosystem including pytest-cov, pytest-mock, and custom plugin development.
  • 90marketplace
    Use when working on the cc-plugins repository itself: adding a plugin, renaming one, removing one, bumping a version, or after editing any plugin's components. Also when writing or revising a skill's description or body, or editing CLAUDE.md — WRITING.md carries the judgment for…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.