melonjs-plugins
Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, on-screen touch controls, 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, GamepadPlugin, gamepad-plugin, touch controls, virtual joystick, floating joystick, floating button, CapacitorPlugin, adapter, custom plugin, plugin version mismatch, already registered.
melonjs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-plugins技能说明
name: melonjs-plugins description: "Use this skill when adding a melonJS plugin or adapter — the debug panel, Spine skeletal animation, compressed Tiled map support, on-screen touch controls, 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, GamepadPlugin, gamepad-plugin, touch controls, virtual joystick, floating joystick, floating button, 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() |
// 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 anappreference, but it defaults togame— whichever Application most recently finishedinit(), since that is wheregameis assigned. On a multi-application page, pass the app explicitly through the constructor args:plugin.register(DebugPanelPlugin, "debugPanel", input.KEY.S, myApp). BasePlugin.versionis a floor, not an identity. It declares the minimum melonJS version the plugin needs, andregisterthrowsPlugin 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/gamepad-plugin
On-screen touch controls, reported as a gamepad: one or two sticks and any
number of buttons, drawn over the game and read by the engine as a pad in a
gamepad slot. The game's bindGamepad bindings drive it unchanged, so one set
of bindings covers a real pad and a touch screen.
import { GamepadPlugin } from "@melonjs/gamepad-plugin";
plugin.register(GamepadPlugin, "gamepad", {
buttons: [{ label: "A" }, { label: "B" }],
});
// plugin.cache.gamepad.visible — showing, to word prompts ("tap" or a key)
Shown on touch screens by default (enabled), hidden while a real pad is in
use. The left stick also presses the D-pad; a button can press a key instead
of a pad button. Since 1.1 a stick or button can be floating (shows up
under the finger anywhere in its area), hideAtRest (drawn only while
held), and a stick can take a tap (a quick touch that does not steer presses
a key or button) — so the mobile layouts, two thumbs or one thumb with
tap-to-act, need no code of their own. See melonjs-input for the bindings,
the layouts and the overlap rules.
@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
阅读完整来源 ↗