mirror of
https://github.com/dream-pep/koring-launcher.git
synced 2026-09-12 05:45:18 +08:00
dream_pep
cd4578de5a
新增完整的程序本体资源管理与内存优化功能： 1. 新增背景图预处理服务，主进程将大图降采样至屏幕适配尺寸，避免全分辨率大图占用渲染进程大量内存 2. 实现资源注册表系统，支持引用计数、LRU自动逐出与释放回调 3. 新增资源与内存调试面板，可查看渲染进程JS堆、Electron进程内存与资源缓存状态 4. 修复进程内存信息API的单位与字段映射错误 5. 优化背景层缓存键避免过长dataURL，为Silk动画添加窗口隐藏时停帧逻辑减少GPU占用 6. 修复资源注册表类型适配问题并更新项目文档
87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
# koring-launcher
|
|
|
|
Minecraft launcher built with Electron + React 19 + TypeScript + Node.js (@xmcl).
|
|
|
|
## Quick commands
|
|
|
|
```bash
|
|
pnpm dev # full app dev (renderer + main process)
|
|
pnpm dev:renderer # frontend only (vite, port 1420)
|
|
pnpm dev:main # electron main process only
|
|
pnpm build # production build (vite + tsc)
|
|
pnpm dist:dev # dev icon + Windows installer
|
|
pnpm dist:beta # beta icon + Windows installer
|
|
pnpm dist:run # production icon + Windows installer
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **Frontend** (`src/`): React 19 + Vite 7 + Tailwind v4 + shadcn/ui + Zustand stores
|
|
- **Main Process** (`electron/`): Node.js/TypeScript, manages windows, IPC handlers, @xmcl/* packages
|
|
- **Icon System** (`public/icons/{dev,beta,run}/`): Mode-specific icons, copied to `build/` at build time
|
|
- IPC: Frontend → `ipcRenderer.invoke()` → `ipcMain.handle()` → main process → `webContents.send()` → Frontend
|
|
|
|
## Key gotchas
|
|
|
|
- **Electron main process**: `electron/main.ts` is the entry point. All @xmcl/* packages run here.
|
|
- **Preload script**: `electron/preload.ts` exposes `window.electronAPI` via context bridge.
|
|
- **IPC handlers**: All handlers are in `electron/handlers/` directory.
|
|
- **Mutable win ref**: `electron/main.ts` uses a mutable `win` object — handlers read `win.mainWindow` at runtime, not at registration time.
|
|
- **Config**: YAML format (`Koring.yml`) stored next to executable. Sparse save (only non-default values).
|
|
- **Auth**: JSON file (`koring-auth.json`) stored next to executable.
|
|
- **Path alias**: `@/` maps to `src/` (configured in `vite.config.ts` and `tsconfig.json`).
|
|
- **Dev mode**: Vite runs on port 1420, Electron loads from localhost.
|
|
- **Asset paths**: Use `import.meta.env.BASE_URL` prefix for public assets. Absolute paths break in packaged app.
|
|
|
|
## Build & bundle
|
|
|
|
```bash
|
|
pnpm build # Vite build + TypeScript compile
|
|
pnpm dist:dev # switch-icon dev + electron-builder Windows installer
|
|
pnpm dist:beta # switch-icon beta + electron-builder Windows installer
|
|
pnpm dist:run # switch-icon run + electron-builder Windows installer
|
|
```
|
|
|
|
Each `dist:*` command runs: `pnpm build` → `pnpm icon:{mode}` → `electron-builder --win`
|
|
|
|
## Icon switching
|
|
|
|
```
|
|
public/icons/
|
|
dev/icon.ico, icon.png
|
|
beta/icon.ico, icon.png
|
|
run/icon.ico, icon.png
|
|
|
|
build/ ← generated by switch-icon.js (gitignored)
|
|
icon.ico
|
|
icon.png
|
|
```
|
|
|
|
`electron-builder.yml` uses `buildResources: build` to read icons from `build/`.
|
|
|
|
## Electron notes
|
|
|
|
- `electron/main.ts`: App entry, window management, splash→main transition (ready-to-show + 1.5s min)
|
|
- `electron/preload.ts`: Context bridge for secure IPC
|
|
- `electron/config.ts`: YAML config management (sparse save)
|
|
- `electron/auth.ts`: Auth data persistence (JSON file)
|
|
- `electron/core/`: @xmcl/* integrations (auth, installer, launcher, modrinth, instance)
|
|
- `electron/core/background-image.ts`: 背景图处理服务（自选背景降采样/重编码，程序本体资源管理）
|
|
- `electron/handlers/`: IPC handlers (config, auth, install, launch, mods, instance, background, task, system, window)
|
|
|
|
## Frontend notes
|
|
|
|
- `src/api/ipc.ts`: Core IPC utilities (invoke, onIpcEvent)
|
|
- `src/api/*.ts`: API modules wrapping IPC calls
|
|
- `src/stores/`: Zustand state management
|
|
- `src/resources/`: 启动器程序本体「资源管理」子系统（与游戏无关）：
|
|
- `registry.ts` 资源注册表服务（acquire/release、引用计数、预算 + LRU 逐出、onRelease 释放回调）
|
|
- `store.ts` 注册表 → zustand 镜像（调试面板消费）
|
|
- `image.ts` 图片解码管线（按显示尺寸降采样）、`hooks.ts`/`ManagedImage.tsx` 复用组件（供列表缩略图）
|
|
- 当前接线点：`BackgroundLayer` 把当前背景登记为 `background` 类资源；主进程 `background:prepare` 在进渲染端前压小大图
|
|
- 监控入口：debug 页「资源与内存」(`debug-resource`)
|
|
- `src/hooks/useTheme.ts`: Dark mode sync with Electron theme
|
|
- `src/components/system/WindowControls.tsx`: Custom window controls (min/max/close), uses `<button>` with `WebkitAppRegion: "no-drag"`
|
|
- `src/components/system/TitleBar.tsx`: Custom title bar with navigation, uses `WebkitAppRegion: "drag"`
|
|
- `src/lib/mode.ts`: Build mode constants (`DEFAULT_BG`, `LOGO_SVG`, `APP_ICON`, `BUILD_MODE`)
|