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
GameVersionCatalogandLoaderVersionCatalogcontracts. - Direct, profiled, installer-driven, and RetroFutura installation families.
- A shared
Drivertrait 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
[]
= "1"
= "0.2"
= { = "1", = ["macros", "rt-multi-thread"] }
Quick Start
Game versions
List the Minecraft versions known to the Vanilla catalog:
use ;
async
Loader versions
Loader catalogs use LoaderVersionCatalog. Fabric exposes a flavor selector for
Legacy Fabric and Babric:
use MinecraftVersionId;
use ;
async
Forge-family catalogs use their Default endpoint configuration:
use MinecraftVersionId;
use ;
async
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.
use ;
let driver = new
.new_driver_with_overrides?;
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
Sourcethat fetches the profile; - a
RemoteResolverfor loader and Vanilla URLs; - an optional
ProfiledDriverIdentityfor 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.
use async_trait;
use MinecraftVersionId;
use ;
use ProfileJson;
const MY_DRIVER: DriverDescriptor = DriverDescriptor ;
const MY_LIBRARIES: LibraryPrefixSet =
new;
const MY_IDENTITY: ProfiledDriverIdentity = new;
// MyEndpoints implements LoaderMetaEndpoints + UpstreamUrlRewriter + Default.
type MySource = ;
type MyResolver = ;
;
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:
type MyEndpoints = ;
type MySource = ;
type MyDriver = ;
type MyCatalog = ;
For a loader that replaces the runtime of an old Minecraft version, implement
RetroFuturaCatalog instead and use the shared RetroFutura aliases:
type MyDriver = ;
type MyCatalog = ;
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:
use async_trait;
use ;
use ;
const MY_DRIVER: DriverDescriptor = DriverDescriptor ;
;
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 provides storage, runtime, authentication, and process primitives.
- elemental-infra provides the downloader used during installation.
- elemental-schema defines the upstream manifest models.
- elemental-launcher exposes the high-level instance lifecycle built on these drivers.
- elemental-kit
re-exports this crate behind the
driverfeature.