hytale-server/docs/README.md

Hytale Server Modding Documentation

Welcome to the Hytale Server modding documentation. This guide provides comprehensive information for creating mods and extensions for the Hytale Server.

LLM Reference

LLM-Optimized API Reference - Complete API reference with exact class names, method signatures, and JSON structures. Use this for quick lookups.

Documentation Index

Getting Started

1. Getting Started - Introduction and first mod tutorial

Core Systems

2. Plugin Development - Creating and structuring plugins
3. Event System - Handling game events
4. Command System - Creating custom commands
5. Entity System (ECS) - Working with entities and components
6. World Management - Managing worlds and chunks

Communication & Data

7. Networking - Network protocol and packet handling
8. Asset System - Managing game assets
9. Configuration - Plugin and server configuration
10. Codec/Serialization - Data serialization framework

Game Systems

11. NPC/AI System - Creating and controlling NPCs
12. Built-in Modules - Using server modules

UI & Presentation

15. UI System - Pages, windows, HUD, and UI commands

Reference

13. Utilities - Common utility classes and APIs
14. Early Plugin System - Advanced bytecode transformation

Quick Start

Creating Your First Mod

1. Create a manifest.json:

{
    "Group": "com.example",
    "Name": "MyMod",
    "Version": "1.0.0",
    "Main": "com.example.MyMod"
}

2. Create your main class:

public class MyMod extends JavaPlugin {
    public MyMod(JavaPluginInit init) {
        super(init);
    }
    
    @Override
    protected void setup() {
        getLogger().info("MyMod loaded!");
    }
}

3. Build and place in mods/ directory

Key Concepts

Plugin Lifecycle

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

• SETUP: Register commands, events, entities
• START: Initialize plugin logic
• SHUTDOWN: Clean up resources

Available Registries

Registry	Purpose
CommandRegistry	Custom commands
EventRegistry	Event listeners
EntityRegistry	Custom entities
AssetRegistry	Custom assets
TaskRegistry	Scheduled tasks

Event Priority

Priority	Value	Use Case
FIRST	-21844	Monitoring/logging
EARLY	-10922	Pre-processing
NORMAL	0	Standard handling
LATE	10922	Post-processing
LAST	21844	Final processing

Package Structure

com.hypixel.hytale/
├── server/core/       # Core server functionality
├── event/             # Event system
├── component/         # Entity Component System
├── codec/             # Serialization
├── protocol/          # Networking
├── common/            # Utilities
├── math/              # Math utilities
└── builtin/           # Built-in modules

API Highlights

Events

getEventRegistry().register(PlayerConnectEvent.class, event -> {
    Player player = event.getPlayer();
    player.sendMessage("Welcome!");
});

Commands

public class MyCommand extends AbstractCommand {
    public MyCommand() {
        super("mycommand", "Description");
        withRequiredArg("player", "Target player");
    }
    
    @Override
    public void execute(CommandContext ctx, Arguments args) {
        String player = args.getString("player");
        ctx.sendMessage("Hello, " + player);
    }
}

Entities

public class CustomEntity extends Entity {
    public CustomEntity(World world) {
        super(world);
    }
}

// Register
getEntityRegistry().register("custom", CustomEntity.class, CustomEntity::new);

Configuration

public static final Codec<MyConfig> CODEC = BuilderCodec.of(MyConfig::new)
    .with("enabled", Codec.BOOLEAN, c -> c.enabled, true)
    .with("maxCount", Codec.INTEGER, c -> c.maxCount, 100)
    .build();

Best Practices

1. Register in setup() - All registrations should happen during setup
2. Use events - Prefer events over polling
3. Respect lifecycle - Don't access other plugins during setup
4. Handle errors - Log and handle exceptions gracefully
5. Clean up - Release resources in shutdown()
6. Use codecs - Serialize data with the codec system
7. Namespace assets - Use your mod ID as namespace
8. Document - Document your mod's features and configuration

Support

For questions and support:

• Check the Hytale modding forums
• Join the Discord community
• Report issues on GitHub

Contributing

Contributions to this documentation are welcome. Please submit pull requests with improvements or corrections.

---

This documentation is for Hytale Server modding. For official Hytale information, visit hytale.com.