187 lines
4.5 KiB
Markdown
187 lines
4.5 KiB
Markdown
---
|
|
title: Plugin Lifecycle
|
|
type: docs
|
|
weight: 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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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
|
|
|
|
```java
|
|
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:
|
|
|
|
```java
|
|
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](../building-and-running) your plugin.
|