elemental-driver 0.2.0

Driver library for Elemental, providing implementations for interacting with different modloaders and game versions.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
# elemental-driver

Catalog, inspect, prepare, and launch Minecraft distributions across vanilla and
modloader ecosystems.

`elemental-driver` turns upstream metadata into one normalized installation
model. It fetches Mojang, Fabric, Quilt, Forge-family, and legacy loader
manifests, resolves the files and arguments required by each distribution, and
exposes typed catalogs and drivers. The crate is independent of the high-level
instance lifecycle, so its catalogs and driver families can also be used
directly.

> [!NOTE]
> Driver selection is type-driven. Descriptors are stable identifiers used for
> display and persistence; they are not used to decide which implementation to
> run.

## Features

- Catalogs for Vanilla, Fabric, Legacy Fabric, Babric, Quilt, LiteLoader, Rift,
  Forge, NeoForge, Cleanroom, and Outlands.
- Separate `GameVersionCatalog` and `LoaderVersionCatalog` contracts.
- Direct, profiled, installer-driven, and RetroFutura installation families.
- A shared `Driver` trait for inspection, preparation, and loading.
- Local instance inspection with driver and loader-version detection.
- Configurable origins and mirror overrides for restricted networks.
- Typed Java runtime options and shared version JSON launch construction.
- A prepared version JSON view that exposes metadata, natives, and classpath
  without importing family traits.
- Shared version JSON layouts for game roots and individual instances.

## Installation

```toml
[dependencies]
anyhow = "1"
elemental-driver = "0.2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

## Quick Start

### Game versions

List the Minecraft versions known to the Vanilla catalog:

```rust
use elemental_driver::{
    catalog::GameVersionCatalog,
    drivers::vanilla::catalog::VanillaCatalog,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let versions = VanillaCatalog::with_defaults().game_versions().await?;
    println!("{} game versions", versions.len());
    Ok(())
}
```

### Loader versions

Loader catalogs use `LoaderVersionCatalog`. Fabric exposes a flavor selector for
Legacy Fabric and Babric:

```rust
use elemental_core::minecraft::MinecraftVersionId;
use elemental_driver::{
    catalog::LoaderVersionCatalog,
    drivers::fabric::{
        catalog::FabricCatalog,
        source::{FabricEndpoints, FabricFlavor},
    },
    families::version_json::LoaderMetaSource,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let catalog = FabricCatalog::new(LoaderMetaSource::new(
        FabricEndpoints::for_flavor(FabricFlavor::LegacyFabric)?,
    ));
    let game_version = MinecraftVersionId::from("1.12.2");
    let releases = catalog.loader_versions(&game_version).await?;
    println!("{} Legacy Fabric loader versions", releases.len());
    Ok(())
}
```

Forge-family catalogs use their `Default` endpoint configuration:

```rust
use elemental_core::minecraft::MinecraftVersionId;
use elemental_driver::{
    catalog::LoaderVersionCatalog,
    drivers::{
        cleanroom::CleanroomCatalog,
        forge::ForgeCatalog,
        neoforge::NeoForgeCatalog,
    },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let game_version = MinecraftVersionId::from("1.20.1");
    let forge = ForgeCatalog::with_defaults()
        .loader_versions(&game_version)
        .await?;
    let neoforge = NeoForgeCatalog::with_defaults()
        .loader_versions(&game_version)
        .await?;
    let cleanroom = CleanroomCatalog::with_defaults()
        .loader_versions(&MinecraftVersionId::from("1.12.2"))
        .await?;

    println!(
        "{} Forge, {} NeoForge, {} Cleanroom releases",
        forge.len(),
        neoforge.len(),
        cleanroom.len()
    );
    Ok(())
}
```

## Driver Families

| Family | Drivers | Installation model |
| --- | --- | --- |
| Direct version JSON | Vanilla | Resolve Mojang metadata and install the client, libraries, and assets directly |
| Profiled version JSON | Fabric, Legacy Fabric, Babric, Quilt, LiteLoader, Rift | Merge a loader profile with the base Vanilla version |
| Installer-driven | Forge, NeoForge | Download and run a Maven installer, then apply its profile and processors |
| RetroFutura installer | Cleanroom, Outlands | Reuse an old base version while replacing its runtime through an installer |

Every driver implements the `Driver` trait for inspection. The family-specific
drivers add preparation, loading, and launch-command construction.

RetroFutura is the shared path for old Minecraft lines whose runtime is replaced
while the original game metadata remains the base. Cleanroom and Outlands are
two declarations of that model.

## Customization

### Override origins and mirrors

All remote endpoints are typed. Use the endpoint constructors when only the base
URLs change, or implement `Origin` when you need a new endpoint family.

```rust
use elemental_driver::drivers::fabric::{
    driver::FabricDriverFamily,
    source::{FabricEndpointOverrides, FabricFlavor},
};

let driver = FabricDriverFamily::new(FabricFlavor::Fabric)
    .new_driver_with_overrides(FabricEndpointOverrides {
        meta_origin: "https://meta.example.com".to_owned(),
        maven_origin: "https://maven.example.com".to_owned(),
    })?;
```

`build_driver(source)` constructs the driver with the official Vanilla source.
For a complete Vanilla mirror, use `VanillaEndpoints::mirror(...)`, wrap it in
`VanillaSource::new(...)`, then call `.with_vanilla_source(...)`.

### Add a profiled loader

Profiled loaders merge a loader profile with the base Vanilla metadata. Implement
`ProfiledVersionJsonFamily` and provide:

- a `DriverDescriptor`;
- a `Source` that fetches the profile;
- a `RemoteResolver` for loader and Vanilla URLs;
- an optional `ProfiledDriverIdentity` for local-instance detection;
- `profile()` to fetch loader metadata.

The default `merge_profile()` is suitable for Fabric-like pass-through profiles.
Override it when the loader changes libraries or arguments.

```rust
use async_trait::async_trait;
use elemental_core::minecraft::MinecraftVersionId;
use elemental_driver::{
    driver::DriverDescriptor,
    drivers::vanilla::source::VanillaSource,
    error::Result,
    families::version_json::{
        LoaderMetaSource, ProfiledVersionJsonFamily, ProfiledVersionJsonFamilyExt,
        VanillaFallbackRemoteResolver,
    },
    inspect::{LibraryPrefixSet, ProfileIdPattern, ProfiledDriverIdentity},
    loader_version::LoaderVersionId,
};
use elemental_schema::fabric::ProfileJson;

const MY_DRIVER: DriverDescriptor = DriverDescriptor {
    id: "myloader",
    name: "MyLoader",
};
const MY_LIBRARIES: LibraryPrefixSet =
    LibraryPrefixSet::new(&["com.example:myloader:"]);
const MY_IDENTITY: ProfiledDriverIdentity = ProfiledDriverIdentity::new(
    MY_DRIVER,
    MY_LIBRARIES,
    MY_LIBRARIES,
    ProfileIdPattern::new("-myloader-"),
);

// MyEndpoints implements LoaderMetaEndpoints + UpstreamUrlRewriter + Default.
type MySource = LoaderMetaSource<MyEndpoints>;
type MyResolver = VanillaFallbackRemoteResolver<MyEndpoints>;

#[derive(Debug, Clone, Copy, Default)]
struct MyFamily;

#[async_trait(?Send)]
impl ProfiledVersionJsonFamily for MyFamily {
    type Source = MySource;
    type RemoteResolver = MyResolver;

    fn descriptor(&self) -> DriverDescriptor {
        MY_DRIVER
    }

    fn identity(&self) -> Option<ProfiledDriverIdentity> {
        Some(MY_IDENTITY)
    }

    fn remote_resolver(
        &self,
        vanilla_source: &VanillaSource,
        source: &Self::Source,
    ) -> Self::RemoteResolver {
        VanillaFallbackRemoteResolver::new(
            "myloader",
            vanilla_source.endpoints().clone(),
            source.endpoints().clone(),
        )
    }

    async fn profile(
        &self,
        source: &Self::Source,
        game_version: &MinecraftVersionId,
        loader_version: &LoaderVersionId,
    ) -> Result<ProfileJson> {
        source
            .profile_json(game_version.as_str(), loader_version.as_str())
            .await
    }
}

let driver = MyFamily.build_driver_with_defaults()?;
```

`MyEndpoints` must implement `LoaderMetaEndpoints` and `UpstreamUrlRewriter`.
`build_driver_with_defaults()` also requires `Default`; otherwise construct the
source explicitly and call `build_driver(source).with_vanilla_source(...)`. Use
`ProfileIdPattern::loader_prefixed(...)` when the installed profile id is
`<loader-prefix><version>` instead of `<game>-<loader>-<version>`.

### Add an installer loader

For Maven-published installers, implement `MavenSpec` for the coordinate and
release parsing, then implement `InstallerFamily` with the source, endpoint
types, inspection identity, family name, and loader-version prefix. The usual
aliases are:

```rust
type MyEndpoints = MavenEndpoints<MySpec>;
type MySource = InstallerMavenSource<MyEndpoints>;
type MyDriver = InstallerFamilyDriver<MyFamily>;
type MyCatalog = InstallerMavenCatalog<MyEndpoints>;
```

For a loader that replaces the runtime of an old Minecraft version, implement
`RetroFuturaCatalog` instead and use the shared RetroFutura aliases:

```rust
type MyDriver = RetroFuturaDriver<MyRetroFutura>;
type MyCatalog = RetroFuturaReleaseCatalog<MyRetroFutura>;
```

This is the same declaration used by Cleanroom and Outlands. It keeps base game
metadata, installer state, and launch handling shared instead of duplicating a
legacy-runtime driver.

### Add a fully custom driver

If a loader does not fit any shared family, implement `Driver` directly:

```rust
use async_trait::async_trait;
use elemental_core::storage::{Storage, layout::Layout};
use elemental_driver::{
    driver::{Driver, DriverDescriptor, InstalledDriver, PrepareRequest},
    error::Result,
    families::version_json::{
        PreparedVersionJsonInstance, VersionJsonInstanceLayout, VersionJsonRootLayout,
    },
    inspect::InstanceProbe,
};

const MY_DRIVER: DriverDescriptor = DriverDescriptor {
    id: "mydriver",
    name: "MyDriver",
};

struct MyDriver;

#[async_trait(?Send)]
impl<L: Layout, VL: Layout> Driver<L, VL> for MyDriver {
    fn descriptor(&self) -> DriverDescriptor {
        MY_DRIVER
    }

    async fn inspect(
        &self,
        probe: &InstanceProbe,
    ) -> Result<Option<InstalledDriver>> {
        let Some(metadata) = &probe.metadata else {
            return Ok(None);
        };

        // Match loader-specific metadata and return InstalledDriver::version_json(...).
        Ok(None)
    }

    async fn prepare(
        &self,
        request: &PrepareRequest<'_, L, VL>,
    ) -> Result<PreparedVersionJsonInstance<L, VL>>
    where
        L: VersionJsonRootLayout + Clone,
        VL: VersionJsonInstanceLayout + Clone,
    {
        // Resolve metadata, submit downloads through request.session, and
        // return the prepared version.
        todo!()
    }

    async fn load_prepared(
        &self,
        instance: &Storage<VL, Storage<L>>,
    ) -> Result<PreparedVersionJsonInstance<L, VL>>
    where
        L: VersionJsonRootLayout + Clone,
        VL: VersionJsonInstanceLayout + Clone,
    {
        todo!()
    }
}
```

Custom drivers can be passed directly to `InstalledInstance::detect()` or
`inspect_instances()`. A driver that supports preparation must also implement
`prepare` and `load_prepared`; most loaders should use the shared vanilla,
profiled, or installer families instead of implementing those operations
directly. `elemental-launcher` intentionally uses a closed, typed `DriverSpec`;
exposing a custom driver through the high-level launcher requires adding a
`DriverSpec` variant, a descriptor, and a matching `resolve_driver` arm.

## Modules

| Module | Contents |
| --- | --- |
| `catalog` | `GameVersionCatalog`, `LoaderVersionCatalog`, `GameVersion`, `LoaderRelease`, `InstallerMavenCatalog`, and `LoaderMetaCatalog` |
| `descriptors` | Stable driver identifiers and display names |
| `driver` | `DriverDescriptor`, `InstalledDriver`, and the `Driver` trait |
| `drivers` | Per-loader catalogs, sources, drivers, configs, and prepared state |
| `families` | Shared version JSON, installer, processor, and RetroFutura implementation families |
| `inspect` | Instance probes, installed-driver detection, and library markers |
| `loader_version` | The typed `LoaderVersionId` |
| `url` | `Origin` and `OriginPolicy` primitives |

## Core Concepts

### Catalogs

`GameVersionCatalog::game_versions()` returns the game versions known to a
source. `LoaderVersionCatalog::loader_versions(&game_version)` returns the
loader releases for one game version. `LoaderRelease` carries the typed game and
loader versions plus optional upstream metadata such as stability, stream, and
publication time.

`LoaderMetaCatalog` handles Fabric-style metadata APIs.
`InstallerMavenCatalog` handles installer-driven Maven metadata and uses each
endpoint's `release()` parser.

> [!NOTE]
> NeoForge game versions are inferred from the loader version naming. The
> installer profile remains the authoritative source when preparing an
> instance.

### Origins and mirrors

Every remote family declares typed origins. `OriginPolicy` rewrites upstream
URLs to configured overrides without changing the rest of the metadata.

- `VanillaEndpoints::mirror(...)` overrides all five Mojang origins at once.
- Fabric-family endpoints support `for_flavor(...)` and explicit overrides.
- Installer-driven sources expose Maven and installer endpoints.

This keeps mirror support in the source layer instead of spreading URL logic
through drivers.

### Inspection

`InstanceProbe` reads local version metadata. `InstalledInstance::detect()` and
`detect_all()` test available drivers and return the matching descriptor, loader
version, and game version. `ProfiledDriverIdentity` describes how a family
recognizes its marker libraries, profile ids, and loader versions. The
high-level launcher uses the same inspection path when reopening an existing
instance.

More specific drivers should be inspected before Vanilla, because a modded
installation still contains valid Minecraft metadata.

### Launch configuration

Launch command construction lives in `elemental_driver::launch` and is shared
by every driver, including installer-driven families. The driver layer only
defines `RuntimeOptions`, which controls runtime selection, an optional
explicit `Distribution`, and strict or disabled validation. Installer drivers
also use it while running client processors.

Host-facing launch options (launcher branding, client ID, resolution,
quick-play targets, and extra arguments) belong to `elemental-launcher`.
`VersionJsonLaunchBuilder` remains a driver implementation detail; hosts should
use `Launcher::build_launch_command()` instead of depending on it directly.

Both installer and version JSON drivers expose a prepared version JSON
instance, so launch construction does not branch on the driver family.

## Related Crates

- [elemental-core]https://github.com/ElectronicWave/Elemental/blob/main/crates/core/README.md
  provides storage, runtime, authentication, and process primitives.
- [elemental-infra]https://github.com/ElectronicWave/Elemental/blob/main/crates/infra/README.md
  provides the downloader used during installation.
- [elemental-schema]https://github.com/ElectronicWave/Elemental/blob/main/crates/schema/README.md
  defines the upstream manifest models.
- [elemental-launcher]https://github.com/ElectronicWave/Elemental/blob/main/crates/launcher/README.md
  exposes the high-level instance lifecycle built on these drivers.
- [elemental-kit]https://github.com/ElectronicWave/Elemental/blob/main/README.md#the-elemental-kit-facade
  re-exports this crate behind the `driver` feature.