Events

Events are an essential part of building your own launcher. They allow you to receive updates from the backend, such as the current launch status, the game exit code, and many other events during the launch process.

Where events live

Events aren't all posted by one class - different modules post to different categories, but they all follow the same EventBus/subscribe()/unsubscribe() pattern described on this page:

Connection: online/offline detection, posted by minified-launch before network-dependent work.
Download: asset, library and client JAR download progress.
Environment: graphics environment setup on Linux.
Launch: the Minecraft process starting and stopping.
Loader: Forge/NeoForge installer progress.
Java: managed Java runtime resolution, download and extraction (minified-java).
Auth: session encryption (minified-auth).

Only the Connection, Download, Environment, Launch and Loader events are posted to the EventBus you pass to LaunchConfiguration.Builder.eventBus(...) (via LaunchContext).

The Java and Auth events are posted by JavaManager and AuthManager respectively, and each keeps its own internal, static EventBus that has nothing to do with LaunchConfiguration's. AuthManager.init(baseDir, eventBus) does not forward that bus to JavaManager either - internally it always calls the single-argument JavaManager.init(path), which resets Java's bus back to a fresh, private one.

To actually receive EnsureJavaVersionEvent, JavaArchiveDownloadEvent, ExtractArchiveEvent, or any of the Auth encryption events, you need to explicitly (re-)initialize JavaManager (and AuthManager, if you want its events too) with the same EventBus instance - and do it after AuthManager.init(...), since that call would otherwise overwrite JavaManager's bus back to a private one:

EventBus eventBus = new EventBus();

AuthManager.init(authDirectory, eventBus);
// AuthManager.init() just reset JavaManager to a private bus internally,
// so re-point it at the shared bus afterwards:
JavaManager.init(javaDirectory, eventBus);

LaunchConfiguration config = new LaunchConfiguration.Builder()
        // ...
        .eventBus(eventBus)
        .build();

Skip this and subscribers on the LaunchConfiguration's bus will simply never see Java or Auth events - there's no error, they just go to a different, private EventBus instance.

All events

Connection

minified-events

CheckConnectionEventGets fired when we're checking whether the user is online or not

OfflineEventGets fired when no connection could be resolved

Auth

minified-auth

CreateMasterKeyEventGets fired when AuthManager generates a brand new master key used to encrypt/decrypt the saved session file

LoadEncryptedSessionEventGets fired right after AuthManager successfully decrypts a previously saved session from disk

SaveEncryptedSessionEventGets fired right after AuthManager finishes encrypting and saving a session to disk

Java

minified-java

EnsureJavaVersionEventCalled when the Java version requestedMajorVersion must be ensured before the game can launch.

ExtractArchiveEventGets fired while a downloaded Java archive is being extracted

JavaArchiveDownloadEventGets fired while a Java runtime archive is being downloaded

Launch

minified-launch

ConfigureX11EnvironmentEventGets fired when the X11 Environment gets configured, only on Linux when using Wayland

DownloadAssetsEventGets fired every time a new asset file has been downloaded

DownloadClientJarEventGets fired while the Minecraft client JAR is being downloaded

DownloadLibrariesEventGets fired every time a new library file has been downloaded

GameOutputEventGets fired for every line the game prints, only when captureGameOutput is enabled in the launch configuration

GameProcessStartedEventGets fired right after the Minecraft process was spawned, so a launcher can keep a handle to it (to stop it, for example)

GameStartEventGets fired when Minecraft is starting

GameStoppedEventGets fired when the Minecraft Process has been stopped

InstallForgeEventFired continuously while Minecraft Forge is installing

InstallNeoforgeEventFired continuously while NeoForge is installing

Usage

Firstly, create your EventBus Object:

EventBus eventBus = new EventBus();

val eventBus = EventBus()

Then, in your LaunchConfiguration, add

.eventBus(eventBus)

Subscribing to Events

// replace SomeEvent with any event you'd like to listen to
eventBus.subscribe(SomeEvent.class, event -> {
    // Code here will get executed when the event gets triggered
});

// replace SomeEvent with any event you'd like to listen to
eventBus.subscribe(SomeEvent::class.java) { event ->
    // Code here will get executed when the event gets triggered
}

Unsubscribing to Events

This might not seem useful, but it's a requirement for a clean and fast launcher. For example, if the user closes some GUI that displays it, listening to an event that triggers often would waste resources. And generally, forgetting to unsubscribe can eventually lead to memory leaks, which you should avoid.

Unsubscribing from an event prevents the code you registered during subscription from being triggered when the event is fired.

// replace SomeEvent with the event you want to unsubscribe from
eventBus.unsubscribe(SomeEvent.class, listener);

// replace SomeEvent with the event you want to unsubscribe from
eventBus.unsubscribe(SomeEvent::class.java, listener)

Example

EventBus eventBus = new EventBus();

LaunchConfiguration config = new LaunchConfiguration.Builder()
        .downloadThreads(10)
        .launcherName("MinifiedLauncher")
        .launcherVersion("1.0.0")
        .assetsDirectory(Path.of("<assets-directory>"))
        .librariesDirectory(Path.of("<libraries-directory>"))
        .jarFile(Path.of("<client.jar>"))
        .isDemoUser(false)
        .loader(new VanillaLoader("1.21.11"))
        .eventBus(eventBus) // EventBus used by the API to dispatch events
        .build();

Launcher.launchMinecraft(
        user,
        config
);

// Subscribe to the Event
eventBus.subscribe(DownloadAssetsEvent.class, event -> {
    System.out.printf(
            "\rDownloading assets | %.2f%% | %s | %d/%d bytes",
            event.progress() * 100,
            event.currentFile(),
            event.downloadedBytes(),
            event.totalBytes()
    );
    System.out.flush();
});

val eventBus = EventBus()

val config = LaunchConfiguration.Builder()
    .downloadThreads(10)
    .launcherName("MinifiedLauncher")
    .launcherVersion("1.0.0")
    .assetsDirectory(Path.of("<assets-directory>"))
    .librariesDirectory(Path.of("<libraries-directory>"))
    .jarFile(Path.of("<client.jar>"))
    .isDemoUser(false)
    .loader(VanillaLoader("1.21.11"))
    .eventBus(eventBus) // EventBus used by the API to dispatch events
    .build()

Launcher.launchMinecraft(
    user,
    config
)

// Subscribe to the event
eventBus.subscribe(DownloadAssetsEvent::class.java) { event ->
    print(
        "\rDownloading assets | %.2f%% | %s | %d/%d bytes".format(
            event.progress() * 100,
            event.currentFile(),
            event.downloadedBytes(),
            event.totalBytes()
        )
    )
    System.out.flush()
}