hytale-server/docs/01-getting-started.md

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:

{
    "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

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 - In-depth plugin creation guide
• Event System - Handling game events
• Command System - Creating custom commands
• Entity System - Working with entities and ECS
• World Management - Managing worlds and chunks