Koring Launcher

A modern Minecraft launcher for Windows · 基于 Electron + React 的现代化 Minecraft 启动器

---

中文文档

• 项目简介
• 功能特性
• 界面预览
• 快速开始
• 开发指南
• 构建与发布
• 技术架构
• 目录结构
• 版本与自动更新
• 路线图
• 贡献指南
• 许可证

---

项目简介

Koring Launcher 是一款面向现代 Windows 桌面的 Minecraft 启动器，采用 Electron + React 19 + TypeScript 构建，游戏侧核心能力基于成熟的 @xmcl 开源生态（安装、启动、任务）。

项目强调流畅的桌面体验与工程化的进程架构：自定义无边框窗口与启动画面、 三层层级 UI、主进程权威的配置体系、内置资源注册表与内存管理，以及 beta/run 双通道 自动更新。代码库以「渲染进程薄、主进程权威」为原则，所有游戏相关能力 （@xmcl、文件系统、进程管理）均运行于 Electron 主进程，渲染进程只通过类型安全的 IPC 与主进程通信。

状态：项目处于积极开发与内测阶段（beta / run 双通道发布）。主框架与核心 流程稳定可用，部分 UI 模块（见 路线图）仍在打磨。

功能特性

桌面体验

• 自定义无边框窗口：自绘标题栏（毛玻璃）与窗口控制，深浅色模式自动适配
• 独立的 Splash 启动画面（480×320 透明窗，无框架依赖，ready-to-show + 最短停留时间过渡）
• 三层层级 UI：背景层 / 内容层 / 系统层，页面间使用 View Transitions 过渡
• 内置隐藏调试页（debug-* 路由）：显示、更新、任务、资源与内存等专项调试

游戏能力（基于 @xmcl）

• 统一配置驱动启动：主进程读取权威配置，自动映射为 LaunchOption （Java 路径 / 内存 / GC / JVM 参数 / 游戏参数 / 窗口 / 启动前命令）， 支持启动事件推送与 afterLaunch 窗口处理
• Java 自动检测与路径校验（java:scan / java:resolve）
• 实例系统：主库实例 + 游戏目录批量导入（幂等、目录变更自动重扫）
• Mod 生态：Modrinth / CurseForge 检索与安装模块
• 账号体系：Koring 账号、离线账号（规范离线 UUID），微软 OAuth 核心已接入
• 任务系统：安装 / 下载进度统一通过主进程任务队列（task:*）推进，UI 可查看队列

配置与个性化

• 主进程权威配置：YAML（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/ 后在此展示。

快速开始

面向用户：从 GitHub Releases 下载最新安装包（NSIS 安装器，可自选安装目录）。目前发布管线产出 Windows 安装程序， macOS（DMG）与 Linux（AppImage）构建目标已配置，将在 CI 中逐步开放。

开发环境要求

依赖	版本	说明
OS	Windows 10/11（x64）	主要开发与目标平台
Node.js	≥ 20.19（CI 使用 22）	Vite 7 要求
pnpm	≥ 9（CI 使用 11.7）	包管理器，仓库基于 pnpm workspace

国内网络环境：仓库 .npmrc 已配置 Electron 二进制走 npmmirror 镜像， 可避免 Electron 下载超时。

# 安装依赖
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"（Electron 仅识别 CSS 属性）

构建与发布

构建模式

项目支持三种构建模式，通过环境文件（.env.development / .env.beta / .env.production）注入，并配套切换图标（exe / 安装器图标随模式不同）：

模式	Vite mode	图标目录	用途
dev	development	public/icons/dev/	日常开发
beta	beta	public/icons/beta/	内测发布
run	production	public/icons/run/	正式发布

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/ （electron-builder 的 buildResources）→ electron-builder 产出 NSIS 安装程序， 产物位于 dist-electron/koring-launcher-{version}-setup.exe。

发布流水线（GitHub Actions）

.github/workflows/release.yml 手动触发（选择 beta / run 模式）：

1. 从 package.json 读取基础版本号，附加 BUILD ID（GitHub Run Number， 严格递增）生成最终版本：{base}-beta.{buildId}（beta）或 {base}-{buildId}（run）
2. pnpm build:{mode} + pnpm icon:{mode}（renderer + main + 图标）
3. electron-builder --win，经 SignPath 远程签名（无 SIGNPATH_API_TOKEN 时自动跳过，本地构建不受影响；仅对 sha256 签名以节省配额）
4. 生成中文发布说明并发布 GitHub Release：beta 为 prerelease 并额外上传 latest-beta.yml，run 为正式版并上传 latest.yml（electron-updater 更新清单）

配置存储（主进程权威）

• 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，@xmcl 全部运行于此）
│  ├─ 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}（package.json）→ 发布时追加构建号 {base}-beta.{buildId}（beta 通道）/ {base}-{buildId}（run 通道）
• 自动更新：electron-updater + GitHub provider；run 通道读 latest.yml， beta 通道读 latest-beta.yml；客户端开启 allowPrerelease 以接收带构建号的 beta 更新
• ⚠️ 若切换构建号方案（时间戳 → Run Number），旧版数值更大，老用户不会自动 升级，需同步提升 base 版本（详见 docs/auto-update-plan.md）

路线图

• 实例中心 / 资源中心 UI：完整实现已就绪，暂以占位页收尾打磨后放开 （Minecraft 版本 / Mod / 整合包浏览与安装）
• 微软账号登录 UI：OAuth / Xbox / Minecraft 认证核心已接入，入口 UI 完善中
• 以太 / 陶瓦联机页：目前为占位
• macOS（DMG）与 Linux（AppImage）CI 发布产物
• 多语言（app.language 偏好已定义，UI 文案逐步外置）

贡献指南

欢迎提交 Issue 与 Pull Request：

1. Fork 本仓库并以 master 为基线创建功能分支
2. 遵循仓库现有风格（TypeScript 严格模式、组件/处理器分层）， 提交信息建议使用约定式（feat: / fix: / docs: / refactor: …）
3. 修改渲染进程前先阅读 AGENTS.md（架构约束与注意点） 与 DEV.md（开发说明）
4. 涉及图标 / 安装器的改动请分别验证三种构建模式（dist:dev/beta/run）

许可证

本项目使用自定义 LingkeLice 1.0（LL-1.0） 许可证，版权归 Shenzhen Lingke Network Technology Co., Ltd.（深圳灵科网络科技有限公司） 所有。 要点：非商业用途可自由使用、复制、修改与分发（含并入其他项目）；任何 商业用途（含集成进商业产品、商业化提供服务、直接 / 间接获利）须事先获得 版权所有者的书面授权。详见 LICENSE。

商业授权请联系 Shenzhen Lingke Network Technology Co., Ltd.

---

English Version

• Introduction
• Features
• Screenshots
• Quick Start
• Development
• Build & Release
• Architecture
• Project Structure
• Versioning & Auto-Update
• Roadmap
• Contributing
• 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 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).

Features

Desktop experience

• Custom frameless window: glassmorphism title bar and window controls, automatic dark/light mode
• Standalone splash screen (480×320 transparent window, dependency-free, 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.

Quick Start

End users: download the latest installer from GitHub 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.

pnpm install

# Full app dev (Vite :1420 + Electron)
pnpm dev
pnpm dev:renderer   # renderer only (HMR, port 1420)
pnpm dev:main       # main process only

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

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

Pipeline: mode build → scripts/switch-icon.js copies the mode icons into build/ (electron-builder’s 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

┌────────────────────────── Renderer (React 19) ─────────────────────────┐
│  pages / components / stores (Zustand)        resources (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 flow: 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

koring-launcher/
├─ electron/                  # Main process (all @xmcl code runs here)
│  ├─ main.ts                 # Entry: windows, splash → main transition
│  ├─ preload.ts              # contextBridge → window.electronAPI
│  ├─ config.ts               # YAML config (authoritative, sparse save, migrate)
│  ├─ auth.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.ts
│  └─ 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

Versioning & Auto-Update

• 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 release 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 will not upgrade (details: docs/auto-update-plan.md)

Roadmap

• Instance center / Resource center UI: full implementations are ready 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)

Contributing

Issues and pull requests are welcome:

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 (architecture constraints) and DEV.md (development notes)
4. Icon / installer changes should be verified across all three build modes (dist:dev/beta/run)

License

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.

For commercial licensing, contact Shenzhen Lingke Network Technology Co., Ltd.