hytale-server/docs/02-plugin-development.md

# Plugin Development

## Plugin Structure

A Hytale plugin consists of:

1. A main class extending `JavaPlugin`
2. A `manifest.json` file with plugin metadata
3. Optional asset packs for client-side resources

## The Plugin Manifest

The `manifest.json` file must be placed at the root of your JAR:

```json
{
    "Group": "com.example",
    "Name": "MyPlugin",
    "Version": "1.0.0",
    "Description": "A description of what this plugin does",
    "Authors": ["Author1", "Author2"],
    "Website": "https://example.com",
    "Main": "com.example.MyPlugin",
    "ServerVersion": ">=1.0.0",
    "Dependencies": {
        "com.other:OtherPlugin": ">=2.0.0"
    },
    "OptionalDependencies": {
        "com.soft:SoftDep": ">=1.0.0"
    },
    "LoadBefore": ["com.load:BeforeThis"],
    "DisabledByDefault": false,
    "IncludesAssetPack": true
}
```

### Manifest Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `Group` | String | Yes | Maven-style group ID (e.g., `com.example`) |
| `Name` | String | Yes | Plugin name (unique identifier within group) |
| `Version` | String | Yes | Semantic version (e.g., `1.0.0`) |
| `Description` | String | No | Brief description of the plugin |
| `Authors` | String[] | No | List of author names |
| `Website` | String | No | Plugin website or repository URL |
| `Main` | String | Yes | Fully qualified main class name |
| `ServerVersion` | String | No | Required server version range |
| `Dependencies` | Object | No | Required plugin dependencies with version ranges |
| `OptionalDependencies` | Object | No | Optional plugin dependencies |
| `LoadBefore` | String[] | No | Plugins that should load after this one |
| `DisabledByDefault` | Boolean | No | If true, plugin must be explicitly enabled |
| `IncludesAssetPack` | Boolean | No | If true, plugin includes client assets |

### Plugin Identifier

Plugins are identified by `Group:Name` format (e.g., `com.example:MyPlugin`). This identifier is used for:
- Dependency resolution
- Permission namespacing (`com.example.myplugin.*`)
- Configuration keys

## The JavaPlugin Class

```java
package com.example;

import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.java.JavaPluginInit;

public class MyPlugin extends JavaPlugin {
    
    private Config<MyConfig> config;
    
    public MyPlugin(JavaPluginInit init) {
        super(init);
        // Initialize config BEFORE setup() is called
        this.config = withConfig(MyConfig.CODEC);
    }
    
    @Override
    protected void setup() {
        // Register all components during setup
        registerCommands();
        registerEvents();
        registerEntities();
    }
    
    @Override
    protected void start() {
        // Plugin is now active
        // Access other plugins, start services, etc.
    }
    
    @Override
    protected void shutdown() {
        // Clean up resources
        // Save data, close connections, etc.
    }
    
    private void registerCommands() {
        getCommandRegistry().registerCommand(new MyCommand());
    }
    
    private void registerEvents() {
        getEventRegistry().register(PlayerConnectEvent.class, this::onPlayerConnect);
    }
    
    private void registerEntities() {
        getEntityRegistry().register("customEntity", CustomEntity.class, CustomEntity::new);
    }
    
    private void onPlayerConnect(PlayerConnectEvent event) {
        getLogger().info("Player connected: " + event.getPlayer().getName());
    }
}
```

## Plugin Lifecycle States

```
NONE -> SETUP -> START -> ENABLED -> SHUTDOWN -> DISABLED
```

| State | Description |
|-------|-------------|
| `NONE` | Initial state before any lifecycle methods |
| `SETUP` | `setup()` is executing; register components here |
| `START` | `start()` is executing; plugin becoming active |
| `ENABLED` | Plugin is fully operational and handling events |
| `SHUTDOWN` | `shutdown()` is executing; cleanup in progress |
| `DISABLED` | Plugin is fully disabled and unloaded |

## Configuration

### Defining a Configuration Class

```java
public class MyConfig {
    public static final Codec<MyConfig> CODEC = BuilderCodec.of(MyConfig::new)
        .with("enabled", Codec.BOOLEAN, c -> c.enabled, true)
        .with("maxPlayers", Codec.INTEGER, c -> c.maxPlayers, 100)
        .with("welcomeMessage", Codec.STRING, c -> c.welcomeMessage, "Welcome!")
        .build();
    
    public final boolean enabled;
    public final int maxPlayers;
    public final String welcomeMessage;
    
    private MyConfig(boolean enabled, int maxPlayers, String welcomeMessage) {
        this.enabled = enabled;
        this.maxPlayers = maxPlayers;
        this.welcomeMessage = welcomeMessage;
    }
}
```

### Using Configuration

```java
public class MyPlugin extends JavaPlugin {
    private Config<MyConfig> config;
    
    public MyPlugin(JavaPluginInit init) {
        super(init);
        this.config = withConfig(MyConfig.CODEC);
    }
    
    @Override
    protected void setup() {
        MyConfig cfg = config.get();
        if (cfg.enabled) {
            getLogger().info("Max players: " + cfg.maxPlayers);
        }
    }
}
```

Configuration is stored in the server's config under your plugin identifier.

## Available Registries

### CommandRegistry

Register custom commands:

```java
getCommandRegistry().registerCommand(new MyCommand());
```

See [Command System](04-command-system.md) for details.

### EventRegistry

Register event listeners:

```java
// Simple registration
getEventRegistry().register(PlayerConnectEvent.class, this::onConnect);

// With priority
getEventRegistry().register(EventPriority.EARLY, PlayerConnectEvent.class, this::onConnect);

// Global listener (all events of type)
getEventRegistry().registerGlobal(EntityEvent.class, this::onAnyEntity);

// Async event
getEventRegistry().registerAsync(AsyncEvent.class, this::onAsync);
```

See [Event System](03-event-system.md) for details.

### EntityRegistry

Register custom entity types:

```java
getEntityRegistry().register("myEntity", MyEntity.class, MyEntity::new);

// With serialization codec
getEntityRegistry().register("myEntity", MyEntity.class, MyEntity::new, MyEntity.CODEC);
```

### BlockStateRegistry

Register custom block states:

```java
getBlockStateRegistry().register("myBlock", MyBlockState.class);
```

### TaskRegistry

Schedule recurring tasks:

```java
getTaskRegistry().register(new MyTask());
```

### AssetRegistry

Register custom asset types:

```java
getAssetRegistry().register(MyAsset.class, MyAsset.CODEC);
```

### ClientFeatureRegistry

Register client-side features:

```java
getClientFeatureRegistry().register("myFeature", MyFeature.class);
```

## Permissions

Plugins automatically receive a base permission derived from their identifier:

```
{group}.{name} -> com.example.myplugin
```

Commands registered by your plugin will have permissions under:

```
{basePermission}.command.{commandName}
```

For example, if your plugin is `com.example:MyPlugin` and you register a command `spawn`:
- Base permission: `com.example.myplugin`
- Command permission: `com.example.myplugin.command.spawn`

## Logging

Use the built-in logger:

```java
getLogger().info("Information message");
getLogger().warn("Warning message");
getLogger().error("Error message");
getLogger().debug("Debug message");
```

## Dependencies

### Hard Dependencies

Hard dependencies must be present for your plugin to load:

```json
{
    "Dependencies": {
        "com.example:RequiredPlugin": ">=1.0.0"
    }
}
```

### Optional Dependencies

Optional dependencies are loaded if present but not required:

```json
{
    "OptionalDependencies": {
        "com.example:OptionalPlugin": ">=1.0.0"
    }
}
```

Check if optional dependency is loaded:

```java
@Override
protected void setup() {
    if (getPluginManager().isPluginLoaded("com.example:OptionalPlugin")) {
        // Optional plugin is available
    }
}
```

### Load Order

Use `LoadBefore` to ensure specific plugins load after yours:

```json
{
    "LoadBefore": ["com.example:LoadAfterMe"]
}
```

## Asset Packs

If your plugin includes client-side assets, set `IncludesAssetPack` to `true`:

```json
{
    "IncludesAssetPack": true
}
```

Place assets in your JAR under the `assets/` directory following Hytale's asset structure.

## Best Practices

1. **Register everything in `setup()`** - Commands, events, entities should all be registered during setup
2. **Use `start()` for initialization logic** - Access other plugins, connect to databases, etc.
3. **Clean up in `shutdown()`** - Close connections, save data, cancel tasks
4. **Use configuration** - Make your plugin configurable instead of hardcoding values
5. **Handle errors gracefully** - Log errors but don't crash the server
6. **Respect the lifecycle** - Don't access other plugins during setup, wait for start()
7. **Use meaningful permissions** - Follow the automatic permission naming convention