《游戏引擎实现原理》4.3 桌面打包与可选原生路径

// file: src/app/desktop-host.ts
// tier: L3
//
// 桌面壳的接口草图（仅类型）：Electron / Tauri / 纯 Node 都实现同一份
// DesktopHost，游戏代码只依赖这个接口，不 import 任何 electron / tauri 模块。
// 本节需在真实设备上打包并运行才能验证，命令行不可复现——这里只给类型与配置产物。

export type DesktopShell = 'electron' | 'tauri' | 'node';

export interface WindowOptions {
  readonly title: string;
  readonly width: number;
  readonly height: number;
  readonly resizable: boolean;
  readonly fullscreen: boolean;
}

export interface FileFilter {
  readonly name: string;
  readonly extensions: readonly string[];
}

/** 桌面原生能力的最小面：窗口、文件对话框、退出。 */
export interface DesktopHost {
  readonly shell: DesktopShell;
  createWindow(opts: WindowOptions): Promise<void>;
  openFile(filters: readonly FileFilter[]): Promise<string | null>;
  saveFile(defaultName: string): Promise<string | null>;
  quit(): void;
}

/** 渲染进程 <-> 主进程的唯一通道：只允许这几种消息过桥。 */
export type HostMessage =
  | { readonly kind: 'openFile'; readonly filters: readonly FileFilter[] }
  | { readonly kind: 'saveFile'; readonly defaultName: string }
  | { readonly kind: 'quit' };

export interface HostReply {
  readonly kind: 'path' | 'cancelled' | 'ok';
  readonly path?: string;
}

/** 把窗口选项翻译成 Electron BrowserWindow 的配置对象。 */
export function electronWindowConfig(opts: WindowOptions): Record<string, unknown> {
  return {
    title: opts.title,
    width: opts.width,
    height: opts.height,
    resizable: opts.resizable,
    fullscreen: opts.fullscreen,
    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
  };
}

/** 同一份窗口选项翻译成 Tauri window 配置；字段名不同、语义一致。 */
export function tauriWindowConfig(opts: WindowOptions): Record<string, unknown> {
  return {
    title: opts.title,
    width: opts.width,
    height: opts.height,
    resizable: opts.resizable,
    fullscreen: opts.fullscreen,
  };
}

{
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "glimmer-isle",
  "version": "1.0.0",
  "identifier": "com.helio.glimmerisle",
  "build": {
    "frontendDist": "../dist",
    "beforeBuildCommand": "npm run build:web"
  },
  "app": {
    "windows": [
      { "title": "微光岛", "width": 1280, "height": 720, "resizable": true }
    ],
    "security": { "csp": "default-src 'self'" }
  },
  "bundle": {
    "active": true,
    "targets": ["dmg", "app", "msi", "appimage"]
  }
}

{
  "appId": "com.helio.glimmerisle",
  "productName": "微光岛",
  "files": ["dist/**/*", "main.mjs"],
  "directories": { "output": "release" },
  "mac": { "target": "dmg", "category": "public.app-category.games" },
  "win": { "target": "nsis" },
  "linux": { "target": "AppImage" }
}

// snippet: 原生能力必须可缺省——探测不到就走纯 Web 实现
export function resolveHost(): DesktopHost | null {
  if (typeof (globalThis as { __helioHost?: unknown }).__helioHost !== 'undefined') {
    return (globalThis as { __helioHost?: DesktopHost }).__helioHost ?? null;
  }
  return null; // 浏览器：无桌面壳，调用方走 Web 兜底
}

// snippet: Electron 主进程实现 DesktopHost（需真实 Electron 环境，L4）
import { app, BrowserWindow, dialog, ipcMain } from 'electron';

const host = {
  shell: 'electron',
  createWindow: (opts) => {
    const win = new BrowserWindow(opts);
    win.loadFile('dist/index.html');
    return Promise.resolve();
  },
  openFile: (filters) => dialog.showOpenDialog({ filters }).then((r) => r.filePaths[0] ?? null),
  saveFile: (name) => dialog.showSaveDialog({ defaultPath: name }).then((r) => r.filePath ?? null),
  quit: () => app.quit(),
};
ipcMain.handle('helio:host', () => host);

// file: src/app/save-bridge.ts
// tier: L1
// verify: npx vitest run src/app/save-bridge.test.ts
//
// 存档桥：游戏只依赖 SaveBridge，桌面壳给原生实现（文件系统），
// 浏览器给 Web 实现。这里给出纯逻辑：槽位命名 + 内存兜底实现 + 选择器。
// 真正读写文件的那部分属 L3/L4，命令行不可复现。

export interface SaveBridge {
  readonly backend: 'native' | 'web';
  read(slot: string): Promise<string | null>;
  write(slot: string, data: string): Promise<void>;
  list(): Promise<readonly string[]>;
}

/** 槽位命名：前缀 + 三位补零，保证字典序等于序号序。 */
export function slotName(index: number): string {
  if (!Number.isInteger(index) || index < 0) throw new RangeError(`slot index: ${index}`);
  return `glimmer-isle-${String(index).padStart(3, '0')}`;
}

/** 浏览器兜底实现：内存 Map；真实工程换成 IndexedDB 持久化。 */
export function makeWebSaveBridge(store: Map<string, string> = new Map()): SaveBridge {
  return {
    backend: 'web',
    read: (slot) => Promise.resolve(store.get(slot) ?? null),
    write: (slot, data) => {
      store.set(slot, data);
      return Promise.resolve();
    },
    list: () => Promise.resolve([...store.keys()].sort()),
  };
}

/** 有原生桥就用原生，没有就退回 Web 实现——原生能力必须可缺省。 */
export function pickSaveBridge(nativeBridge: SaveBridge | undefined): SaveBridge {
  return nativeBridge ?? makeWebSaveBridge();
}