elemental-core
Foundational primitives for storage, Java runtime discovery, authentication, and process launching.
elemental-core contains the reusable base layer shared by the Elemental
launcher stack. It provides typed version identifiers, resource layouts,
runtime discovery and validation, authorizers, and helpers for building and
spawning launch commands. Minecraft-specific installation logic lives in
elemental-driver; this crate stays focused on the primitives underneath it.
Features
- Tagged version types for Minecraft and loader version identifiers.
- Generic
Storage<L, P>andLayoutabstractions for nested resources. - Java runtime discovery from platform registries,
PATH, package-manager and toolchain directories, Minecraft's bundled runtimes, andJAVA_HOME/JRE_HOME. - Explicit runtime selection with strict or disabled Java version validation.
- Offline and Microsoft device-code authorizers.
- Opt-in Yggdrasil authorizer through the
yggdrasil-authfeature. - Account-level skin and cape queries and mutations for Microsoft and Yggdrasil.
LaunchCommandconstruction, process spawning, and streamed process logs.- SHA-1 helpers for files and in-memory data.
Installation
[]
= "1"
= "0.2"
= { = "1", = ["macros", "rt-multi-thread"] }
Quick Start
Create an offline credential and list the locally discovered Java runtimes:
use Result;
use ;
async
Offline credentials are intended for local development. Use an authorizer that
implements Authorizer for real accounts.
Modules
| Module | Responsibility |
|---|---|
auth |
Account, Authorizer, Credential, offline, Microsoft, and Yggdrasil auth |
consts |
Platform-dependent constants shared by launcher code |
hash |
Synchronous and asynchronous SHA-1 helpers |
launcher |
LaunchCommand plus process spawning and log streaming |
minecraft |
Minecraft version identifiers, parsing, and semantic ordering |
runtime |
Java runtime providers, distributions, and validation |
storage |
Generic Storage and Layout resource resolution |
version |
The tagged Version<Tag> identifier wrapper |
Feature Flags
| Feature | Description |
|---|---|
yggdrasil-auth |
Enables the Yggdrasil account and authorizer, and Credential::auth_server |
offline-server |
Enables yggdrasil-auth and re-exports nidhogg's offline server |
Core Concepts
Typed versions
Version<Tag> wraps a string and carries a domain tag at the type level.
MinecraftVersionId uses MinecraftVersionTag; other crates define additional
tags such as loader versions. The wrapper is an opaque identifier and does not
define semantic ordering.
use ;
let version = from;
assert_eq!;
assert_eq!;
let parsed = parse.unwrap;
assert!;
MinecraftVersion parses legacy releases, year-based releases, snapshots, and
pre-release stages. Use MinecraftVersion::key() for sorting and range queries;
the key normalizes missing components such as the patch number in 26.1, while
the original identifier is preserved unchanged.
Storage and layouts
Storage<L, P> pairs a root path with a layout. A layout maps typed resources
to paths without hard-coding the path rules into callers.
use ;
;
let storage = new;
let logs = storage.try_get_resource?;
# Ok::
Storage::scope() nests a child layout under the current root, and
Storage::ensure_root() creates the directory asynchronously. Layoutable
adds convenience methods for reading resources through the stored layout.
Runtime discovery
The default runtime providers inspect the Windows registry and installed
vendor directories, PATH, JAVA_HOME/JRE_HOME, known package-manager and
user toolchain locations (SDKMAN, asdf, Gradle, IntelliJ), and Minecraft's
bundled runtimes. Candidate roots are canonicalized, deduplicated, and sorted
by Java version. Runtimes without a release file are probed with a bounded
timeout and a cleaned Java environment.
Use RuntimeResolver to own discovery and caching. distributions() returns
every discovered runtime, and resolve() selects one by Java major version:
use RuntimeResolver;
let resolver = with_default_providers;
let runtime = resolver.resolve.await?;
assert!;
Hosts can bypass discovery by setting RuntimeOptions.runtime_override to a
Distribution. In strict mode its detected major version must match the
required version; RuntimeValidationMode::Disabled skips that check.
elemental-launcher injects one resolver per Launcher so different hosts can
use different provider lists without sharing process-wide state.
Custom runtime providers can reuse the public scanning helpers in
runtime::discovery, including find_runtime_homes(),
find_runtime_homes_with_prefixes(), and is_runtime_home(), instead of
reimplementing Java runtime layout checks.
Provider lists and their cache belong to a RuntimeResolver. There is no
process-wide provider override, so independent resolvers can use different
providers without sharing state.
Authentication and launch processes
Authentication is split into two module trees. auth::accounts owns the
Account trait, stable account identities, and the offline, Microsoft, and
Yggdrasil account types. The Yggdrasil types require the
yggdrasil-auth feature. auth::authorizers owns the Authorizer trait and
the corresponding login flows. An Authorizer is a login entry point with a
stable id() used for persistence and a human-readable name().
OfflineAuthorizer derives a deterministic offline UUID,
MicrosoftAuthorizer runs the Microsoft device-code flow, and
YggdrasilAuthorizer authenticates against an authlib-compatible API. An
Account is the persisted result of authorization and can be refreshed; a
Credential is the per-launch projection passed to the game and is never
persisted.
Account::textures() returns the current skin, available capes, and the
texture kinds the account can upload. Microsoft accounts expose the owned cape
inventory for selection; Yggdrasil accounts report the active cape and their
uploadableTextures capabilities. Mutations are explicit:
upload_skin(), delete_skin(), upload_cape(), delete_cape(), and
select_cape(). Providers that do not support an operation return
auth::Error::TextureUnsupported. Offline accounts have no remote textures;
use nidhogg's offline server for local skin and cape files.
A LaunchCommand contains the runtime, structured JVM and game arguments, the
main class, environment variables, and optional working directory. It remains
mutable before launch, so callers can append authentication-specific JVM
arguments or other overrides. spawn_command() launches it directly and lets
the child inherit the parent's stdout and stderr.
Related Crates
- elemental-schema supplies the manifest data models.
- elemental-driver builds Minecraft installations on top of these primitives.
- elemental-launcher exposes the high-level instance lifecycle.
- elemental-kit
re-exports this crate behind the
corefeature.