Unlucky Launcher (ULL)

English · 简体中文

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). 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.

Highlights

• 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 keeps the interface rendering normally 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.
• Accounts: sign in with a Microsoft account over OAuth 2.0 device code flow → Xbox Live → XSTS → api.minecraftservices.com; account tokens are kept on this machine only.
• 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).

Status

Two tracks. They are not the same product yet, so read the headings before downloading anything.

Track A — released: v0.1.0, Slint UI (this is what you can download today)

• 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. Every release also carries SHA256SUMS.txt and the LICENSE / NOTICE / README.md texts as separate assets; on Windows those texts sit next to the .exe because a bare exe cannot hold them, while the unix archives already contain them.
• UI: Slint + Metro. This is the shipped GUI — the instance, download, account, Java, log and settings pages all run on the core engine (the in-app AI chat panel is a scripted placeholder).
• CLI in the same binary: unlucky-launcher instances list, unlucky-launcher launch <instance>, unlucky-launcher logs <sid> and the rest of the command set run before any UI is built — no window, no renderer probe, no font scan. Commands: instances, install, launch, accounts, sessions, logs, diag, config, java, agent, plus --help / --version.
• A second, lighter artifact ull (cargo build --release --bin ull, zero UI dependencies): the same command set from a binary that links no graphics stack at all — not even fontconfig. Servers, CI containers and Termux get ull; desktops get unlucky-launcher and one binary covers both GUI and CLI. Both are release assets from the next tagged release (the v0.1.0 assets predate this).
• 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.

Track B — in progress on dev: next-generation UI (iced + Material 3 Expressive)

This track is not released yet — you can see it only 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; also runs every CLI subcommand
unlucky-launcher-iced	crates/app-iced (iced 0.14)	under construction; skeleton only, not shipped; same subcommand dispatch
ull	crates/cli	the zero-UI build of the same command set, shipped as its own asset

unlucky-launcher and ull are not duplicates. The GUI binary needs the graphics stack when it opens a window (it dlopens X11 / Wayland / GL, and links libfontconfig at load); ull needs nothing beyond glibc, so it runs on a server, a CI container or Termux where no window can exist. Pick ull when there is no desktop, unlucky-launcher <command> when there is. Both print the same CLI text and name themselves after the binary you invoked: unlucky-launcher --help starts with unlucky-launcher ·, ull --help starts with ull ·.

Subcommand dispatch

unlucky-launcher <args> first asks "is this a CLI call?" before any UI code runs:

unlucky-launcher                       # GUI
unlucky-launcher --software-renderer   # GUI, CPU renderer (unchanged)
unlucky-launcher instances list        # CLI, no window
unlucky-launcher --json launch 1.20.1  # CLI, global options before the command
unlucky-launcher --version             # CLI, prints version + OS summary

The rule is deliberately narrow, so nothing that used to work changed meaning:

• The first argument is a bare word (not -…) → it sits in the subcommand position, so the CLI gets it. GUI flags never appear there: --screenshot / --diff / --data-dir take their values after the flag.
• The first argument is a flag → the line is a CLI call only if crates/cli's parser also produces a real command (--help, --version, --json instances list). --data-dir X alone parses to "no subcommand", so it still opens the GUI; every GUI-only flag (--software-renderer, --screenshot*, --renderer, --theme, --diff, --force-state, …) fails CLI parsing, so it still opens the GUI.

Unknown subcommands are an error, not a GUI launch: unlucky-launcher lst prints "未知命令 lst", hints unlucky-launcher --help, and exits 1. Silently opening a window would tell a script that its typo took effect. The subcommand table itself lives in exactly one place — crates/cli/src/cli/parse.rs — so both GUI binaries and ull accept the same set by construction.

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 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:

Module	Responsibility
setting	three data-directory modes, schema-based config, atomic writes, migrations
download	multi-source health scoring, mirrors, chunked downloads, hash-while-downloading
game	version / instance repository, snapshots and inheritance resolution
launch	10-stage launch pipeline, processes, JSONL event stream
auth	Microsoft sign-in (OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services)
addon	mod loader installation, modpacks, CurseForge / Modrinth
diagnose	five signal collectors, YAML rule engine, hs_err parsing
platform	OS abstraction: paths, processes, file locks, capability probing, runtime OS detection

Building

Prerequisites:

• 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)

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/

What the build produces:

• unlucky-launcher — the Slint UI (the released one). It is also the CLI: the same binary answers every subcommand listed above.
• 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. Same subcommand dispatch.
• ull — the CLI as a standalone, UI-free binary. Same command set, no graphics stack, smaller, and the right artifact for a machine that has no display at all.

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 stacks fall back to the CPU path when no usable adapter is there: the Slint build through its own renderer fallback chain, the iced build through its explicit probe

Dependency license check (optional locally, required in CI): cargo deny check licenses bans sources.

CI gates

Every push to main and every pull request runs fmt / clippy (warnings are errors) / the full test suite, and the Linux headless render smoke is a hard gate on the same footing: a red result blocks the merge. The macOS runtime probe is not there yet — it only runs on a manual workflow_dispatch and its result is recorded, not enforced (continue-on-error), until the slot passes a first run on a real runner.

Workflow	Content
.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 probe (manual dispatch only)
.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.

• Windows 10/11 builds use the standard toolchain (MSVC / GNU), built the same way as upstream cargo
• 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
• Each platform runs its own test matrix; capability differences use feature gates with runtime probing.

License and acknowledgements

• This project: Apache License 2.0, see LICENSE; third-party notices in 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.
• 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 and PCL2 (both GPL-3.0). They have been with the vast majority of Minecraft players for years, and this project has benefited a great deal from their design choices and implementation details.