elemental-launcher
High-level instance lifecycle for prepared Minecraft installations.
elemental-launcher coordinates catalogs, drivers, storage layouts, the
downloader, runtime selection, and process launch. Authentication is completed
by the caller before launch. It supports the full range of Elemental drivers
while keeping the caller-facing flow small: inspect an instance, prepare or
reload it, build a mutable launch command, then start the game.
Features
- One facade for Vanilla, Fabric, Legacy Fabric, Babric, Quilt, LiteLoader, Rift, Forge, NeoForge, and Cleanroom.
- Prepare new instances or reopen installations that already exist on disk.
- Automatic driver and loader-version detection during inspection.
- Shared downloader and configurable root or instance layouts.
- Injected runtime providers with a per-launcher distribution cache.
- Launch-command construction for hosts that manage process creation.
- Process spawning through the core launch primitives.
- Typed runtime and launch options for runtime selection, resolution, quick play, and extra arguments.
- A stable read-only view of prepared instance metadata, natives, and the resolved classpath.
Installation
[]
= "1"
= "0.2"
= "0.2"
= { = "1", = ["macros", "process", "rt-multi-thread"] }
elemental-core is needed only for the authorizer used in the example. A real
application can supply its own Authorizer implementation.
Enable yggdrasil-auth to install and inject authlib-injector for any
Yggdrasil-compatible credential. Enable offline-server to additionally
re-export nidhogg's local Yggdrasil server:
= { = "0.2", = ["offline-server"] }
Quick Start
Prepare a Vanilla instance and build its launch command:
use Result;
use ;
use ;
async
prepare() downloads and writes missing artifacts with a default download
session. To start the game, pass the command to launch().
Inspect a prepared instance without touching driver internals:
let info = prepared.info?;
println!;
Authentication is independent from launch. An Authorizer returns a
Account; Account::credential() produces the Credential that
build_launch_command() injects into the game arguments and returns a mutable
LaunchCommand. Authentication-specific JVM arguments can be appended after
that without changing the credential type.
Accounts
AccountStore persists accounts under .elemental/accounts:
index.jsonlistsAccountRefentries and the selected account.<authorizer>/<account_id>.jsonstores one authorizer-specific account.
Authorizer::id() is the stable persistence key, so it must not change once
accounts exist. Authorizer::name() is only for user interfaces. Accounts are
persisted and refreshable; Credential is derived per launch and is
never written to disk. With yggdrasil-auth, Yggdrasil credentials
carry their API root in Credential::auth_server for authlib-injector.
Accounts are serializable domain models; the launcher owns when and where they
are persisted. Third-party authorizers register their account type through
AccountRegistry, then open the store with AccountStore::with_registry().
Textures
AccountStore refreshes an account when needed before texture operations:
use Account;
use SkinModel;
let selected = store.selected.await?.expect;
let account = store.account.await?;
let textures = account.textures.await?;
if let Some = &textures.skin
for cape in &textures.capes
let image_bytes = read?;
account
.upload_skin
.await?;
if let Some = textures.capes.iter.find_map
Microsoft accounts read skins and owned capes from Minecraft Services and
support skin upload, skin reset, cape selection, and cape clearing. Yggdrasil
accounts read textures and uploadableTextures from their session server and
support skin or cape upload and deletion when the server advertises the
capability. ProfileTextures::uploadable tells the UI which upload actions to
offer; ProfileTextures::active_cape() returns the selected cape.
Observing preparation progress
Create and observe the session before passing it to prepare_with_session().
The launcher finishes and validates the session after preparation:
let session = launcher
.downloader
.session
.open
.await?;
let progress = session.progress_receiver;
let prepared = launcher
.prepare_with_session
.await?;
println!;
The view exposes active tasks, the last-seen group, and task and byte counters. Formatting task and group names is left to the UI.
The session is the only progress source. Use progress_receiver() for
snapshots or subscribe() for structured download events; the launcher does not
wrap either stream.
Custom download sessions
Use prepare_with_session() when the host needs custom retry or rate-limit
settings. Build and observe the session first, then pass ownership to the
launcher for finishing and validation:
let session = launcher
.downloader
.session
.parallelism
.open
.await?;
let prepared = launcher
.prepare_with_session
.await?;
The session exposes progress_receiver(), subscribe(), and snapshot() for
UI progress reporting.
Offline server and authlib-injector
With the offline-server feature, elemental_launcher::offline_server
re-exports nidhogg's local Yggdrasil service:
use ;
use ;
let server = builder
.server_name
.profile
.start?;
let credential = account
.credential
.await?
.with_auth_server;
When Credential::auth_server is set and the yggdrasil-auth feature is
enabled (included by offline-server), build_launch_command() installs
authlib-injector to .elemental/authlib-injector/authlib-injector.jar and adds:
-javaagent:<jar>=<auth_server>
-Dauthlibinjector.side=client
The latest artifact metadata is fetched at runtime, and downloads are verified
against the SHA-256 checksum in that metadata. Enable authlib-injector-embed
to include a build-time snapshot; metadata, download, or verification failures
then fall back to the embedded JAR. Without that feature, failures are returned
to the caller. Call launcher.install_authlib_injector().await? to install it
before launch.
Instance Lifecycle
| Operation | Method |
|---|---|
| Discover local instances | inspect_instances() |
| Detect one instance and its driver | inspect_instance(name) |
| Install or refresh an instance | prepare(name, driver, runtime) |
| Install with an observed or configured session | prepare_with_session(session, name, driver, runtime) |
| Reload an existing installation | load_instance(instance) |
| Build a command without spawning | build_launch_command(...) |
| Spawn a customized command | launch(command) |
| Build and spawn in one call | launch_prepared_instance(...) |
| Launch an installed instance by name | launch_instance(...) |
Catalogs are not wrapped by the launcher. Use
DriverCatalog::for_driver(driver)?.game_versions() and
DriverCatalog::for_driver(driver)?.loader_versions(&game_version) directly.
Reopen an instance without preparing it again:
let instances = launcher.inspect_instances.await?;
for instance in instances
if let Some = launcher
.inspect_instance
.await?
[!NOTE]
load_instance()expects a complete local installation. Use--local-onlyin launchpad, or inspect before loading, when network access is unavailable.
Driver Specifications
DriverSpec selects the installation flow:
| Variant | Loader version |
|---|---|
DriverSpec::vanilla(game_version) |
Game version only |
FABRIC_DRIVER, LEGACY_FABRIC_DRIVER, BABRIC_DRIVER, QUILT_DRIVER |
Game and loader version |
LITELOADER_DRIVER, RIFT_DRIVER |
Game and loader version |
FORGE_DRIVER, NEOFORGE_DRIVER, CLEANROOM_DRIVER, OUTLANDS_DRIVER |
Game and loader version |
Vanilla has no loader version and uses its own constructor. DriverSpec::any()
is for loader-driven distributions and requires all three values:
use FABRIC_DRIVER;
let driver = any?;
When the driver comes from inspection or a CLI, build the spec from the descriptor instead of matching on it:
let game_version = instance
.driver
.game_version
.clone
.ok_or_else?;
let spec = from_descriptor?;
from_descriptor() rejects a loader version for Vanilla and requires one for
every loader-driven distribution.
Launch Options
Launch configuration is split by lifecycle:
RuntimeOptionscoversruntime_major_version,runtime_override, andruntime_validation.LaunchOptionscovers launcher name and version, client ID, window resolution, quick-play targets, and extra JVM and game arguments.
LaunchOptions is owned by elemental-launcher. The driver crate only exposes
RuntimeOptions; version JSON launch configuration stays an implementation
detail behind Launcher::build_launch_command().
Use RuntimeOptions::default() for automatic runtime selection with strict
Java version validation, and LaunchOptions::default() when no branding or
window customization is needed.
Pass the same RuntimeOptions to preparation and launch. Installer-driven
families resolve their client-processor runtime during preparation, so the
override must be available there as well.
Builder Customization
The default storage root is .minecraft, and the builder creates a shared
downloader automatically. Applications can override either:
use ElementalDownloader;
use Launcher;
let launcher = builder
.storage_root
.downloader
.build;
Use root_layout() and instance_layout() for custom layouts. All launcher
construction goes through Launcher::builder().
Custom layouts
A layout only maps typed resources to paths; storage_root remains the game
root. Implement Layout with Resource = VersionJsonRootResource or
Resource = VersionJsonInstanceResource; the marker traits are implemented
automatically. Delegating unknown resources to the base layout keeps the
custom layout complete:
use ;
use Layout;
use ;
use Launcher;
;
;
let launcher = builder
.storage_root
.root_layout
.instance_layout
.build;
Root layouts receive the game root; instance layouts receive the instance
directory. Custom instance layouts must be Clone + Send, and both layouts
must be Clone because the launcher clones them into scoped storage views.
Extending resources
VersionJsonRootResource and VersionJsonInstanceResource are closed enums:
the launcher and drivers match them to locate metadata, libraries, assets, and
natives. Hosts cannot add variants to them.
Use Layout::ExtendedResource for resources that only your application
consumes. Wrap the standard resource in your own enum and delegate through
get_resource():
;
When the launcher uses this layout, read extended resources through
Layoutable:
use Layoutable;
let screenshots = prepared
.version
.try_get_extended_resource?;
If a resource must participate in installation or launch, it cannot be added from the host; it belongs in the driver's resource enum and its installation or launch logic.
Runtime discovery is a launcher dependency rather than a process-wide setting. Pass providers explicitly when the host needs its own set:
use default_providers;
let launcher = builder
.runtime_providers
.build;
for runtime in launcher.runtime_resolver.distributions.await
The launcher caches distributions per RuntimeResolver, so multiple launchers
can use different provider lists in the same process without sharing state.
Origin Overrides
origin_overrides() receives one configuration block per driver, so each
driver keeps its own typed origin enum instead of collapsing them into a
launcher-wide list. Overrides replace the base URL while preserving the
upstream path suffix:
use ;
use Launcher;
let launcher = builder
.origin_overrides?
.build;
[!WARNING] Preparing an instance may download metadata, libraries, assets, and loader installers. Launching it requires a compatible local Java runtime unless an explicit executable is supplied.
Related Crates
- elemental-core supplies authentication, runtime discovery, storage, and process primitives.
- elemental-driver supplies catalogs and loader-specific preparation logic.
- elemental-infra supplies the downloader.
- elemental-kit
re-exports this crate behind the
launcherfeature. - launchpad shows the complete CLI flow.