Init

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

@@ -0,0 +1,186 @@
+---
+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.