# Unlucky Launcher (ULL)

[English](README.md) · **简体中文**

> **官方项目主页**：https://github.com/AskaEth/Unlucky-Launcher ｜ 下载、议题、发布说明都在这里：
> <https://github.com/AskaEth/Unlucky-Launcher/releases>

Unlucky Launcher（ULL）是一个用 Rust 写的免费开源 Minecraft: Java 版启动器（Apache-2.0）。
每个平台就一个原生二进制——没有安装包、没有捆绑运行时、没有 WebView。启动器内置 AI Agent
客户端（对话 / 改配置 / 崩溃诊断），也能作为 MCP server 接进别的 Agent 工具。

## 合规声明

- **用 Microsoft 账户登录**：认证走 Microsoft OAuth 2.0 device code flow → Xbox Live → XSTS →
  `api.minecraftservices.com`，用的是玩家自己的 Microsoft 账户与自己已购的游戏权益。
- **凭据只存本机**：账户令牌只保存在本机，不上传本项目运营的任何服务器，AI 功能也读不到。
- **联机游玩需要 Microsoft 账户与有效的游戏权益。**
- 不分发、不镜像、不代理、不修改任何 Minecraft 游戏文件。
- 与 Mojang、Microsoft 无关联。

## 特性

- **单文件原生二进制**：启动器本体不需要 JVM、不需要 WebView、不带旁挂运行时。游戏要的 JDK 由
  启动器按实例下载管理，不是启动器的依赖。
- **重写期两套 UI 并存**：已发布版本是 Slint（Royalty-Free 2.0）；下一代 UI 是 iced 0.14 +
  Material 3 Expressive，目前仍在写（见「当前状态」）。
- **CPU 软渲染兜底**：`--software-renderer` 让没有可用 GPU 或驱动有问题的老机也能拿到完整界面。
- **AI Agent + MCP**：启动器内可对话、改设置、读崩溃诊断；`ull agent serve` 把同一个内核以 MCP
  server 形态（stdio 或 Streamable HTTP）开放给外部 Agent 工具。
- **加载器**：Fabric / Quilt / NeoForge / Forge；整合包与 CurseForge / Modrinth 客户端在 core 里。
- **Java 管理**：Temurin → Oracle → Microsoft → Zulu 回退链，带地区判定。
- **引擎**：多源下载（健康度评分、镜像、分块传输、边下边算）与 YAML 规则引擎的崩溃诊断。
- **许可**：Apache-2.0 © AskaEth (YeiJ)。

## 当前状态

两条轨道，还不是同一个东西——看小标题再决定下载什么。

### 轨道 A —— 已发布：v0.1.0，Slint 版（现在真能下载的就是它）

- **GitHub Releases `v0.1.0`**（2026-11-01，标记为 pre-release）：单文件产物覆盖 Windows x64（裸
  `.exe`）、Linux x64、macOS（arm64 与 x64）`.tar.gz`。每个 Release 另挂 `SHA256SUMS.txt` 与
  `LICENSE` / `NOTICE` / `README.md` 三份文本——Windows 是「一个 exe 装不下文本」所以并列挂出，
  unix 归档里本来就装着。
- **UI**：Slint + Metro。这是已交付的图形界面——实例、下载、账户、Java、日志、设置各页驱动真实引擎
  （应用内 AI 对话面板仍是脚本化的占位）。
- **CLI `ull`** 与 v0.1.0 同源同版本、完整可用，但发布资产里只有 GUI 单文件——要用它请自己构建：
  `cargo build --release --bin ull`。命令：`instances`、`install`、`launch`、`accounts`、`sessions`、
  `logs`、`diag`、`config`、`java`、`agent`。
- Windows ARM64 与 Linux ARM64 两个槽位已接进发布流水线，随下一个 tag 发布；`v0.1.0` 的资产早于
  这两个槽位。

### 轨道 B —— dev 上的下一代 UI（iced + M3 Expressive，施工中）

**这条轨道没有任何已发布的东西，任何下载都拿不到它。** 想看只能自己从源码编。

- **方向已锁死**：视觉 = Material 3 Expressive，框架 = iced 0.14，UI 层从头写；风格与框架都不会再换。
- **已完成**：令牌 crate `crates/design`（零 UI 框架依赖、零第三方 crate——真 HCT 色彩、排版档位、
  形状刻度、间距、高程、动效、图标几何、组件度量）与骨架 crate `crates/app-iced`（能开窗、自绘标题栏
  与窗口键、导航轨、颜色与字号只从令牌取、GPU→CPU 后端探测与自动降级、视觉验收用的截图与逐像素
  对比通道）。
- **没完成**：组件库（按钮、对话框、列表、菜单、搜索栏，以及 M3 其余组件）、页面搬迁、i18n 文案。
  iced 版里现在每一个页面都是占位。
- **Slint 版在翻牌前不退场**：`crates/app` 作为参考实现保留，直到 iced 版通过等价验收；那时才把
  `unlucky-launcher-iced` 改名成 `unlucky-launcher`，并让 Slint 版退役。

工作区里的三个 bin，先认清楚：

| 二进制 | crate | 状态 |
|--------|-------|------|
| `unlucky-launcher` | `crates/app`（Slint） | v0.1.0 已发布，仍是当前能用的图形界面 |
| `unlucky-launcher-iced` | `crates/app-iced`（iced 0.14） | 施工中，仅骨架，不随发布包分发 |
| `ull` | `crates/cli` | 与发布版同源同版本构建；未随 v0.1.0 资产分发 |

## 模块地图

```
Unlucky-Launcher (cargo workspace)
├── crates/core       # 领域库：零 UI 依赖，八模块
├── crates/agent      # AI Agent：ToolSpec 注册表 + 内置客户端 + MCP server（双形态共用一个内核）
├── crates/design     # 设计令牌：真 HCT 色彩 / 排版 / 形状 / 间距 / 高程 / 动效 / 图标 / 组件度量
│                     #   —— 零 UI 依赖、零第三方 crate
├── crates/app        # Slint UI（bin `unlucky-launcher`）：已发布的图形界面，保留到等价验收通过
├── crates/app-iced   # 下一代 iced UI（bin `unlucky-launcher-iced`）：施工中
├── crates/cli        # CLI（bin `ull`）：headless，零 UI
└── packaging         # 单文件产物矩阵与发布脚本
```

`crates/core` 的八个模块：

| 模块 | 职责 |
|------|------|
| `setting` | 三模式数据目录、schema 配置、原子写、迁移 |
| `download` | 多源健康度、镜像、分块下载、边下边算 |
| `game` | 版本/实例仓库、快照与继承解析 |
| `launch` | 10 阶段启动管线、进程、JSONL 事件流 |
| `auth` | Microsoft 正版登录（OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services） |
| `addon` | 加载器安装、整合包、CurseForge / Modrinth |
| `diagnose` | 五类信号采集、YAML 规则引擎、hs_err 解析 |
| `platform` | OS 抽象：路径、进程、文件锁、能力探测、运行期 OS 检测 |

## 构建

前置：

- Rust stable（`rust-toolchain.toml` 会自动选工具链；门禁还需要 `rustfmt` / `clippy` 组件）
- Windows：MSVC 工具链（CI 用这套）或 MinGW-w64（`x86_64-pc-windows-gnu`）
- Linux：`libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev
  libxcb1-dev`——两套 UI 都要用（Slint 的 winit + femtovg，iced 的 winit + wgpu/tiny-skia）

```bash
cargo fmt --all --check                                # 格式
cargo clippy --workspace --all-targets -- -D warnings  # 静态检查（零 warning 门禁）
cargo test --workspace                                 # 测试
cargo build --release                                  # 三个 bin 都落在 target/release/
```

编出来的三个 bin：

- `unlucky-launcher`——Slint 版（已发布的那个）
- `unlucky-launcher-iced`——iced 版骨架。名字是临时的：只有翻牌时才能改成 `unlucky-launcher`，
  因为同一个工作区里两个 crate 不能往同一个 target 目录里产出同名 bin。
- `ull`——CLI

渲染开关：

- `unlucky-launcher --software-renderer`（等价于 `SLINT_BACKEND=winit-software`）强制 Slint 版走 CPU
- `unlucky-launcher-iced --software-renderer` 强制 tiny-skia（`ICED_BACKEND=tiny-skia`）；
  `--screenshot <png>` 出一帧图后退出，这是验收通道
- 两套栈在没有可用适配器时都会退到 CPU：Slint 版走它自己的渲染器回退链，iced 版走显式探测

依赖许可检查（本地可选，CI 必跑）：`cargo deny check licenses bans sources`。

## CI 门禁

每次推送到 `main` 与每个 PR 都跑 fmt / clippy（warnings 视为错误）/ 全量测试，Linux 无头渲染冒烟
与它们同级、是硬门禁：红了就不许合。macOS 运行期探针还不算——它只在手动 `workflow_dispatch` 时跑，
结果留证据但不作为流水线结论（`continue-on-error`），直到该槽位在真实 runner 上首跑通过。

| Workflow | 内容 |
|----------|------|
| `.github/workflows/ci.yml` | fmt + clippy + test + release build（Windows / Linux 矩阵）；Linux runtime smoke（Xvfb 里真渲染一帧，再断言 PNG 非空白）；macOS 运行期探针（仅手动 dispatch） |
| `.github/workflows/guards.yml` | `crates/core` 零 UI 守门（依赖表 + `cargo tree`）、单文件 ≤400 行守门、cargo-deny 许可与来源守门 |
| `.github/workflows/release.yml` | tag `v*` → 分槽位构建 → 单文件产物 + `SHA256SUMS.txt` → GitHub Release |

## 平台基线

最低基线 **Windows 10**；Windows 8.1 / 8 / 7 不在支持范围内。

- Windows 10/11 走**标准工具链**产物（MSVC / GNU），无自定义 target spec、无 `-Zbuild-std`、无导入表白名单
- macOS 12+（Apple Silicon 与 Intel）与 Linux x64 / arm64 都是支持槽位；Linux 上 X11 是当前首选路径，
  Wayland 是大方向。macOS 产物未签名，首次启动要自己清掉 Gatekeeper 隔离标记
  （`xattr -d com.apple.quarantine`）
- Android Termux 试验级、不承诺：只保证 CLI，GUI 未验证
- 平台独立性体现在**独立测试矩阵**，而非独立产物链；能力差异用 feature gate + 运行期探测表达
- **两套 UI 都有渲染兜底**：Slint 版降软渲染，iced 版从 wgpu 降到 tiny-skia，没有可用 GPU 的机器
  同样能拿到完整界面

## 许可证与致谢

- **本项目**：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE)。
- **Slint**（<https://slint.dev>），Royalty-Free 2.0：v0.1.0 发布的正是 Slint 版，这项义务继续有效
  ——关于页放 `AboutSlint` 部件（尚未落地），在此之前由 NOTICE、本节与发布页的「Made with Slint」
  说明承担告知义务。只要还有链接 Slint 的产物在发，这条义务就保留。
- **iced**（<https://github.com/iced-rs/iced>），MIT：下一代 UI 的框架；与它同栈的 `winit`、以及经它
  引入的 `wgpu` / `tiny-skia`（Apache-2.0 / MIT）。
- **Google Material Color Utilities**（Apache-2.0）：`crates/design` 的色彩令牌是它 HCT /
  ColorSpec2021 算法的 Rust 重写移植，移植清单与逐函数对照写在 [NOTICE](NOTICE)。
- **其余主要依赖**：MCP server 的 `rmcp` 与 `axum`（Apache-2.0 / MIT）、`tokio`（MIT）、`reqwest`
  与 rustls（MIT / Apache-2.0）、`serde` / `serde_json`（MIT / Apache-2.0）、`zip` / `flate2` / `tar`
  （MIT / Apache-2.0）。cargo-deny 强制执行的白名单在 `deny.toml`；GPL 系依赖不得进主干。

感谢 [HMCL](https://github.com/HMCL-dev/HMCL) 和 [PCL2](https://github.com/Meloong-Git/PCL)
（均 GPL-3.0）——这两位陪着绝大多数 MC 玩家走了好多年的老前辈。启动器该是什么手感、该怎么把一件
事做顺，我们是从它们身上学的；这个项目欠它们一份很大的人情。