elemental-driver 0.2.0

Driver library for Elemental, providing implementations for interacting with different modloaders and game versions.
Documentation

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

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

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:

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:

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.

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.

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:

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:

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:

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