Modding Overview

This documentation provides a comprehensive guide to creating mods and plugins for the Hytale dedicated server.

Documentation Sections

🔌 Plugin Development

Plugin system, events, commands, permissions, and task scheduling.

🎯 Entity System (ECS)

Components, entity stats, physics simulation, and player persistence.

⚙️ Gameplay Systems

Damage, movement, mounts, interactions, projectiles, and effects.

🤖 NPC & AI

AI behaviors, spawning, flocking, and navigation.

🌍 World Generation

Zones, biomes, and cave systems.

📦 Content & World

Assets, inventory, prefabs, fluids, time, and lighting.

🌐 Networking

Protocol handling, packet interception, and network utilities.

📚 JavaDoc API Reference

Full API documentation for all Hytale server classes, methods, and fields.

Server Architecture

HytaleServer
├── PluginManager      - Plugin loading, lifecycle, and hot-reloading
├── EventBus           - Event dispatch system
├── CommandManager     - Command registration and execution
├── Universe           - World, entity, and player management
├── ServerManager      - Network I/O (QUIC/UDP protocol)
└── AssetModule        - Asset pack loading and management

Plugin Locations

Plugins are loaded from multiple locations in this order:

1. Core plugins - Built-in server functionality
2. Builtin directory - builtin/ next to the server JAR
3. Classpath - Plugins bundled with the server
4. Mods directory - mods/ (user plugins)
5. Additional directories - Specified via --mods-directories option

Key Concepts

Plugins

Plugins are Java JAR files placed in the mods/ directory. Each plugin has a manifest.json that defines metadata, dependencies, and the main class. See Plugin Development for details.

Components (ECS)

Hytale uses an Entity-Component-System architecture. Entities are lightweight references, components store data, and systems process logic. See Entity System for details.

Events

The event system allows plugins to react to game occurrences. Events can be synchronous or asynchronous, and support priority ordering. See Events for details.

Registries

Custom content (components, commands, assets) is registered through type-safe registries that handle lifecycle management. See Assets & Registry for details.

Requirements

• Java 25 or higher (Adoptium/Temurin recommended)
• HytaleServer.jar

Quick Start

1. Create a new Java project
2. Add HytaleServer.jar to your classpath
3. Create your plugin class extending JavaPlugin
4. Create a manifest.json file
5. Build your JAR and place it in the mods/ directory

See Plugin System for a complete guide.

Default Server Port

The default server port is 5520 (UDP with QUIC protocol).