AskaEth/Unlucky-Launcher
1
0 Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
a426cb5dcb912706f969d4427d883a72236bf2a4
Unlucky-Launcher/README.zh-CN.md
T
AskaEth 9d9ab3e7e0 docs(readme): 合规段第一条去掉防御腔 —— 平静陈述「用 Microsoft 账户登录」 
- 英文：Microsoft sign-in only → Sign-in with your Microsoft account；删掉 There is no other
  account provider（过度否认本身是信号）
- 中文：只走 Microsoft 正版登录 → 用 Microsoft 账户登录；删掉「没有别家账户通道」，
  并避开「正版」这个词（中文圈里该词天然与「破解」对照，带防御姿态）
- 事实不变：device code → XBL → XSTS → api.minecraftservices.com，用玩家自己的账户与权益
- 第三条「联机游玩需要 Microsoft 账户与有效权益」保留独立一条（事实陈述，非否认）
2026-11-01 19:49:08 +08:00

176 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 玩家走了好多年的老前辈。启动器该是什么手感、该怎么把一件
事做顺，我们是从它们身上学的；这个项目欠它们一份很大的人情。
Reference in new issue View Git Blame Copy Permalink