Hytale Modding Documentation

Choose Your Path

Pick the type of mod you want to create and get started.

Key Concepts

All Mods Are Server-Side

In Hytale, all mods run on the server. This means players can join any modded server without downloading anything. The server sends all needed content to players automatically.

The game client cannot be modified. This keeps the game secure and fair for everyone.

Two Types of Mods

Hytale has two main ways to create mods:

You can use these together. Packs handle content, plugins handle logic, and visual scripts (coming soon) will bridge the gap for non-programmers.

No Lua or Text Scripting

Hytale does not use Lua or other scripting languages. The team chose a different path:

• Visual Scripting (coming soon) - Build logic by connecting nodes
• Java Plugins - Full programming power for complex mods
• JSON Data - Configure content without code

"Text-based scripting is usually introduced to 'help non-programmers.' In reality, script languages like Lua are still programming languages. We see that as a false compromise." — Hypixel Studios

NPC AI & Behavior System

Hytale uses an advanced behavior system where NPCs respond naturally to their environment. The AI is built on components like fear, aggression, hunger, and emotions.

Behavior Scripting (JSON)

NPC behaviors use a two-part structure:

• Sensor — NPC detects environment (players, weather, items)
• Action — NPC responds (flee, seek, attack, alert)

{
  "sensor": {
    "type": "detectPlayer",
    "radius": 20
  },
  "action": {
    "type": "alert",
    "animation": "alerted",
    "beacon": {
      "radius": 15,
      "alertNearby": true
    }
  }
}

Modular Design

Abstract actions like 'flee' or 'seek' handle movement automatically. Scripts trigger animations and state changes without specifying low-level details. Combine multiple components to create complex behaviors.

Entity Component System (Flecs)

Hytale uses Flecs, a high-performance Entity Component System (ECS) framework. This allows dozens of creatures to run complex AI with excellent performance.

Modding Implications

Plugins can register custom Entity Stores via getEntityStoreRegistry(). This enables high-performance NPC systems, custom components for mod entities, and complex game logic using Flecs queries.

Sound & Audio Modding

Hytale's audio system supports custom sound effects, music, ambient audio, and NPC sounds.

Sound Design

• Foley-based sound creation
• Multiple audio layers (e.g., 8 clips for Fen Stalker alert)
• Processing: pitch shifting, reverb, EQ, layering
• Each weapon type has distinct audio signature

Block Event Sounds

Sounds can be linked to block events:

• Walking/running on blocks
• Hitting, breaking, building
• Material-specific sounds (soft vs hard)

UI/Interface Modding

Hytale is consolidating on NoesisGUI for UI rendering. Server-side plugins can create windows, dialogs, and HUD elements.

API Classes

• UICommandBuilder — Create/update UI elements
• UIEventBuilder — Handle UI events
• .ui files — Client-side layout format

Security & Anti-Cheat

Hytale uses a server-authoritative architecture with no kernel-level anti-cheat. The client cannot be modified, keeping the game secure.

Content Handshake

When joining a modded server:

1. Client connects to server
2. Server sends required assets
3. Client downloads automatically
4. No manual mod installation needed

Monetization & Creator Program

Hytale supports creators through a revenue-sharing program and fair monetization policies.

Creator Program

Apply at creators@hytale.com for eligibility as a content creator (videos, music, mods, art, streams).

Mod Monetization

• 0% commission for first two years
• Commission will never exceed 20%
• Visual mods can be sold (furniture, pets, hats, cosmetics)

Pay-to-Win Prohibition

Explicitly banned:

• Gameplay advantages, stronger weapons/armor
• Stat boosts, exclusive zones/quests/dungeons
• Resource advantages, progression shortcuts

Development History

Hytale has had a remarkable journey from concept to Early Access.

Current Status

• Ownership: 100% owned by original founders (no investors/publishers)
• Team Size: 50+ developers (many returned after cancellation)
• Funding: 10-year personal funding commitment secured
• Engine: Returned to original legacy engine for faster development

What You Need

For Packs (No Code)

• Hytale game (installed via launcher)
• Blockbench (free, for models)
• Any image editor (for textures)

For Plugins (Java)

• Hytale game (installed via launcher)
• Java 25 (Adoptium works best)
• IntelliJ IDEA (free Community Edition)
• Basic Java knowledge

Popular Topics

Popular Mods

Some of the most popular mods available on CurseForge:

Community Resources

Official Sources

• Hytale Modding Strategy and Status
• Hytale Creative Mode
• An Introduction to Making Models for Hytale
• The Future of World Generation
• Hytale Server Manual

Frequently Asked Questions

Quick answers to the most common questions about Hytale modding, servers, and gameplay.

System Requirements

How much RAM does Hytale need?

Minimum: 8 GB RAM. Recommended: 16 GB RAM for smooth gameplay with mods. Heavy modded servers benefit from 32 GB.

What CPU is best for Hytale?

Any modern quad-core processor (Intel i5/AMD Ryzen 5 or better). Hytale uses multi-threading, so more cores help with large worlds and many entities.

What graphics card does Hytale require?

Minimum: GTX 1050 / RX 560. Recommended: GTX 1660 / RX 5600 or better. Hytale uses Vulkan rendering for better performance.

How much storage space does Hytale need?

Base game requires approximately 15 GB. With mods and world saves, plan for 30-50 GB. SSD is highly recommended for faster loading.

What operating systems does Hytale support?

Hytale runs on Windows 10/11 (64-bit), macOS, and Linux. Windows has the best mod compatibility.

What internet speed do I need for Hytale multiplayer?

Minimum: 5 Mbps download / 1 Mbps upload. Recommended: 25+ Mbps for hosting or playing on modded servers.

Server Hosting

What port does Hytale use?

Hytale uses port 5520 UDP by default (QUIC protocol). You can change this with the --bind launch argument.

How do I port forward for Hytale?

Forward UDP port 5520 in your router settings to your server's local IP address. Hytale uses QUIC over UDP, not TCP.

How much RAM does a Hytale server need?

Small server (1-10 players): 4 GB. Medium (10-50 players): 8-16 GB. Large (50+ players): 32+ GB. Add more for heavy plugins.

How many players can a Hytale server hold?

Depends on hardware and mods. Well-optimized servers handle 100+ concurrent players. Default limit can be configured in server settings.

Can I run a Hytale server 24/7?

Yes! Use a dedicated server or VPS with Linux for best stability. The server runs headless without a GUI. Many hosting providers offer Hytale-specific plans.

How much does Hytale server hosting cost?

Ranges from $5-50/month depending on RAM and player slots. Self-hosting is free but requires your own hardware and internet.

What VPS specs are recommended for Hytale?

Minimum: 4 vCPU, 8 GB RAM, 50 GB SSD. Recommended: 8 vCPU, 16 GB RAM, 100 GB NVMe for production servers.

Modding Basics

How do I install Hytale mods?

Most mods install automatically when joining modded servers. For single-player packs, place them in %appdata%\Hytale\UserData\Mods\.

Where is the Hytale mods folder?

Windows: %appdata%\Hytale\UserData\Mods\
Full path: C:\Users\YourName\AppData\Roaming\Hytale\UserData\Mods\

Where can I download Hytale mods?

The official mod platform is CurseForge. Only download mods from trusted sources.

What types of mods can I create for Hytale?

Packs: No-code mods (models, textures, sounds, behaviors). Plugins: Java code for complex functionality. Both run server-side only.

Can I make client-side mods for Hytale?

No. Hytale does not support client modification. All mods run on the server and assets are downloaded automatically by clients.

Are Minecraft mods compatible with Hytale?

No. Hytale has its own modding API and file formats. Mods must be created specifically for Hytale.

Does Hytale use Lua scripting?

No. Hytale uses JSON for data configuration and Java for plugins. Visual scripting is planned for the future.

Can I sell my Hytale mods?

Yes! Visual mods (cosmetics, furniture, etc.) can be sold. Hypixel Studios takes 0% commission for the first two years, never exceeding 20% after.

Plugin Development

What Java version does Hytale require?

Hytale requires Java 25 or newer. Download from Adoptium (Eclipse Temurin).

What IDE should I use for Hytale plugins?

IntelliJ IDEA (Community or Ultimate) is recommended. The official plugin template includes IntelliJ run configurations.

Does Hytale use Gradle or Maven?

The official plugin template uses Gradle with Kotlin DSL (build.gradle.kts). Shadow plugin is used for fat JAR packaging.

Where is the Hytale API documentation?

Official API docs are available through the game's Javadocs. Community documentation at HytaleDocs.com.

How do I debug Hytale plugins?

Use IntelliJ's debug mode with the included run configuration. Remote debugging available on port 5005. Use --disable-sentry during development.

Can I hot-reload Hytale plugins?

Some changes reload automatically in development mode. For major changes, restart the server. The debug port (5005) allows live debugging.

Is there an official Hytale plugin template?

Yes! The official template is available on GitHub: hytale-template-plugin by Darkhax & Jared.

What are Bootstrap/Early plugins?

Advanced plugins that run before server initialization. They allow bytecode injection and class transformation using ASM or Mixin libraries.

Technical Questions

What network protocol does Hytale use?

Hytale uses QUIC over UDP for networking. This provides faster connections and better performance than traditional TCP.

Does Hytale use Vulkan or OpenGL?

Hytale uses Vulkan for rendering, providing better multi-core CPU utilization and performance compared to OpenGL.

What is the Hytale Entity Component System?

Hytale uses Flecs, a high-performance ECS framework. Entities are stored in tables with components as columns for efficient querying.

What UI framework does Hytale use?

Hytale uses NoesisGUI for user interface rendering. Plugins can create custom UIs using UICommandBuilder and UIEventBuilder.

Where are Hytale save files located?

Windows: %appdata%\Hytale\UserData\Saves\
Server worlds are stored in the server's worlds/ directory.

Where are Hytale config files?

Client: %appdata%\Hytale\UserData\Config\
Server: config/ folder in server directory.

Where are Hytale server logs?

Server logs are stored in the logs/ folder. Use getLogger().info(), .warn(), or .error() in plugins.

Gameplay Questions

Does Hytale have multiplayer?

Yes! Hytale supports dedicated servers, LAN play, and can host large multiplayer communities with custom game modes.

Does Hytale support cross-platform play?

Windows, macOS, and Linux players can all play together on the same servers. Mobile/console versions may have separate considerations.

Can I play Hytale offline/single-player?

Yes. Hytale includes a full single-player mode with Adventure Mode and Creative Mode. No internet required after installation.

Does Hytale have Creative Mode?

Yes! Creative Mode includes unlimited resources, flying, World Edit tools, and the Model Maker for creating custom content.

What are Hytale's world zones?

The world is divided into zones with different biomes: Zone 1 (temperate), Zone 2 (desert), Zone 3 (arctic), Zone 4 (tropical). Each has unique content.

How much does Hytale cost?

Hytale is a buy-to-play game (not free-to-play). Check the official website for current pricing during Early Access.

Do I need a launcher for Hytale?

Yes. Hytale uses its own launcher for downloading, updating, and launching the game. Available from hytale.com.

Content Creation

What is Blockbench used for in Hytale?

Blockbench is the recommended free tool for creating 3D models, including blocks, items, entities, and decorations for Hytale packs.

What model format does Hytale use?

Hytale uses its own .hymdl format for models. Blockbench can export directly to this format with the Hytale plugin.

What texture resolution should I use for Hytale?

Default is 16x16 pixels per block face. Higher resolutions (32x, 64x) are supported but increase file sizes and memory usage.

Can I create custom animations for Hytale?

Yes! Animations are defined in JSON files using keyframe data. The Model Maker includes animation tools for entity and item animations.

How do I add custom sounds to Hytale?

Place audio files (OGG format recommended) in your pack's sounds folder. Reference them in JSON behavior files for entities, blocks, or items.

Can I create custom particles in Hytale?

Yes. Particle effects are defined in JSON files specifying sprites, physics, colors, and emitter behaviors.

Troubleshooting

Why does Hytale crash on startup?

Common causes: outdated GPU drivers, insufficient RAM, incompatible Java version (need Java 25+), or corrupted game files. Verify files through launcher.

How do I reduce lag in Hytale?

Lower render distance, disable unnecessary mods, allocate more RAM (but not more than 75% of system RAM), update graphics drivers, use an SSD.

Why can't I connect to a Hytale server?

Check: correct IP/port (default 5520 UDP), server is online, firewall allows Hytale, router port forwarding configured, no VPN interference.

How do I fix mod conflicts in Hytale?

Check server logs for errors, disable mods one-by-one to identify conflicts, ensure mod versions match server version, report conflicts to mod authors.

Why isn't my plugin loading?

Verify: manifest.json is valid JSON, main class path is correct, compiled with Java 25, JAR is in plugins folder, check server logs for errors.

Why is Gradle sync failing?

Ensure Java 25 is installed and configured in IntelliJ. Check JAVA_HOME environment variable. Try: File → Invalidate Caches → Restart.

How do I allocate more RAM to Hytale?

Edit launcher settings or use JVM arguments: -Xmx8G for 8 GB max heap. Don't allocate more than 75% of your total system RAM.

Why is my FPS low in Hytale?

Update GPU drivers, lower graphics settings, reduce render distance, disable VSync, close background applications, ensure you're using Vulkan renderer.