alts

A Minecraft Java Edition account library for sign-in, account management, an encrypted store and a shared vault.

Install

The coordinate is com.github.trq-lol:lol.trq.alts. Replace VERSION with the release tag, for example v1.0.0. Releases up to 0.11.1 were published under the repository’s previous owner and are not served under this coordinate.

Gradle (Groovy)</summary>

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.trq-lol:lol.trq.alts:VERSION'
}

</details>

Gradle (Kotlin)</summary>

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.trq-lol:lol.trq.alts:VERSION")
}

</details>

Requirements:

  • Java 25. The library is compiled for Java 25 and uses virtual threads.
  • Gson, as a transitive dependency. @SerializedName sits on the public records, so Gson is part of the API and the library declares it as an ordinary api dependency: Gradle and Maven consumers receive com.google.code.gson:gson at compile and run time without declaring it. An application that ships its own Gson resolves the version as for any other dependency.
  • Module path. The jar is the named module lol.trq.alts (a module-info.java, no Automatic-Module-Name). It exports the API packages only and requires transitive com.google.gson, so requires lol.trq.alts; is all a consumer module needs. On the class path the jar is sealed, so no other jar can add classes to its packages.

Quick start

// 1. Wire the host seams once at startup. H is your texture-handle type; a host that draws no
//    avatars can use any type and leave textureUploader unset.
//    build() also reads whatever store is already on disk, so alts.store().accounts()
//    is populated the moment it returns. Close the runtime when the host is done with it.
AltsRuntime<MyHandle> alts = new AltsRuntime.Builder<MyHandle>()
        .sessionInjector(new MySessionInjector())   // REQUIRED: install a SessionData as the live session
        .vaultDirectory(() -> myDataDir)             // REQUIRED: where the two encrypted store files live
        .mainThread(myExecutor::execute)             // REQUIRED: run a task on the host's main thread
        .toastSink(new MyToastSink())                // REQUIRED: surface a notification
        .textureUploader(new MyUploader())           // optional: avatar bytes -> host texture
        .microsoftAuth(MicrosoftAuthConfig.of(MY_AZURE_CLIENT_ID))  // optional: your own Azure app id
        .build();

// 2. Sign in through the browser.
alts.loginService().loginMicrosoft(LoginMode.ADD)
        .thenAccept(result -> { /* result.success(), result.account(), result.failure() */ });

// Or with a device code, when there is no browser to open.
alts.loginService().loginDeviceCode(
                (userCode, verificationUri, expiresAt) -> show(verificationUri, userCode),
                LoginMode.ADD)
        .thenAccept(result -> { /* result.success(), result.failure().map(AltsFailure::kind) */ });

// 3. Operate on a stored account without logging into it. A failure throws AltsException;
//    switch on e.kind().
AccountServices services = alts.accountServices(account);
PlayerProfile profile = services.profile().fetch();
Entitlements owned = services.entitlements().fetch();

// 4. On shutdown: write what is pending and release the store files.
alts.close();

See docs/GETTING_STARTED.md for a full walkthrough and docs/ARCHITECTURE.md for the internals.