# Getting Started with Hytale Server Modding

## Overview

The Hytale Server provides a comprehensive modding API that allows developers to extend and customize the game. This
documentation covers the essential systems and APIs available for mod development.

## Architecture Overview

The server is built on several core systems:

| System                        | Purpose                                                        |
|-------------------------------|----------------------------------------------------------------|
| Plugin System                 | Mod loading, lifecycle management, and dependency resolution   |
| Entity Component System (ECS) | High-performance entity management with components and systems |
| Event System                  | Prioritized event dispatching with sync/async support          |
| Command System                | Player and console command handling                            |
| Asset System                  | Game asset loading and registration                            |
| Codec System                  | Data serialization/deserialization framework                   |
| Protocol Layer                | Network communication and packet handling                      |

## Package Structure

The codebase is organized under `com.hypixel.hytale`:

```
com.hypixel.hytale/
├── server/core/           # Core server functionality
│   ├── plugin/            # Plugin management
│   ├── command/           # Command system
│   ├── entity/            # Entity management
│   ├── universe/          # World/Universe management
│   ├── registry/          # Server registries
│   └── ...
├── event/                 # Event bus and handlers
├── component/             # ECS framework
├── codec/                 # Serialization framework
├── protocol/              # Network protocol
├── common/                # Shared utilities
├── math/                  # Math utilities and vectors
└── builtin/               # Built-in game modules
```

## Creating Your First Mod

### 1. Project Setup

Create a new Java project with the Hytale Server API as a dependency.

### 2. Create the Plugin Manifest

Create a `manifest.json` file in your JAR's root:

```json
{
    "Group": "com.example",
    "Name": "MyFirstMod",
    "Version": "1.0.0",
    "Description": "My first Hytale mod",
    "Authors": ["YourName"],
    "Main": "com.example.MyFirstMod",
    "ServerVersion": ">=1.0.0",
    "Dependencies": {},
    "IncludesAssetPack": false
}
```

### 3. Create the Main Plugin Class

```java
package com.example;

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

public class MyFirstMod extends JavaPlugin {
    
    public MyFirstMod(JavaPluginInit init) {
        super(init);
    }
    
    @Override
    protected void setup() {
        // Called during plugin setup phase
        // Register commands, events, components here
        getLogger().info("MyFirstMod is setting up!");
    }
    
    @Override
    protected void start() {
        // Called when the plugin starts
        getLogger().info("MyFirstMod has started!");
    }
    
    @Override
    protected void shutdown() {
        // Called when the plugin is shutting down
        // Clean up resources here
        getLogger().info("MyFirstMod is shutting down!");
    }
}
```

### 4. Build and Deploy

1. Build your project as a JAR file
2. Place the JAR in the server's `mods/` directory
3. Start the server

## Plugin Lifecycle

Plugins go through the following states:

1. **NONE** - Initial state before loading
2. **SETUP** - `setup()` is called; register components, commands, events
3. **START** - `start()` is called; plugin becomes active
4. **ENABLED** - Plugin is fully operational
5. **SHUTDOWN** - `shutdown()` is called during server stop
6. **DISABLED** - Plugin is disabled and unloaded

## Available Registries

Your plugin has access to several registries for registration:

| Registry              | Access Method                | Purpose                       |
|-----------------------|------------------------------|-------------------------------|
| CommandRegistry       | `getCommandRegistry()`       | Register custom commands      |
| EventRegistry         | `getEventRegistry()`         | Register event listeners      |
| EntityRegistry        | `getEntityRegistry()`        | Register custom entity types  |
| BlockStateRegistry    | `getBlockStateRegistry()`    | Register block states         |
| TaskRegistry          | `getTaskRegistry()`          | Schedule recurring tasks      |
| AssetRegistry         | `getAssetRegistry()`         | Register custom asset types   |
| ClientFeatureRegistry | `getClientFeatureRegistry()` | Register client-side features |
| EntityStoreRegistry   | `getEntityStoreRegistry()`   | Register ECS entity stores    |
| ChunkStoreRegistry    | `getChunkStoreRegistry()`    | Register chunk data stores    |

## Next Steps

- [Plugin Development](02-plugin-development.md) - In-depth plugin creation guide
- [Event System](03-event-system.md) - Handling game events
- [Command System](04-command-system.md) - Creating custom commands
- [Entity System](05-entity-system.md) - Working with entities and ECS
- [World Management](06-world-management.md) - Managing worlds and chunks