@@ -1,193 +1,614 @@
# Koring Launcher
<p align="center">
<img src="public/icons/run/icon.png" width="96" alt="Koring Launcher" />
</p>
Minecraft launcher built with Electron + React 19 + TypeScript + Node.js (@xmcl ).
<h1 align="center">Koring Launcher</h1>
<p align="center">
A modern Minecraft launcher for Windows · 基于 Electron + React 的现代化 Minecraft 启动器
</p>
<p align="center">
<a href="https://github.com/dream-pep/koring-launcher/releases"><img src="https://img.shields.io/github/v/release/dream-pep/koring-launcher?display_name=release&label=Release&logo=github&color=4c6ef5" alt="Release"></a>
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-8a94a6" alt="Platform">
<img src="https://img.shields.io/badge/Electron%2033%20%C2%B7%20React%2019%20%C2%B7%20TypeScript-20242e" alt="Electron · React · TypeScript">
<img src="https://img.shields.io/badge/license-LL--1.0-7d5fb8" alt="License">
<a href="https://github.com/dream-pep/koring-launcher/actions/workflows/release.yml"><img src="https://github.com/dream-pep/koring-launcher/actions/workflows/release.yml/badge.svg" alt="Build & Release"></a>
</p>
<p align="center">
<a href="https://github.com/dream-pep/koring-launcher"><img src="https://img.shields.io/github/stars/dream-pep/koring-launcher?style=social" alt="Stars"></a>
</p>
---
# 中文文档
- [项目简介 ](#项目简介 )
- [功能特性 ](#功能特性 )
- [界面预览 ](#界面预览 )
- [快速开始 ](#快速开始 )
- [开发指南 ](#开发指南 )
- [构建与发布 ](#构建与发布 )
- [技术架构 ](#技术架构 )
- [目录结构 ](#目录结构 )
- [版本与自动更新 ](#版本与自动更新 )
- [路线图 ](#路线图 )
- [贡献指南 ](#贡献指南 )
- [许可证 ](#许可证 )
---
## 项目简介
**Koring Launcher ** 是一款面向现代 Windows 桌面的 Minecraft 启动器，采用
**Electron + React 19 + TypeScript ** 构建，游戏侧核心能力基于成熟的
[@xmcl ](https://github.com/Voxelum/xmcl ) 开源生态（安装、启动、任务）。
项目强调**流畅的桌面体验**与**工程化的进程架构**：自定义无边框窗口与启动画面、
三层层级 UI、主进程权威的配置体系、内置资源注册表与内存管理，以及 beta/run 双通道
自动更新。代码库以「渲染进程薄、主进程权威」为原则，所有游戏相关能力
（ @xmcl 、文件系统、进程管理）均运行于 Electron 主进程，渲染进程只通过类型安全的
IPC 与主进程通信。
> **状态**：项目处于积极开发与内测阶段（`beta` / `run` 双通道发布）。主框架与核心
> 流程稳定可用，部分 UI 模块（见 [路线图](#路线图)）仍在打磨。
## 功能特性
**桌面体验 **
- 自定义**无边框窗口**：自绘标题栏（毛玻璃）与窗口控制，深浅色模式自动适配
- 独立的 **Splash 启动画面 ** （ × `ready-to-show` + 最短停留时间过渡）
- **三层层级 UI**：背景层 / 内容层 / 系统层，页面间使用 View Transitions 过渡
- 内置**隐藏调试页**（ `debug-*` 路由）：显示、更新、任务、资源与内存等专项调试
**游戏能力（基于 @xmcl） **
- **统一配置驱动启动**：主进程读取权威配置，自动映射为 `LaunchOption`
（
支持启动事件推送与 `afterLaunch` 窗口处理
- **Java 自动检测与路径校验**（`java:scan` / `java:resolve` ）
- **实例系统**：主库实例 + 游戏目录批量导入（幂等、目录变更自动重扫）
- **Mod 生态**：
- **账号体系**：Koring 账号、离线账号（规范离线 UUID），微软 OAuth 核心已接入
- 任务系统：安装 / 下载进度统一通过主进程任务队列（`task:*` ）推进，UI 可查看队列
**配置与个性化 **
- **主进程权威配置**： （ `Koring.yml` ），深度合并 + 稀疏写盘 + 变更广播
- **设置中心**（参考 PCL2 的分组结构）：游戏（账号 / Java / 目录 / 高级）、
个性化（主题背景 / 主界面 / 语言 / 无障碍）、网络（下载 / 安全识别）等均已接入
- **背景系统**：颜色 / 渐变 / 模糊 / 自选壁纸；自选壁纸由主进程按屏幕尺寸降采样并
落盘存储，经 `koring-res://` 特权协议流式读取（**全程无 base64**），并纳入
**资源注册表**统一管理（引用计数、预算 + LRU 逐出）
- **引导流程**：首次启动 OOBE 向导（语言 / 协议 / 登录 / 版本）与更新后引导（UPvP），
「关于此版本」将 GitHub Release Notes 按新增 / 修复 / 优化等**分类卡片化**展示
- **意见反馈**：设置 → 服务与反馈内置 HeroUI 反馈按钮，点击在系统浏览器打开 YouTrack 反馈表单
（ `components/feedback/FeedbackButton` ，直链 `lingke.youtrack.cloud/form/<uuid>` ）
- **设备识别码**：关于页展示设备唯一标识 —— 由硬件指纹（主板 UUID / 硬盘序列号 / BIOS 序列号，过滤 OEM 占位值）
优先取源，缺失时回退注册表 `MachineGuid` ，经 SHA-256 生成 UUID 样式标识（`electron/core/device-id.ts` ，进程内缓存）
## 界面预览
> 截图整理中 —— 欢迎将截图放入 `docs/screenshots/` 后在此展示。
<!--
示例：
<img src="docs/screenshots/home.png" width="720" alt="主界面" />
-->
## 快速开始
**面向用户 ** ：从 [GitHub Releases ](https://github.com/dream-pep/koring-launcher/releases )
下载最新安装包（NSIS 安装器，可自选安装目录）。目前发布管线产出 Windows 安装程序，
macOS（ （
**开发环境要求 **
| 依赖 | 版本 | 说明 |
| --- | --- | --- |
| OS | Windows 10/11（ ）
| Node.js | ≥ 20.19（ ）
| pnpm | ≥ 9（ ）
> 国内网络环境：仓库 `.npmrc` 已配置 Electron 二进制走 npmmirror 镜像，
> 可避免 Electron 下载超时。
``` bash
# 安装依赖
pnpm install
# 开发（完整应用：Vite dev server :1420 + Electron）
pnpm dev
# 仅渲染进程（HMR，端口 1420）/ 仅主进程
pnpm dev:renderer
pnpm dev:main
```
## 开发指南
常用脚本一览（完整说明见 `DEV.md` 与 `AGENTS.md` ）：
| 命令 | 说明 |
| --- | --- |
| `pnpm dev` | 完整开发环境（先编译主进程，再并行启动 Vite + Electron）
| `pnpm dev:renderer` | 仅渲染进程（Vite HMR，端口 1420）
| `pnpm dev:main` | 仅主进程（`tsc` 编译后启动 Electron）
| `pnpm build:renderer:{dev,beta,run}` | 按模式构建渲染进程 |
| `pnpm build:main` | 编译主进程 TypeScript |
| `pnpm build:{dev,beta,run}` | 对应模式的完整构建（渲染进程 + 主进程） |
| `pnpm preview` | 预览 Vite 产物 |
| `pnpm version:set` | 设置版本号（单一事实源为 `package.json` ）
| `pnpm pack` | `electron-builder --dir` （未打包目录产物） |
| `pnpm dist` / `dist:win` / `dist:mac` / `dist:linux` | electron-builder 按目标平台打包 |
**开发要点速览 **
- `@/` 路径别名映射到 `src/` （同时配置于 `vite.config.ts` 与 `tsconfig.json` ）
- 渲染进程公共资源路径须使用 `import.meta.env.BASE_URL` 前缀（打包后绝对路径失效）
- 所有 `@xmcl/*` 、文件系统与子进程能力运行于主进程；渲染进程经
`ipcRenderer.invoke()` → `ipcMain.handle()` 调用，方向性事件经 `webContents.send()` 推送
- 主进程配置为唯一权威：渲染端只提交补丁，不直接写盘（详见「配置存储」）
- HeroUI 3（基于 react-aria）控件使用 `onChange` ， `onValueChange` 已移除
- 窗口拖拽需使用内联样式 `WebkitAppRegion: "drag"` （
## 构建与发布
### 构建模式
项目支持三种构建模式，通过环境文件（`.env.development` / `.env.beta` /
`.env.production` ）注入，并配套**切换图标**（exe / 安装器图标随模式不同）：
| 模式 | Vite mode | 图标目录 | 用途 |
| --- | --- | --- | --- |
| `dev` | `development` | `public/icons/dev/` | 日常开发 |
| `beta` | `beta` | `public/icons/beta/` | 内测发布 |
| `run` | `production` | `public/icons/run/` | 正式发布 |
``` bash
pnpm dist:dev # build:dev → icon:dev → electron-builder --win
pnpm dist:beta # build:beta → icon:beta → electron-builder --win
pnpm dist:run # build:run → icon:run → electron-builder --win
```
打包流程：模式构建 → `scripts/switch-icon.js` 将对应图标复制到 `build/`
（ `buildResources` ）→ electron-builder 产出 NSIS 安装程序，
产物位于 `dist-electron/koring-launcher-{version}-setup.exe` 。
### 发布流水线（GitHub Actions）
`.github/workflows/release.yml` 手动触发（选择 `beta` / `run` 模式）：
1. 从 `package.json` 读取基础版本号，附加 **BUILD ID ** （ ，
严格递增）生成最终版本：`{base}-beta.{buildId}` （ `{base}-{buildId}` （ ）
2. `pnpm build:{mode}` + `pnpm icon:{mode}` （
3. `electron-builder --win` ，经 **SignPath 远程签名 ** （无 `SIGNPATH_API_TOKEN`
时自动跳过，本地构建不受影响；仅对 sha256 签名以节省配额）
4. 生成中文发布说明并发布 GitHub Release：
`latest-beta.yml` ， `latest.yml` （
### 配置存储（主进程权威）
- **`Koring.yml` **：打包后存 `app.getPath('userData')` （ `%APPDATA%/Koring Launcher/` ），
开发模式存项目根目录；旧版 exe 旁文件首次启动自动迁移
- 主进程内存缓存为唯一权威：渲染端经 `config:update` 提交补丁 → 主进程深度合并 →
300ms debounce **稀疏写盘 ** （仅写非默认值）→ 广播 `config:changed` 同步渲染端镜像
- **`koring-auth.json` **（账号数据）与崩溃日志采用相同存储策略
- ⚠️ 数据文件不可放入安装目录：NSIS 重装 / 升级会经旧卸载器删除整个安装目录
## 技术架构
```
┌────────────────────────── Renderer (React 19) ─────────────────────────┐
│ pages / components / stores (Zustand) resources (注册表+LRU) │
│ │ ipcRenderer.invoke() ▲ ipcMain.handle() │
│ ▼ │ webContents.send() (方向性事件) │
├────────────────────────── Main Process (Electron / Node) ──────────────┤
│ handlers/* ── config.ts (YAML 权威) · auth.ts · updater.ts │
│ core/* ── @xmcl/core · @xmcl/installer · @xmcl/task │
│ launch-options (配置→LaunchOption) │
│ resource-protocol.ts koring-res://（白名单流式读取，realpath 校验） │
└────────────────────────────────────────────────────────────────────────┘
```
- **IPC 流**：渲染进程 `invoke` → 主进程 `handle` → 处理完成返回；主进程主动事件
经 `webContents.send` 推送给渲染端（如 `config:changed` 、`launch:event` ）
- **可变的 `win` 引用**： `main.ts` 使用可变 `win` 对象，各 handler 在运行时读取
`win.mainWindow` ，而非注册时捕获
- **`koring-res://` **：特权自定义协议，仅服务 userData 内
`background-custom*` 白名单文件（realpath 二次校验，防目录穿越），
用于渲染进程「按引用」流式读取本地壁纸，避免 base64 膨胀内存
- **背景图处理**：自选壁纸由主进程复制到 userData，并按屏幕尺寸降采样 / 重编码
**落盘 ** ；配置文件只存文件路径
- **资源注册表**（ `src/resources/` ）：acquire / release 引用计数、预算 + LRU 逐出、
onRelease 释放回调；图片按显示尺寸降采样，供列表缩略图复用
## 目录结构
```
koring-launcher/
├─ electron/ # 主进程（Electron，
│ ├─ main.ts # 入口：窗口管理、splash→主界面过渡
│ ├─ preload.ts # contextBridge 暴露 window.electronAPI
│ ├─ config.ts # YAML 配置（权威、稀疏写盘、迁移）
│ ├─ auth.ts · updater.ts · resource-protocol.ts
│ ├─ core/ # @xmcl 集成与业务核心
│ │ ├─ auth.ts · koring-auth.ts · installer.ts · launcher.ts
│ │ ├─ launch-options.ts · modrinth.ts · instance.ts
│ │ ├─ task.ts · paths.ts · background-image.ts · crash-logger.ts
│ └─ handlers/ # IPC 处理器（config/auth/install/launch/java/
│ # mods/instance/background/task/system/update/
│ # koring-auth/crash-monitor/window）
├─ src/ # 渲染进程（React 19）
│ ├─ api/ # IPC 类型封装
│ ├─ components/ # background/ system/ setting/ task/
│ │ # about-version/ ui/ (shadcn) …
│ ├─ pages/ # home · gallery · store · today · play-link ·
│ │ # setting(分组子页) · oobe · upvp · update ·
│ │ # task-queue · crash · debug
│ ├─ resources/ # 资源注册表（引用计数/预算/LRU）与图片解码管线
│ ├─ stores/ # Zustand 状态（config/auth/theme/route/launch…）
│ ├─ layouts/ · hooks/ · lib/ (mode/buildInfo/version) · assets/ · types/
│ ├─ App.tsx · main.tsx · index.css
├─ public/ # 静态资源：icons/{dev,beta,run}/、背景、字体
├─ scripts/ # switch-icon · version · gen-build-info ·
│ # signpath-sign · release-notes …
├─ docs/ · DEV.md · AGENTS.md # 开发文档与仓库约定
├─ electron-builder.yml # appId / 打包目标 / NSIS / 签名配置
├─ vite.config.ts · tsconfig*.json · .env.{development,beta,production}
└─ package.json # 版本单一事实源
```
## 版本与自动更新
- **版本单一事实源**： `package.json` 的 `version` 字段（`scripts/version.js`
`get` / `set` ），本地与 CI 共用，消除双轨
- **版本号格式**： `{base}` （
`{base}-beta.{buildId}` （ `{base}-{buildId}` （
- **自动更新**： `electron-updater` + GitHub provider； `latest.yml` ，
beta 通道读 `latest-beta.yml` ；客户端开启 `allowPrerelease` 以接收带构建号的
beta 更新
- ⚠️ 若切换构建号方案（时间戳 → Run Number），旧版数值更大，老用户不会自动
升级，需同步提升 base 版本（详见 `docs/auto-update-plan.md` ）
## 路线图
- [ ] **实例中心 / 资源中心 UI ** ：完整实现已就绪，暂以占位页收尾打磨后放开
（
- [ ] **微软账号登录 UI ** ：
- [ ] **以太 / 陶瓦联机页 ** ：目前为占位
- [ ] macOS（ （ ）
- [ ] 多语言（`app.language` 偏好已定义，UI 文案逐步外置）
## 贡献指南
欢迎提交 Issue 与 Pull Request：
1. Fork 本仓库并以 `master` 为基线创建功能分支
2. 遵循仓库现有风格（TypeScript 严格模式、组件/处理器分层），
提交信息建议使用约定式（`feat:` / `fix:` / `docs:` / `refactor:` …）
3. 修改渲染进程前先阅读 [AGENTS.md ](AGENTS.md )（架构约束与注意点）
与 [DEV.md ](DEV.md )（开发说明）
4. 涉及图标 / 安装器的改动请分别验证三种构建模式（`dist:dev/beta/run` ）
## 许可证
本项目使用自定义 **LingkeLice 1.0（ ） ** 许可证，版权归
**Shenzhen Lingke Network Technology Co., Ltd.（深圳灵科网络科技有限公司） ** 所有。
要点：**非商业用途**可自由使用、复制、修改与分发（含并入其他项目）；任何
**商业用途 ** （含集成进商业产品、商业化提供服务、直接 / 间接获利）须事先获得
版权所有者的**书面授权**。详见 [LICENSE ](LICENSE )。
商业授权请联系 Shenzhen Lingke Network Technology Co., Ltd.
---
# English Version
- [Introduction ](#introduction )
- [Features ](#features )
- [Screenshots ](#screenshots )
- [Quick Start ](#quick-start )
- [Development ](#development )
- [Build & Release ](#build--release )
- [Architecture ](#architecture )
- [Project Structure ](#project-structure )
- [Versioning & Auto-Update ](#versioning--auto-update )
- [Roadmap ](#roadmap )
- [Contributing ](#contributing )
- [License ](#license )
## Introduction
**Koring Launcher ** is a modern Minecraft launcher for Windows built with
**Electron + React 19 + TypeScript ** , with game-side capabilities powered by the
mature [@xmcl ](https://github.com/Voxelum/xmcl ) ecosystem (install, launch, task).
The project favors a * thin renderer, authoritative main process * architecture:
game-related features (@xmcl , filesystem, subprocesses) all run in the Electron
main process, while the renderer talks to it only through type-safe IPC. Notable
engineering practices include a custom frameless window and splash screen,
a three-layer UI model, main-process-authoritative configuration, a built-in
resource registry with memory management, and dual-channel (beta/run) auto-update.
> **Status**: under active development with public beta/run releases. The core
> framework and main flows are stable; a few UI modules are being polished
> (see [Roadmap](#roadmap)).
## Features
**Desktop experience **
- Custom **frameless window ** : glassmorphism title bar and window controls,
automatic dark/light mode
- Standalone **splash screen ** (480×
`ready-to-show` + minimum-duration transition)
- **Three-layer UI** (background / content / system) with View Transitions
- Hidden **debug pages ** (`debug-*` routes) for display, update, task, and
resource/memory inspection
**Game capabilities (via @xmcl) **
- **Config-driven unified launch**: the main process maps authoritative config
to `LaunchOption` (Java path, memory, GC, JVM args, window, pre-launch
commands), with launch event streaming and `afterLaunch` window handling
- **Java auto-detection & validation** (`java:scan` / `java:resolve` )
- **Instance system**: instances in the main library + bulk import from an
existing game directory (idempotent, auto-rescan on directory change)
- **Mod ecosystem**: Modrinth / CurseForge search & install modules
- **Accounts**: Koring account, offline login (spec-compliant offline UUID),
Microsoft OAuth core integrated
- **Task system**: install / download progress flows through a main-process
task queue (`task:*` ) with a visible UI queue
**Configuration & personalization **
- **Main-process-authoritative config**: YAML (`Koring.yml` ), deep merge +
sparse save + change broadcast
- **Settings center** (PCL2-inspired groups): game (account / Java / directory /
advanced), personalization (theme & background / UI / language / a11y),
network (download / security ID), etc.
- **Background system**: color / gradient / blur / custom wallpaper. Custom
wallpapers are downsampled to screen size and stored **on disk ** by the main
process, streamed via the privileged `koring-res://` protocol (**no base64**),
and managed by a **resource registry ** (ref-counting, budget + LRU eviction)
- **Onboarding flows**: first-launch OOBE wizard (language / agreement / login /
version) and post-update wizard (UPvP); “About this version” renders GitHub
release notes as categorized cards (added / fixed / improved / …)
## Screenshots
> Coming soon — contributions welcome: drop screenshots into `docs/screenshots/`
> and reference them here.
<!--
e.g. <img src="docs/screenshots/home.png" width="720" alt="Home" />
-->
## Quick Start
**End users ** : download the latest installer from
[GitHub Releases ](https://github.com/dream-pep/koring-launcher/releases ) (NSIS,
custom install directory). The release pipeline currently publishes Windows
setups; macOS (DMG) and Linux (AppImage) targets are configured and will be
opened up in CI gradually.
**Development requirements **
| Dependency | Version | Notes |
| --- | --- | --- |
| OS | Windows 10/11 (x64) | Primary development & target platform |
| Node.js | ≥ 20.19 (CI uses 22) | Required by Vite 7 |
| pnpm | ≥ 9 (CI uses 11.7) | Package manager (pnpm workspace) |
> In China, `.npmrc` already redirects Electron binaries to the npmmirror
> mirror to avoid download timeouts.
``` bash
pnpm install
pnpm dev # full app (frontend + electron)
pnpm dev:renderer # frontend only (v ite, port 1420 )
pnpm dev:main # electron main process only
# Full app dev (V ite :1420 + Electron )
pnpm dev
pnpm dev:renderer # renderer only (HMR, port 1420)
pnpm dev:main # main process only
```
## Build
## Development
Common scripts (full details in `DEV.md` and `AGENTS.md` ):
| Command | Description |
| --- | --- |
| `pnpm dev` | Full dev environment (compile main, then Vite + Electron) |
| `pnpm dev:renderer` | Renderer only (Vite HMR, port 1420) |
| `pnpm dev:main` | Main process only (`tsc` then launch Electron) |
| `pnpm build:renderer:{dev,beta,run}` | Build renderer for a mode |
| `pnpm build:main` | Compile main-process TypeScript |
| `pnpm build:{dev,beta,run}` | Full build for a mode (renderer + main) |
| `pnpm preview` | Preview the Vite build |
| `pnpm version:set` | Set the version (`package.json` is the single source) |
| `pnpm pack` | `electron-builder --dir` (unpacked output) |
| `pnpm dist` / `dist:win` / `dist:mac` / `dist:linux` | Package for a target |
**Quick notes **
- `@/` maps to `src/` (in both `vite.config.ts` and `tsconfig.json` )
- Public assets in the renderer must use the `import.meta.env.BASE_URL` prefix
(absolute paths break when packaged)
- All `@xmcl/*` , filesystem and subprocess code lives in the main process; the
renderer calls via `ipcRenderer.invoke()` → `ipcMain.handle()` , and
directional events are pushed with `webContents.send()`
- Main-process config is authoritative — the renderer submits patches, never
writes files directly
- HeroUI 3 (built on react-aria) controls use `onChange` (`onValueChange`
no longer exists)
- Window dragging requires the inline style `WebkitAppRegion: "drag"`
(Electron only honors the CSS property)
## Build & Release
### Build modes
Three build modes are driven by env files (`.env.development` / `.env.beta` /
`.env.production` ) and each ships its **own icon set ** for the exe and
installer:
| Mode | Vite mode | Icon dir | Purpose |
| --- | --- | --- | --- |
| `dev` | `development` | `public/icons/dev/` | Daily development |
| `beta` | `beta` | `public/icons/beta/` | Beta release |
| `run` | `production` | `public/icons/run/` | Production release |
``` bash
pnpm build # produ cti on build (vite + tsc)
pnpm dist:dev # dev icon + Windows installer
pnpm dist:beta # beta icon + Windows installer
pnpm dist:run # production icon + Windows installer
pnpm dist:mac # build macOS DMG
pnpm dist:linux # build Linux AppImage
pnpm dist:dev # build:dev → icon:dev → ele ctr on- builder --win
pnpm dist:beta # build:beta → icon:beta → electron-builder --win
pnpm dist:run # build:run → icon:run → electron-builder --win
```
Pipeline: mode build → `scripts/switch-icon.js` copies the mode icons into
`build/` (electron-builder’ `buildResources` ) → electron-builder produces an
NSIS installer at `dist-electron/koring-launcher-{version}-setup.exe` .
### Release pipeline (GitHub Actions)
`.github/workflows/release.yml` is triggered manually with a `beta` / `run` mode:
1. Read the base version from `package.json` , append a **BUILD ID **
(GitHub Run Number, strictly increasing): `{base}-beta.{buildId}` (beta) or
`{base}-{buildId}` (run)
2. `pnpm build:{mode}` + `pnpm icon:{mode}`
3. `electron-builder --win` with **SignPath remote signing ** (auto-skipped when
`SIGNPATH_API_TOKEN` is absent; sha256-only to save quota)
4. Generate Chinese release notes and publish a GitHub Release: beta releases
are prereleases that also upload `latest-beta.yml` ; run releases are stable
and upload `latest.yml` (the electron-updater manifest)
### Config storage (main-process authoritative)
- **`Koring.yml` **: stored under `app.getPath('userData')`
(`%APPDATA%/Koring Launcher/` ) when packaged, or in the project root in dev;
legacy files next to the old exe are auto-migrated on first launch
- The in-memory cache in the main process is the single source of truth:
renderer submits a patch via `config:update` → deep merge → 300 ms debounced
**sparse write ** (non-default values only) → broadcast `config:changed`
- **`koring-auth.json` ** (account data) and crash logs follow the same policy
- ⚠️ Never store data files inside the install directory: NSIS reinstall /
upgrade removes the whole directory via the old uninstaller
## Architecture
```
src/ Frontend (React 19 + Vite 7 + Tailwind v4 + shadcn/ui + Zustand)
electron/ Main pro cess (Node.js/TypeScript, @xmcl/* packages)
public/ Static assets (icons, fonts, images)
build/ Build resources (generated, gitignored)
┌────────────────────────── Renderer (React 19) ─────────────────────────┐
│ pages / components / stores (Zustand) resour ces (registry+LRU) │
│ │ ipcRenderer.invoke() ▲ ipcMain.handle() │
│ ▼ │ webContents.send() (directional) │
├────────────────────────── Main Process (Electron / Node) ──────────────┤
│ handlers/* ── config.ts (YAML authority) · auth.ts · updater.ts │
│ core/* ── @xmcl/core · @xmcl/installer · @xmcl/task │
│ launch-options (config → LaunchOption) │
│ resource-protocol.ts koring-res:// (whitelist streaming, realpath) │
└────────────────────────────────────────────────────────────────────────┘
```
**IPC F low: **
Frontend → `ipcRenderer.invoke()` → `ipcMain.handle()` → main process → `webContents.send()` → Frontend
**Config storage (main-process authoritative): **
- `Koring.yml` — 打包后存 `app.getPath('userData')` （ `%APPDATA%/Koring Launcher/` ），开发模式在项目根目录；旧版 exe 旁文件首次启动自动迁移
- 主进程内存缓存为唯一权威：渲染进程通过 `config:update` 提交补丁，主进程深度合并 → 300ms debounce 稀疏写盘 → 广播 `config:changed` 同步渲染端镜像
- `koring-auth.json` / `koring-crash.log` 与配置同策略（打包后 userData）
- f low**: renderer `invoke` → main `handle` → result returns; the main
process pushes directional events (e.g. `config:changed` , `launch:event` )
via `webContents.send`
- **Mutable `win` reference**: `main.ts` keeps a mutable `win` object, and
handlers read `win.mainWindow` at runtime instead of capture time
- ** `koring-res://` **: privileged custom protocol serving only whitelisted
`background-custom*` files inside userData (realpath double-check against
path traversal) so the renderer can stream local wallpapers by reference
- **Wallpaper pipeline**: custom wallpapers are copied into userData,
downsampled/re-encoded to screen size and written **to disk ** ; the config
stores only the file path
- **Resource registry** (`src/resources/` ): acquire/release ref-counting,
budget + LRU eviction, onRelease callbacks; images are decoded at display
size and shared by list thumbnails
## Project Structure
```
src /
├── api / # Frontend API layer (IPC wrapp ers )
│ ├── ipc .ts # Core IPC utilities
│ ├── background.ts # Background control
│ ├── install.ts # Minecraft install
│ ├─ ─ l aunc h.ts # Game launch
│ ├── auth.ts # Microsoft/offline auth
│ ├── mods.ts # Modrinth/CurseForge
│ └── instance.ts # Instance management
├── stores/ # Zustand state store s
├── components /
│ ├── background/ # Background layer (z-0)
│ ├── system/ # Title bar + window controls (z-100 )
│ └── ui/ # shadcn/ui components
├── layouts/
│ └── RootLayout.tsx # Three-layer page structure
├── pages/
│ ├── Home.tsx # Main page
│ └── Debug.tsx # Debug tools
├── lib/
│ ├── mode.ts # Build mode constants (DEFAULT_BG, LOGO_SVG, APP_ICON)
│ └── utils.ts # cn() helper
└── App.tsx # Root component with state router
electron/
├── main.ts # Electron entry, window management, splash→main transition
├── preload.ts # Context bridge (window.electronAPI)
├── config.ts # YAML config management (main-process authoritative, debounce sparse save)
├── auth.ts # Auth data persistence
├── core/ # @xmcl/* integrations
│ ├── auth.ts # Microsoft OAuth, Xbox Live, MC auth
│ ├── installer.ts # @xmcl/installer
│ ├── launcher.ts # Unified game launcher (@xmcl/core launch + config-driven)
│ ├── launch-options.ts # Config → LaunchOption mapping (parseArgs/buildLaunchOptions/resolveJavaPath)
│ ├── modrinth.ts # Modrinth/CurseForge API
│ └── instance.ts # Instance management
├── handlers/ # IPC handlers
│ ├── config.ts # Config load/save/update (config:get/update/save + config:changed broadcast)
│ ├── auth.ts # Auth operations
│ ├── install.ts # Install operations
│ ├── launch.ts # Unified game launch (launch:launch / launch:diagnose + afterLaunch)
│ ├── java.ts # Java detection (java:scan / java:resolve)
│ ├── mods.ts # Mod operations
│ ├── instance.ts # Instance operations
│ ├── background.ts # Background operations
│ ├── task.ts # Task system
│ ├── system.ts # System info
│ └── window.ts # Window controls + splash management
└── types/
└── electron.d.ts # TypeScript declarations
koring-launcher /
├─ electron / # Main process (all @xmcl code runs h ere )
│ ├─ main .ts # Entry: windows, splash → main transition
│ ├─ preload.ts # contextBridge → window.electronAPI
│ ├─ config.ts # YAML config (authoritative, sparse save, migrate)
│ ├ ─ aut h.ts · updater.ts · resource-protocol.ts
│ ├─ core/ # @xmcl integrations & business core
│ │ ├─ auth.ts · koring-auth.ts · installer.ts · launcher.ts
│ │ ├─ launch-options.ts · modrinth.ts · instance.ts
│ │ ├─ task.ts · paths.ts · background-image.ts · crash-logger.t s
│ └─ handlers/ # IPC handlers (config/auth/install/launch/java /
│ # mods/instance/background/task/system/update/
│ # koring-auth/crash-monitor/window )
├─ src/ # Renderer (React 19)
│ ├─ api/ # Typed IPC wrappers
│ ├─ components/ # background/ system/ setting/ task/
│ │ # about-version/ ui/ (shadcn) …
│ ├─ pages/ # home · gallery · store · today · play-link ·
│ │ # setting (grouped subpages) · oobe · upvp ·
│ │ # update · task-queue · crash · debug
│ ├─ resources/ # Resource registry (ref-count/budget/LRU) +
│ │ # image decode pipeline
│ ├─ stores/ # Zustand (config/auth/theme/route/launch…)
│ ├─ layouts/ · hooks/ · lib/ (mode/buildInfo/version) · assets/ · types/
│ ├─ App.tsx · main.tsx · index.css
├─ public/ # Static assets: icons/{dev,beta,run}/, bg, fonts
├─ scripts/ # switch-icon · version · gen-build-info ·
│ # signpath-sign · release-notes …
├─ docs/ · DEV.md · AGENTS.md # Docs & repository conventions
├─ electron-builder.yml # appId / targets / NSIS / signing
├─ vite.config.ts · tsconfig*.json · .env.{development,beta,production}
└─ package.json # Single source of truth for the version
```
## Three-Layer Page Structur e
## Versioning & Auto-Updat e
```
┌──────────────────────────────────────┐
│ z-index: 100 System Layer │ pointer-events: non e
│ ┌──────────────────────────────┐ │
│ │ TitleBar (frosted glass) │ │ pointer-events: auto
│ │ WindowControls (25px btns) │ │
│ └──────────────────────────────┘ │
├──────────────────────────────────────┤
│ z-index: 1 Content Layer │ pointer-events: auto
│ A ll page content │
├──────────────────────────────────────┤
│ z-index: 0 Background Layer │ pointer-events: none
│ Image / color / gradient / blur │
└──────────────────────────────────────┘
```
- **Single source of truth**: the `version` field in `package.json`
(`scripts/version.js` `get` /`set` ) shared by local builds and CI
- **Version format**: `{base}` (package.json) gains a build suffix at releas e
time: `{base}-beta.{buildId}` (beta) / `{base}-{buildId}` (run)
- **Auto-update**: `electron-updater` with the GitHub provider; run reads
`latest.yml` , beta reads `latest-beta.yml` ; the client enables
`allowPrerelease` so suffixed beta builds are detected
- ⚠️ Switching the build-ID scheme (timestamp → Run Number) makes old versions
numerically larger; raise the base version at the same time or old clients
wi ll not upgrade (details: `docs/auto-update-plan.md` )
## Splash Screen
## Roadmap
- Standalone HTML/CSS (`splash.html` ), no React/Vite dependenc y
- Loads instantly while Vite dev server starts
- Window: 480×
- Auto-adapts to system dark mode (`prefers-color-scheme` )
- Logo: `filter: invert(1)` in dark mode
- Startup: splash shows first → main loads behind → transition after `ready-to-show` + 1.5s minimum
- [ ] **Instance center / Resource center UI ** : full implementations are read y
but temporarily behind placeholder pages (Minecraft versions / mods /
modpacks browse & install)
- [ ] **Microsoft account login UI ** : OAuth / Xbox / Minecraft auth core is
integrated; UI entry is being polished
- [ ] **Ether / Tawa online play pages ** : currently placeholders
- [ ] macOS (DMG) and Linux (AppImage) CI artifacts
- [ ] i18n rollout (`app.language` preference is defined; UI strings are being
externalized)
## Icon System
## Contributing
Three icon variants in `public/icons/`
Issues and pull requests are welcome :
```
public/icons/
dev/icon.ico, icon.png # Development
beta/icon.ico, icon.png # Testing
run/icon.ico, icon.png # Production release
```
1. Fork the repository and branch from `master`
2. Follow the existing style (strict TypeScript, layered components/handlers);
prefer conventional commits (`feat:` / `fix:` / `docs:` / `refactor:` …)
3. Before touching the renderer, read [AGENTS.md ](AGENTS.md ) (architecture
constraints) and [DEV.md ](DEV.md ) (development notes)
4. Icon / installer changes should be verified across all three build modes
(`dist:dev/beta/run` )
**Build-time switching: **
``` bash
pnpm icon:dev # copies public/icons/dev/ → build/
pnpm icon:beta # copies public/icons/beta/ → build/
pnpm icon:run # copies public/icons/run/ → build/
```
## License
`electron-builder.yml` reads icons from `build/` (`buildResources: build` ).
This project is licensed under the custom **LingkeLice 1.0 (LL-1.0) ** , ©
**Shenzhen Lingke Network Technology Co., Ltd. ** In short: **non-commercial
use** (use, copy, modify, distribute, including incorporation into other
projects) is free; any **commercial use ** — integrating into commercial
products, providing paid services, or earning direct/indirect revenue — requires
**prior written authorization ** from the copyright holder. See
[LICENSE ](LICENSE ).
**Frontend usage: **
``` tsx
import { APP_ICON , DEFAULT_BG , LOGO_SVG , BUILD_MODE , isDev } from "@/lib/mode" ;
< img src = { APP_ICON } / >
< img src = { LOGO_SVG } / >
< img src = { DEFAULT_BG } / >
{ isDev && < span > Dev Mode < / span > }
```
## IPC Handlers
- `config:get` / `config:update` / `config:save` / `config:changed` — 配置读写（主进程权威：update 深度合并 + debounce 稀疏写盘 + 广播）
- `auth:*` — Microsoft OAuth, offline login
- `install:*` — Minecraft install, mod loader, version lists
- `launch:launch` / `launch:diagnose` — 统一游戏启动：主进程读取权威配置自动应用 Java/内存/GC/JVM/游戏参数/窗口/启动前命令，事件经 `launch:event` 推送，window-ready 时按 `afterLaunch` 处理启动器窗口
- `java:scan` / `java:resolve` — Java 环境检测 / 路径校验
- `mods:*` — Modrinth/CurseForge search, install
- `instance:*` — Instance CRUD（安装/导入/诊断；启动统一走 `launch:launch` ）
- `background:*` — Background image/color/blur/animation/theme
- `task:*` — Task system progress
- `system:*` — System info
- `window:*` — Minimize/maximize/close + splash management
- `dialog:*` — File picker
## Key Gotchas
- **@xmcl packages run in main process**: `@xmcl/core` , `@xmcl/installer` require `fs` /`child_process` . All run in Electron main process.
- **Path alias**: `@/` maps to `src/` .
- **Window dragging**: Use CSS `WebkitAppRegion: "drag"` as inline style (Electron only respects CSS property, not HTML attributes).
- **Transparent windows**: `transparent: true` + `frame: false` in BrowserWindow options.
- **Mutable win ref**: `electron/main.ts` uses a mutable `win` object — all handlers read `win.mainWindow` at runtime (not captured at registration time).
- **Asset paths**: Use `import.meta.env.BASE_URL` prefix for public assets (e.g., `${import.meta.env.BASE_URL}background.png` ). Absolute paths like `/background.png` break in packaged app.
- **Config**: YAML format (`Koring.yml` ). 打包后存 `app.getPath('userData')` （开发模式在项目根目录）；主进程内存缓存为唯一权威，渲染进程经 `config:update` 提交、`config:changed` 同步，不在渲染端直接写盘。Sparse save（只写非默认值）。
- **Auth**: JSON file (`koring-auth.json` )，打包后存 userData（与配置同策略）。
- **Launch is config-driven**: `launch:launch` 由主进程读取权威配置映射为 `@xmcl/core` 的 `LaunchOption` （ `buildLaunchOptions` ），前端只传实例名 + 游戏根目录 + 账户档案。
- **HeroUI 3 基于 react-aria**： `onChange` （不是 `onValueChange` ），`onValueChange` 在 HeroUI 3 中不存在且静默失效。
- **设置子页面统一原语**： `src/components/setting/` （ `fieldCls` ），一套样式组合；Radio 必须显式渲染 `<Radio.Control><Radio.Indicator /></Radio.Control>` 才有圆点；HeroUI field 默认边框宽度为 0，输入框需叠加 `fieldCls` 。
- **游戏目录导入**：版本从**当前扫描目录**导入（`sourceGamePath` ），实例建在主库；主目录变更自动重扫；批量导入幂等（已存在跳过）；相对 `gameDir` （默认 `.minecraft` ）由主进程 `resolveGamePath` 按 exe 目录/项目根归一化。
- **设置页结构（参考 PCL2）**：通用（主页/Koring 账户/关于/版权）与其他（服务与反馈/赞助/开发者）保留；游戏组（账户·离线登录、Java、目录、高级·含快速进入服务器）、个性化组（主题背景/主界面/语言/辅助）、网络组（下载/安全识别）已对接设置接口；以太/陶瓦联机页暂为占位。新增配置段：`app.language` （语言偏好）、`ui.showInstanceTitle/showTaskButton` （主界面元素）、`advanced.server` （快速进入服务器，启动自动加入）。
- **离线账号登录**： `auth:offline-login` 处理器生成离线 UUID（
- **AboutVersion（关于此版本）**： `src/components/about-version/` 拉取当前版本 GitHub 发布说明，解析后**按提交类型（新增/修复/优化/重构/文档/其他）分类卡片**展示（不渲染原始 Markdown）；OOBE/UPvP 流程步骤为「版本卡片 → 关于此版本」。
## Tech Stack
| Layer | Technology |
|-------|-----------|
| Frontend | React 19, Vite 7, Tailwind CSS v4, shadcn/ui, Zustand |
| Main Process | Node.js, TypeScript, @xmcl/ * packages |
| Build | pnpm, Vite, electron-builder |
For commercial licensing, contact Shenzhen Lingke Network Technology Co., Ltd.
