@maoyugames/phaser-framework 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maoyugames
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @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` 命令构建出包。**升级框架版本不会动你的业务代码与平台占位**(模板在包内、占位值在你的项目)。
+
+---
+
+## 安装
+
+### 方式一:脚手架开新项目(推荐)
+
+```bash
+npm create @maoyugames/phaser-game my-game
+cd my-game
+npm install
+npm run dev
+```
+
+### 方式二:已有项目接入
+
+```bash
+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` 里包装(脚手架已生成):
+
+```jsonc
+{
+  "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 组件、工具与契约类型:
+
+```ts
+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` 约束:
+
+```ts
+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

package/dist/BasePlatform-BCOkvvDW.d.ts

@@ -0,0 +1,47 @@
+import { d as IPlatform, p as PlatformName, S as SafeArea, t as SystemInfo, L as LaunchOptions, j as IPlatformNet, m as IPlatformStorage, i as IPlatformLifecycle, g as IPlatformAuth, e as IPlatformAds, k as IPlatformPayment, h as IPlatformDevice, f as IPlatformAnalytics, P as PlatformInfo } from './types-DtcRFbM0.js';
+
+/**
+ * 平台抽象基类:封装"有 DOM/BOM 的环境"通用实现,供
+ * web / tiktok / facebook / capacitor 复用。
+ *
+ * 提供:
+ * - 基于 fetch 的 HTTP request(支持超时、AbortSignal、json/text/arraybuffer)
+ * - 基于标准 WebSocket 的 createSocket(包成 IPlatformSocket)
+ * - 基于 localStorage 的 storage
+ * - 基于 document.visibilitychange 的 lifecycle
+ * - 从 window/navigator 读取 SystemInfo / SafeArea / LaunchOptions 的默认实现
+ *
+ * 微信小游戏(无 DOM)不继承本类,自行用 wx.* 实现。
+ */
+
+/**
+ * 有 DOM 环境的平台基类。子类需:
+ * - 在构造或 init 中设置 name / isMiniGame / hasDOM
+ * - 实现 init()(读取系统信息、注入 SDK 等)
+ * - 按需提供 auth/ads/payment/device/analytics(不支持则保持 undefined)
+ */
+declare abstract class BasePlatform implements IPlatform {
+    abstract readonly platformName: PlatformName;
+    abstract readonly isMiniGame: boolean;
+    readonly hasDOM: boolean;
+    protected _safeArea: SafeArea;
+    protected _system: SystemInfo;
+    protected _launchOptions: LaunchOptions;
+    readonly net: IPlatformNet;
+    readonly storage: IPlatformStorage;
+    readonly lifecycle: IPlatformLifecycle;
+    readonly auth?: IPlatformAuth;
+    readonly ads?: IPlatformAds;
+    readonly payment?: IPlatformPayment;
+    readonly device?: IPlatformDevice;
+    readonly analytics?: IPlatformAnalytics;
+    get info(): PlatformInfo;
+    abstract init(): Promise<void>;
+    getLaunchOptions(): LaunchOptions;
+    /** 从 window/navigator 读取系统信息(子类可在 init 中调用) */
+    protected readDomSystemInfo(): void;
+    /** 从 location.search 解析启动 query(子类可覆盖以注入平台 scene) */
+    protected readDomLaunchOptions(): void;
+}
+
+export { BasePlatform as B };

package/dist/chunk-H5CUVYCN.js

@@ -0,0 +1,229 @@
+import { __publicField } from './chunk-PKBMQBKP.js';
+
+// src/platform/impl/BasePlatform.ts
+var DomWebSocket = class {
+  constructor(options) {
+    __publicField(this, "ws");
+    this.ws = options.protocols ? new WebSocket(options.url, options.protocols) : new WebSocket(options.url);
+    this.ws.binaryType = options.binaryType ?? "arraybuffer";
+  }
+  get readyState() {
+    return this.ws.readyState;
+  }
+  send(data) {
+    this.ws.send(data);
+  }
+  close(code, reason) {
+    this.ws.close(code, reason);
+  }
+  onOpen(cb) {
+    const handler = () => cb();
+    this.ws.addEventListener("open", handler);
+    return () => this.ws.removeEventListener("open", handler);
+  }
+  onMessage(cb) {
+    const handler = (ev) => cb(ev.data);
+    this.ws.addEventListener("message", handler);
+    return () => this.ws.removeEventListener("message", handler);
+  }
+  onError(cb) {
+    const handler = () => cb(new Error("WebSocket \u8FDE\u63A5\u53D1\u751F\u9519\u8BEF"));
+    this.ws.addEventListener("error", handler);
+    return () => this.ws.removeEventListener("error", handler);
+  }
+  onClose(cb) {
+    const handler = (ev) => cb({ code: ev.code, reason: ev.reason });
+    this.ws.addEventListener("close", handler);
+    return () => this.ws.removeEventListener("close", handler);
+  }
+};
+var LocalStorageAdapter = class {
+  getItem(key) {
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  }
+  setItem(key, value) {
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+    }
+  }
+  removeItem(key) {
+    try {
+      localStorage.removeItem(key);
+    } catch {
+    }
+  }
+  clear() {
+    try {
+      localStorage.clear();
+    } catch {
+    }
+  }
+};
+var DomLifecycle = class {
+  constructor(getLaunchOptions) {
+    __publicField(this, "getLaunchOptions");
+    this.getLaunchOptions = getLaunchOptions;
+  }
+  onShow(cb) {
+    const handler = () => {
+      if (document.visibilityState === "visible") cb(this.getLaunchOptions());
+    };
+    document.addEventListener("visibilitychange", handler);
+    return () => document.removeEventListener("visibilitychange", handler);
+  }
+  onHide(cb) {
+    const handler = () => {
+      if (document.visibilityState === "hidden") cb();
+    };
+    document.addEventListener("visibilitychange", handler);
+    return () => document.removeEventListener("visibilitychange", handler);
+  }
+};
+var FetchNet = class {
+  async request(options) {
+    const method = options.method ?? "GET";
+    const headers = { ...options.headers ?? {} };
+    let body;
+    if (options.body !== void 0 && method !== "GET" && method !== "HEAD") {
+      if (options.body instanceof ArrayBuffer || ArrayBuffer.isView(options.body)) {
+        body = options.body;
+      } else if (typeof options.body === "string") {
+        body = options.body;
+      } else {
+        body = JSON.stringify(options.body);
+        if (!hasHeader(headers, "content-type")) {
+          headers["Content-Type"] = "application/json";
+        }
+      }
+    }
+    const controller = new AbortController();
+    let timer;
+    if (options.timeout && options.timeout > 0) {
+      timer = setTimeout(() => controller.abort(), options.timeout);
+    }
+    if (options.signal) {
+      if (options.signal.aborted) controller.abort();
+      else options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    try {
+      const resp = await fetch(options.url, {
+        method,
+        headers,
+        body,
+        signal: controller.signal
+      });
+      const respHeaders = {};
+      resp.headers.forEach((v, k) => {
+        respHeaders[k] = v;
+      });
+      const responseType = options.responseType ?? "json";
+      let data;
+      if (responseType === "arraybuffer") {
+        data = await resp.arrayBuffer();
+      } else if (responseType === "text") {
+        data = await resp.text();
+      } else {
+        const text = await resp.text();
+        data = text ? safeJsonParse(text) : null;
+      }
+      return {
+        status: resp.status,
+        ok: resp.ok,
+        headers: respHeaders,
+        data
+      };
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  createSocket(options) {
+    return new DomWebSocket(options);
+  }
+};
+var BasePlatform = class {
+  constructor() {
+    __publicField(this, "hasDOM", true);
+    __publicField(this, "_safeArea", { top: 0, bottom: 0, left: 0, right: 0 });
+    __publicField(this, "_system", createDefaultSystemInfo());
+    __publicField(this, "_launchOptions", { query: {} });
+    // 公共底层实现(基于 DOM)
+    __publicField(this, "net", new FetchNet());
+    __publicField(this, "storage", new LocalStorageAdapter());
+    __publicField(this, "lifecycle", new DomLifecycle(() => this.getLaunchOptions()));
+    // 可选 capability 默认不提供,子类按平台覆盖为具体实现
+    __publicField(this, "auth");
+    __publicField(this, "ads");
+    __publicField(this, "payment");
+    __publicField(this, "device");
+    __publicField(this, "analytics");
+  }
+  get info() {
+    return {
+      name: this.platformName,
+      isMiniGame: this.isMiniGame,
+      hasDOM: this.hasDOM,
+      safeArea: this._safeArea,
+      system: this._system
+    };
+  }
+  getLaunchOptions() {
+    return this._launchOptions;
+  }
+  /** 从 window/navigator 读取系统信息(子类可在 init 中调用) */
+  readDomSystemInfo() {
+    this._system = createDefaultSystemInfo();
+    this._safeArea = { top: 0, bottom: 0, left: 0, right: 0 };
+  }
+  /** 从 location.search 解析启动 query(子类可覆盖以注入平台 scene) */
+  readDomLaunchOptions() {
+    const query = {};
+    try {
+      const search = typeof location !== "undefined" && location.search ? location.search : "";
+      const params = new URLSearchParams(search);
+      params.forEach((v, k) => {
+        query[k] = v;
+      });
+    } catch {
+    }
+    this._launchOptions = { query, raw: void 0 };
+  }
+};
+function createDefaultSystemInfo() {
+  const hasWindow = typeof window !== "undefined";
+  const nav = typeof navigator !== "undefined" ? navigator : void 0;
+  const ua = nav?.userAgent ?? "";
+  return {
+    screenWidth: hasWindow ? window.innerWidth : 0,
+    screenHeight: hasWindow ? window.innerHeight : 0,
+    pixelRatio: hasWindow ? window.devicePixelRatio || 1 : 1,
+    os: detectOsFromUa(ua),
+    language: nav?.language ?? "en",
+    hostVersion: ua ? ua.slice(0, 120) : void 0
+  };
+}
+function detectOsFromUa(ua) {
+  const s = ua.toLowerCase();
+  if (/iphone|ipad|ipod/.test(s)) return "ios";
+  if (/android/.test(s)) return "android";
+  if (/windows/.test(s)) return "windows";
+  if (/macintosh|mac os x/.test(s)) return "mac";
+  return "unknown";
+}
+function hasHeader(headers, name) {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export { BasePlatform, DomLifecycle };

package/dist/chunk-II3JM4R3.js

@@ -0,0 +1,9 @@
+// src/platform/types.ts
+var PlatformUnsupportedError = class extends Error {
+  constructor(platform, capability) {
+    super(`[platform:${platform}] \u4E0D\u652F\u6301\u80FD\u529B: ${capability}`);
+    this.name = "PlatformUnsupportedError";
+  }
+};
+
+export { PlatformUnsupportedError };

package/dist/chunk-PKBMQBKP.js

@@ -0,0 +1,5 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+export { __publicField };

package/dist/cli/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * @maoyugames/phaser-framework CLI 入口(命令名:pf)。
+ *
+ * 子命令:
+ *   pf dev [platform]            编程式起某平台 dev server(默认 web,临时入口 + HMR)
+ *   pf build <platform|all>      构建某平台/全部平台(临时入口 + 编程式 vite + 外壳注入 + 校验)
+ *   pf size-check [platform]     产物体积检查(扫 <root>/dist/<p>)
+ *   pf verify-isolation [platform] SDK 隔离校验(扫 <root>/dist/<p>)
+ *   pf cap <sync|open> [android|ios]  Capacitor 同步/打开原生工程
+ *   pf help                      查看帮助
+ *
+ * 设计:占位值来自用户项目根的 platform.config.ts;外壳模板内联在包内(shells/),
+ * 编程式 vite(import('vite').build/createServer)绕开 Windows shell/.cmd 问题,
+ * vite/phaser 等从用户项目 resolve(peerDependency)。
+ */
+/** CLI 主入口 */
+declare function main(argv?: string[]): Promise<void>;
+
+export { main };