跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
视频与音频

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
Pluginsplugin.register(Class, name?, ...args) — after await app.init()
Physics adaptersan 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/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

阅读完整来源 ↗