> For the complete documentation index, see [llms.txt](https://hamadi.gitbook.io/lightylauncher/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hamadi.gitbook.io/lightylauncher/readme.md).

# LightyLauncherLib

[![Maintained](https://img.shields.io/badge/Maintained-yes-2ea44f.svg)](/lightylauncher/readme.md) [![Crates.io](https://img.shields.io/crates/v/lighty-launcher.svg)](https://crates.io/crates/lighty-launcher) [![Documentation](https://img.shields.io/badge/docs-gitbook-blue.svg)](https://hamadi.gitbook.io/lightylauncher) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Rust Version](https://img.shields.io/badge/rust-1.95%2B-red.svg)](https://www.rust-lang.org) [![Maintainer](https://img.shields.io/badge/Maintainer-Hamadi-blue.svg)](https://github.com/Kalandi)

<div align="center"><img src="/files/FdohgFslOwcQgTuVSwHZ" alt="LightyLauncher banner"></div>

## A launcher built with LightyLauncherLib

[exemple\_launcher\_with\_lightylauncherlib\_small.webm](https://github.com/user-attachments/assets/36134ddf-935b-4f2d-9047-78c8d6504ade)

## Quick start

```toml
[dependencies]
lighty-launcher = { version = "26.5.12", features = ["vanilla"] }
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"
```

```rust
use lighty_launcher::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    AppState::init("MyLauncher")?;

    let mut instance = VersionBuilder::new(
        "my-instance",
        Loader::Vanilla,
        "",
        "1.21.1",
    );

    let mut auth = OfflineAuth::new("Player123");
    let profile = auth.authenticate().await?;

    instance
        .launch(&profile, JavaDistribution::Temurin)
        .run()
        .await?;

    Ok(())
}
```

Microsoft auth, modpacks, event streams, every loader — runnable samples in [`examples/`](https://github.com/Lighty-Launcher/LightyLauncherLib/blob/production/examples/README.md).

## What you get

* **Light.** Only ships what you use. A pure-Fabric build never pulls in the Forge pipeline.
* **Fast.** Mods, libs, assets, resourcepacks, shaders — downloaded in parallel.
* **Mods & modpacks just work.** Drop a Modrinth slug or a CurseForge id and the file lands in the right folder. `.mrpack` and `.zip` modpacks supported out of the box.
* **Tokens stay yours.** Microsoft and Azuriom secrets can't leak through logs or JSON dumps. OS keychain storage is one method call away.
* **You see everything.** Typed events stream every step on a broadcast bus — perfect for a real-time UI.

## Architecture

```
lighty-launcher/             # Root crate (prelude + feature gates)
└── crates/
    ├── core/                # AppState, HTTP, hashing, extract
    ├── auth/                # Offline / Microsoft / Azuriom
    ├── event/               # Broadcast bus + typed events
    ├── java/                # JRE auto-download
    ├── launch/              # Install + game lifecycle
    ├── loaders/             # Vanilla / Fabric / Quilt / Forge / NeoForge
    ├── modsloader/          # Modrinth + CurseForge + modpack pipelines
    └── version/             # VersionBuilder
```

## Cargo features

| Feature                                               | Effect                                                                  |
| ----------------------------------------------------- | ----------------------------------------------------------------------- |
| `vanilla` / `fabric` / `quilt` / `neoforge` / `forge` | Enable that loader (`forge` covers modern + legacy 1.7.10–1.12.2)       |
| `lighty_updater`                                      | Custom updater backend (auto-pulls vanilla/fabric/quilt/neoforge/forge) |
| `all-loaders`                                         | Every loader above                                                      |
| `modrinth`                                            | Modrinth API + `.mrpack` modpack support                                |
| `curseforge`                                          | CurseForge API + `.zip` modpack support (requires API key)              |
| `all-mods`                                            | Both `modrinth` and `curseforge`                                        |
| `events`                                              | Typed broadcast events (`LaunchEvent`, `ModloaderEvent`, …)             |
| `keyring`                                             | OS-keychain storage for auth tokens (opt-in)                            |
| `tracing`                                             | Structured logging via `tracing`                                        |

Mix and match:

```toml
lighty-launcher = { version = "26.5.12", features = ["fabric", "modrinth", "events"] }
```

## Documentation

📚 **Full docs on GitBook**: <https://hamadi.gitbook.io/lightylauncher>

Per-crate API reference next to the code:

| Crate                                                                     | What it does                              |
| ------------------------------------------------------------------------- | ----------------------------------------- |
| [`lighty-core`](/lightylauncher/crates/core.md)                           | App state, HTTP, hashing, archive extract |
| [`lighty-auth`](/lightylauncher/crates/auth.md)                           | Offline / Microsoft / Azuriom auth        |
| [`lighty-event`](/lightylauncher/crates/event.md)                         | Broadcast event bus                       |
| [`lighty-java`](/lightylauncher/crates/java.md)                           | JRE download and discovery                |
| [`lighty-launch`](/lightylauncher/crates/launch.md)                       | Install orchestrator + game runner        |
| [`lighty-loaders`](/lightylauncher/crates/loaders.md)                     | Minecraft loader implementations          |
| [`lighty-modsloader`](/lightylauncher/crates/modsloader/docs/overview.md) | Mod sources + modpack parsers             |
| [`lighty-version`](/lightylauncher/crates/version.md)                     | Fluent `VersionBuilder`                   |

## Contributing

PRs welcome — see [CONTRIBUTING.md](/lightylauncher/contributing.md).

## License

[MIT](https://github.com/Lighty-Launcher/LightyLauncherLib/blob/production/LICENSE/README.md).

## Related

* [**LightyUpdater**](https://github.com/Lighty-Launcher/LightyUpdater) — companion server for custom modpack distribution.
* [**FlowUpdater**](https://github.com/FlowArg/FlowUpdater) — Java launcher library by FlowArg, one of the early inspirations for this project.

## Acknowledgements

Special thanks to [**FlowArg**](https://github.com/FlowArg) whose work on FlowUpdater provided valuable guidance and direction in the early stages of this project.

Thanks to everyone who has contributed — issues, PRs, and feedback all help make this library better.