docs(readme): 两份 README 改写为 iced/M3 Expressive 现状(双 bin 并存 + 两轨 Status)
- UI 描述:已发布 v0.1.0 = Slint + Metro;下一代 = iced 0.14 + Material 3 Expressive,dev 上施工中 - 双 bin 并存逐条讲清:unlucky-launcher(Slint,v0.1.0 已发布)/ unlucky-launcher-iced(施工中) / ull(CLI),并说明翻牌前不改名的原因(同 target 目录不能同名 bin) - 模块地图补 crates/design(真 HCT 令牌、零 UI 依赖)与 crates/app-iced;crates/app 保留到等价验收 - Status 重写为两轨:Track A 已发布(含 v0.1.0 资产范围与 CLI 命令集,取自 release.yml 与 cli/help.rs) / Track B 施工中(已完成=令牌+骨架;未完成=组件库/页面/i18n,页面全是占位) - 删除全部过期统计数字(983+ tests 等),改为行为性门禁表述;无测试数、无产物体积 - 合规段落只留 Microsoft 正版登录 / 凭据只存本机且 AI 不可访 / 离线不能联机 / 不分发不镜像不代理 / 与 Mojang-Microsoft 无关联;无第三方账户服务字样 - 许可:Slint RF 2.0 归属保留并补 iced(MIT)、MCU(Apache-2.0)、其余主要依赖 - 致谢 HMCL / PCL2 改为口语化语气,不加粗、不撇清 - 开头保留 GitHub 官方主页行(英文自指、中文醒目指引 + Releases 链接),全文无 gitea 地址 - 平台基线补 macOS 未签名需清 Gatekeeper 隔离标记
This commit is contained in:
1 parent
cf52751124
commit
2a0493c3eb
2 files changed
+246
-101
No files matched your search
@@ -2,57 +2,97 @@
|
||||
|
||||
**English** · [简体中文](README.zh-CN.md)
|
||||
|
||||
> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher
|
||||
> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher | downloads, issues and
|
||||
> release notes all live there: <https://github.com/AskaEth/Unlucky-Launcher/releases>
|
||||
|
||||
Unlucky Launcher (ULL) is a free, open-source Minecraft: Java Edition launcher written in Rust
|
||||
(Apache-2.0, non-commercial), with a Slint + Metro UI. It embeds an AI agent client (chat /
|
||||
configuration / crash diagnosis) and integrates with the broader agent tooling ecosystem via MCP.
|
||||
Minimum baseline: Windows 10.
|
||||
(Apache-2.0). It ships as one native binary per platform — no installer, no bundled runtime, no
|
||||
WebView. The launcher embeds an AI agent client (chat / configuration / crash diagnosis) and can be
|
||||
attached to other agent tooling as an MCP server.
|
||||
|
||||
- Runtime: a single native Rust binary — no JVM, no WebView, no external runtime
|
||||
- UI: Slint (Royalty-Free 2.0; GL preferred, CPU software-rendering fallback so older machines
|
||||
without a usable GPU still get the full UI)
|
||||
- License: Apache-2.0 © AskaEth (YeiJ)
|
||||
- **Single-file native binary**: the launcher itself needs no JVM, no WebView and no sidecar
|
||||
runtime. The JDK a game needs is downloaded and managed per instance, not as a launcher
|
||||
dependency.
|
||||
- **Two UI stacks during the rewrite**: the released UI is Slint (Royalty-Free 2.0); the
|
||||
next-generation UI is iced 0.14 + Material 3 Expressive and is still being written (see Status).
|
||||
- **CPU software-rendering fallback**: `--software-renderer` gives the full UI on machines with no
|
||||
usable GPU or with broken drivers.
|
||||
- **AI agent + MCP**: chat, setting edits and crash diagnosis inside the launcher; `ull agent
|
||||
serve` exposes the same core as an MCP server (stdio or Streamable HTTP) to external agent tools.
|
||||
- **Mod loaders**: Fabric, Quilt, NeoForge, Forge, with modpack and CurseForge / Modrinth clients in
|
||||
the core.
|
||||
- **Java management**: a Temurin → Oracle → Microsoft → Zulu fallback chain, region-aware.
|
||||
- **Engine**: multi-source download (health scoring, mirrors, chunked transfers, hash while
|
||||
downloading) and a YAML rule-based crash diagnosis engine.
|
||||
- **License**: Apache-2.0 © AskaEth (YeiJ).
|
||||
|
||||
## Compliance statement
|
||||
|
||||
Authentication uses only official Microsoft/Mojang endpoints — Microsoft OAuth 2.0 device code
|
||||
flow, Xbox Live, XSTS, and api.minecraftservices.com — so players sign in with their own Microsoft
|
||||
account and launch the game they already own. Account tokens are stored only on the user's local
|
||||
machine and are never sent to any server operated by the project. ULL does not distribute, mirror,
|
||||
proxy or modify any Minecraft game files. Online play always requires a Microsoft account with
|
||||
valid entitlements. Local offline profiles never contact Microsoft or Mojang services and cannot
|
||||
join online-mode servers. Not affiliated with Mojang or Microsoft.
|
||||
- **Microsoft sign-in only.** Authentication is Microsoft OAuth 2.0 device code flow → Xbox Live →
|
||||
XSTS → `api.minecraftservices.com`, using the player's own Microsoft account and their own game
|
||||
entitlement. There is no other account provider.
|
||||
- **Credentials stay on your machine.** Account tokens are stored locally only, are never sent to
|
||||
any server operated by this project, and the AI features cannot read them.
|
||||
- **Offline profiles cannot play online.** A local offline profile performs no Microsoft
|
||||
authentication, contacts no Microsoft/Mojang service, exists for local and isolated-network
|
||||
testing only, and cannot join servers that check accounts against the official service.
|
||||
- ULL does not distribute, mirror, proxy or modify any Minecraft game files.
|
||||
- Not affiliated with Mojang or Microsoft.
|
||||
|
||||
## Status
|
||||
|
||||
The core engine is complete (workspace: 983+ tests passing):
|
||||
Two tracks. They are not the same product yet, so read the headings before downloading anything.
|
||||
|
||||
- **Microsoft sign-in**: OAuth 2.0 device code flow → Xbox Live → XSTS → Minecraft Services, with
|
||||
entitlement verification
|
||||
- **Account credentials are stored only on the local machine** — never uploaded, and inaccessible
|
||||
to the AI features
|
||||
- Mod loaders: Forge / NeoForge / Fabric / Quilt, verified on real machines
|
||||
- Java management: Temurin / Oracle / Microsoft / Zulu with a regional fallback chain
|
||||
- Multi-source download engine; YAML rule-based crash diagnosis
|
||||
- Usable as an MCP server for external agent tooling (`ull agent serve`)
|
||||
- Local offline profiles: for local / isolated-network testing only; they perform no Microsoft
|
||||
authentication and cannot join servers with online-mode enabled
|
||||
### Track A — released: v0.1.0, Slint UI (this is what you can download today)
|
||||
|
||||
**CLI (`ull`) is fully usable**: `install / launch / accounts / java / diagnose / agent`.
|
||||
- **GitHub Releases `v0.1.0`** (2026-11-01, flagged pre-release): single-file assets for Windows
|
||||
x64 (a bare `.exe`), Linux x64 and macOS (arm64 and x64) `.tar.gz`, plus `SHA256SUMS.txt` and
|
||||
`LICENSE` / `NOTICE` / `README.md` as side assets on Windows.
|
||||
- **UI**: Slint + Metro. This is the shipped GUI — the instance, download, account, Java, log and
|
||||
settings pages drive the real engine (the in-app AI chat panel is a scripted placeholder).
|
||||
- **CLI `ull`** ships in the same release and is fully usable: `instances`, `install`, `launch`,
|
||||
`accounts`, `sessions`, `logs`, `diag`, `config`, `java`, `agent`.
|
||||
- Windows ARM64 and Linux ARM64 slots are wired into the release pipeline; the next tagged release
|
||||
builds them. The `v0.1.0` assets predate those two slots.
|
||||
|
||||
**GUI in development**: `crates/app` is currently a Slint + Metro skeleton; the theme system and
|
||||
the full interface ship with subsequent versions — use the CLI until then.
|
||||
### Track B — in progress on `dev`: next-generation UI (iced + Material 3 Expressive)
|
||||
|
||||
**Nothing on this track is released, and no download contains it.** You can only see it by
|
||||
building from source.
|
||||
|
||||
- **Locked direction**: the look is Material 3 Expressive and the framework is iced 0.14; the UI
|
||||
layer is written from scratch. Neither the style nor the framework will change again.
|
||||
- **Done**: the token crate `crates/design` (no UI framework, no third-party crates — real HCT
|
||||
color, type scale, shape scale, spacing, elevation, motion, icon geometry, per-component
|
||||
metrics) and the skeleton crate `crates/app-iced` (opens a window, self-drawn title bar and
|
||||
window buttons, navigation rail, colors and type taken from tokens only, GPU→CPU backend probe
|
||||
with automatic fallback, and the screenshot/diff channel the visual reviews use).
|
||||
- **Not done**: the component library (buttons, dialogs, lists, menus, search, and the rest of the
|
||||
M3 set), page migration, and the i18n pass. Every page in the iced binary is a placeholder.
|
||||
- **Slint stays until the flip**: `crates/app` remains the reference implementation until the iced
|
||||
build passes equivalence acceptance; only then is `unlucky-launcher-iced` renamed to
|
||||
`unlucky-launcher` and the Slint crate retired.
|
||||
|
||||
Binaries in the workspace, so you can tell them apart:
|
||||
|
||||
| Binary | Crate | State |
|
||||
|--------|-------|-------|
|
||||
| `unlucky-launcher` | `crates/app` (Slint) | released in v0.1.0; still the usable GUI |
|
||||
| `unlucky-launcher-iced` | `crates/app-iced` (iced 0.14) | under construction; skeleton only, not shipped |
|
||||
| `ull` | `crates/cli` | released in v0.1.0; headless and fully usable |
|
||||
|
||||
## Module map
|
||||
|
||||
```
|
||||
Unlucky-Launcher (cargo workspace)
|
||||
├── crates/core # domain library, zero UI dependencies, eight modules
|
||||
├── crates/agent # AI agent: ToolSpec registry + built-in client + MCP server (one shared core)
|
||||
├── crates/app # Slint UI: the only crate allowed to depend on a UI framework
|
||||
├── crates/cli # CLI (bin `ull`): headless, zero UI, depends on core + agent
|
||||
└── packaging # single-file artifact matrix and packaging assets (planned)
|
||||
├── crates/core # domain library: zero UI dependencies, eight modules
|
||||
├── crates/agent # AI agent: ToolSpec registry + built-in client + MCP server (one core, two shapes)
|
||||
├── crates/design # design tokens: real HCT color / type / shape / spacing / elevation / motion / icons
|
||||
│ # / component metrics — zero UI dependencies, no third-party crates
|
||||
├── crates/app # Slint UI (bin `unlucky-launcher`): the released GUI, kept until equivalence acceptance
|
||||
├── crates/app-iced # next-generation iced UI (bin `unlucky-launcher-iced`): under construction
|
||||
├── crates/cli # CLI (bin `ull`): headless, zero UI
|
||||
└── packaging # single-file artifact matrix and release scripts
|
||||
```
|
||||
|
||||
The eight modules of `crates/core`:
|
||||
@@ -72,53 +112,86 @@ The eight modules of `crates/core`:
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; components `rustfmt` /
|
||||
`clippy`)
|
||||
- Windows: MSVC toolchain (used by CI) or MinGW-w64 (`x86_64-pc-windows-gnu`)
|
||||
- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev`
|
||||
(Slint winit backend + femtovg build dependencies)
|
||||
- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; the gates also need the
|
||||
`rustfmt` and `clippy` components)
|
||||
- Windows: MSVC toolchain (what CI uses) or MinGW-w64 (`x86_64-pc-windows-gnu`)
|
||||
- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev
|
||||
libxcb1-dev` — needed by both UI stacks (Slint's winit + femtovg, iced's winit + wgpu/tiny-skia)
|
||||
|
||||
```bash
|
||||
cargo fmt --all --check # formatting
|
||||
cargo clippy --workspace --all-targets -- -D warnings # lints (zero-warning gate)
|
||||
cargo test --workspace # tests
|
||||
cargo build --release # artifact: target/release/unlucky-launcher[.exe]
|
||||
cargo fmt --all --check # formatting
|
||||
cargo clippy --workspace --all-targets -- -D warnings # lints (zero-warning gate)
|
||||
cargo test --workspace # tests
|
||||
cargo build --release # binaries land in target/release/
|
||||
```
|
||||
|
||||
Software-rendering switch (machines without a usable GPU / with broken drivers):
|
||||
`unlucky-launcher --software-renderer` (equivalent to `SLINT_BACKEND=winit-software`).
|
||||
What the build produces:
|
||||
|
||||
- `unlucky-launcher` — the Slint UI (the released one)
|
||||
- `unlucky-launcher-iced` — the iced UI skeleton. The name is temporary: it can only become
|
||||
`unlucky-launcher` at the flip, because two crates in one workspace cannot emit the same binary
|
||||
name into the same target directory.
|
||||
- `ull` — the CLI
|
||||
|
||||
Rendering switches:
|
||||
|
||||
- `unlucky-launcher --software-renderer` (equivalent to `SLINT_BACKEND=winit-software`) forces the
|
||||
CPU path on the Slint build
|
||||
- `unlucky-launcher-iced --software-renderer` forces tiny-skia (`ICED_BACKEND=tiny-skia`);
|
||||
`--screenshot <png>` writes one frame and exits, which is the acceptance channel
|
||||
- Both builds probe the backend at startup and fall back to CPU automatically when no adapter is
|
||||
usable
|
||||
|
||||
Dependency license check (optional locally, required in CI):
|
||||
`cargo deny check licenses bans sources`.
|
||||
|
||||
## CI gates
|
||||
|
||||
Every push runs fmt / clippy (warnings are errors) / the full test suite, plus a headless render
|
||||
smoke on Linux and a macOS runtime probe. Nothing here is advisory: a red gate blocks the merge.
|
||||
|
||||
| Workflow | Content |
|
||||
|----------|---------|
|
||||
| `.github/workflows/ci.yml` | fmt + clippy + test + build, Windows / Linux matrix |
|
||||
| `.github/workflows/guards.yml` | zero-UI guard for core, 400-line-per-file guard, cargo-deny license guard |
|
||||
| `.github/workflows/ci.yml` | fmt + clippy + test + release build (Windows / Linux matrix); Linux runtime smoke (Xvfb: renders one real frame, then asserts the PNG is not blank); macOS runtime smoke |
|
||||
| `.github/workflows/guards.yml` | zero-UI guard for `crates/core` (manifest plus `cargo tree`), 400-lines-per-file guard, cargo-deny license and source guard |
|
||||
| `.github/workflows/release.yml` | tag `v*` → per-slot builds → single-file artifacts + `SHA256SUMS.txt` → GitHub Release |
|
||||
|
||||
## Platform baseline
|
||||
|
||||
Minimum baseline: **Windows 10**. Windows 8.1 / 8 / 7 are not supported:
|
||||
Minimum baseline: **Windows 10**; Windows 8.1 / 8 / 7 are not supported.
|
||||
|
||||
- Windows 10/11 builds use the **standard toolchain** (MSVC / GNU) — no custom target specs, no
|
||||
`-Zbuild-std`, no import-table allowlists
|
||||
- Other platforms: macOS 12+ first class; Linux x64 with X11 preferred, Wayland as the long-term
|
||||
direction; Android Termux experimental, not committed
|
||||
- UI fallback: Slint software rendering (fully usable on machines without a GPU or with broken
|
||||
drivers)
|
||||
- macOS 12+ (Apple Silicon and Intel) and Linux x64 / arm64 are supported build slots; on Linux,
|
||||
X11 is the preferred path today and Wayland is the long-term direction. macOS builds are unsigned,
|
||||
so the first launch needs the Gatekeeper quarantine attribute cleared
|
||||
(`xattr -d com.apple.quarantine`)
|
||||
- Android Termux is experimental and not promised: CLI only, GUI unverified
|
||||
- Platform independence is expressed through **separate test matrices**, not separate artifact
|
||||
pipelines; capability differences use feature gates with runtime probing
|
||||
- **Renderer fallback on both UI stacks**: the Slint build drops to software rendering, the iced
|
||||
build drops from wgpu to tiny-skia, so a machine without a usable GPU still gets the full UI
|
||||
|
||||
## License and acknowledgements
|
||||
|
||||
- This project: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in [NOTICE](NOTICE)
|
||||
- The GUI uses [Slint](https://slint.dev) (Royalty-Free 2.0 track). Per the RF 2.0 obligations an
|
||||
`AboutSlint` widget will be placed on the about page (P2); until then NOTICE and this section
|
||||
serve the attribution duty.
|
||||
- **This project**: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in
|
||||
[NOTICE](NOTICE).
|
||||
- **Slint** (<https://slint.dev>), Royalty-Free 2.0: obligation for the Slint build that v0.1.0
|
||||
ships — an `AboutSlint` widget on the about page (still outstanding) and, until it lands, the
|
||||
NOTICE file, this section and a "Made with Slint" note on the release page. The obligation is
|
||||
kept for as long as a Slint-linked binary ships.
|
||||
- **iced** (<https://github.com/iced-rs/iced>), MIT: the framework of the next-generation UI,
|
||||
together with `winit` and, through it, `wgpu` / `tiny-skia` (Apache-2.0 / MIT).
|
||||
- **Google Material Color Utilities** (Apache-2.0): the color tokens in `crates/design` are a Rust
|
||||
port of its HCT / ColorSpec2021 algorithms; details and the exact ported functions are listed in
|
||||
[NOTICE](NOTICE).
|
||||
- **Other major dependencies**: `rmcp` and `axum` (Apache-2.0 / MIT) for the MCP server, `tokio`
|
||||
(MIT), `reqwest` with rustls (MIT / Apache-2.0), `serde` / `serde_json` (MIT / Apache-2.0),
|
||||
`zip` / `flate2` / `tar` (MIT / Apache-2.0). The allow-list cargo-deny enforces is in `deny.toml`;
|
||||
GPL-family dependencies may not enter the main line.
|
||||
|
||||
Thanks to [HMCL](https://github.com/HMCL-dev/HMCL) and
|
||||
[PCL2](https://github.com/Meloong-Git/PCL) (both GPL-3.0) — these two launchers have accompanied
|
||||
the vast majority of Minecraft players for many years. ULL learned a great deal about design and
|
||||
implementation from them, and this project is dedicated to those two pioneers.
|
||||
[PCL2](https://github.com/Meloong-Git/PCL) (both GPL-3.0) — those two old-timers have been riding
|
||||
along with the overwhelming majority of Minecraft players for years now. This launcher learned an
|
||||
enormous amount from them about how a launcher should feel and how it should work, and it exists
|
||||
very much in their debt.
|
||||
Reference in new issue
Block a user