# lighty-loaders

Per-loader manifest fetching + metadata extraction for LightyLauncher. Maps `(Loader, minecraft_version, loader_version)` to a fully-merged `VersionMetaData` that the launch crate can install and execute.

Mod-source clients (Modrinth, CurseForge) live in a separate crate — see [`lighty-modsloader`](/lightylauncher/crates/modsloader/docs/overview.md).

## Supported loaders

| Loader        | Feature flag               | MC range                             | Status       | Per-loader doc                                                                               |
| ------------- | -------------------------- | ------------------------------------ | ------------ | -------------------------------------------------------------------------------------------- |
| Vanilla       | `vanilla`                  | all                                  | stable       | [`loaders/vanilla.md`](/lightylauncher/crates/loaders/docs/loaders/vanilla.md)               |
| Fabric        | `fabric`                   | 1.14+                                | stable       | [`loaders/fabric.md`](/lightylauncher/crates/loaders/docs/loaders/fabric.md)                 |
| Quilt         | `quilt`                    | 1.14+                                | stable       | [`loaders/quilt.md`](/lightylauncher/crates/loaders/docs/loaders/quilt.md)                   |
| NeoForge      | `neoforge`                 | 1.20.1+                              | stable       | [`loaders/neoforge.md`](/lightylauncher/crates/loaders/docs/loaders/neoforge.md)             |
| Forge         | `forge`                    | 1.5.2+ (legacy + modern in one flag) | stable       | [`loaders/forge.md`](/lightylauncher/crates/loaders/docs/loaders/forge.md)                   |
| OptiFine      | always on (uses `vanilla`) | varies                               | experimental | [`loaders/optifine.md`](/lightylauncher/crates/loaders/docs/loaders/optifine.md)             |
| LightyUpdater | `lighty_updater`           | any (server-defined)                 | stable       | [`loaders/lighty_updater.md`](/lightylauncher/crates/loaders/docs/loaders/lighty_updater.md) |

The `forge` feature covers both **modern** (≥ 1.13) and **legacy** (1.5.2 → 1.12.2) Forge — the loader detects the right install schema from the installer JAR. There's no separate `forge_legacy` feature.

`lighty_updater` activates `fabric`, `quilt`, `neoforge` and `forge` at the workspace level so a LightyUpdater server can pick any base loader.

## Core building blocks

```mermaid
flowchart TD
    APP[VersionBuilder / LightyVersionBuilder] --> VI[VersionInfo trait]
    VI --> LE[LoaderExtensions trait]
    LE --> REPO[ManifestRepository<Q>]
    REPO --> CACHE[Cache layer<br/>raw + per-query]
    REPO --> Q[Query trait impl<br/>vanilla/fabric/forge/…]
    Q --> API[Provider API]
```

| Building block           | Lives in                              | Docs                                                           |
| ------------------------ | ------------------------------------- | -------------------------------------------------------------- |
| `VersionInfo` trait      | `types::VersionInfo`                  | [`traits.md`](/lightylauncher/crates/loaders/docs/traits.md)   |
| `LoaderExtensions` trait | `types::LoaderExtensions`             | [`traits.md`](/lightylauncher/crates/loaders/docs/traits.md)   |
| `Loader` enum            | `types::Loader`                       | this page                                                      |
| `Query` trait            | `utils::query::Query`                 | [`query.md`](/lightylauncher/crates/loaders/docs/query.md)     |
| `ManifestRepository<Q>`  | `utils::manifest::ManifestRepository` | [`query.md`](/lightylauncher/crates/loaders/docs/query.md)     |
| `Cache<K, V>`            | `utils::cache::Cache`                 | [`cache.md`](/lightylauncher/crates/loaders/docs/cache.md)     |
| `VersionMetaData` family | `types::version_metadata`             | see source                                                     |
| `InstanceSize`           | `types::InstanceSize`                 | [`exports.md`](/lightylauncher/crates/loaders/docs/exports.md) |

## How a query flows

1. The host crate creates a `VersionBuilder` (or `LightyVersionBuilder`) — both implement `VersionInfo`.
2. The blanket `LoaderExtensions` impl matches on the `Loader` variant and dispatches to the right `ManifestRepository`.
3. The repository checks its `query_cache`; on miss it falls back to the `raw_cache`; on miss again it calls `Query::fetch_full_data` and `Query::extract`.
4. Results land back wrapped in `Arc<VersionMetaData>` so concurrent subscribers share the same allocation.

## Cargo features

```toml
[dependencies]
lighty-loaders = { version = "...", features = ["fabric", "forge"] }
```

`all-loaders` is the shortcut for everything (vanilla + fabric + quilt

* neoforge + forge + lighty\_updater + all-mods). Mod-source flags (`modrinth`, `curseforge`, `all-mods`) light up extra optional dependencies and switch on the equivalent modsloader features at the workspace level.

`events` (workspace) routes `LoaderEvent` variants through `lighty_event::EVENT_BUS`.

## See also

* [`how-to-use.md`](/lightylauncher/crates/loaders/docs/how-to-use.md) — minimum-viable example
* [`traits.md`](/lightylauncher/crates/loaders/docs/traits.md) — `VersionInfo` + `LoaderExtensions`
* [`query.md`](/lightylauncher/crates/loaders/docs/query.md) — implementing a new loader
* [`cache.md`](/lightylauncher/crates/loaders/docs/cache.md) — TTL behaviour + thundering-herd guard
* [`events.md`](/lightylauncher/crates/loaders/docs/events.md) — `LoaderEvent` variants
* [`exports.md`](/lightylauncher/crates/loaders/docs/exports.md) — public API surface
* Per-loader pages: [`loaders/`](https://github.com/Lighty-Launcher/LightyLauncherLib/blob/production/crates/loaders/docs/loaders/README.md)
* [`../../version/docs/how-to-use.md`](/lightylauncher/crates/version/docs/how-to-use.md) — `VersionBuilder` / `LightyVersionBuilder` canonical reference
* [`../../launch/docs/installation.md`](/lightylauncher/crates/launch/docs/installation.md) — what the launch pipeline does with the resolved metadata


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hamadi.gitbook.io/lightylauncher/crates/loaders/docs/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.