使用 @melonjs/capacitor-plugin 将 melonJS 游戏桥接到 Capacitor:生命周期、硬件返回键与移动端适配

原创2026-10-05 11:28:131,645 阅读
文章标签:游戏开发图形学

使用 @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。

登录后查看全文
melonJS