Lifecycle API

The lifecycle API can be used for lifecycle-related registration. It is currently used by the Brigadier command API. It is planned to be used for the Registry Modification API as well. Generally, systems that are initialized very early in the startup process can take advantage of this event system.

The LifecycleEventManager is tied to either a Plugin instance or a BootstrapContext depending on where you access it from. For example in your plugin’s main class:

@Override
public void onEnable() {
    final LifecycleEventManager<Plugin> lifecycleManager = this.getLifecycleManager();
}

Or, with a bootstrapper:

@Override
public void bootstrap(BootstrapContext context) {
    final LifecycleEventManager<BootstrapContext> lifecycleManager = context.getLifecycleManager();
}

After obtaining the correct LifecycleEventManager, create a event handler by selecting an event type from LifecycleEvents:

@Override
public void onEnable() {
    final LifecycleEventManager<Plugin> lifecycleManager = this.getLifecycleManager();
    PrioritizedLifecycleEventHandlerConfiguration<LifecycleEventOwner> config = LifecycleEvents.SOME_EVENT.newHandler((event) -> {
        // Handler for the event
    });
}

Each handler created can be configured in several ways. The available configuration options depend on the event type itself and will vary from event type to event type.

Setting the priority of a handler can determine where it runs relative to other handlers on the same event type. The lower the number, the earlier it will be run. The default priority is 0.

Marking the handler as a monitor will cause it to be called after all other non-monitor handlers have been called. Only use this to inspect some state in the event. Do not modify any state in the handler.

The priority and monitor state are exclusive options, setting one will reset the other.

@Override
public void onEnable() {
    final LifecycleEventManager<Plugin> lifecycleManager = this.getLifecycleManager();
    PrioritizedLifecycleEventHandlerConfiguration<LifecycleEventOwner> config = LifecycleEvents.SOME_EVENT.newHandler((event) -> {
        // Handler for the event
    });
    config.priority(10); // sets a priority of 10
    // or
    config.monitor(); // marks the handler as a monitor
}

Once the handler has been configured, it can be registered with the lifecycle manager:

@Override
public void onEnable() {
    final LifecycleEventManager<Plugin> lifecycleManager = this.getLifecycleManager();
    PrioritizedLifecycleEventHandlerConfiguration<LifecycleEventOwner> config = LifecycleEvents.SOME_EVENT.newHandler((event) -> {
        // Handler for the event
    }).priority(10);
    lifecycleManager.registerEventHandler(config);
}

There is also a shorthand way to register just the handler without doing any configuration:

@Override
public void onEnable() {
    final LifecycleEventManager<Plugin> lifecycleManager = this.getLifecycleManager();
    lifecycleManager.registerEventHandler(LifecycleEvents.COMMANDS, (event) -> {
        // Handler for the event
    });
}

We already have an event system, why do we need another one? This is a fair question. The answer is that some of these events fire well before JavaPlugin instances are created, before the MinecraftServer instance is created, right at the very start of server startup. These can be before all the registries have been initialized which is one of the first things to happen on a Vanilla server. The existing Bukkit event system is not designed to exist at this time, and modifying it to support this environment is more trouble than just having a separate system for specific events that can fire during this early initialization.