@maoyugames/phaser-framework

多平台 Phaser 游戏框架(npm 包形态):业务/底层彻底分离,内置 HTTP/WebSocket/KCP 三种网络协议,内置 pf 构建 CLI,支持 Web H5 / TikTok 小游戏 / 微信小游戏 / Facebook Instant Games / iOS+Android App(Capacitor),各平台 SDK 按需隔离打包。

业务代码只 import { ... } from '@maoyugames/phaser-framework'(barrel 出口),用 pf 命令构建出包。升级框架版本不会动你的业务代码与平台占位(模板在包内、占位值在你的项目)。

安装

方式一:脚手架开新项目(推荐)

npm create @maoyugames/phaser-game my-game
cd my-game
npm install
npm run dev

方式二:已有项目接入

npm i @maoyugames/phaser-framework
# 安装 peerDependencies(框架不替你装,版本由你的项目锁定)
npm i -D phaser@^3.90 vite@^5 typescript@^5 terser@^5

Phaser 锁 3.x(^3.60 || ^3.80 || ^3.90),暂不支持 Phaser 4。

peerDependencies

框架把这些列为 peer(由你的项目安装并锁版本,避免重复打包/版本冲突):

| 包 | 版本范围 | 用途 | 必装 | |----|----------|------|------| | phaser | ^3.60.0 \|\| ^3.80.0 \|\| ^3.90.0 | 游戏引擎 | 是 | | vite | ^5.0.0 | 构建工具(pf 编程式调用,从你的项目 resolve) | 是 | | typescript | ^5.0.0 | 类型检查(tsc --noEmit) | 是 | | terser | ^5.0.0 | 生产压缩(标记为 optional) | 否(建议) |

pf 命令

包内置可执行 pf(bin.pf)。在你的项目里(根目录有 game.config.ts + platform.config.ts,且 package.json 依赖本包)运行:

| 命令 | 作用 | 产物 / 行为 | |------|------|------------| | pf dev [platform] | 起 Vite dev server(临时入口 + HMR),默认 web | 常驻;支持 web/tiktok/facebook/capacitor(wechat 无 HTML dev 形态) | | pf build <web\|tiktok\|wechat\|facebook\|capacitor\|all> | 构建某平台 / 全部 | dist/<platform>/;含外壳注入 + 体积检查 + 隔离校验 | | pf size-check [platform] | 产物体积检查 | 扫 dist/<platform>;TikTok 50MB 整包硬上限,微信主包 4MB 软提示 | | pf verify-isolation [platform] | SDK 隔离校验 | 扫 dist/<platform> JS,命中其它平台 SDK 签名即失败 | | pf cap <sync\|open> [android\|ios] | Capacitor 同步 / 打开原生工程 | 透传 npx cap ...;open 必须带 android/ios |

退出码:成功 0,失败 1。通常在项目 package.json 的 scripts 里包装(脚手架已生成):

{
  "scripts": {
    "dev": "pf dev",
    "build:web": "pf build web",
    "build:all": "pf build all",
    "size-check": "pf size-check",
    "verify-isolation": "pf verify-isolation",
    "cap:sync": "pf cap sync",
    "cap:open:android": "pf cap open android"
  }
}

命令细节见框架文档 docs/cli-reference.md。

exports(导出口)

barrel(业务唯一入口)

业务只从包名根导出取门面、基类、UI 组件、工具与契约类型:

import { App, startGame, BaseScene, BasePanel, BaseModule, Button } from '@maoyugames/phaser-framework';
import type { AppConfig, IApp, PlatformConfig } from '@maoyugames/phaser-framework';

barrel 导出(摘要,完整以 src/index.ts 为准):App / startGame / BaseScene / BasePanel / PanelManager / Layers / BaseModule / ModuleRegistry / I18n / SaveManager / ConfigTable / ConfigTableManager / createStore / TypedEventBus / createTypedEventBus / ObjectPool / Scheduler / FrameworkError / ErrorCode / isFrameworkError / MessageChannel / JsonCodec / Button / NetManager / HttpClient / WebSocketClient / KcpClient / PlatformContext 等,及 AppConfig / IApp / PlatformConfig / Store 等类型。

平台子路径(只由 CLI 用,业务禁 import)

各平台适配器类经子路径单独导出,仅由 pf 生成的临时单平台入口 import,以保证打包时各平台 SDK 互不串联(SDK 隔离):

• @maoyugames/phaser-framework/platform/web → WebPlatform
• @maoyugames/phaser-framework/platform/tiktok → TikTokPlatform
• @maoyugames/phaser-framework/platform/wechat → WeChatPlatform
• @maoyugames/phaser-framework/platform/facebook → FacebookPlatform
• @maoyugames/phaser-framework/platform/capacitor → CapacitorPlatform

业务代码不要 import @maoyugames/phaser-framework/platform/*。 平台选择由 pf <命令> <platform> 决定,CLI 自动生成只含该平台适配器的临时入口并 tree-shaking,业务无需也不应碰平台类。

其它子路径

• @maoyugames/phaser-framework/global — 构建期全局常量声明(__PLATFORM__ / __DEV__ / __FRAMEWORK_VERSION__)。在项目里用三斜线引用即可:/// <reference types="@maoyugames/phaser-framework/global" />。
• @maoyugames/phaser-framework/cli — CLI 入口(等价 pf bin)。

PlatformConfig 占位(单一来源:你项目根的 platform.config.ts)

各平台后台/外壳"必须由开发者填写"的占位项,集中在你项目根的 platform.config.ts,satisfies PlatformConfig 约束:

import type { PlatformConfig } from '@maoyugames/phaser-framework';

export default {
  web: { title: 'My Game' },
  tiktok: { sdkUrl: 'https://developers.tiktok.com/js/minis.js' },
  wechat: { appid: 'wxYOUR_APPID', projectname: 'my-game' },
  facebook: { appId: 'YOUR_FB_APP_ID', appName: 'My Game', fbSdkVersion: '7.1' },
  capacitor: { appId: 'com.example.mygame', appName: 'My Game' },
} satisfies PlatformConfig;

pf build 把这些占位注入包内的外壳模板(index.html / game.json / project.config.json / fbapp-config.json / capacitor.config.ts)生成产物。运行时业务配置(apiBaseURL 等)另在 game.config.ts(gameConfig: AppConfig)。

PlatformConfig 字段全表见框架文档 docs/package-usage.md。

隔离与升级安全

• 三层隔离防御:① package exports 子路径封死深路径(业务摸不到平台 impl);② pf 为每平台生成单平台临时入口(只 import 一个平台类);③ pf verify-isolation 在产物级扫描,命中其它平台 SDK 签名即失败。
• 升级不还原:外壳模板在包内,占位值在你的 platform.config.ts/game.config.ts。npm update @maoyugames/phaser-framework 只换包内 dist,不动你的项目文件。详见 docs/upgrading.md。

许可证

MIT