@maoyugames/phaser-framework 1.0.0

package/dist/types-DtcRFbM0.d.ts

@@ -0,0 +1,239 @@
+/**
+ * 框架通用基础类型。底层与业务共用,业务层只读取不修改。
+ */
+/** 可释放资源 */
+interface IDisposable {
+    dispose(): void;
+}
+/** 通用事件回调 */
+type Handler<T = void> = (payload: T) => void;
+/** 取消订阅句柄 */
+type Unsubscribe = () => void;
+/** 二维坐标 */
+interface Vec2 {
+    x: number;
+    y: number;
+}
+/** 安全区(刘海屏 / 小游戏胶囊按钮规避用) */
+interface SafeArea {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+/** 设备 / 运行环境信息 */
+interface SystemInfo {
+    /** 屏幕逻辑宽度(px) */
+    screenWidth: number;
+    /** 屏幕逻辑高度(px) */
+    screenHeight: number;
+    /** 设备像素比 */
+    pixelRatio: number;
+    /** 操作系统:ios / android / windows / mac / devtools / unknown */
+    os: string;
+    /** 宿主语言,如 zh-CN / en */
+    language: string;
+    /** 宿主 App 版本(小游戏宿主版本 / 浏览器 UA 摘要) */
+    hostVersion?: string;
+}
+/** 通用结果包装,避免到处抛异常 */
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: Error;
+};
+declare function ok<T>(value: T): Result<T>;
+declare function err<T = never>(error: Error | string): Result<T>;
+/** 日志级别 */
+declare enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3,
+    Silent = 4
+}
+
+/**
+ * 平台抽象契约。这是整个框架"业务无关、平台可替换"的核心。
+ *
+ * 设计原则:
+ * 1. 业务代码与底层服务一律只依赖这些接口,绝不直接调用 wx / TTMinis / FBInstant 等平台全局对象。
+ * 2. 每个平台一个独立实现(src/core/platform/impl/<platform>),并由独立入口
+ *    (src/platform-entries/main.<platform>.ts)静态导入 —— 保证打包时 tree-shaking,
+ *    TikTok 包不会混入微信 / Facebook 的 SDK 适配代码。
+ * 3. 不支持的能力返回 undefined(可选 capability)或抛出 PlatformUnsupportedError,
+ *    由上层服务统一降级处理。
+ */
+
+/** 受支持的平台名 */
+type PlatformName = 'web' | 'tiktok' | 'wechat' | 'facebook' | 'capacitor';
+/** 平台静态信息 */
+interface PlatformInfo {
+    /** 平台名 */
+    readonly name: PlatformName;
+    /** 是否为"小游戏"类宿主(TikTok / 微信 / Facebook Instant) */
+    readonly isMiniGame: boolean;
+    /**
+     * 运行环境是否具备完整 DOM/BOM(window/document)。
+     * - web / tiktok(HTML 运行时,真 webview)/ capacitor(WebView):true
+     * - wechat 小游戏(JSCore/V8,无 DOM):false —— 资源加载等需走适配器
+     */
+    readonly hasDOM: boolean;
+    /** 安全区 */
+    readonly safeArea: SafeArea;
+    /** 系统信息 */
+    readonly system: SystemInfo;
+}
+/** 启动参数(深链 / 分享回流 / 场景值等) */
+interface LaunchOptions {
+    /** 小游戏场景值 / 来源标识 */
+    scene?: number | string;
+    /** 透传查询参数 */
+    query: Record<string, string>;
+    /** 平台原始启动对象,逃生舱 */
+    raw?: unknown;
+}
+/** 平台不支持该能力时抛出 */
+declare class PlatformUnsupportedError extends Error {
+    constructor(platform: PlatformName, capability: string);
+}
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD';
+interface HttpRequestOptions {
+    url: string;
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    /** 请求体:对象会按 JSON 序列化;ArrayBuffer 原样发送 */
+    body?: unknown;
+    /** 期望响应类型 */
+    responseType?: 'json' | 'text' | 'arraybuffer';
+    /** 超时毫秒 */
+    timeout?: number;
+    /** 中断信号(web/capacitor 支持;小游戏侧尽力而为) */
+    signal?: AbortSignal;
+}
+interface HttpResponse<T = unknown> {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    data: T;
+}
+interface SocketOptions {
+    url: string;
+    /** 子协议 */
+    protocols?: string[];
+    /** 期望接收二进制类型(默认 arraybuffer) */
+    binaryType?: 'arraybuffer' | 'blob';
+    /** 附加请求头(仅部分平台支持,如微信) */
+    headers?: Record<string, string>;
+}
+/** 与具体平台无关的 Socket 抽象(包裹 WebSocket / wx.SocketTask) */
+interface IPlatformSocket {
+    readonly readyState: number;
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    onOpen(cb: () => void): Unsubscribe;
+    onMessage(cb: (data: string | ArrayBuffer) => void): Unsubscribe;
+    onError(cb: (err: Error) => void): Unsubscribe;
+    onClose(cb: (info: {
+        code: number;
+        reason: string;
+    }) => void): Unsubscribe;
+}
+interface IPlatformNet {
+    /** HTTP 请求底层实现(fetch / wx.request) */
+    request(options: HttpRequestOptions): Promise<HttpResponse>;
+    /** 建立 Socket(WebSocket / wx.connectSocket),供 WebSocket / KCP 协议层使用 */
+    createSocket(options: SocketOptions): IPlatformSocket;
+}
+/** 本地存储(localStorage / wx.setStorageSync / Capacitor Preferences) */
+interface IPlatformStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/** 登录态 */
+interface LoginResult {
+    /** 平台下发的临时凭证(微信 code / TikTok auth code / FB signature 等) */
+    code: string;
+    /** 平台用户唯一标识(若可直接获取) */
+    openId?: string;
+    raw?: unknown;
+}
+interface IPlatformAuth {
+    login(): Promise<LoginResult>;
+    /** 获取用户公开信息(昵称头像),需平台授权 */
+    getProfile(): Promise<{
+        nickname: string;
+        avatarUrl: string;
+    } | null>;
+}
+/** 广告 */
+type AdResult = 'completed' | 'skipped' | 'failed' | 'closed';
+interface IPlatformAds {
+    /** 预加载激励视频 */
+    preloadRewarded(adUnitId?: string): Promise<void>;
+    /** 展示激励视频,返回是否看完 */
+    showRewarded(adUnitId?: string): Promise<AdResult>;
+    /** 展示插屏 */
+    showInterstitial(adUnitId?: string): Promise<AdResult>;
+}
+/** 内购 */
+interface PurchaseResult {
+    productId: string;
+    transactionId: string;
+    /** 平台回执,交由业务后端校验 */
+    receipt: string;
+    raw?: unknown;
+}
+interface IPlatformPayment {
+    /** 拉起内购 */
+    purchase(productId: string, extra?: Record<string, unknown>): Promise<PurchaseResult>;
+    /** 查询历史未发货订单(掉单恢复) */
+    restore?(): Promise<PurchaseResult[]>;
+}
+/** 设备能力(震动 / 剪贴板 / 分享等;注意 TikTok 禁用部分 Web API,须走桥接) */
+interface IPlatformDevice {
+    vibrateShort?(): void;
+    vibrateLong?(): void;
+    setClipboard?(text: string): Promise<void>;
+    getClipboard?(): Promise<string>;
+    /** 触发平台分享 */
+    share?(payload: {
+        title?: string;
+        imageUrl?: string;
+        query?: string;
+    }): Promise<void>;
+}
+/** 平台原生埋点(可选;通常业务用 AnalyticsManager 统一上报) */
+interface IPlatformAnalytics {
+    reportEvent(name: string, params?: Record<string, unknown>): void;
+}
+/** 生命周期 */
+interface IPlatformLifecycle {
+    onShow(cb: Handler<LaunchOptions>): Unsubscribe;
+    onHide(cb: Handler<void>): Unsubscribe;
+}
+/**
+ * 平台总接口。每个平台一个实现类。
+ * 可选 capability 为 undefined 表示该平台不提供,服务层自行降级。
+ */
+interface IPlatform {
+    readonly info: PlatformInfo;
+    /** 平台初始化(读取系统信息、注入 SDK、初始化适配器) */
+    init(): Promise<void>;
+    /** 获取启动参数 */
+    getLaunchOptions(): 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;
+}
+
+export { type AdResult as A, type Handler as H, type IDisposable as I, type LaunchOptions as L, type PlatformInfo as P, type Result as R, type SafeArea as S, type Unsubscribe as U, type Vec2 as V, type HttpMethod as a, type HttpRequestOptions as b, type HttpResponse as c, type IPlatform as d, type IPlatformAds as e, type IPlatformAnalytics as f, type IPlatformAuth as g, type IPlatformDevice as h, type IPlatformLifecycle as i, type IPlatformNet as j, type IPlatformPayment as k, type IPlatformSocket as l, type IPlatformStorage as m, LogLevel as n, type LoginResult as o, type PlatformName as p, PlatformUnsupportedError as q, type PurchaseResult as r, type SocketOptions as s, type SystemInfo as t, err as u, ok as v };

package/global.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 构建期注入的全局常量(由 Vite define 提供)。
+ * 业务/底层可据此做平台分支,但平台相关实现应优先走平台抽象层而非裸判断。
+ */
+declare const __PLATFORM__: 'web' | 'tiktok' | 'wechat' | 'facebook' | 'capacitor';
+declare const __DEV__: boolean;
+/** 框架版本,构建期注入 */
+declare const __FRAMEWORK_VERSION__: string;

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@maoyugames/phaser-framework",
+  "version": "1.0.0",
+  "description": "多平台 Phaser 游戏框架:业务/底层分离,HTTP/WebSocket/KCP,Web/TikTok/微信/Facebook/App 隔离打包",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "bin": {
+    "pf": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./platform/web": {
+      "types": "./dist/platform/web.d.ts",
+      "import": "./dist/platform/web.js"
+    },
+    "./platform/tiktok": {
+      "types": "./dist/platform/tiktok.d.ts",
+      "import": "./dist/platform/tiktok.js"
+    },
+    "./platform/wechat": {
+      "types": "./dist/platform/wechat.d.ts",
+      "import": "./dist/platform/wechat.js"
+    },
+    "./platform/facebook": {
+      "types": "./dist/platform/facebook.d.ts",
+      "import": "./dist/platform/facebook.js"
+    },
+    "./platform/capacitor": {
+      "types": "./dist/platform/capacitor.d.ts",
+      "import": "./dist/platform/capacitor.js"
+    },
+    "./cli": "./dist/cli/index.js",
+    "./global": {
+      "types": "./global.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "global.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "phaser": "^3.60.0 || ^3.80.0 || ^3.90.0",
+    "vite": "^5.0.0",
+    "typescript": "^5.0.0",
+    "terser": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "terser": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "picocolors": "^1.0.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.5",
+    "@types/node": "^20.12.7",
+    "@types/fs-extra": "^11.0.4",
+    "phaser": "^3.90.0",
+    "vite": "^5.2.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  }
+}