Documentation/content/getting-started/plugin-lifecycle.en.md

title, type, weight

title	type	weight
Plugin Lifecycle	docs	4

Understanding the plugin lifecycle is essential for properly initializing and cleaning up your plugin resources.

Lifecycle States

A plugin goes through several states during its lifetime:

NONE → SETUP → START → ENABLED → SHUTDOWN → DISABLED

State	Description
NONE	Initial state before any initialization
SETUP	Plugin is in the setup phase
START	Plugin is starting
ENABLED	Plugin is fully operational
SHUTDOWN	Plugin is shutting down
DISABLED	Plugin has been disabled

Lifecycle Methods

Constructor

The constructor is called when the plugin is instantiated. Use this for:

• Registering configuration files with withConfig() (recommended)
• Storing the init reference if needed

import com.hypixel.hytale.server.core.util.Config;

private Config<MyConfig> config;

public MyPlugin(JavaPluginInit init) {
    super(init);
    // Register config in constructor - loaded asynchronously during preLoad()
    config = withConfig(MyConfig.CODEC);
}

{{< callout type="info" >}} Registering configs in the constructor ensures they are loaded asynchronously during preLoad(), before setup() is called. This is the recommended approach. {{< /callout >}}

setup()

Called during the initial setup phase, after configs are loaded. Use this for:

• Preparing resources that don't depend on other plugins
• Early initialization logic
• Accessing loaded configuration values

import java.util.logging.Level;

@Override
public void setup() {
    // Config is already loaded and available
    getLogger().at(Level.INFO).log("Setup complete!");
}

{{< callout type="info" >}} To create configuration classes with CODEC, see the [Codecs documentation]({{< ref "core-concepts/codecs#buildercodec" >}}). {{< /callout >}}

{{< callout type="warning" >}} Do not register commands or events in setup(). Other plugins may not be loaded yet. {{< /callout >}}

start()

Called after all plugins have completed setup. Use this for:

• Registering commands
• Registering event listeners
• Registering entities
• Interacting with other plugins

import com.hypixel.hytale.server.core.event.events.player.PlayerConnectEvent;
import com.hypixel.hytale.server.core.universe.PlayerRef;
import java.util.logging.Level;

@Override
public void start() {
    // Register commands
    getCommandRegistry().registerCommand(new MyCommand());

    // Register events
    getEventRegistry().register(PlayerConnectEvent.class, this::onPlayerConnect);

    getLogger().at(Level.INFO).log("Plugin started!");
}

private void onPlayerConnect(PlayerConnectEvent event) {
    // See PlayerRef documentation for thread-safe player references
    PlayerRef playerRef = event.getPlayerRef();
    getLogger().at(Level.INFO).log("Player connecting: " + playerRef.getUsername());
}

{{< callout type="info" >}} See the [Registries documentation]({{< ref "core-concepts/registries" >}}) for a complete list of available registries and their usage. {{< /callout >}}

shutdown()

Called when the plugin is being disabled or the server is stopping. Use this for:

• Saving data
• Cleaning up resources
• Canceling scheduled tasks

import java.util.logging.Level;

@Override
public void shutdown() {
    // Save any pending data
    savePlayerData();

    getLogger().at(Level.INFO).log("Plugin shutdown complete!");
}

{{< callout type="info" >}} Registries are automatically cleaned up after shutdown(). You don't need to manually unregister commands or events. {{< /callout >}}

Lifecycle Flow Diagram

{{< steps >}}

Plugin Loading

The server discovers your plugin JAR and reads manifest.json

Constructor Called

MyPlugin(JavaPluginInit init) is instantiated

preLoad()

Configuration files registered with withConfig() are loaded asynchronously

setup()

Your setup() method is called

start()

Your start() method is called after all plugins are set up

Running

Plugin is now in ENABLED state and fully operational

shutdown()

Called when server stops or plugin is disabled

Cleanup

All registries are automatically cleaned up

{{< /steps >}}

Checking Plugin State

You can check if your plugin is enabled:

if (isEnabled()) {
    // Plugin is running
}

if (isDisabled()) {
    // Plugin is not running
}

// Get current state
PluginState state = getState();

Next Steps

Learn how to Build and Run your plugin.