使用 @melonjs/capacitor-plugin 将 melonJS 游戏桥接到 Capacitor:生命周期、硬件返回键与移动端适配
使用 @melonjs/capacitor-plugin 将 melonJS 游戏桥接到 Capacitor:生命周期、硬件返回键与移动端适配
将 melonJS 游戏打包为 iOS / Android 原生 App 时,最繁琐的不是渲染适配,而是把「后台挂起 / 前台恢复」和「Android 硬件返回键」这两类原生事件,正确、无泄漏地接进游戏引擎。@melonjs/capacitor-plugin 正是为此设计的运行时适配层:它把 Capacitor 的原生生命周期与硬件返回事件桥接到 melonJS 的事件总线,让游戏在后台自动暂停、回到前台自动恢复,并让每个 Stage 都能以极简代码拦截硬件返回键,而无需手动维护 event.on / event.off。读完本文你将掌握:完整的安装与注册流程、全部四个可配置选项的语义、bindStageBack 与 onBackButton 两种返回键策略的取舍,以及可选的屏幕方向锁定与启动页(Splash)隐藏辅助函数。
插件定位:零引擎改动的人体工程学层
melonJS 游戏本身就可以在 Capacitor 的 WebView 中原样运行,引擎不需要任何改动。这个插件纯属「人体工程学(ergonomics)层」,它所做的只是把标准 @capacitor/app 事件整理成 melonJS 熟悉的形态:
appStateChange→state.pause()/state.resume()(见 connect.ts);backButton→ 转发到 melonJS 事件总线,携带一个带preventDefault()语义的CapacitorBackEvent(见 connect.ts)。
在 plugin.ts 中,CapacitorPlugin 继承自引擎的 plugin.BasePlugin,构造时即调用 connectCapacitor(options) 完成接线;而引擎侧的插件注册机制见 packages/melonjs/src/plugin/plugin.ts:注册名全局唯一、重复注册会抛错,插件实例会被放进 cache 供后续获取。
安装与依赖说明
npm install melonjs @melonjs/capacitor-plugin @capacitor/app
运行时必需的对等依赖是 @capacitor/app(见 package.json,要求 >=6.0.0)。方向锁定与启动页辅助函数是可选能力,各自的对等依赖采用「用到才装」的惰性策略:
# 仅当你调用 lockOrientation / unlockOrientation 时才需要
npm install @capacitor/screen-orientation
# 仅当你调用 hideSplash 时才需要
npm install @capacitor/splash-screen
从源码看,这两个可选依赖是在调用时才通过动态 import() 加载(见 orientation.ts 与 splash.ts),因此在不需要它们时无需承担安装与打包成本。
快速开始
下面是一段完整的注册与使用示例(来自 README.md 并补充注释):
import { Application, plugin, state, Stage } from "melonjs";
import {
CapacitorPlugin,
bindStageBack,
hideSplash,
lockOrientation,
} from "@melonjs/capacitor-plugin";
await lockOrientation("landscape");
// `new Application(...)` 取代了旧版 boot() + video.init(...) 的组合。
// 注意:melonJS 20.0 起,仅构造 Application 并不会创建渲染器——
// 必须 await app.init(),它才是真正获取 WebGPU 设备的地方。
const app = new Application(1024, 768, {
parent: "screen",
scaleMethod: "flex",
});
await app.init();
// 一次 register 调用即可完成两件事:
// 1) appStateChange → state.pause/resume 的生命周期桥接;
// 2) 把硬件返回键事件转发进引擎事件总线。
plugin.register(CapacitorPlugin, "capacitor", {
pauseAudio: true,
});
class PlayStage extends Stage {
onResetEvent() {
// 绑定一个与当前 Stage 生命周期同长的返回键处理器。
// 调用 evt.preventDefault() 可阻止引擎执行默认动作(App.exitApp)。
bindStageBack(this, (evt) => {
state.change(state.MENU);
evt.preventDefault();
});
}
}
state.set(state.PLAY, new PlayStage());
state.change(state.PLAY);
await hideSplash({ fadeOutDuration: 300 });
hideSplash 放在第一帧渲染之后(例如首个 Stage.onResetEvent 内)调用最为合适,让玩家看到的是游戏画面而不是启动图。
API 详解
CapacitorPlugin
继承自引擎 plugin.BasePlugin 的插件类,通过引擎插件系统注册:
plugin.register(CapacitorPlugin, "capacitor", options?);
注册后,实例可通过 plugin.cache.capacitor 或 plugin.get(CapacitorPlugin) 获取。构造时插件会读取 peerDependencies.melonjs 作为自身版本,并交由引擎做兼容性校验(见 plugin.ts)。
注册选项 ConnectCapacitorOptions 的四个键位(见 types.ts):
| key | 默认值 | 说明 |
|---|---|---|
pauseOnBackground |
true |
OS 将 App 置于后台时调用 state.pause(),回到前台时 state.resume()。 |
pauseAudio |
true |
透传给 state.pause(music) / state.resume(music)。设为 false 则后台音频继续播放。 |
forwardBackButton |
true |
将 Capacitor 的 backButton 事件转发进引擎事件总线供订阅者拦截。设为 false 时返回键处理完全交给用户代码。 |
onUnhandledBack |
() => App.exitApp() |
当一次返回键按下没有任何订阅者调用 evt.preventDefault() 时调用。可覆盖为弹出确认框等;允许返回 Promise(支持异步)。 |
从 connect.ts 可以看出,pauseAudio 会作为布尔参数传入 state.pause(...) / state.resume(...),从而同时控制当前音频轨道的暂停/恢复;而 onUnhandledBack 被设计为可能异步执行,其抛出的错误或 Promise 拒绝会被捕获并以 console.warn 输出,而不是产生未处理的拒绝(见 connect.ts)。
实例还暴露一个 teardown() 方法,用于移除它安装的全部 Capacitor 监听器——主要服务于热重载与单元测试场景。它是异步的:await cap.teardown() 可等待所有移除操作落定,也可以不等待直接触发(fire-and-forget)。其内部用 Promise.allSettled 逐个移除监听,单个失败不会中断其余移除,仅记录警告(见 connect.ts)。
bindStageBack(stage, handler)
订阅一个硬件返回键处理器,其生命周期与给定 Stage 的重置/销毁生命周期一致:在 onResetEvent 中挂载、在 onDestroyEvent 中自动卸载。处理器收到的参数类型为:
interface CapacitorBackEvent {
readonly defaultPrevented: boolean;
preventDefault(): void;
}
该类型刻意镜像 DOM Event 的形状(见 types.ts)。只要有任何处理器调用了 evt.preventDefault(),本次按下的默认动作(onUnhandledBack)就会被抑制。
实现上有两个值得注意的细节(见 bind-stage-back.ts):
- 使用
WeakMap<Stage, StageBinding>按 Stage 身份维护绑定注册表,条目随 Stage 一起被 GC,不会泄漏; bindStageBack对每个 Stage 只包装一次onResetEvent/onDestroyEvent,之后再次调用只替换内部 handler,而不会层层嵌套闭包,从而避免在销毁/重置循环中造成泄漏;重复调用是幂等的。
onBackButton(handler)
订阅一个全局处理器(不绑定任何 Stage),返回一个取消订阅函数。适合那些与当前场景无关、始终生效的返回键策略;大多数场景下,针对每个屏幕的行为应优先使用 bindStageBack。它实际上订阅的是内部事件名 @melonjs/capacitor-plugin:backButton(见 back-event.ts)。
lockOrientation(o) / unlockOrientation()
对 @capacitor/screen-orientation 的薄封装,o 取 "portrait" 或 "landscape"。依赖仅在调用时才动态 import()(见 orientation.ts)。
hideSplash(opts?)
对 @capacitor/splash-screen 的 hide() 的薄封装,同样采用惰性导入。opts.fadeOutDuration 为淡出时长(毫秒)(见 splash.ts)。
Capacitor 项目搭建
本插件是运行时适配器,不替代标准的 Capacitor 项目搭建流程。在脚手架出 melonJS 游戏(例如 npm create melonjs my-game)之后,按正常方式接入 Capacitor:
npm install -D @capacitor/cli
npm install @capacitor/core @capacitor/app
npx cap init my-game com.example.mygame
npx cap add ios
npx cap add android
npm run build
npx cap copy
npx cap open ios # 或:npx cap open android
melonJS 基于 Vite 的构建输出到 dist/,这正好是 Capacitor 的默认 webDir,无需额外配置。注意先执行 npm run build 再 npx cap copy,否则原生工程里拷贝到的会是旧的 web 资源。
底层机制小结
一次硬件返回键按下的完整链路是:Capacitor 的 backButton 事件 → 插件在 connect.ts 中创建的监听器 → emitBackEvent() 构造新的 CapacitorBackEvent 并在引擎事件总线上广播(见 back-event.ts)→ 所有订阅者依次收到事件 → 若无人调用 preventDefault(),则执行 onUnhandledBack(默认退出 App)。
生命周期链路则更直接:appStateChange 的 isActive 为真时 state.resume(pauseAudio),为假时 state.pause(pauseAudio)(见 connect.ts),与引擎 packages/melonjs/src/state/state.ts 的 pause(music) 语义对应。
License
MIT — 见 packages/capacitor-plugin/LICENSE。