# Table of Contents - [Overview | Hytale Modding Documentation](#overview-hytale-modding-documentation) - [Frequently Asked Questions | Hytale Modding Documentation](#frequently-asked-questions-hytale-modding-documentation) - [Youtube Tutorials | Hytale Modding Documentation](#youtube-tutorials-hytale-modding-documentation) - [Technical Insights | Hytale Modding Documentation](#technical-insights-hytale-modding-documentation) - [Hytale Modding Overview | Hytale Modding Documentation](#hytale-modding-overview-hytale-modding-documentation) - [Setting Up a Local Server | Hytale Modding Documentation](#setting-up-a-local-server-hytale-modding-documentation) - [Server Commands & Permissions | Hytale Modding Documentation](#server-commands-permissions-hytale-modding-documentation) - [Running a Dedicated Server | Hytale Modding Documentation](#running-a-dedicated-server-hytale-modding-documentation) - [Hytale Server Manager | Hytale Modding Documentation](#hytale-server-manager-hytale-modding-documentation) - [Server Configuration | Hytale Modding Documentation](#server-configuration-hytale-modding-documentation) - [Server Tips & Optimization | Hytale Modding Documentation](#server-tips-optimization-hytale-modding-documentation) - [Future Server Additions | Hytale Modding Documentation](#future-server-additions-hytale-modding-documentation) - [Block State Changing | Hytale Modding Documentation](#block-state-changing-hytale-modding-documentation) - [Item Categories | Hytale Modding Documentation](#item-categories-hytale-modding-documentation) - [Example Command to Show Title | Hytale Modding Documentation](#example-command-to-show-title-hytale-modding-documentation) - [Getting Started with Packs | Hytale Modding Documentation](#getting-started-with-packs-hytale-modding-documentation) - [Adding a Block | Hytale Modding Documentation](#adding-a-block-hytale-modding-documentation) - [Block Animations | Hytale Modding Documentation](#block-animations-hytale-modding-documentation) - [Getting Started with Plugins | Hytale Modding Documentation](#getting-started-with-plugins-hytale-modding-documentation) - [Blockbench Modeling Guide | Hytale Modding Documentation](#blockbench-modeling-guide-hytale-modding-documentation) - [Custom Config Files | Hytale Modding Documentation](#custom-config-files-hytale-modding-documentation) - [Gradle Automation & Testing | Hytale Modding Documentation](#gradle-automation-testing-hytale-modding-documentation) - [Useful Tools & Links | Hytale Modding Documentation](#useful-tools-links-hytale-modding-documentation) - [Bootstrap/Early Plugins | Hytale Modding Documentation](#bootstrap-early-plugins-hytale-modding-documentation) - [Common Plugin Features | Hytale Modding Documentation](#common-plugin-features-hytale-modding-documentation) - [Advanced Plugin Patterns | Hytale Modding Documentation](#advanced-plugin-patterns-hytale-modding-documentation) - [World Generation Modding | Hytale Modding Documentation](#world-generation-modding-hytale-modding-documentation) - [Plugin Project Template | Hytale Modding Documentation](#plugin-project-template-hytale-modding-documentation) --- # Overview | Hytale Modding Documentation **Compiled:** January 16, 2026 **Status:** Hytale is currently in Early Access **Official Reference:** [Hytale Modding Strategy and Statusarrow-up-right](https://hytale.com/news/2025/11/hytale-modding-strategy-and-status) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#important-notice) Important Notice ------------------------------------------------------------------------------------------------------------------ Hytale is currently in **Early Access**. This documentation is based on official Hytale sources and community testing. **Key Points:** * Official tools are actively being developed and improved. * Official GitBook documentation is in progress by Hytale developers. * **Take frequent backups** - crashes can cause data loss. > _"We're building Hytale with modding at its core. Most of what you see in the game can be changed, extended, or removed entirely."_ - Slikey (Technical Director) [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#if-you-need-further-help-feel-free-to-join-my-discord-and-write-a-message-to-britakee) if you need further help, feel free to join my [Discordarrow-up-right](https://discord.gg/gCRv62araB) , and write a message to @Britakee --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#table-of-contents) Table of Contents -------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#introduction) INTRODUCTION * **Overview** (README.md) * [**Frequently Asked Questions**](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions) ❓ * [**Technical Insights**](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights) ⚙️ * [**Youtube Tutorials**](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials) 📺 ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#getting-started) GETTING STARTED * [**Hytale Modding Overview**](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview) ⭐ Official modding categories, philosophy, tools, and long-term vision. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#server-administration) SERVER - ADMINISTRATION * [**Setting Up a Local Server**](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server) 🏠 * [**Running a Dedicated Server**](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server) ☁️ * [**Hytale Server Manager**](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager) 🛠️ * [**Server Configuration**](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration) 📝 * [**Server Commands & Permissions**](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions) 🛡️ * [**Server Tips & Optimization**](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization) ⚡ * [**Future Server Additions**](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions) 🚀 ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#packs-content-creation) PACKS - CONTENT CREATION * [**Getting Started with Packs**](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs) How to create your first Pack: folder structure, manifest file, and basic setup. * [**Adding a Block**](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block) Complete guide to creating custom blocks with textures, properties, and Asset Editor usage. * [**Block State Changing**](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing) How to create blocks with multiple states (on/off, open/closed). * [**Item Categories**](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories) Creating custom categories and subcategories for the Creative Menu. * [**Block Animations**](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations) Adding animations to blocks using Blockbench and `.blockyanim` files. * [**Blockbench Modeling Guide**](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide) 🎨 ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#plugins-java-development) PLUGINS - JAVA DEVELOPMENT * [**Getting Started with Plugins**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins) Setting up IntelliJ IDEA and creating your first Java plugin. * [**Example Command to Show Title**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title) Practical implementation of a title command. * [**Custom Config Files**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files) Registering configuration files using Hytale's Codec system. * [**Common Plugin Features**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features) Placeholders, translations, utilities, and chat channels. * [**Advanced Plugin Patterns**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns) Architecture patterns: Service-Storage, thread pools, and event systems. * [**Gradle Automation & Testing**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing) Automated server testing and development workflows. * [**Bootstrap/Early Plugins**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins) ⚠️ Advanced: Low-level modifications using class transformers. * [**Plugin Project Template**](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template) ⭐ Ready-to-use plugin template with modern build tools and CI/CD. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#resources-and-tools) RESOURCES & TOOLS * [**Useful Tools & Links**](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links) ⭐ * [**World Generation Modding**](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding) 🌍 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#quick-start-guides) 🚀 Quick Start Guides ------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#for-content-creators-no-coding) For Content Creators (No Coding): **Creating Asset Packs:** 1. Start with [Hytale Modding Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview) 2. Follow [Getting Started with Packs](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs) 3. Learn [Adding a Block](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block) 4. Explore [Block Animations](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations) and [Block State Changing](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing) **Required Tools:** * **Blockbench** (for 3D models) * **Image editor** (for textures) * **Text editor** (for JSON files) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#for-developers-java-programming) For Developers (Java Programming): **Creating Plugins:** 1. Read [Hytale Modding Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview) 2. Clone the [Plugin Project Template](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template) - Start with a working project! 3. Follow [Getting Started with Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins) 4. Study [Example Command: Show Title](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title) **Required Tools:** * **IntelliJ IDEA** * **Java 25 JDK** * **Gradle** (included in template) **Quick Start:** Copy git clone https://github.com/realBritakee/hytale-template-plugin.git cd hytale-template-plugin ./gradlew shadowJar # Builds immediately! * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#what-are-mods-in-hytale) What Are Mods in Hytale? --------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#four-official-modding-categories) Four Official Modding Categories: 1. **Server Plugins (Java .jar files)** * **Purpose:** Extend server functionality programmatically. * **Use Cases:** Minigames, economies, custom logic. * **Tools:** Java 25, IntelliJ IDEA. 1. **Data Assets (JSON files)** * **Purpose:** Drive gameplay behavior and define core content. * **Content:** Blocks, items, NPCs, world generation. * **Tools:** Asset Editor (no coding required). 1. **Art Assets (Sounds, Models, Textures)** * **Purpose:** Visual and audio representation. * **Tools:** Blockbench (Official Support). 1. **Save Files (Worlds and Prefabs)** * **Purpose:** Share complete creations and structures. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#file-paths-quick-reference) 📂 File Paths Quick Reference ----------------------------------------------------------------------------------------------------------------------------------------- **For Packs:** `%AppData%/Roaming/Hytale/UserData/mods/` **For Plugins:** `%AppData%/Roaming/Hytale/UserData/earlyplugins/` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#version-history) 📜 Version History ------------------------------------------------------------------------------------------------------------------- Date Version Changes **Jan 16, 2026** **1.2** Full restructure to match documentation taskbar; added all 24 local pages. Jan 10, 2026 1.1 Updated with official Hytale modding strategy, categories, and visual scripting info. Jan 9, 2026 1.0 Initial compilation of community tutorials. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#official-resources) 🌐 Official Resources ------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#official-hytale) Official Hytale * [**Hytale Official Site**arrow-up-right](https://hytale.com/) — Main website * [**Modding Strategy & Status**arrow-up-right](https://hytale.com/news/2025/11/hytale-modding-strategy-and-status) — Official roadmap * [**Official Discord**arrow-up-right](https://discord.gg/hytale) — Direct access to developers * [**Official Blog**arrow-up-right](https://hytale.com/news) — Latest updates and announcements ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#official-tools) Official Tools * **Blockbench** — Official 3D modeling tool * **Hytale Asset Editor** — Built into the game (Creation Tools) * **Asset Graph Editor** — Coming soon (node-based editor) * **Visual Scripting** — Planned for future release ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#official-documentation-in-progress) Official Documentation (In Progress) * **GitBook Documentation** — Being developed by Hytale team * **Server Source Code** — Expected March 2026 (1-2 months after Early Access) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#support) 🆘 Support --------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#getting-help) Getting Help: 1. **Read the relevant tutorial** — Most questions are answered in the docs. 2. **Check Troubleshooting sections** — Common issues are documented. 3. **Search Community Forums** — Your question may have been answered. 4. **Ask the Community** — Join Hytale modding communities. 5. **Check Official Resources** — Refer to official documentation. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#when-asking-for-help) When Asking for Help: Please include: * What you're trying to achieve * What you've tried * Error messages (if any) * Relevant code/JSON * Your environment (OS, Java version, Hytale version) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#license-and-terms) ⚖️ License & Terms --------------------------------------------------------------------------------------------------------------------- This documentation is provided for educational purposes to help the Hytale modding community. * **License:** Community documentation * **Usage:** Free for educational and development purposes * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation#stay-updated) ✨ Stay Updated ------------------------------------------------------------------------------------------------------------ Hytale modding is evolving! Stay informed: * Join Hytale modding communities * Follow official Hytale channels * Check community resources regularly * Watch for announcements in-game [NextFrequently Asked Questionschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions) Last updated 2 days ago --- # Frequently Asked Questions | Hytale Modding Documentation **Last Modified:** Friday, January 16, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#overview) Overview --------------------------------------------------------------------------------------------------------------------------------------------- This page answers frequently asked questions about Hytale modding, server architecture, and technical capabilities. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#client-and-server-architecture) Client & Server Architecture --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#id-1.-can-the-client-be-modded) 1\. Can the client be modded? **No**, the client cannot be modded directly. **However:** * The server controls how the game and UI looks * Works similar to "Resource Packs" in Minecraft * The server decides what mods are used * Visuals are server-side controlled * No client-side mods needed for security and consistency **Benefits of Server-Side Modding:** * Join any modded server without downloading external mods * One stable client for all players * Better security (no client modifications) * Unified community experience * Server owners control the experience **Philosophy:** > _"One Community, One Client"_ - Hytale avoids the fragmented ecosystem of different modded clients by keeping all modifications server-side. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#network-and-technical) Network & Technical --------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#id-2.-what-network-protocol-will-be-used) 2\. What Network Protocol will be used? **Hytale uses the QUIC transport protocol.** ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#understanding-internet-protocols) Understanding Internet Protocols: **UDP (User Datagram Protocol):** * Connectionless and fast * Fire-and-forget packets * Less reliability (packets can be lost) **TCP (Transmission Control Protocol):** * Connection-based * Slower than UDP * Guaranteed packet delivery * Much more reliability **QUIC (Quick UDP Internet Connections):** * **Hybrid protocol** building on UDP * Same speed benefits as UDP * Adds reliability layers like TCP * **Excellent for game development** * Blends speed and reliability **Why QUIC?** * Best of both worlds for multiplayer gaming * Modern, efficient protocol * Designed for low-latency applications * Industry-proven (used by Google, YouTube, etc.) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#server-infrastructure) Server Infrastructure ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#id-3.-what-are-transfer-packets) 3\. What are Transfer Packets? **Transfer packets** are small data payloads (4KB) that allow players to move from one server to another while carrying information. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#key-points) Key Points: **What They Are:** * Small data containers (4KB limit) * Carry player information between servers * Enable seamless server transitions * Preserve inventory, stats, and progress **What They Are NOT:** * **Not equivalent to BungeeCord or Velocity** * Do not manage network-wide features * Do not support global plugins * DDOS protection would be very difficult for small networks ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#best-use-cases) Best Use Cases: **Perfect For:** * Small server networks * Hub-based setups * Server-to-server player transfers * Preserving player state across servers **Example Scenario:** Copy Player finishes dungeon on Server A ↓ Transfer packet created with inventory + stats ↓ Player moves to Server B (lobby) ↓ Inventory and stats intact ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#benefits) Benefits: * **Lower Server Costs** - Distribute players across multiple servers * **Better Performance** - Dedicated servers for specific game modes * **Development Focus** - Less time on network infrastructure, more on gameplay * **Seamless Experience** - Players don't lose progress when switching servers ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#limitations) Limitations: * Primarily intended for **smaller servers** * Not a full proxy solution like BungeeCord * 4KB data limit per transfer * Network-wide features require custom implementation * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#id-4.-will-hytale-support-dedicated-servers) 4\. Will Hytale support dedicated servers? **Yes!** Hytale will fully support dedicated servers. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#what-this-means) What This Means: **Hosting Options:** * Host on your own hardware * Use third-party hosting services * Full control over server settings * Install and configure mods * Optimize performance ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#benefits-of-dedicated-servers) Benefits of Dedicated Servers: **Complete Control:** * Server settings and configurations * Mod installation and management * Performance tuning and optimization * Backup and maintenance schedules **Flexibility:** * Choose your hosting provider * Scale resources as needed * Run custom plugins and packs * Full administrative access **Professional Options:** * Enterprise-grade hosting * Custom hardware configurations * Advanced networking setups * Professional support options ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#hosting-methods) Hosting Methods: 1. **Self-Hosted** - Run on your own hardware 2. **VPS/Cloud** - Rent virtual private servers (DigitalOcean, AWS, etc.) 3. **Game Hosting** - Specialized game server hosts 4. **Hybrid** - Mix of self-hosted and cloud resources * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#platform-support) Platform Support ------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#id-5.-will-hytale-support-modding-on-consoles) 5\. Will Hytale support modding on consoles? **As of now, Hytale modding is primarily focused on PC platforms.** ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#current-status) Current Status: **PC Platforms:** * Windows * macOS * Linux **Console Support:** * Not confirmed for modding * Game may come to consoles in the future * Modding tools designed for PC ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#why-pc-first) Why PC-First? **Technical Reasons:** * Modding requires file system access * Console platforms have restrictions * Development tools are PC-based * Testing and iteration easier on PC **Platform Limitations:** * Console manufacturers restrict modifications * Certification processes are complex * Updates and patches have approval delays * File access is limited or prohibited ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#future-possibilities) Future Possibilities: While current modding support is PC-focused, the team hasn't ruled out future console support for: * Playing on modded servers (server-side mods) * Official mod marketplace * Curated content packs **Stay Updated:** * Follow official Hytale announcements * Join the [Official Discordarrow-up-right](https://discord.gg/hytale) * Check the [Hytale Blogarrow-up-right](https://hytale.com/news) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions#getting-help) Getting Help ----------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousOverviewchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation) [NextTechnical Insightschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights) Last updated 1 day ago --- # Youtube Tutorials | Hytale Modding Documentation This tutorial by **Britakee** provides a step-by-step guide on using the in-game Asset Editor to create your first Pack and add a custom item to Hytale. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials#hytale-modding-tutorial-1-setup-packs-and-custom-item) Hytale Modding Tutorial #1: Setup Packs & Custom Item ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ > **Note:** If the video player above does not appear, you can [click here to watch on YouTubearrow-up-right](https://www.youtube.com/watch?v=_XwdR1fOl5U) > . * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials#key-takeaways) Key Takeaways ---------------------------------------------------------------------------------------------------------------------------------------------- * **Asset Editor Access:** To use the editor, you must first op yourself in a creative world by typing `/op self` in the chat \[[00:56arrow-up-right](http://www.youtube.com/watch?v=_XwdR1fOl5U&t=56)\ \]. * **Pack Creation:** Packs can be created directly within the Asset Editor by clicking the three dots in the corner and selecting "Add Pack" \[[01:18arrow-up-right](http://www.youtube.com/watch?v=_XwdR1fOl5U&t=78)\ \]. * **Folder Setup:** After creating a pack in-game, you must manually create a `Common/Resources` folder structure in the pack's directory to hold your texture files \[[02:10arrow-up-right](http://www.youtube.com/watch?v=_XwdR1fOl5U&t=130)\ \]. * **Custom Items:** You can quickly create new items by using the "Copy Asset" feature to duplicate an existing Hytale item and then modifying its texture and properties \[[02:52arrow-up-right](http://www.youtube.com/watch?v=_XwdR1fOl5U&t=172)\ \]. * **Localization:** To fix the item's name in the inventory, you need to create a `Server/Languages/en-US/server.lang` file and define the item name key \[[04:05arrow-up-right](http://www.youtube.com/watch?v=_XwdR1fOl5U&t=245)\ \]. * **Sharing Mods:** To make your mod available globally, compress the manifest and folders into a `.zip` file and move it to `%AppData%/Hytale/UserData/Mods/` \[[04:52arrow-up-right](http://www.youtube.com/watch?v=_XwdR1fOl5U&t=292)\ \]. [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials#getting-help) Getting Help -------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousTechnical Insightschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights) [NextHytale Modding Overviewchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview) Last updated 1 day ago * [Hytale Modding Tutorial #1: Setup Packs & Custom Item](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials#hytale-modding-tutorial-1-setup-packs-and-custom-item) * [Key Takeaways](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials#key-takeaways) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Technical Insights | Hytale Modding Documentation **Last Modified:** Friday, January 16, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------- Comprehensive summary of technical insights from Hytale developers covering architecture, modding, gameplay systems, and development philosophy. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#technical-architecture) Technical Architecture ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#network-and-infrastructure) Network & Infrastructure #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-network-protocol-does-hytale-use) What network protocol does Hytale use? **QUIC (Quick UDP Internet Connections)** Hytale uses QUIC, which is a reliable UDP protocol with unreliable channels, instead of traditional TCP. **Benefits:** * Fast like UDP * Reliable like TCP * Optimized for gaming * Modern internet standard **Known Limitation:** * QUIC may be blocked in some regions * No alternative protocol currently planned * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-platforms-can-run-hytale-servers) What platforms can run Hytale servers? **Any platform supporting Java 25** * Windows (primary) * Linux (actively supported) * macOS (in development) * Any OS with Java 25 runtime **Server Hosting:** * Available on day 1 of Early Access * No business agreements required * Just comply with EULA/TOS * Full self-hosting support * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-does-multiplayer-connectivity-work) How does multiplayer connectivity work? **Connection Methods:** * **Launch:** Direct IP connection * **Post-Launch:** Server discovery system planned * **No Authentication Server Required:** For direct connections * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-is-the-server-tick-rate) What is the server tick rate? **Default: 30 TPS (Ticks Per Second)** * Base server tick rate is 30 TPS * Can be changed using server plugins * Multi-core support for better performance * Each world has main thread + parallel execution * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-rendering-technology-does-hytale-use) What rendering technology does Hytale use? **OpenGL 3.3** **Why OpenGL 3.3:** * Mac compatibility * Wide hardware support * Stable and proven **Future Plans:** * Potential migration to Vulkan * Potential migration to Metal * Performance improvements planned * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#security-and-distribution) Security & Distribution #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-clients-execute-custom-code) Can clients execute custom code? **No - Absolutely not.** **Security Model:** * No client-side code execution * Prevents remote code execution exploits * Server controls everything * Safe, sandboxed environment **What Clients Can Download:** * Configuration files * Assets (models, textures, sounds) * Executable code * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-are-mods-distributed) How are mods distributed? **Community Platforms** **Primary Channels:** * [CurseForgearrow-up-right](https://www.curseforge.com/) * [Modrintharrow-up-right](https://modrinth.com/) * GitHub releases * Community websites **In-Game Marketplace:** * Not planned for immediate launch * May be added later * Focus on community platforms first * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#modding-capabilities) Modding Capabilities ------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#server-side-power) Server-Side Power #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-can-java-plugins-do) What can Java plugins do? **Full Java Access - Anything Java Can Do** **Capabilities:** * Database connections (MySQL, PostgreSQL, MongoDB) * Web requests (REST APIs, webhooks) * Any Java library or framework * Custom systems (economy, permissions, clans) * Machine learning frameworks * Scripting languages (Lua, JavaScript) **Example Use Cases:** * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-server-code-be-modified) Can server code be modified? **Yes - Full Server Source Access** **Features:** * Shared server source code * Developer comments included * Unobfuscated code * Heavy modifications possible * Learn from official implementation **Benefits:** * Understand how systems work * Unblock yourself when documentation is sparse * Contribute improvements and bug fixes * Create deep integrations * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#is-hot-reload-supported) Is hot reload supported? **Yes - For Most Asset Types** **Hot Reload Support:** * JSON data files * Models and textures * World generation assets * Most visual assets * Some code changes may require restart **Developer Experience:** * Fast iteration cycles * See changes immediately * No full server restarts needed * Efficient testing workflow * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#content-creation-no-code-required) Content Creation (No Code Required) #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-i-create-custom-biomes-without-coding) Can I create custom biomes without coding? **Yes - Visual Node Editor** **World Generation V2:** * Visual node-based editor * Custom biomes and maps * Terrain shape control * Prop placement systems * Material providers * Live-reload in-game **No Java Knowledge Required:** * Accessible with tutorials and practice * Same tools used by Hytale team * Link simple nodes to create complex systems See: [World Generation Modding](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding) * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-are-npcs-and-items-configured) How are NPCs and items configured? **JSON-Based Configuration** **Data-Driven Systems:** * Items and blocks * NPC behavior and AI * Combat abilities * Loot tables * Crafting recipes * Custom interactions **Hytale Asset Editor:** * Visual editor for JSON files * No coding required * Live preview of changes * Built into the game * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-is-visual-scripting) What is Visual Scripting? **Replaces Command Blocks** **Features:** * Node-based logic builder * Fully sandboxed and safe * No coding required * Programmers can extend with custom nodes * Eventually: Visual scripting in 3D world **Use Cases:** * Door mechanisms * Puzzle logic * Custom interactions * Quest triggers * Minigame mechanics **Timeline:** Long-term priority, core pillar of Hytale modding * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-is-the-prefab-system) What is the Prefab System? **Sophisticated Building Blocks** **Features:** * Prebuilt structures * In-game prefab editor * Trees, houses, landmarks * Creative tool integration * World generation usage **Creator Tools:** * Browse 100+ official prefabs * Edit in separate environment * Save custom prefabs * Share with community * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#advanced-modding) Advanced Modding #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-does-the-combat-system-work) How does the combat system work? **Data-Driven Interaction System** **Features:** * Attack chains and combos * Custom abilities * Interaction sequences * Configurable via JSON * No coding required for basic combat **Extensibility:** * Custom attack patterns * Unique weapon behaviors * Special abilities * Boss mechanics * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#are-there-sub-hitboxes-for-bosses) Are there sub-hitboxes for bosses? **Yes - But Needs Improvement** **Current Status:** * Sub-hitbox support exists * Enables complex boss mechanics * System needs improvement * Actively being enhanced **Use Cases:** * Multi-part bosses * Weak point targeting * Limb-specific damage * Complex enemy designs * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-i-create-custom-status-effects) Can I create custom status effects? **Yes - Buff/Debuff System** **Features:** * Custom buffs and debuffs * Custom stats and attributes * Duration and stacking * Visual effects * Fully extensible **Examples:** * Poison damage over time * Speed boosts * Armor buffs * Custom attribute modifiers * Unique effects * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-i-create-custom-uis) Can I create custom UIs? **Yes - NoesisGUI Transition** **Current Status:** * Transitioning to NoesisGUI * Powerful interface customization * Asset-driven UIs available * Currently incomplete * Actively being improved **Capabilities:** * Custom menus and HUDs * Interactive interfaces * Data visualization * Mini-map systems * Quest trackers **Recommendation:** Start experimenting and provide feedback * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-does-block-physics-work) How does block physics work? **Selective System** **What Falls:** * Trees collapse when chopped * Natural blocks can fall * Specific physics-enabled blocks **What Doesn't Fall:** * Player-placed blocks (by default) * Buildings can float * Most constructed structures **Why Selective:** * Gameplay balance * Building freedom * Performance considerations * Can be modded for different behavior * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#gameplay-systems) Gameplay Systems ----------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#core-mechanics) Core Mechanics #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#is-there-a-hunger-stamina-system) Is there a hunger/stamina system? **No Hunger by Default** **Stamina System:** * Stamina for actions * No hunger mechanic * Can be modded in **Design Philosophy:** * Focus on exploration and combat * Reduce survival tedium * Fully customizable by servers * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-does-gravity-work) How does gravity work? **Selective Block Physics** **Natural Blocks:** * Trees fall when cut * Leaves decay * Sand/gravel may fall **Player Structures:** * Buildings can float * No structural integrity requirements * Creative freedom prioritized **Modding:** * Physics can be customized * Different rules for different blocks * Full control via plugins * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#whats-planned-for-lighting) What's planned for lighting? **Major Overhaul Planned** **Current Issues:** * Model/voxel lighting inconsistencies * Some visual artifacts **Improvements Coming:** * Fix model/voxel conflicts * Better light propagation * Enhanced shadow quality * More realistic lighting * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-is-the-world-height-limit) What is the world height limit? **Currently Limited** **Status:** * Current height limit exists * May change with voxel storage updates * Technical limitations being addressed **Future:** * Potential height increase * Voxel storage improvements * Better vertical world space * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#is-there-a-redstone-equivalent) Is there a redstone equivalent? **Not at Launch** **Visual Scripting Instead:** * Node-based logic * More powerful than redstone * Sandboxed and safe * Fully moddable **Can Be Modded:** * Plugins can add redstone-like systems * Community may create alternatives * Full flexibility for servers * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#player-systems) Player Systems #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-character-models-are-available) What character models are available? **Humans by Default** **Creative Mode:** * Change to any NPC model * Player Model Changer tool * Become any creature **Multiplayer:** * Server-controlled avatars * No custom models in multiplayer (for now) * Skin customization available * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-i-customize-my-skin) Can I customize my skin? **Full Customization Possible** > _"Mod yourself into a potato"_ - Developers **Features:** * Complete skin customization * Upload custom textures * Unique character appearance * Creative freedom **Cosmetics:** * Official cosmetic packs (low price) * Support server infrastructure * No pay-to-win * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#are-there-transformation-shapeshifting-mechanics) Are there transformation/shapeshifting mechanics? **Yes - Transformation Potions** **Features:** * Potions that change player form * Transform into different creatures * Fun gameplay mechanic * Moddable for custom transformations * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#world-and-npcs) World & NPCs #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-does-the-faction-system-work) How does the faction system work? **Living World with Dynamic NPCs** **Features:** * Factions interact with each other * Dynamic relationships * Territory control * Player reputation * Consequence-driven world **Immersion:** * NPCs remember player actions * World reacts to player choices * Ongoing faction conflicts * Living, breathing world * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#are-there-dynamic-villages) Are there dynamic villages? **Planned for Future Updates** **Vision:** * Villages with relationships * NPC behaviors and routines * Village growth and development * Village defense and raids * Player interaction with communities **Status:** Being designed and developed * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-do-chunks-and-entities-load) How do chunks and entities load? **Render Distance Based** **Loading Rules:** * Entities load when in ANY player's render distance * Entities unload when ALL players are out of range * Chunks load/unload dynamically * Optimized for performance **Benefits:** * Better server performance * Reduced memory usage * Smooth gameplay * Efficient resource management * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-i-share-world-generation-seeds) Can I share world generation seeds? **Yes - Shareable Seeds** **Features:** * Enter custom seeds * Generate identical worlds * Share with friends * Community seed databases * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#development-philosophy) Development Philosophy ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#release-strategy) Release Strategy #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-is-the-priority-for-early-access) What is the priority for Early Access? **Adventure Mode First** **Focus Areas:** 1. Base game experience 2. Core gameplay loops 3. Adventure mode content 4. Modding architecture (supports everything) **Modding Support:** * Built alongside adventure mode * Same tools used internally * "Anything we do, you can do" * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-about-technical-debt) What about technical debt? **Acknowledged as Necessary** **Approach:** * Some tech debt required for release * Commitment to continuous improvement * Transparent about limitations * Active post-launch refinement **Philosophy:** > _"Release first, improve continuously"_ * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-often-will-hytale-be-updated) How often will Hytale be updated? **Very Frequent Updates** **Cadence:** * Especially frequent post-launch * Bug fixes and improvements * New features and content * Community-driven priorities **Commitment:** * Long-term support * Active development * Community feedback integration * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-is-the-versioning-policy) What is the versioning policy? **Always Latest Version** **Server Flexibility:** * Official client always latest * Servers can run modified versions * Server source code available * Customize as needed **Benefits:** * No fragmentation * Consistent client experience * Server flexibility * Modding freedom * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#community-focus) Community Focus #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#will-there-be-development-bounties) Will there be development bounties? **Yes - Planned for Community Contributors** **Vision:** * Reward contributions * Strengthen ecosystem * Community-driven development * Recognize talent **Timeline:** Takes time to set up properly * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#will-there-be-official-tutorials) Will there be official tutorials? **Yes - Planned with Partners** **Content:** * Official modding tutorials * Video guides * Written documentation * Partner collaborations **Documentation:** * GitBook public documentation * Initially sparse * Expands based on community questions * Community contributions welcome * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-is-community-feedback-integrated) How is community feedback integrated? **Strong Commitment** **Process:** * Active listening on Discord * Community-driven improvements * Feedback shapes development * Transparent communication **Accountability:** > _"Hold us accountable, demand answers, provide feedback"_ - Developers * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-are-the-system-requirements) What are the system requirements? **Designed for Accessibility** **Target:** * Lower-end hardware support * Reasonable requirements * Wide player base * Performance optimization **Performance:** * Uncapped framerate * Multi-core support * Optimization focus * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#tools-and-documentation) Tools & Documentation ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#development-tools) Development Tools #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-modeling-tool-should-i-use) What modeling tool should I use? **Blockbench (Official)** **Integration:** * Hytale Blockbench Plugin * Replaces "Hytale Model Maker" * Official support * Direct integration **Why Blockbench:** * Better community workflow support * Established creative tool * Active development * Wide adoption See: [Blockbench Modeling Guide](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide) * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-machinima-tools-are-available) What machinima tools are available? **Full Cinematic Creation** **Features:** * Camera keyframe animation * Used for official trailers * In-game recording * Needs technical fixes **Status:** * Available but rough * Massive upgrade planned post-launch * Used professionally by Hytale team * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-creative-tools-are-coming) What creative tools are coming? **Major Reveal Planned** **Confirmed Tools:** * Building tools * Creation features * Creative mode enhancements * Advanced editing capabilities **See:** [Creative Mode Blogarrow-up-right](https://hytale.com/news/2025/11/hytale-creative-mode) * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#will-server-source-code-be-available) Will server source code be available? **Yes - Unobfuscated with Comments** **Features:** * Full server source code * Developer comments * No obfuscation * Learn from implementation **Timeline:** Within 1-2 months after Early Access launch **Benefits:** * Understand systems * Self-service debugging * Contribute improvements * Deep customization * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#platform-support) Platform Support ----------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#current-and-planned-platforms) Current & Planned Platforms #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-platforms-are-supported) What platforms are supported? **Current:** * **Windows** (primary platform) * **Mac** (actively in development) * **Linux** (actively in development) **Not Planned:** * **VR** (not feasible in near future) * **Consoles** (TBD for modding) * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#does-hytale-work-offline) Does Hytale work offline? **Yes - Single-Player Offline** **Features:** * No internet required for single-player * Full game experience offline * Local world saves * Multiplayer requires connection * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-about-performance) What about performance? **Uncapped Framerate** **Optimization:** * Multi-core support * Performance focus * Accessible to lower-end hardware * Continuous optimization * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#monetization-and-legal) Monetization & Legal --------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#business-model) Business Model #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#will-there-be-pay-to-win-mechanics) Will there be pay-to-win mechanics? **Absolutely Not - Firm Commitment** **Policy:** * No pay-to-win mechanics * Cosmetics only * Low-price cosmetic packs * Support infrastructure costs **Philosophy:** > _"We are firmly against pay-to-win"_ - Hypixel Studios * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-cosmetics-will-be-available) What cosmetics will be available? **Low-Price Cosmetic Packs** **Purpose:** * Support server infrastructure * Optional purchases * Customization options * No gameplay advantages **Pricing:** * Affordable * No aggressive monetization * Player-first approach * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#what-about-server-monetization) What about server monetization? **EULA/TOS Being Finalized** **Status:** * Server monetization policies being defined * Terms of Service in development * Balance between freedom and fairness * Details coming soon **Hosting:** * No business agreements required * Day 1 server hosting available * Just comply with EULA/TOS * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#current-limitations) Current Limitations ----------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#technical-constraints) Technical Constraints #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-i-use-custom-shaders) Can I use custom shaders? **Not Currently - Security Concern** **Issue:** * No sandboxing solution yet * Security risk * Being researched **Future:** * May be added if sandboxing solved * Community interest acknowledged * No timeline yet * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#are-ui-and-input-systems-limited) Are UI and input systems limited? **Currently Yes - Being Expanded** **Status:** * Some limitations exist * Actively being improved * NoesisGUI transition in progress * More capabilities coming **Timeline:** Continuous improvement * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#how-complete-is-the-documentation) How complete is the documentation? **Sparse Initially** **Reality:** * Starting incomplete * Will improve over time * Community questions guide expansion * Contributions welcome **Approach:** * Transparent about limitations * Honest about readiness * Commitment to improvement * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-clients-run-mods) Can clients run mods? **No - Security Design** **Reason:** * No client-side code execution * Prevents exploits * Server controls everything * Security first **Benefits:** * Safe for all players * No malware risk * Consistent experience * Server-controlled content * * * #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#can-i-customize-player-nameplates) Can I customize player nameplates? **Currently Limited** **Status:** * Limited customization options * Being improved * More options planned * Future updates * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#vision-and-future) Vision & Future ----------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#long-term-goals) Long-Term Goals > _"This comprehensive technical foundation positions Hytale as a secure, extensible platform that empowers creators while maintaining performance, accessibility, and a commitment to continuous improvement."_ **Core Commitments:** 1. Security without compromising creativity 2. Accessibility for all skill levels 3. Continuous improvement 4. Community-driven development 5. Long-term support * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousFrequently Asked Questionschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-frequently-asked-questions) [NextYoutube Tutorialschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#overview) * [Technical Architecture](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#technical-architecture) * [Network & Infrastructure](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#network-and-infrastructure) * [Security & Distribution](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#security-and-distribution) * [Modding Capabilities](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#modding-capabilities) * [Server-Side Power](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#server-side-power) * [Content Creation (No Code Required)](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#content-creation-no-code-required) * [Advanced Modding](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#advanced-modding) * [Gameplay Systems](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#gameplay-systems) * [Core Mechanics](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#core-mechanics) * [Player Systems](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#player-systems) * [World & NPCs](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#world-and-npcs) * [Development Philosophy](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#development-philosophy) * [Release Strategy](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#release-strategy) * [Community Focus](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#community-focus) * [Tools & Documentation](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#tools-and-documentation) * [Development Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#development-tools) * [Platform Support](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#platform-support) * [Current & Planned Platforms](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#current-and-planned-platforms) * [Monetization & Legal](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#monetization-and-legal) * [Business Model](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#business-model) * [Current Limitations](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#current-limitations) * [Technical Constraints](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#technical-constraints) * [Vision & Future](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#vision-and-future) * [Long-Term Goals](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#long-term-goals) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-technical-insights#getting-help) sun-brightdesktopmoon Copy - Connect to external databases - Create REST APIs - Integrate with Discord bots - Implement custom payment systems - Build AI-powered NPCs - Create mini-game frameworks sun-brightdesktopmoon --- # Hytale Modding Overview | Hytale Modding Documentation **Source:** [Official Hytale Modding Strategyarrow-up-right](https://hytale.com/news/2025/11/hytale-modding-strategy-and-status) **Last Modified:** Friday, January 10, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#introduction) Introduction ----------------------------------------------------------------------------------------------------------------------------------------------------- Welcome to Hytale modding! This documentation provides comprehensive tutorials and guides for creating mods in Hytale, from asset packs to advanced Java plugins. > **Important:** Hytale is currently in **Early Access**. The modding tools and documentation are actively being developed and improved. Expect rough edges, but also expect rapid improvements based on community feedback. > **Official Statement:** _"We're building Hytale with modding at its core. Most of what you see in the game can be changed, extended, or removed entirely."_ - Slikey (Technical Director) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#four-official-modding-categories) Four Official Modding Categories --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- According to Hytale's official modding strategy, Hytale modding falls into **four technical categories**: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-1.-server-plugins-java-.jar-files) 1\. Server Plugins (Java .jar files) **Server Plugins** are Java-based mods that: * Extend the functionality of the server programmatically * Are extremely powerful and allow deep modifications to gameplay and core systems * Enable you to build minigames, economies, commands, custom logic, new asset types, and more * Require Java programming knowledge **Use Cases:** * Custom game modes and minigames * Economy systems * Custom commands * Server management tools * Advanced gameplay mechanics ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-2.-data-assets-json-files) 2\. Data Assets (JSON files) **Data Assets** drive gameplay behavior and define core content: * **Blocks and Items** - Define properties, behaviors, and interactions * **NPCs** - Configure mob behavior and AI * **World Generation** - Control terrain, biomes, and structures * **Drop Tables and Loot** - Define what items drop from blocks and mobs * **And more** - Most game content is data-driven **Key Feature:** No coding required - edit JSON files to modify game content ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-3.-art-assets-sounds-models-textures) 3\. Art Assets (Sounds, Models, Textures) **Art Assets** provide the visual and audio representation of game elements: * **Models** - 3D block and entity models * **Textures** - Visual appearance of blocks, items, and entities * **Sounds** - Audio effects and music * **Animations** - Movement and behavior animations **Official Tool:** Blockbench is officially supported for creating Hytale models, textures, and animations ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-4.-save-files-worlds-and-prefabs) 4\. Save Files (Worlds and Prefabs) **Save Files** allow you to share complete creations: * **Worlds** - Share entire playable worlds * **Prefabs** - Prebuilt structures like trees, houses, or landmarks * **Usage** - Prefabs are used in creative tools and world generation * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#important-no-text-based-scripting) Important: No Text-Based Scripting ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Official Clarification:** Hytale will **NOT** support text-based scripting languages like Lua. **Why?** * Text-based scripting claims to "help non-programmers" but still requires programming concepts * It forces programmers to juggle two languages * It increases complexity for both designers and programmers ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#instead-visual-scripting-coming-soon) Instead: Visual Scripting (Coming Soon) Hytale will implement **Visual Scripting** (similar to Unreal Engine Blueprints): * **For Designers:** Build logic visually without coding * **For Programmers:** Extend the system by creating new nodes in Java * **Sandboxed and Safe:** Visual scripts can be shared safely without security risks * **Future Vision:** Visual scripting directly in the 3D world (link levers, doors, triggers, etc.) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#modding-philosophy) Modding Philosophy ----------------------------------------------------------------------------------------------------------------------------------------------------------------- Hytale's modding is built on key principles: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#server-side-first) Server-Side First * All modding is server-based (both singleplayer and multiplayer) * Join any modded server without downloading external mods * No client-side mods for security and consistency ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#one-community-one-client) One Community, One Client * Avoid fragmented ecosystem with different modded clients * Client remains stable, secure, and consistent * Servers provide creativity and variation ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#modding-for-longevity) Modding for Longevity * Long-term commitment to modding support * Built with the same tools used to create the game * "Anything we do, you can do as well" * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-modding-tools) Official Modding Tools ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Hytale provides several official tools for creating content: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-1.-hytale-asset-editor) 1\. Hytale Asset Editor * **Purpose:** Editor for data assets (JSON files) * **Status:** Available now * **Capabilities:** Supports most asset types * **Limitations:** Notable limitations around NPCs, world generation, and interactions (being improved) * **Access:** Built into the game ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-2.-blockbench-plugin) 2\. Blockbench Plugin * **Purpose:** Create Hytale-compatible models, textures, and animations * **Status:** Releasing soon * **Integration:** Direct integration with Blockbench * **Replaces:** Hytale's own internal modeling tools * **Why:** Better support for established creative workflows in the community ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-3.-asset-graph-editor) 3\. Asset Graph Editor * **Purpose:** Node-based editor for complex assets * **Status:** Currently being released * **Use Cases:** World generation, creative tool brushes, NPCs * **Note:** Internal tool being made public - expect rough edges but useful functionality ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-4.-creative-mode-tools) 4\. Creative Mode Tools * **Purpose:** Interactive suite of in-game world editing and creation tools * **Status:** Available in Early Access * **Access:** Switch to Creative Mode in any world * **Official Info:** [Creative Mode Blogarrow-up-right](https://hytale.com/news/2025/11/hytale-creative-mode) **Available Tools:** * **Scripted Brushes** - Create mountains, paths, procedural ruins (asset-defined, modder-creatable) * **Shape Brush** - Paint pyramids, cones, squares with customizable size, density, materials * **Selection Tool** - 3D selections, copy, paste, move, rotate, save prefabs, regenerate chunks * **Paste Tool** - Precise prefab placement with arrow key controls * **Ruler/Laser Pointer** - Measure distances and point out locations * **Prefab Browser/Editor** - Browse 100+ models, edit in separate environment * **Player Model Changer** - Become any NPC model * **Machinima Camera** - Keyframe animation for cinematic recording **Creative Mode Features:** * Customizable flight (speed, controls, hover/directional, inertia) * Quick Settings Panel (changes based on tool in hand) * Help Menu for quick command discovery * Real-time world modification with instant feedback ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-5.-machinima-tools) 5\. Machinima Tools * **Purpose:** Create cinematic content (used for the 2018 trailer) * **Status:** Available but needs technical fixes * **Quality:** Delivered great results for official trailers ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-6.-custom-ui-framework-noesisgui) 6\. Custom UI Framework (NoesisGUI) * **Purpose:** Create custom user interfaces * **Status:** In transition - consolidating from 3 UI frameworks to 1 * **Framework:** NoesisGUI (official UI framework) * **Current State:** Asset-driven UIs are available but incomplete * **Recommendation:** Start experimenting and provide feedback * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-documentation-and-resources) Official Documentation & Resources --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-hytale-documentation-gitbook) Official Hytale Documentation (GitBook) * **Status:** In progress * **Platform:** GitBook (same as this documentation!) * **Note:** Will start incomplete but expand based on community questions * **Official Statement:** _"We are working on public creator documentation hosted on GitBook"_ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#server-source-code-coming-soon) Server Source Code (Coming Soon) * **Release:** Within 1-2 months after Early Access launch (March 2026) * **Access:** Full server source code will be shared * **Purpose:** - Inspect how systems work under the hood * Unblock yourself when documentation is incomplete * Contribute improvements and bug fixes * **Note:** Server is not obfuscated - can be decompiled now ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#development-bounties-future) Development Bounties (Future) * **Plan:** Open bounties for specific improvements and features * **Goal:** Reward contributions that strengthen the ecosystem * **Timeline:** Takes time to set up properly * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#community-and-support) Community & Support --------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-channels) Official Channels * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) - Talk directly with developers and modders * **Discord (CurseForge):** [CurseForge UGC Discordarrow-up-right](https://discord.gg/S3EaZArYz2) - User-generated content focus * **X / Reddit:** Tweet at @Hytale or post on Hytale subreddits * **Official Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) - Latest updates and strategy posts ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#what-to-expect) What to Expect * **Early Access Reality:** Tools are uneven, documentation is incomplete, some workflows are frustrating * **Rapid Improvements:** Developers are fixing issues as they come in * **Transparency:** Developers commit to being honest about what's ready and what's not * **Your Feedback Matters:** Hold developers accountable, demand answers, provide feedback * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#important-warnings) Important Warnings ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#data-safety) Data Safety > **Critical:** Hytale is in true Early Access. There are crashes, and some can cause **data loss**. **Practical Advice:** * **Take frequent backups** of your savegames and creations * Treat this phase as valuable but **not yet safe for irreplaceable work** * Automatic backup solutions are being developed ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#current-limitations) Current Limitations * Missing editing capabilities for some features * Client behavior not fully exposed to server * Some tools are rough, inconsistent, or painful to work with * Modding maturity varies wildly depending on what you're building * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#long-term-vision) Long-Term Vision ------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#node-editors-coming) Node Editors (Coming) * **Purpose:** Visual editors for complex JSON assets * **Target:** NPCs, Interactions, World Generation * **Integration:** Directly into Hytale Asset Editor * **Goal:** Unified creator suite instead of patchwork tools ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#visual-scripting-core-pillar) Visual Scripting (Core Pillar) * **Timeline:** Long-term priority * **Features:** * Sandboxed, safe environment for sharing logic * Great learnability for all skill levels * Programmers can extend with performance-critical nodes * Eventually: Visual scripting directly in the 3D world ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#first-party-server-network) First-Party Server Network * **Plan:** Hypixel-style minigames network * **Purpose:** - Validate modding tools at scale * Share code and assets for learning * Ensure playable content during early days * **Note:** Not trying to compete with community servers * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#getting-started) Getting Started ----------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#for-content-creators-no-coding) For Content Creators (No Coding) 1. Start with **Packs** - Create blocks, items, and content using JSON 2. Use the **Asset Editor** to modify properties visually 3. Learn **Blockbench** for custom models and textures 4. Follow the [Getting Started with Packs](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs) guide ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#for-developers-java) For Developers (Java) 1. Learn **Java programming** fundamentals 2. Set up your development environment (IntelliJ IDEA recommended) 3. Clone the [Plugin Templatearrow-up-right](https://github.com/realBritakee/hytale-template-plugin) 4. Follow the [Getting Started with Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins) guide ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#for-advanced-users) For Advanced Users 1. Explore **Bootstrap/Early Plugins** for low-level modifications 2. Study the decompiled server source (or wait for official release) 3. Follow the [Bootstrap/Early Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins) guide * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#closing-words) Closing Words ------------------------------------------------------------------------------------------------------------------------------------------------------- _From Slikey (Technical Director):_ > "If you're willing to join us in this phase - bugs, rough edges and all - you won't just be modding Hytale. You'll be shaping what Hytale modding becomes." This documentation aims to help you navigate the current state of Hytale modding while preparing you for the exciting future ahead. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#getting-help) Getting Help ----------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousYoutube Tutorialschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/introduction/00-youtube-tutorials) [NextSetting Up a Local Serverchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server) Last updated 1 day ago * [Introduction](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#introduction) * [Four Official Modding Categories](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#four-official-modding-categories) * [1\. Server Plugins (Java .jar files)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-1.-server-plugins-java-.jar-files) * [2\. Data Assets (JSON files)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-2.-data-assets-json-files) * [3\. Art Assets (Sounds, Models, Textures)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-3.-art-assets-sounds-models-textures) * [4\. Save Files (Worlds and Prefabs)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-4.-save-files-worlds-and-prefabs) * [Important: No Text-Based Scripting](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#important-no-text-based-scripting) * [Instead: Visual Scripting (Coming Soon)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#instead-visual-scripting-coming-soon) * [Modding Philosophy](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#modding-philosophy) * [Server-Side First](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#server-side-first) * [One Community, One Client](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#one-community-one-client) * [Modding for Longevity](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#modding-for-longevity) * [Official Modding Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-modding-tools) * [1\. Hytale Asset Editor](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-1.-hytale-asset-editor) * [2\. Blockbench Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-2.-blockbench-plugin) * [3\. Asset Graph Editor](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-3.-asset-graph-editor) * [4\. Creative Mode Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-4.-creative-mode-tools) * [5\. Machinima Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-5.-machinima-tools) * [6\. Custom UI Framework (NoesisGUI)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#id-6.-custom-ui-framework-noesisgui) * [Official Documentation & Resources](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-documentation-and-resources) * [Official Hytale Documentation (GitBook)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-hytale-documentation-gitbook) * [Server Source Code (Coming Soon)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#server-source-code-coming-soon) * [Development Bounties (Future)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#development-bounties-future) * [Community & Support](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#community-and-support) * [Official Channels](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#official-channels) * [What to Expect](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#what-to-expect) * [Important Warnings](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#important-warnings) * [Data Safety](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#data-safety) * [Current Limitations](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#current-limitations) * [Long-Term Vision](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#long-term-vision) * [Node Editors (Coming)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#node-editors-coming) * [Visual Scripting (Core Pillar)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#visual-scripting-core-pillar) * [First-Party Server Network](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#first-party-server-network) * [Getting Started](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#getting-started) * [For Content Creators (No Coding)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#for-content-creators-no-coding) * [For Developers (Java)](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#for-developers-java) * [For Advanced Users](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#for-advanced-users) * [Closing Words](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#closing-words) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Setting Up a Local Server | Hytale Modding Documentation Copy # Setting Up a Local Server **Source:** [Hytale Server Manual](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) **Last Modified:** Friday, January 16, 2026 at 12:53 PM --- ## Overview This guide helps you set up a local Hytale server for testing mods, LAN play, or development on your machine.[file:12] --- ## Prerequisites Before you begin, ensure you have: - **Hytale** installed via the official launcher - **Java 25** from [Adoptium](https://adoptium.net/temurin/releases) - Basic command line/terminal knowledge[file:12] --- ## Step 1: Locating Hytale Server Files 1. Open Hytale Launcher → **Settings** → **Open Directory** 2. Go to: `%appdata%\Hytale\install\release\package\game\latest\` 3. Copy **Server/** folder and **Assets.zip** to `C:\HytaleServer\` C:\\HytaleServer ├── Server\\HytaleServer.jar └── Assets.zip cd C:\\HytaleServer java -Xmx4G -jar Server\\HytaleServer.jar --assets Assets.zip New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow **Key files:** * `config.json` - Server settings * `universe/worlds/*/config.json` - World settings * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#installing-mods-on-your-server) Installing Mods on Your Server 1. Create `mods/` folder in server directory 2. Drop `.zip` or `.jar` files into `mods/` 3. Restart server * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#troubleshooting) Troubleshooting #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#server-wont-start) Server won't start * Verify: `java --version` shows OpenJDK 25 * Use 4GB+ RAM: `-Xmx4G` * Check Assets.zip path #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#cant-connect-to-server) Can't connect to server * Use **UDP port 5520** (not 25565) * Allow UDP 5520 in firewall * Server must be authenticated #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#port-already-in-use) Port already in use Kill process or change port with `--bind 0.0.0.0:25565` #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#authentication-issues) Authentication issues * Delete auth files * Retry `/auth login device` * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#getting-help) Getting Help **Official Channels:** * **Server Manual:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousHytale Modding Overviewchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview) [NextRunning a Dedicated Serverchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server) Last updated 1 day ago * [Installing Mods on Your Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#installing-mods-on-your-server) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#troubleshooting) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server#getting-help) sun-brightdesktopmoon Copy --- ## Step 2: Launching the Server Copy --- ## Step 3: Server Authentication ### You MUST authenticate your server! 1. Run: `/auth login device` 2. Visit printed URL + code in browser 3. Login with Hytale account 4. Run: `/auth persistence Encrypted` **Never share your encrypted auth file!**[file:12] --- ## Step 4: Connecting to Your Server **Local:** `localhost:5520` **LAN:** `192.168.x.x:5520` **In Hytale client:** 1. **Play** → **Servers** → **Add Server** 2. Enter address above 3. Join! **Firewall (Windows):** Copy --- ## Step 5: Basic Server Configuration Edit `config.json` (server stopped): ```json { "max-players": 10, "view-distance": 12 } Copy netstat -ano | findstr :5520 sun-brightdesktopmoon --- # Server Commands & Permissions | Hytale Modding Documentation **Source:** [Server Commands & Permissionsarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 16, 2026 at 08:00 AM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------------- This guide covers all available server commands, permission systems, and how to manage operator status and player permissions on your Hytale server. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#basic-server-commands) Basic Server Commands --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#authentication-commands) Authentication Commands ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#auth-login-device) auth login device Authenticates your server with Hytale. This command prints a URL that you can use to authenticate the server using your Hytale account. Copy auth login device ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#auth-persistence-encrypted) auth persistence Encrypted Keeps your server authenticated after restarting. Run this after authenticating once. **Warning:** Never share your encrypted auth file! * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#player-management-commands) Player Management Commands ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#op) /op Gives operator status to a player. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#deop) /deop \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#kick) /kick \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#ban) /ban \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#pardon) /pardon \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#world-management-commands) World Management Commands ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#server-control-commands) Server Control Commands ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#permission-system) Permission System ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#permission-levels) Permission Levels ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#creating-custom-permission-groups) Creating Custom Permission Groups --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#plugin-specific-commands) Plugin-Specific Commands --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#command-examples) Command Examples ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#making-yourself-operator) Making yourself operator ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#authenticating-the-server) Authenticating the server * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#commands-not-working) Commands not working \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#permission-denied-errors) Permission denied errors \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#cant-give-operator-status) Can't give operator status \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Server Manual:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousServer Configurationchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration) [NextServer Tips & Optimizationchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#overview) * [Basic Server Commands](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#basic-server-commands) * [Authentication Commands](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#authentication-commands) * [auth login device](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#auth-login-device) * [auth persistence Encrypted](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#auth-persistence-encrypted) * [Player Management Commands](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#player-management-commands) * [/op](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#op) * [/deop](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#deop) * [/kick](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#kick) * [/ban](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#ban) * [/pardon](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#pardon) * [World Management Commands](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#world-management-commands) * [Server Control Commands](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#server-control-commands) * [Permission System](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#permission-system) * [Permission Levels](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#permission-levels) * [Creating Custom Permission Groups](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#creating-custom-permission-groups) * [Plugin-Specific Commands](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#plugin-specific-commands) * [Command Examples](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#command-examples) * [Making yourself operator](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#making-yourself-operator) * [Authenticating the server](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#authenticating-the-server) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#troubleshooting) * [Commands not working](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#commands-not-working) * [Permission denied errors](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#permission-denied-errors) * [Can't give operator status](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#cant-give-operator-status) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions#getting-help) sun-brightdesktopmoon Copy auth persistence Encrypted Copy /op /op self Copy /op self Copy auth login device auth persistence Encrypted sun-brightdesktopmoon --- # Running a Dedicated Server | Hytale Modding Documentation **Source:** [Running a Dedicated Serverarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 16, 2026 at 08:00 AM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#overview) Overview ---------------------------------------------------------------------------------------------------------------------------------------------------- This guide covers setting up a dedicated Hytale server for 24/7 hosting, whether on a VPS, dedicated server, or home server machine. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#prerequisites) Prerequisites -------------------------------------------------------------------------------------------------------------------------------------------------------------- Before you begin, ensure you have: * A server machine or VPS (recommended specifications below) * **Java 25** installed * Basic Linux/Windows server administration knowledge * Static IP or domain name (recommended) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#recommended-server-specifications) Recommended Server Specifications ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-1-server-setup) Step 1: Server Setup --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-2-installing-java-25) Step 2: Installing Java 25 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-3-downloading-hytale-server-files) Step 3: Downloading Hytale Server Files ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-4-server-authentication) Step 4: Server Authentication --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#you-must-authenticate-your-server) You MUST authenticate your server! In order to allow players to connect to your dedicated server, you must authenticate it with Hytale. This is done by running the `auth login device` command in the server terminal. Once authenticated, you can run the `auth persistence Encrypted` command to keep your server authenticated after restarting it. **Never share your encrypted auth file!** * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-5-configuring-server-settings) Step 5: Configuring Server Settings --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-6-running-the-server) Step 6: Running the Server --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-7-firewall-configuration) Step 7: Firewall Configuration ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-8-setting-up-auto-start-linux) Step 8: Setting Up Auto-Start (Linux) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#performance-optimization) Performance Optimization ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#backup-strategies) Backup Strategies ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#server-crashes-on-startup) Server crashes on startup \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#high-cpu-memory-usage) High CPU/Memory usage \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#players-cant-connect) Players can't connect \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#getting-help) Getting Help ------------------------------------------------------------------------------------------------------------------------------------------------------------ **Official Channels:** * **Server Manual:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousSetting Up a Local Serverchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/18-setting-up-local-server) [NextHytale Server Managerchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager) Last updated 1 day ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#overview) * [Prerequisites](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#prerequisites) * [Recommended Server Specifications](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#recommended-server-specifications) * [Step 1: Server Setup](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-1-server-setup) * [Step 2: Installing Java 25](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-2-installing-java-25) * [Step 3: Downloading Hytale Server Files](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-3-downloading-hytale-server-files) * [Step 4: Server Authentication](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-4-server-authentication) * [You MUST authenticate your server!](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#you-must-authenticate-your-server) * [Step 5: Configuring Server Settings](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-5-configuring-server-settings) * [Step 6: Running the Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-6-running-the-server) * [Step 7: Firewall Configuration](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-7-firewall-configuration) * [Step 8: Setting Up Auto-Start (Linux)](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#step-8-setting-up-auto-start-linux) * [Performance Optimization](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#performance-optimization) * [Backup Strategies](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#backup-strategies) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#troubleshooting) * [Server crashes on startup](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#server-crashes-on-startup) * [High CPU/Memory usage](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#high-cpu-memory-usage) * [Players can't connect](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#players-cant-connect) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Hytale Server Manager | Hytale Modding Documentation **Source:** [Hytale Server Managerarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 16, 2026 at 08:00 AM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------- This guide will help you set up and use the Hytale Server Manager (HSM) - a powerful tool for managing your Hytale servers with ease. **GitHub Repository:** [nebula-codes/hytale\_server\_managerarrow-up-right](https://github.com/nebula-codes/hytale_server_manager) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#what-is-hytale-server-manager) What is Hytale Server Manager? -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#features) Features ------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#prerequisites) Prerequisites ----------------------------------------------------------------------------------------------------------------------------------------------------------- Before you begin, ensure you have: * **Hytale Server** already installed * **Java 25** installed * Basic command line knowledge * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-1-installation) Step 1: Installation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-2-initial-configuration) Step 2: Initial Configuration ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-3-starting-the-server-manager) Step 3: Starting the Server Manager ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-4-managing-your-server) Step 4: Managing Your Server ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#web-interface) Web Interface ----------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#managing-mods-and-plugins) Managing Mods and Plugins ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#backup-and-restore) Backup and Restore --------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#automatic-updates) Automatic Updates ------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#manager-wont-start) Manager won't start \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#cant-access-web-interface) Can't access web interface \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#server-crashes-when-using-manager) Server crashes when using manager \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Server Manual:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousRunning a Dedicated Serverchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/19-running-dedicated-server) [NextServer Configurationchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#overview) * [What is Hytale Server Manager?](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#what-is-hytale-server-manager) * [Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#features) * [Prerequisites](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#prerequisites) * [Step 1: Installation](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-1-installation) * [Step 2: Initial Configuration](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-2-initial-configuration) * [Step 3: Starting the Server Manager](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-3-starting-the-server-manager) * [Step 4: Managing Your Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#step-4-managing-your-server) * [Web Interface](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#web-interface) * [Managing Mods and Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#managing-mods-and-plugins) * [Backup and Restore](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#backup-and-restore) * [Automatic Updates](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#automatic-updates) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#troubleshooting) * [Manager won't start](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#manager-wont-start) * [Can't access web interface](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#cant-access-web-interface) * [Server crashes when using manager](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#server-crashes-when-using-manager) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Server Configuration | Hytale Modding Documentation **Source:** [Server Configurationarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 16, 2026 at 08:00 AM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------ This guide covers all the configuration options available for Hytale servers, including performance tuning, gameplay settings, and security options. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#configuration-files) Configuration Files ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#server-properties) Server Properties ------------------------------------------------------------------------------------------------------------------------------------------------------------------ \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#world-settings) World Settings ------------------------------------------------------------------------------------------------------------------------------------------------------------ \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#performance-settings) Performance Settings ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#memory-allocation) Memory Allocation \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#cpu-usage) CPU Usage \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#network-settings) Network Settings \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#gameplay-settings) Gameplay Settings ------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#difficulty) Difficulty \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#pvp-settings) PvP Settings \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#world-generation) World Generation \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#security-settings) Security Settings ------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#whitelist) Whitelist \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#ban-list) Ban List \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#authentication) Authentication \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#mod-plugin-configuration) Mod/Plugin Configuration -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#logging-and-monitoring) Logging and Monitoring ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#advanced-configuration) Advanced Configuration ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#configuration-not-taking-effect) Configuration not taking effect \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#server-wont-start-after-config-change) Server won't start after config change \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#configuration-examples) Configuration Examples ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#small-private-server) Small Private Server \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#large-public-server) Large Public Server \[Content to be added\] ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#development-testing-server) Development/Testing Server \[Content to be added\] * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#getting-help) Getting Help -------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Server Manual:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousHytale Server Managerchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/20-hytale-server-manager) [NextServer Commands & Permissionschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#overview) * [Configuration Files](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#configuration-files) * [Server Properties](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#server-properties) * [World Settings](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#world-settings) * [Performance Settings](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#performance-settings) * [Memory Allocation](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#memory-allocation) * [CPU Usage](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#cpu-usage) * [Network Settings](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#network-settings) * [Gameplay Settings](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#gameplay-settings) * [Difficulty](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#difficulty) * [PvP Settings](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#pvp-settings) * [World Generation](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#world-generation) * [Security Settings](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#security-settings) * [Whitelist](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#whitelist) * [Ban List](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#ban-list) * [Authentication](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#authentication) * [Mod/Plugin Configuration](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#mod-plugin-configuration) * [Logging and Monitoring](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#logging-and-monitoring) * [Advanced Configuration](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#advanced-configuration) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#troubleshooting) * [Configuration not taking effect](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#configuration-not-taking-effect) * [Server won't start after config change](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#server-wont-start-after-config-change) * [Configuration Examples](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#configuration-examples) * [Small Private Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#small-private-server) * [Large Public Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#large-public-server) * [Development/Testing Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#development-testing-server) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/21-server-configuration#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Server Tips & Optimization | Hytale Modding Documentation **Source:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) **Last Modified:** Friday, January 16, 2026 at 1:04 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#installing-mods) Installing Mods --------------------------------------------------------------------------------------------------------------------------------------------------------------- **Simple 3-step process:** 1. Download `.zip` or `.jar` from [CurseForgearrow-up-right](https://www.curseforge.com/hytale) 2. Drop into `mods/` folder 3. Restart server Copy 📁 Server Folder └── mods/ ├── MyMod.zip └── CoolPlugin.jar * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#disable-sentry-crash-reporting) Disable Sentry Crash Reporting --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Important:** Disable during plugin development Copy java -jar HytaleServer.jar --assets Assets.zip --disable-sentry * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#leverage-aot-cache) Leverage AOT Cache --------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Faster startup** with pre-trained cache: [JEP-514arrow-up-right](https://openjdk.org/jeps/514) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#recommended-plugins) Recommended Plugins ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Plugin Purpose [Nitrado:WebServerarrow-up-right](https://github.com/nitrado/hytale-plugin-webserver) Web APIs [Nitrado:Queryarrow-up-right](https://github.com/nitrado/hytale-plugin-query) Server status [PerformanceSaverarrow-up-right](https://github.com/nitrado/hytale-plugin-performance-saver) Dynamic view distance [PrometheusExporterarrow-up-right](https://github.com/apexhosting/hytale-plugin-prometheus) Performance metrics * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#view-distance-tuning) View Distance Tuning ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **RAM Usage Guide:** **vs Minecraft:** Game Chunks Blocks Minecraft 10 160 Hytale **12** **384** * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#multiserver-architecture) Multiserver Architecture --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **No BungeeCord needed** - native routing. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#player-referral) Player Referral **⚠️ Sign payloads** (HMAC required) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#connection-redirect) Connection Redirect * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#quick-commands) Quick Commands ------------------------------------------------------------------------------------------------------------------------------------------------------------- Use Case Command Development `java -jar HytaleServer.jar --assets Assets.zip --disable-sentry` Production `java -Xmx6G -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip` Custom Port `java -jar HytaleServer.jar --bind 0.0.0.0:25565 --assets Assets.zip` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Server Manual:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousServer Commands & Permissionschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/22-server-commands-permissions) [NextFuture Server Additionschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions) Last updated 2 days ago * [Installing Mods](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#installing-mods) * [Disable Sentry Crash Reporting](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#disable-sentry-crash-reporting) * [Leverage AOT Cache](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#leverage-aot-cache) * [Recommended Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#recommended-plugins) * [View Distance Tuning](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#view-distance-tuning) * [Multiserver Architecture](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#multiserver-architecture) * [Player Referral](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#player-referral) * [Connection Redirect](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#connection-redirect) * [Quick Commands](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#quick-commands) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization#getting-help) sun-brightdesktopmoon Copy java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip Copy 8 chunks → 2-4GB RAM (4 players) 12 chunks → 4-6GB RAM (8-12 players) ✅ RECOMMENDED 16 chunks → 8GB+ RAM (Risky!) Copy PlayerRef.referToServer("lobby.com", 5520, data); Copy PlayerSetupConnectEvent.referToServer("eu.server", 5520); sun-brightdesktopmoon --- # Future Server Additions | Hytale Modding Documentation **Source:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) **Last Modified:** Friday, January 16, 2026 at 12:56 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#overview) Overview -------------------------------------------------------------------------------------------------------------------------------------------- Upcoming Hytale server features will enhance discoverability, social gameplay, monetization, and operations for server administrators. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#server-and-minigame-discovery) Server & Minigame Discovery ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Status:** Planned for main menu integration. **Features:** * In-game server browser for servers and minigames * Server operators opt-in to promote content * Real-time player discovery catalogue **Listing Requirements:** Requirement Description Server Operator Guidelines Must follow Hytale community standards Self-Rating Accurate content ratings for parental controls Enforcement Violations lead to delisting **Player Count Verification:** * Uses client telemetry (not server-reported) * Prevents count spoofing * Unverified counts shown for manually added servers * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#parties-system) Parties System -------------------------------------------------------------------------------------------------------------------------------------------------------- **Status:** In development. **Features:** * Cross-server party persistence * Party-aware server browsing * Visible party size limits before joining **Integration:** * Groups browse/join servers together * Seamless social experience across Hytale ecosystem * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#integrated-payment-system) Integrated Payment System ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Status:** Planned client integration. **Server Operator Benefits:** * Accept payments without external services * No payment infrastructure required * Secure transactions via Hytale **Player Benefits:** * In-game payments (no external websites) * Fully secure and traceable * Ecosystem-contained transactions * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#srv-record-support) SRV Record Support ---------------------------------------------------------------------------------------------------------------------------------------------------------------- **Status:** Unsupported, under evaluation. **What it enables:** * Connect via `play.example.com` (no port needed) * DNS resolves address + port automatically **Current Limitations:** * No production-ready C# SRV library * Full DNS client adds complexity/risk * Revisit when suitable solution available * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#first-party-api-endpoints) First-Party API Endpoints ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Status:** Planned for authenticated servers. **Core Endpoints:** Endpoint Description UUID ↔ Name Lookup Single/bulk player name resolution Game Version Protocol/version checking Player Profile Cosmetics, avatar, public data Server Telemetry Status reporting for discovery Report ToS violation reporting Payments Built-in payment processing **Under Consideration:** Endpoint Description Global Sanctions Platform-level ban checks Friends List Social features (permissioned) Webhook Subscriptions Event notifications **Design Goals:** * Generous rate limits + bulk endpoints * Server authentication required * Versioned APIs with deprecation windows * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#getting-help) Getting Help ---------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Server Manual:** [Hytale Server Manualarrow-up-right](https://support.hytale.com/hc/en-us/articles/45326769420827-Hytale-Server-Manual) * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousServer Tips & Optimizationchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/23-tips-and-optimization) [NextGetting Started with Packschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#overview) * [Server & Minigame Discovery](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#server-and-minigame-discovery) * [Parties System](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#parties-system) * [Integrated Payment System](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#integrated-payment-system) * [SRV Record Support](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#srv-record-support) * [First-Party API Endpoints](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#first-party-api-endpoints) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Block State Changing | Hytale Modding Documentation **Source:** [Block State Changingarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 9, 2026 at 12:01 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------- This is a basic beginner's guide on how to modify block state changes and cycling. Block states allow you to create blocks that can change appearance, behavior, or properties when interacted with, similar to doors, lights, or buttons in the game. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#what-are-block-states) What are Block States? ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Block states allow a single block to have multiple configurations or modes: * **Lamps** that can be on or off * **Doors** that can be open or closed * **Machines** that can be active or inactive * **Any block** with multiple visual or functional states * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#step-1-select-your-block) Step 1: Select Your Block ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- First, locate your block definition file: **Path:** `Packs/YourPackName/Server/Item/Items/your_block.json` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#step-2-create-an-interaction) Step 2: Create an Interaction ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Define an interaction that will trigger the state change. This tells the game what should happen when the player interacts with the block. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-structure) Interaction Structure: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-properties-explained) Interaction Properties Explained: Property Description `"Use"` The interaction type (player right-clicks/uses the block) `"Type": "ChangeState"` Tells the game to change the block's state `"Changes"` Maps current state -> next state ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#state-cycling-logic) State Cycling Logic: This creates a toggle behavior: On -> Off -> On -> Off... * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#step-3-define-states) Step 3: Define States -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now define what each state looks like and behaves like: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#state-definition-structure) State Definition Structure: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#state-properties) State Properties: Property Description Example `InteractionHint` Tooltip shown when hovering `"interactionHints.turnoff"` `CustomModel` Model file for this state `"Blocks/model_one.blockymodel"` `CustomModelTexture` Texture(s) for this state Array of texture objects * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#complete-example-block) Complete Example Block ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here's a full example of a block with state changing: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#advanced-state-features) Advanced State Features ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can add additional properties to each state: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#sounds) Sounds ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#animations) Animations ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#particles) Particles * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#multiple-states-beyond-on-off) Multiple States (Beyond On/Off) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can have more than two states: Then define all three states: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-hints-translation) Interaction Hints Translation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Remember to add translations for your interaction hints: **Path:** `YourPackName/Server/Languages/en-US/interactionHints.lang` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#required-files) Required Files ------------------------------------------------------------------------------------------------------------------------------------------------------------- For a state-changing block with custom models, you need: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#testing-your-state-changing-block) Testing Your State-Changing Block --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Enable your Pack in a world 2. Place the block 3. Observe its initial state (default) 4. Right-click/use the block 5. Verify it changes to the next state 6. Check that the model/texture updates 7. Verify the interaction hint displays correctly * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#states-dont-change) States don't change: * Verify `"Type": "ChangeState"` is set correctly * Check that state names match in `Changes` and `Definitions` * Ensure interaction type is correct (`"Use"`) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#wrong-initial-state) Wrong initial state: * Check `"default"` value in `Changes` * Verify the default state is defined in `Definitions` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#models-textures-dont-update) Models/textures don't update: * Verify model paths are correct for each state * Check that texture paths exist * Ensure models are properly formatted `.blockymodel` files ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-hints-dont-show) Interaction hints don't show: * Verify translation keys exist in `interactionHints.lang` * Check that language file is in correct location * Ensure no typos in translation keys * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousAdding a Blockchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block) [NextItem Categorieschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories) Last updated 1 day ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#overview) * [What are Block States?](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#what-are-block-states) * [Step 1: Select Your Block](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#step-1-select-your-block) * [Step 2: Create an Interaction](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#step-2-create-an-interaction) * [Interaction Structure:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-structure) * [Interaction Properties Explained:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-properties-explained) * [State Cycling Logic:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#state-cycling-logic) * [Step 3: Define States](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#step-3-define-states) * [State Definition Structure:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#state-definition-structure) * [State Properties:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#state-properties) * [Complete Example Block](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#complete-example-block) * [Advanced State Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#advanced-state-features) * [Sounds](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#sounds) * [Animations](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#animations) * [Particles](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#particles) * [Multiple States (Beyond On/Off)](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#multiple-states-beyond-on-off) * [Interaction Hints Translation](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-hints-translation) * [Required Files](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#required-files) * [Testing Your State-Changing Block](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#testing-your-state-changing-block) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#troubleshooting) * [States don't change:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#states-dont-change) * [Wrong initial state:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#wrong-initial-state) * [Models/textures don't update:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#models-textures-dont-update) * [Interaction hints don't show:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#interaction-hints-dont-show) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing#getting-help) sun-brightdesktopmoon Copy "Interactions": { "Use": { "Interactions": [\ {\ "Type": "ChangeState",\ "Changes": {\ "default": "Off",\ "On": "Off",\ "Off": "On"\ }\ }\ ] } } Copy "Changes": { "default": "Off", // Initial state when placed "On": "Off", // When "On", change to "Off" "Off": "On" // When "Off", change to "On" } Copy "State": { "Definitions": { "On": { "InteractionHint": "interactionHints.turnoff", "CustomModel": "Blocks/model_one.blockymodel", "CustomModelTexture": [\ {\ "Texture": "Blocks/Texture/textureone.png"\ }\ ] }, "Off": { "InteractionHint": "interactionHints.turnon", "CustomModel": "Blocks/model_two.blockymodel", "CustomModelTexture": [\ {\ "Texture": "Blocks/Texture/textureone.png"\ }\ ] } } } Copy { "TranslationProperties": { "Name": "server.Toggle_Block.name" }, "MaxStack": 100, "Icon": "Icons/ItemsGenerated/Toggle_Block.png", "Categories": [\ "Blocks.Decoration"\ ], "BlockType": { "DrawType": "Model", "CustomModel": "Blocks/model_one.blockymodel", "CustomModelTexture": [\ {\ "Texture": "Blocks/your_texture.png"\ }\ ], "Interactions": { "Use": { "Interactions": [\ {\ "Type": "ChangeState",\ "Changes": {\ "default": "Off",\ "On": "Off",\ "Off": "On"\ }\ }\ ] } }, "State": { "Definitions": { "On": { "InteractionHint": "interactionHints.turnoff", "CustomModel": "Blocks/model_one.blockymodel", "CustomModelTexture": [\ {\ "Texture": "Blocks/Texture/textureone.png"\ }\ ] }, "Off": { "InteractionHint": "interactionHints.turnon", "CustomModel": "Blocks/model_two.blockymodel", "CustomModelTexture": [\ {\ "Texture": "Blocks/Texture/textureone.png"\ }\ ] } } } } } Copy "On": { "InteractionHint": "interactionHints.turnoff", "CustomModel": "Blocks/model_one.blockymodel", "BlockSoundSetId": "Metal_On" } Copy "On": { "InteractionHint": "interactionHints.turnoff", "CustomModel": "Blocks/model_one.blockymodel", "CustomModelAnimation": "Blocks/Animations/Light_On.blockyanim" } Copy "On": { "InteractionHint": "interactionHints.turnoff", "CustomModel": "Blocks/model_one.blockymodel", "ParticleColor": "#ffff00" } Copy "Interactions": { "Use": { "Interactions": [\ {\ "Type": "ChangeState",\ "Changes": {\ "default": "State1",\ "State1": "State2",\ "State2": "State3",\ "State3": "State1"\ }\ }\ ] } } Copy "State": { "Definitions": { "State1": { /* ... */ }, "State2": { /* ... */ }, "State3": { /* ... */ } } } Copy turnon = Turn On turnoff = Turn Off Copy YourPackName/ |-- Common/ | `-- Blocks/ | |-- model_one.blockymodel | |-- model_two.blockymodel | `-- Texture/ | `-- textureone.png `-- Server/ |-- Item/ | `-- Items/ | `-- your_block.json `-- Languages/ `-- en-US/ `-- interactionHints.lang sun-brightdesktopmoon --- # Item Categories | Hytale Modding Documentation **Source:** [Item Categoriesarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 9, 2026 at 12:01 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#overview) Overview -------------------------------------------------------------------------------------------------------------------------------------------- Item Categories are the different tabs shown in the Creative Menu. This guide provides a basic introduction to creating your own categories and subcategories for organizing your custom items and blocks. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#what-are-item-categories) What are Item Categories? ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Item Categories allow you to: * Create custom tabs in the Creative Menu * Organize items and blocks logically * Add subcategories for better organization * Customize icons for each category * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-1-creating-the-category-file) Step 1: Creating the Category File ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a JSON file for your custom category: **Path:** `AppData/Roaming/Hytale/UserData/Packs/YourPackName/Server/Item/Category/CreativeLibrary/MyItemCategory.json` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-template) Category Template: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-properties-explained) Category Properties Explained -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#main-category-properties) Main Category Properties Property Description Example `Id` Unique identifier for the category `"MyCategory"` `Name` Translation key for tooltip text `"ui.itemcategory.mycategory"` `Icon` Path to the category icon `"Icons/ItemCategories/MyCategory.png"` `Order` Position in Creative Menu (lower = left) `6` `Children` Array of subcategories See template above ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#subcategory-properties-children) Subcategory Properties (Children) Each child/subcategory has: * `Id` - Unique identifier for the subcategory * `Name` - Translation key for the subcategory tooltip * `Icon` - Path to the subcategory icon * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-2-adding-translations) Step 2: Adding Translations --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Define the display names for your categories by creating translation files: **Path:** `YourPackName/Server/Languages/en-US/ui.lang` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#translation-format) Translation Format: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#key-points) Key Points: * Translation keys in JSON start with `"ui."` but the `.lang` file omits this prefix * The text after `=` is what displays when hovering over the category icon * Create files for other languages (e.g., `es-ES/ui.lang`) for internationalization * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-3-adding-icons) Step 3: Adding Icons ------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create icon images for your categories: **Main Category Icon Path:** `YourPackName/Common/Icons/ItemCategories/MyCategory.png` **Subcategory Icon Paths:** `YourPackName/Common/Icons/ItemCategories/My_Example_Category.png` `YourPackName/Common/Icons/ItemCategories/My_Example_Category_Two.png` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#icon-requirements) Icon Requirements: * **Format:** PNG with transparency support * **Recommended Size:** 32x32 pixels * **Style:** Should match Hytale's UI aesthetic * **Naming:** Must match exactly the path in your JSON file * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-4-adding-blocks-items-to-categories) Step 4: Adding Blocks/Items to Categories ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To add your custom blocks or items to your new categories, edit the item/block JSON file: **Path:** `YourPackName/Server/Item/Items/your_block.json` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#add-category-reference) Add Category Reference: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-path-format) Category Path Format: * **Main Category Only:** `"MyCategory"` * **Subcategory:** `"MyCategory.Example_Category"` * **Multiple Categories:** Add multiple strings to the array ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#example-multiple-categories) Example - Multiple Categories: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#finding-vanilla-category-names) Finding Vanilla Category Names ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To use Vanilla categories in your items, look in the game's asset files: **Path:** `Assets/Server/Item/Category/CreativeLibrary` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#common-vanilla-categories) Common Vanilla Categories: * `Blocks.Rocks` * `Blocks.Wood` * `Blocks.Nature` * `Items.Tools` * `Items.Weapons` * `Items.Food` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#complete-folder-structure-example) Complete Folder Structure Example ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#advanced-category-order) Advanced: Category Order --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `Order` property determines the position of your category in the Creative Menu: * **Lower numbers** = Further left * **Higher numbers** = Further right * **Vanilla categories** typically use orders 0-5 * **Custom categories** should use 6+ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#example-order) Example Order: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#testing-your-categories) Testing Your Categories -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Enable your Pack in a world 2. Enter the world 3. Open your inventory in Creative Mode 4. Look for your custom category icon(s) in the Creative Menu 5. Click the icon to see your subcategories 6. Verify items appear in the correct subcategories * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-doesnt-appear) Category doesn't appear: * Verify JSON syntax is valid * Check that icon paths are correct * Ensure translation file exists * Verify Pack is enabled in world ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#icon-is-missing) Icon is missing: * Check icon file exists at specified path * Verify PNG format * Ensure path in JSON matches file location exactly ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#items-dont-appear-in-category) Items don't appear in category: * Verify category ID matches in both files * Check subcategory path format: `"MainCategory.SubCategory"` * Ensure item JSON includes `Categories` array ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#tooltip-shows-translation-key) Tooltip shows translation key: * Check `ui.lang` file exists * Verify translation key matches (without `ui.` prefix) * Ensure no typos in the key * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#getting-help) Getting Help ---------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousBlock State Changingchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing) [NextBlock Animationschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations) Last updated 1 day ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#overview) * [What are Item Categories?](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#what-are-item-categories) * [Step 1: Creating the Category File](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-1-creating-the-category-file) * [Category Template:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-template) * [Category Properties Explained](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-properties-explained) * [Main Category Properties](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#main-category-properties) * [Subcategory Properties (Children)](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#subcategory-properties-children) * [Step 2: Adding Translations](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-2-adding-translations) * [Translation Format:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#translation-format) * [Key Points:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#key-points) * [Step 3: Adding Icons](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-3-adding-icons) * [Icon Requirements:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#icon-requirements) * [Step 4: Adding Blocks/Items to Categories](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#step-4-adding-blocks-items-to-categories) * [Add Category Reference:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#add-category-reference) * [Category Path Format:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-path-format) * [Example - Multiple Categories:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#example-multiple-categories) * [Finding Vanilla Category Names](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#finding-vanilla-category-names) * [Common Vanilla Categories:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#common-vanilla-categories) * [Complete Folder Structure Example](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#complete-folder-structure-example) * [Advanced: Category Order](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#advanced-category-order) * [Example Order:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#example-order) * [Testing Your Categories](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#testing-your-categories) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#troubleshooting) * [Category doesn't appear:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#category-doesnt-appear) * [Icon is missing:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#icon-is-missing) * [Items don't appear in category:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#items-dont-appear-in-category) * [Tooltip shows translation key:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#tooltip-shows-translation-key) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories#getting-help) sun-brightdesktopmoon Copy { "Id": "MyCategory", "Name": "ui.itemcategory.mycategory", "Icon": "Icons/ItemCategories/MyCategory.png", "Order": 6, "Children": [\ {\ "Id": "Example_Category",\ "Name": "ui.itemcategory.example_category",\ "Icon": "Icons/ItemCategories/My_Example_Category.png"\ },\ {\ "Id": "Example_Category_Two",\ "Name": "ui.itemcategory.example_category_two",\ "Icon": "Icons/ItemCategories/My_Example_Category_Two.png"\ }\ ] } Copy itemcategory.mycategory = My Custom Category itemcategory.example_category = Example Tab One itemcategory.example_category_two = Example Tab Two Copy { "TranslationProperties": { "Name": "server.Your_Block.name" }, "Categories": [\ "MyCategory.Example_Category"\ ], // ... rest of block properties } Copy "Categories": [\ "MyCategory.Example_Category",\ "Blocks.Rocks",\ "MyCategory.Example_Category_Two"\ ] Copy YourPackName/ |-- manifest.json |-- Common/ | `-- Icons/ | `-- ItemCategories/ | |-- MyCategory.png | |-- My_Example_Category.png | `-- My_Example_Category_Two.png `-- Server/ |-- Item/ | |-- Category/ | | `-- CreativeLibrary/ | | `-- MyItemCategory.json | `-- Items/ | `-- your_block.json |-- Languages/ | `-- en-US/ | `-- ui.lang Copy "Order": 6, // Appears after vanilla categories sun-brightdesktopmoon --- # Example Command to Show Title | Hytale Modding Documentation **Source:** [Official Hytale Resourcesarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 9, 2026 at 12:02 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#overview) Overview --------------------------------------------------------------------------------------------------------------------------------------------------------- This tutorial demonstrates how to create custom commands that display event titles using Hytale's plugin API. Titles are a powerful way to provide visual feedback to players during events, achievements, or system announcements. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#example-result) Example Result --------------------------------------------------------------------------------------------------------------------------------------------------------------------- When executed, the command displays a high-impact title and subtitle directly on the player's screen. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#command-implementation) Command Implementation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#complete-code-example) Complete Code Example: Copy public class ModdedCommand extends CommandBase { public ModdedCommand() { // Name, Description, Requires OP super("moddedcommand", "A test command", false); } @Override protected void executeSync(@Nonnull CommandContext commandContext) { // Ensure the sender is a player before proceeding commandContext.senderAsPlayer().getWorld().execute(() -> { EventTitleUtil.showEventTitleToPlayer( commandContext.senderAsPlayer().getReference(), Message.raw("It's modded!"), // Main Title Message.raw("Yeppers"), // Subtitle true, // Is Major (Shows gold bars/animation) commandContext.senderAsPlayer().getWorld().getEntityStore().getStore() ); }); } } * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#code-breakdown) Code Breakdown --------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#id-1.-command-constructor) 1\. Command Constructor The `super` call defines how players interact with the command in the chat console. * `**"moddedcommand"**`: The trigger (e.g., `/moddedcommand`). * `**"A test command"**`: The tooltip shown in the `/help` menu. * `**false**`: Setting this to `true` would restrict the command to server operators. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#id-2.-the-execute-method) 2\. The Execute Method * `**executeSync**`: This method runs on the main server thread, making it safe to access world data. * `**CommandContext**`: Contains data about the `sender`, the `world`, and any `arguments` passed. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#id-3.-eventtitleutil-parameters) 3\. EventTitleUtil Parameters The `EventTitleUtil` class handles the packet logic for you: * **Player Reference**: Obtained via `senderAsPlayer().getReference()`. * **Main/Subtitle**: Wrapped in `Message.raw()` to handle plain text. * **Is Major**: If set to `true`, the title displays with "major" styling (often including decorative bars and a more pronounced animation). * **Entity Store**: Required for the server to track the display lifecycle relative to the player entity. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#registering-the-command) Registering the Command --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To activate your command, register it within the `onEnable()` method of your main plugin class. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#customization-and-styling) Customization & Styling ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#using-colors) Using Colors You can use standard Hytale color codes (e.g., `&6` for Gold, `&b` for Aqua) within your messages: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#formatting-the-duration) Formatting the Duration While the basic utility uses default timings, you can also specify fade-in, stay, and fade-out durations using advanced overloads of the `EventTitleUtil` (if available in your API version). * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#best-practices) Best Practices --------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **Thread Safety**: Always wrap world-altering or visual logic in a `world.execute()` block to ensure it runs on the correct synchronization cycle. * **Player Validation**: Before calling `senderAsPlayer()`, verify the sender is actually a player (and not the console) to avoid `NullPointerExceptions`. * **Clarity**: Avoid using titles for frequent spam; they are best reserved for significant milestones to maintain their visual impact. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#getting-help) Getting Help ----------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousGetting Started with Pluginschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins) [NextCustom Config Fileschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files) Last updated 1 day ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#overview) * [Example Result](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#example-result) * [Command Implementation](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#command-implementation) * [Complete Code Example:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#complete-code-example) * [Code Breakdown](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#code-breakdown) * [1\. Command Constructor](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#id-1.-command-constructor) * [2\. The Execute Method](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#id-2.-the-execute-method) * [3\. EventTitleUtil Parameters](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#id-3.-eventtitleutil-parameters) * [Registering the Command](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#registering-the-command) * [Customization & Styling](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#customization-and-styling) * [Using Colors](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#using-colors) * [Formatting the Duration](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#formatting-the-duration) * [Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#best-practices) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title#getting-help) sun-brightdesktopmoon Copy public class ExamplePlugin extends JavaPlugin { @Override public void onEnable() { // Register the command with the server's command manager getServer().getCommandManager().registerCommand(new ModdedCommand()); getLogger().info("Modded Title Plugin has been enabled!"); } } Copy Message.raw("&6CONGRATULATIONS!") Message.raw("&bYou found a secret area.") sun-brightdesktopmoon --- # Getting Started with Packs | Hytale Modding Documentation **Source:** [Getting Started with Packsarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 16, 2026 at 12:47 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------------- This guide walks you through creating your first Hytale Pack. Packs are asset/content packs that allow you to add new blocks, items, mobs, and behavior to Hytale without requiring coding knowledge. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#step-1-creating-a-folder) Step 1: Creating a Folder ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- First, create a folder for your Pack: **Path:** `./AppData/Roaming/Hytale/UserData/Mods/YourPackName` Replace `YourPackName` with the desired name of your Pack. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#example) Example: Copy C:\Users\YourUsername\AppData\Roaming\Hytale\UserData\Mods\MyFirstPack [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#asset-editor-alternative) Asset Editor (Alternative) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Use the in-game Asset Editor for a quicker start: 1. Launch Hytale and create a new **Creative World**. 2. Grant yourself OP status by typing `/op self` in chat. 3. Open your **Inventory**, then navigate to **Creative Tools** > **Assets** > **Asset Editor**. 4. In the Asset Editor, click the three dots in the top left and select **Add Pack**. 5. Enter your pack details. 6. Proceed to Step 3. > **Note:** Check our [YouTube Tutorialsarrow-up-right](https://www.google.com/search?q=00-youtube-tutorials.md) > for more on the Asset Editor. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#step-2-manifest-file) Step 2: Manifest File -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a `manifest.json` file in your Pack folder. This file contains metadata about your Pack. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#manifest-template) Manifest Template: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#manifest-fields-explained) Manifest Fields Explained: Field Description Required `Group` Your organization or group name Yes `Name` The name of your Pack Yes `Version` Version number (semantic versioning) Yes `Description` A brief description of what your Pack does Yes `Authors` Array of author information Yes `Website` Your website or project page Optional `ServerVersion` Compatible server version (`*` for all) Yes `Dependencies` Packs required for this to work Optional `OptionalDependencies` Packs that enhance but aren't required Optional `DisabledByDefault` Whether Pack loads automatically Optional * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#step-3-common-and-server-folders) Step 3: Common and Server Folders -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create two main folders inside your Pack directory: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#folder-structure) Folder Structure: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#common-folder) Common Folder **Path:** `./AppData/Roaming/Hytale/UserData/Packs/YourPackName/Common` **Handles:** * Models * Textures * Visual assets ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#server-folder) Server Folder **Path:** `./AppData/Roaming/Hytale/UserData/Packs/YourPackName/Server` **Handles:** * Item creation * Block creation * Translations * Particle creation * Game logic and behavior * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#complete-folder-structure-example) Complete Folder Structure Example --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Note:** This shows key folders; full structures vary. For a complete overview: > > 1. Open the Hytale launcher. > > 2. Click **Settings** (top left). > > 3. Select **Open Directory**. > > 4. Navigate to `install\release\package\game\latest` and explore `Assets.zip`. > * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#activating-your-pack) Activating Your Pack ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To use your Pack in Hytale: 1. Open Hytale. 2. Go to the **Worlds** tab. 3. Right-click the target world. 4. Toggle on your Pack. 5. Enter the world to test changes. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) Would you like me to clean up any other guides in this series for you? [PreviousFuture Server Additionschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/server-administration/24-future-additions) [NextAdding a Blockchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#overview) * [Step 1: Creating a Folder](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#step-1-creating-a-folder) * [Example:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#example) * [Asset Editor (Alternative)](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#asset-editor-alternative) * [Step 2: Manifest File](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#step-2-manifest-file) * [Manifest Template:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#manifest-template) * [Manifest Fields Explained:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#manifest-fields-explained) * [Step 3: Common and Server Folders](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#step-3-common-and-server-folders) * [Folder Structure:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#folder-structure) * [Common Folder](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#common-folder) * [Server Folder](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#server-folder) * [Complete Folder Structure Example](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#complete-folder-structure-example) * [Activating Your Pack](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#activating-your-pack) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs#getting-help) sun-brightdesktopmoon Copy { "Group": "YourGroupName", "Name": "PackName", "Version": "1.0.0", "Description": "Add the pack description here", "Authors": [\ {\ "Name": "AuthorName",\ "Email": "example@example.com",\ "Url": "https://your-url.com"\ }\ ], "Website": "https://your-website.com", "ServerVersion": "*", "Dependencies": {}, "OptionalDependencies": {}, "DisabledByDefault": false } Copy ./AppData/Roaming/Hytale/UserData/Packs/YourPackName/ |-- manifest.json |-- Common/ `-- Server/ Copy MyFirstPack/ |-- manifest.json |-- Common/ | |-- BlockTextures/ | |-- Icons/ | `-- Models/ `-- Server/ |-- Item/ | |-- Items/ | `-- Category/ |-- Languages/ | `-- en-US/ `-- Block/ sun-brightdesktopmoon --- # Adding a Block | Hytale Modding Documentation **Source:** [Adding a Blockarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 9, 2026 at 12:01 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------- This guide teaches you how to add a custom block to Hytale using Packs. You'll learn how to create the block definition, add textures, and modify properties using the Asset Editor. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#prerequisites) Prerequisites ----------------------------------------------------------------------------------------------------------------------------------------------------- Before starting, ensure you have: * Created a Pack folder structure (see "Getting Started with Packs") * A `manifest.json` file in your Pack root * `Common/` and `Server/` folders created * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-1-creating-the-block-manifest-file) Step 1: Creating the Block Manifest File ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a JSON file for your block in the Items directory: **Path:** `./AppData/Roaming/Hytale/UserData/Packs/YourPackName/Server/Item/Items/your_block.json` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#block-manifest-template) Block Manifest Template: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#block-properties-explained) Block Properties Explained ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#top-level-properties) Top-Level Properties Property Description Example `TranslationProperties.Name` Translation key for block name `"server.Example_Block.name"` `MaxStack` Maximum stack size in inventory `100` `Icon` Path to inventory icon `"Icons/ItemsGenerated/Example_Block.png"` `Categories` Creative menu categories `["Blocks.Rocks"]` `PlayerAnimationsId` Animation set when placing `"Block"` `Set` Block set identifier `"Rock_Stone"` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#blocktype-properties) BlockType Properties Property Description Options/Example `Material` Block material type `"Solid"`, `"Liquid"`, `"Gas"` `DrawType` Rendering method `"Cube"`, `"Cross"`, `"Model"` `Group` Block group for behavior `"Stone"`, `"Wood"`, `"Dirt"` `Flags` Special block flags `{}` (varies by block type) `ParticleColor` Color of break particles `"#aeae8c"` (hex color) `BlockSoundSetId` Sound set for interactions `"Stone"`, `"Wood"`, `"Grass"` `BlockBreakingDecalId` Breaking animation overlay `"Breaking_Decals_Rock"` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#gathering-properties) Gathering Properties ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#texture-properties) Texture Properties **Alternative - Different Textures Per Side:** * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-2-creating-texture-files) Step 2: Creating Texture Files -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create texture files in the Common folder: **Texture Path:** `./AppData/Roaming/Hytale/UserData/Packs/YourPackName/Common/BlockTextures/your_block_texture.png` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#texture-requirements) Texture Requirements: * **Format:** PNG * **Recommended Size:** 16x16 or 32x32 pixels * **Transparency:** Supported (for non-solid blocks) * **Naming:** Match the path in your block JSON ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#icon-path) Icon Path: Also create an icon for the inventory: **Icon Path:** `./AppData/Roaming/Hytale/UserData/Packs/YourPackName/Common/Icons/ItemsGenerated/Example_Block.png` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-3-creating-translation-file) Step 3: Creating Translation File -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a translation file to define the block's display name: **Path:** `./AppData/Roaming/Hytale/UserData/Packs/YourPackName/Server/Languages/en-US/server.lang` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#translation-format) Translation Format: The key (`Example_Block.name`) must match the `TranslationProperties.Name` in your block JSON (without the `"server."` prefix). ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#multiple-languages) Multiple Languages: Create additional `.lang` files for other languages: * `es-ES/server.lang` - Spanish * `fr-FR/server.lang` - French * `de-DE/server.lang` - German * etc. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-4-modify-in-asset-editor) Step 4: Modify in Asset Editor -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now you can visually edit your block using the in-game Asset Editor: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#steps-to-access-asset-editor) Steps to Access Asset Editor: 1. **Add Pack to World:** * Open Hytale * Visit the "Worlds" tab * Right-click on your world * Toggle on your Pack 1. **Enter the World:** * Join the world with your Pack enabled 1. **Open Asset Editor:** * Open your inventory * Click on the "Creation Tools" tab * Click on "Asset Editor" 1. **Edit Your Block:** * Select your Pack from the list * Find your block in the items list * Modify any settings you desire * Changes are saved automatically ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#what-you-can-edit-in-asset-editor) What You Can Edit in Asset Editor: * Material properties * Breaking behavior * Sounds * Particle effects * Textures (paths) * Drop items * Stack size * Categories * And much more! * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#complete-folder-structure-example) Complete Folder Structure Example --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#testing-your-block) Testing Your Block --------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Launch Hytale with your Pack enabled 2. Open Creative Mode 3. Open your inventory 4. Find your block in the category you specified 5. Place it in the world 6. Test breaking it to verify drops and sounds * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#block-doesnt-appear-in-game) Block doesn't appear in game: * Verify `manifest.json` is correct * Check that Pack is enabled in world settings * Ensure JSON syntax is valid (use a JSON validator) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#texture-is-missing-pink) Texture is missing/pink: * Verify texture path matches JSON exactly * Check texture file exists at specified path * Ensure texture is PNG format ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#translation-shows-key-instead-of-name) Translation shows key instead of name: * Verify translation key matches in JSON and `.lang` file * Check that `en-US` folder and `server.lang` file exist * Ensure no typos in translation key * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousGetting Started with Packschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/02-getting-started-with-packs) [NextBlock State Changingchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/04-block-state-changing) Last updated 1 day ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#overview) * [Prerequisites](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#prerequisites) * [Step 1: Creating the Block Manifest File](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-1-creating-the-block-manifest-file) * [Block Manifest Template:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#block-manifest-template) * [Block Properties Explained](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#block-properties-explained) * [Top-Level Properties](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#top-level-properties) * [BlockType Properties](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#blocktype-properties) * [Gathering Properties](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#gathering-properties) * [Texture Properties](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#texture-properties) * [Step 2: Creating Texture Files](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-2-creating-texture-files) * [Texture Requirements:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#texture-requirements) * [Icon Path:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#icon-path) * [Step 3: Creating Translation File](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-3-creating-translation-file) * [Translation Format:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#translation-format) * [Multiple Languages:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#multiple-languages) * [Step 4: Modify in Asset Editor](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#step-4-modify-in-asset-editor) * [Steps to Access Asset Editor:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#steps-to-access-asset-editor) * [What You Can Edit in Asset Editor:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#what-you-can-edit-in-asset-editor) * [Complete Folder Structure Example](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#complete-folder-structure-example) * [Testing Your Block](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#testing-your-block) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#troubleshooting) * [Block doesn't appear in game:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#block-doesnt-appear-in-game) * [Texture is missing/pink:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#texture-is-missing-pink) * [Translation shows key instead of name:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#translation-shows-key-instead-of-name) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/03-adding-a-block#getting-help) sun-brightdesktopmoon Copy { "TranslationProperties": { "Name": "server.Example_Block.name" }, "MaxStack": 100, "Icon": "Icons/ItemsGenerated/Example_Block.png", "Categories": [\ "Blocks.Rocks"\ ], "PlayerAnimationsId": "Block", "Set": "Rock_Stone", "BlockType": { "Material": "Solid", "DrawType": "Cube", "Group": "Stone", "Flags": {}, "Gathering": { "Breaking": { "GatherType": "Rocks", "ItemId": "Rock_Stone_Cobble" } }, "BlockParticleSetId": "Stone", "Textures": [\ {\ "All": "BlockTextures/Example_Block.png"\ }\ ], "ParticleColor": "#aeae8c", "BlockSoundSetId": "Stone", "BlockBreakingDecalId": "Breaking_Decals_Rock" }, "ResourceTypes": [\ {\ "Id": "Rock"\ }\ ] } Copy "Gathering": { "Breaking": { "GatherType": "Rocks", // Tool type required "ItemId": "Rock_Stone_Cobble" // Item dropped when broken } } Copy "Textures": [\ {\ "All": "BlockTextures/Example_Block.png" // Same texture all sides\ }\ ] Copy "Textures": [\ {\ "Top": "BlockTextures/Example_Block_Top.png",\ "Bottom": "BlockTextures/Example_Block_Bottom.png",\ "Sides": "BlockTextures/Example_Block_Sides.png"\ }\ ] Copy Example_Block.name = Example Block Copy YourPackName/ |-- manifest.json |-- Common/ | |-- BlockTextures/ | | `-- Example_Block.png | `-- Icons/ | `-- ItemsGenerated/ | `-- Example_Block.png `-- Server/ |-- Item/ | `-- Items/ | `-- your_block.json `-- Languages/ `-- en-US/ `-- server.lang sun-brightdesktopmoon --- # Block Animations | Hytale Modding Documentation **Source:** [Block Animationsarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 9, 2026 at 12:01 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#overview) Overview --------------------------------------------------------------------------------------------------------------------------------------------- This guide explains how to add animations to blocks in Hytale. Animations can make your blocks come alive with moving parts, opening mechanisms, or any other dynamic movement. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------------------------------------------------------- * Basic understanding of block states (see "Block State Changing" guide) * Blockbench installed ([https://www.blockbench.net/arrow-up-right](https://www.blockbench.net/) ) * A block model with named groups * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#what-can-be-animated) What Can Be Animated? ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Block animations can modify: * **Position** - Move elements in X, Y, Z coordinates * **Orientation** - Rotate elements * **ShapeStretch** - Stretch or scale elements * **ShapeVisible** - Show or hide elements * **ShapeUvOffset** - Animate textures (advanced) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#step-1-add-animation-to-block-state) Step 1: Add Animation to Block State ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- First, reference your animation file in the block's state definition: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#step-2-create-groups-in-blockbench) Step 2: Create Groups in Blockbench -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Open your block model in Blockbench: 1. **Create a Group:** * In Blockbench, create a new group * Give it a descriptive name (e.g., "Water", "Door", "Drawer") * This group name will be referenced in your animation file 1. **Add Elements:** * Place the elements you want to animate inside the group * You can have multiple elements in one group * All elements in the group will animate together 1. **Export:** * Export as `.blockymodel` format for Hytale * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#step-3-create-animation-file) Step 3: Create Animation File -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a `.blockyanim` file in your Pack's animation folder: **Path:** `YourPackName/Common/Blocks/Animations/Rising_Water.blockyanim` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#basic-animation-structure) Basic Animation Structure: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-properties) Animation Properties: Property Description Example `formatVersion` Animation format version `1` `duration` Animation length in ticks `50` (2.5 seconds) `holdLastKeyframe` Whether to hold at final position `true` or `false` `nodeAnimations` Object containing group animations See below * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-types) Animation Types ----------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#position-animation) Position Animation Moves elements in 3D space: **This example:** Moves the element 8.5 units up on the Y-axis over 50 ticks. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#orientation-animation-rotation) Orientation Animation (Rotation) Rotates elements using quaternions: **Note:** Quaternions are complex. Common rotation values: * **No rotation:** `{x:0, y:0, z:0, w:1}` * **90° Y-axis:** `{x:0, y:0.707, z:0, w:0.707}` * **180° Y-axis:** `{x:0, y:1, z:0, w:0}` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#example-1-rising-water-animation) Example 1: Rising Water Animation ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This animation makes water rise from 0 to 8.5 units upward: **File:** `Rising_Water.blockyanim` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#example-2-wardrobe-opening-animation) Example 2: Wardrobe Opening Animation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ A complex example with multiple animated groups (doors, knockers, drawer): **File:** `Wardrobe_Open.blockyanim` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#breakdown-of-wardrobe-animation) Breakdown of Wardrobe Animation: * **Door-L:** Left door swings open (rotates on Y-axis) * **Door-R:** Right door swings open (opposite direction) * **Drawer:** Pulls out (moves on Z-axis) * **Door-Knocker:** Bounces back and forth (multiple rotation keyframes) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#keyframe-properties) Keyframe Properties ------------------------------------------------------------------------------------------------------------------------------------------------------------------- Each keyframe contains: Property Description `time` When this keyframe occurs (in ticks) `delta` The transformation values `interpolationType` How to transition (`"smooth"`, `"linear"`, `"step"`) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#interpolation-types) Interpolation Types: * **smooth:** Gradual acceleration/deceleration (natural) * **linear:** Constant speed (mechanical) * **step:** Instant change (no interpolation) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#complete-file-structure) Complete File Structure --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#tips-for-creating-animations) Tips for Creating Animations ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. **Start Simple:** Begin with single-axis position animations 2. **Use Vanilla as Reference:** Look at wardrobe, door, and chest animations 3. **Plan Timing:** Map out when each group should start/stop moving 4. **Test Iteratively:** Test in-game frequently, adjust values 5. **Empty Arrays:** Use `[]` for animation types you don't need * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#testing-your-animations) Testing Your Animations --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Enable your Pack in a world 2. Place the animated block 3. Trigger the state change (e.g., right-click) 4. Observe the animation 5. Adjust timing and delta values as needed 6. Reload the Pack to see changes * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#troubleshooting) Troubleshooting ----------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-doesnt-play) Animation doesn't play: * Verify animation file path in block JSON * Check that group names match exactly (case-sensitive) * Ensure `.blockyanim` extension is correct ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-is-choppy) Animation is choppy: * Increase duration for smoother movement * Use "smooth" interpolation instead of "linear" * Add more intermediate keyframes ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#wrong-elements-animate) Wrong elements animate: * Check group names in Blockbench * Verify correct elements are in the group * Ensure animation references the right group name ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-plays-backwards) Animation plays backwards: * Check time values increase correctly * Verify keyframes are in chronological order * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#advanced-studying-vanilla-animations) Advanced: Studying Vanilla Animations ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ To learn more, examine vanilla Hytale animations: **Path:** `Assets/Common/Blocks/Animations/` Look at: * Door animations * Chest animations * Wardrobe animations * Machine animations * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#getting-help) Getting Help ----------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousItem Categorieschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/05-item-categories) [NextBlockbench Modeling Guidechevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide) Last updated 1 day ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#overview) * [Prerequisites](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#prerequisites) * [What Can Be Animated?](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#what-can-be-animated) * [Step 1: Add Animation to Block State](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#step-1-add-animation-to-block-state) * [Step 2: Create Groups in Blockbench](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#step-2-create-groups-in-blockbench) * [Step 3: Create Animation File](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#step-3-create-animation-file) * [Basic Animation Structure:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#basic-animation-structure) * [Animation Properties:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-properties) * [Animation Types](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-types) * [Position Animation](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#position-animation) * [Orientation Animation (Rotation)](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#orientation-animation-rotation) * [Example 1: Rising Water Animation](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#example-1-rising-water-animation) * [Example 2: Wardrobe Opening Animation](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#example-2-wardrobe-opening-animation) * [Breakdown of Wardrobe Animation:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#breakdown-of-wardrobe-animation) * [Keyframe Properties](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#keyframe-properties) * [Interpolation Types:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#interpolation-types) * [Complete File Structure](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#complete-file-structure) * [Tips for Creating Animations](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#tips-for-creating-animations) * [Testing Your Animations](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#testing-your-animations) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#troubleshooting) * [Animation doesn't play:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-doesnt-play) * [Animation is choppy:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-is-choppy) * [Wrong elements animate:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#wrong-elements-animate) * [Animation plays backwards:](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#animation-plays-backwards) * [Advanced: Studying Vanilla Animations](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#advanced-studying-vanilla-animations) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations#getting-help) sun-brightdesktopmoon Copy "State": { "Definitions": { "On": { "CustomModelAnimation": "Blocks/Animations/Rising_Water.blockyanim" }, "Off": { "CustomModelAnimation": "Blocks/Animations/Empty_Water.blockyanim" } } } Copy { "formatVersion": 1, "duration": 50, "holdLastKeyframe": true, "nodeAnimations": { "Water": { "position": [ /* keyframes */ ], "orientation": [ /* keyframes */ ], "shapeStretch": [ /* keyframes */ ], "shapeVisible": [ /* keyframes */ ], "shapeUvOffset": [ /* keyframes */ ] } } } Copy "position": [\ {\ "time": 0,\ "delta": {\ "x": 0,\ "y": 0,\ "z": 0\ },\ "interpolationType": "smooth"\ },\ {\ "time": 50,\ "delta": {\ "x": 0,\ "y": 8.5,\ "z": 0\ },\ "interpolationType": "smooth"\ }\ ] Copy "orientation": [\ {\ "time": 0,\ "delta": {\ "x": 0,\ "y": 0,\ "z": 0,\ "w": 1\ },\ "interpolationType": "smooth"\ },\ {\ "time": 15,\ "delta": {\ "x": 0,\ "y": 0.866025,\ "z": 0,\ "w": 0.5\ },\ "interpolationType": "smooth"\ }\ ] Copy { "formatVersion": 1, "duration": 50, "holdLastKeyframe": true, "nodeAnimations": { "Water": { "position": [\ {\ "time": 0,\ "delta": {\ "x": 0,\ "y": 0,\ "z": 0\ },\ "interpolationType": "smooth"\ },\ {\ "time": 50,\ "delta": {\ "x": 0,\ "y": 8.5,\ "z": 0\ },\ "interpolationType": "smooth"\ }\ ], "orientation": [], "shapeStretch": [], "shapeVisible": [], "shapeUvOffset": [] } } } Copy { "formatVersion": 1, "duration": 50, "holdLastKeyframe": true, "nodeAnimations": { "Door-L": { "position": [], "orientation": [\ {\ "time": 0,\ "delta": {"x": 0, "y": 0, "z": 0, "w": 1},\ "interpolationType": "smooth"\ },\ {\ "time": 15,\ "delta": {"x": 0, "y": 0.866025, "z": 0, "w": 0.5},\ "interpolationType": "smooth"\ },\ {\ "time": 25,\ "delta": {"x": 0, "y": 0.793353, "z": 0, "w": 0.608761},\ "interpolationType": "smooth"\ }\ ], "shapeStretch": [], "shapeVisible": [], "shapeUvOffset": [] }, "Door-R": { "position": [], "orientation": [\ {\ "time": 0,\ "delta": {"x": 0, "y": 0, "z": 0, "w": 1},\ "interpolationType": "smooth"\ },\ {\ "time": 20,\ "delta": {"x": 0, "y": -0.866025, "z": 0, "w": 0.5},\ "interpolationType": "smooth"\ },\ {\ "time": 30,\ "delta": {"x": 0, "y": -0.793353, "z": 0, "w": 0.608761},\ "interpolationType": "smooth"\ }\ ], "shapeStretch": [], "shapeVisible": [], "shapeUvOffset": [] }, "Drawer": { "position": [\ {\ "time": 0,\ "delta": {"x": 0, "y": 0, "z": 0},\ "interpolationType": "smooth"\ },\ {\ "time": 10,\ "delta": {"x": 0, "y": 0, "z": 12},\ "interpolationType": "smooth"\ },\ {\ "time": 20,\ "delta": {"x": 0, "y": 0, "z": 10},\ "interpolationType": "smooth"\ }\ ], "orientation": [], "shapeStretch": [], "shapeVisible": [], "shapeUvOffset": [] }, "Door-Knocker": { "position": [], "orientation": [\ {\ "time": 0,\ "delta": {"x": 0, "y": 0, "z": 0, "w": 1},\ "interpolationType": "smooth"\ },\ {\ "time": 17,\ "delta": {"x": -0.5, "y": 0, "z": 0, "w": 0.866025},\ "interpolationType": "smooth"\ },\ {\ "time": 24,\ "delta": {"x": 0, "y": 0, "z": 0, "w": 1},\ "interpolationType": "smooth"\ },\ {\ "time": 32,\ "delta": {"x": -0.130526, "y": 0, "z": 0, "w": 0.991445},\ "interpolationType": "smooth"\ },\ {\ "time": 40,\ "delta": {"x": 0, "y": 0, "z": 0, "w": 1},\ "interpolationType": "smooth"\ }\ ], "shapeStretch": [], "shapeVisible": [], "shapeUvOffset": [] } } } Copy YourPackName/ |-- Common/ | `-- Blocks/ | |-- Animations/ | | |-- Rising_Water.blockyanim | | |-- Empty_Water.blockyanim | | `-- Wardrobe_Open.blockyanim | |-- your_model.blockymodel | `-- Texture/ | `-- your_texture.png `-- Server/ `-- Item/ `-- Items/ `-- your_block.json sun-brightdesktopmoon --- # Getting Started with Plugins | Hytale Modding Documentation **Source:** [Getting Started with Pluginsarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 16, 2026 at 07:30 AM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#overview) Overview ----------------------------------------------------------------------------------------------------------------------------------------------------------- This guide will help you get started with creating **Plugins** for Hytale. Plugins are mods written in **Java** that use the game's API to expand vanilla functionality and add new content programmatically. > **Early Access Warning**: The game Hytale is in early access, and so is this project! Features may be incomplete, unstable, or change frequently. Please be patient and understanding as development continues. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#prerequisites) Prerequisites --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Before you begin, ensure you have: * **Hytale** installed via the official launcher * **IntelliJ IDEA** (Community Edition is fine) * **Java 25** downloaded and configured * Basic **Java programming** knowledge * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-1-download-the-idea-template) Step 1: Download the IDEA Template -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The easiest way to start developing plugins is by using the official template created by **Darkhax & Jared**. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#plugin-template) Plugin Template: * **Hytale Plugin Template:** [Github Repoarrow-up-right](https://github.com/realBritakee/hytale-template-plugin) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#template-features) Template Features: The template includes many great features: * Adds the latest Hytale server files to your classpath * Run the game from your IDE with breakpoint support * Bundle assets with your plugin (editable with in-game Asset Editor) * Supports various patch lines (releases and pre-releases) * Includes example code and assets * Pre-configured Gradle build system * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-2-configure-the-template-before-importing) Step 2: Configure the Template Before Importing ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Important:** Configure the project before importing it into IDEA to avoid caching issues later. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-2.1-extract-the-template) 2.1 Extract the Template 1. Download the ZIP file from the GitHub repository 2. Extract contents to your desired development location 3. Read the included `README.md` for detailed setup instructions ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-2.2-configure-project-files) 2.2 Configure Project Files Before importing the project, you need to configure three key files: #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-1.-set-project-name-in-settings.gradle) 1\. Set Project Name in `settings.gradle` Set the name of your project. Use capitalized names and avoid whitespace and special characters, as this will be used as the base name for files produced by Gradle (like the JAR file). #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-2.-review-gradle-properties-in-gradle.properties) 2\. Review Gradle Properties in `gradle.properties` Update the properties to match your project: #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-3.-update-manifest-file-in-src-main-resources-manifest.json) 3\. Update Manifest File in `src/main/resources/manifest.json` The manifest file provides important information about your plugin to Hytale. Update every property to reflect your project: **Important Manifest Properties:** * **Main**: The most critical property - tells the game which class file to load as the entry point for your plugin * **Version** and **IncludesAssetPack**: These are automatically updated by Gradle during development and builds, allowing you to use the in-game asset editor * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-3-import-the-project-into-idea) Step 3: Import the Project into IDEA ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ 1. **Launch IntelliJ IDEA** 2. **Open Project:** * Click `File` -> `Open` * Navigate to your extracted and configured template folder * Select the folder and click `OK` 1. **Wait for Initialization:** * IDEA will automatically import the Gradle project * The `HytaleServer` run configuration will be created automatically * A `./run` folder will be generated * Dependencies will be downloaded automatically * This may take several minutes on first run > **Note:** If you don't see the `HytaleServer` run configuration, open the dropdown menu or click "Edit Configurations..." once to unhide it. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-4-configure-java-25-sdk) Step 4: Configure Java 25 SDK ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you haven't already added Java 25 as an SDK: 1. **Open Project Structure:** * `File` -> `Project Structure` (or `Ctrl+Alt+Shift+S`) 1. **Add SDK:** * Click `SDKs` under `Platform Settings` * Click `+` -> `Add JDK` * Navigate to your Java 25 installation * Click `OK` 1. **Set Project SDK:** * Go to `Project` settings * Set `SDK` to Java 25 * Click `Apply` and `OK` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-5-understanding-the-project-structure) Step 5: Understanding the Project Structure -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-6-authenticating-your-test-server) Step 6: Authenticating Your Test Server ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ > **CRITICAL:** You MUST authenticate your test server before you can connect to it! ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#initial-authentication) Initial Authentication 1. Run the server once from IDEA (it will start but you won't be able to connect yet) 2. In the server terminal, run: 1. The command will print a URL 2. Open the URL in your browser and authenticate using your Hytale account ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#persistent-authentication) Persistent Authentication After authenticating once, run this command to keep your server authenticated after restarting: > **Security Warning:** Never share your encrypted auth file with anyone! ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#alternative-authenticate-from-code) Alternative: Authenticate from Code If you're unable to run commands from the IDEA terminal, you can authenticate from code: **Important:** Remove this code after your server is authenticated! * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-7-running-the-game-from-idea) Step 7: Running the Game from IDEA -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#using-the-pre-configured-run-configuration) Using the Pre-configured Run Configuration 1. **Select Run Configuration:** * Look for the dropdown in the top-right of IDEA * Select `HytaleServer` 1. **Run or Debug:** * Click the green play button to run * Click the bug button to debug with breakpoints 1. **Server Starts:** * Hytale server will start with your plugin loaded * Default assets from the game will be loaded into the `./run` folder * You can set breakpoints in your code * Debug console shows plugin output ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#connecting-to-your-local-server) Connecting to Your Local Server Once the server is running: 1. **Launch the standard Hytale client** (not from IDEA) 2. **Connect to Local Server:** * The server should appear automatically * If it doesn't, manually add the IP: `127.0.0.1` 1. **Join the server** to test your plugin * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-8-verifying-the-example-plugin) Step 8: Verifying the Example Plugin ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The template includes an example plugin you can use to verify everything is working: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#test-command) Test Command Run the `/test` command in-game. It will print the name and version of your plugin. > **Note:** This is for demonstration purposes and should be removed before your final release. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#example-recipe) Example Recipe The example plugin includes a recipe that allows you to craft 10 dirt into 1 dirt using the crafting window. This demonstrates how assets can be bundled with your plugin. > **Note:** This example should also be removed before release. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-9-building-your-plugin) Step 9: Building Your Plugin -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To create a shareable JAR file of your plugin: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#build-with-gradle) Build with Gradle **Option 1: Terminal** **Option 2: IDEA Gradle Panel** 1. Open the Gradle panel (right side of IDEA) 2. Navigate to: `Tasks` -> `build` -> `build` 3. Double-click `build` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#output-location) Output Location Your plugin JAR will be located at: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-10-installing-plugins-in-hytale) Step 10: Installing Plugins in Hytale -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#installation-path) Installation Path **Full Path (Windows):** ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#installation-steps) Installation Steps 1. **Create Mods Folder** (if it doesn't exist) 2. **Copy your plugin JAR** into the `Mods/` folder 3. **Launch Hytale** 4. Your plugin will be loaded automatically * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#alternative-ide-support) Alternative IDE Support ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#using-vscode) Using VSCode While VSCode is not officially supported, you can generate launch configurations by running: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#example-plugin-code) Example Plugin Code --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here's a basic plugin structure: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#plugin-development-tips) Plugin Development Tips ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-1.-use-the-logger) 1\. Use the Logger ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-2.-register-event-listeners) 2\. Register Event Listeners ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-3.-access-the-api) 3\. Access the API The template includes Hytale's API in the classpath: * Explore the API through IntelliJ's autocomplete * Check the example code included in the template * Browse available classes and methods ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-4.-bundle-assets) 4\. Bundle Assets You can include Packs (assets) with your Plugin: * Add assets to `src/main/resources/Common/` and `Server/` * They'll be bundled with your plugin JAR * Editable in-game via the Asset Editor * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#debugging-tips) Debugging Tips ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#breakpoints) Breakpoints 1. Click in the left margin next to a line number 2. A red dot appears indicating a breakpoint 3. Run in Debug mode (bug icon) 4. Execution pauses at breakpoints ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#console-output) Console Output * Plugin logs appear in the IDEA console * Use `getLogger()` for clean output * Check for error stack traces ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#hot-reload) Hot Reload * Some changes can be reloaded without restarting * Rebuild the project (`Ctrl+F9`) * Major changes require a full restart * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#gradle-sync-fails) Gradle sync fails * Check internet connection (downloads dependencies) * Verify Java 25 is properly installed * Try: `./gradlew clean build` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#hytaleserver-run-config-missing) HytaleServer run config missing * Re-import Gradle project * Check `build.gradle` for run configuration setup * Open the run configuration dropdown or click "Edit Configurations..." to unhide it ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#plugin-doesnt-load) Plugin doesn't load * Verify `manifest.json` is correct (especially the `Main` property) * Check logs for error messages * Ensure plugin JAR is in correct Mods folder * Confirm Hytale version compatibility ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#cannot-connect-to-local-server) Cannot connect to local server * Ensure you've authenticated the server with `auth login device` * Verify the server is running (check IDEA console) * Try manually adding IP: `127.0.0.1` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#breakpoints-dont-work) Breakpoints don't work * Ensure you're running in Debug mode (bug icon) * Verify breakpoint is in executed code * Check that source code matches compiled JAR * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#getting-help) Getting Help ------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousBlockbench Modeling Guidechevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide) [NextExample Command to Show Titlechevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#overview) * [Prerequisites](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#prerequisites) * [Step 1: Download the IDEA Template](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-1-download-the-idea-template) * [Plugin Template:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#plugin-template) * [Template Features:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#template-features) * [Step 2: Configure the Template Before Importing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-2-configure-the-template-before-importing) * [2.1 Extract the Template](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-2.1-extract-the-template) * [2.2 Configure Project Files](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-2.2-configure-project-files) * [Step 3: Import the Project into IDEA](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-3-import-the-project-into-idea) * [Step 4: Configure Java 25 SDK](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-4-configure-java-25-sdk) * [Step 5: Understanding the Project Structure](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-5-understanding-the-project-structure) * [Step 6: Authenticating Your Test Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-6-authenticating-your-test-server) * [Initial Authentication](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#initial-authentication) * [Persistent Authentication](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#persistent-authentication) * [Alternative: Authenticate from Code](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#alternative-authenticate-from-code) * [Step 7: Running the Game from IDEA](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-7-running-the-game-from-idea) * [Using the Pre-configured Run Configuration](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#using-the-pre-configured-run-configuration) * [Connecting to Your Local Server](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#connecting-to-your-local-server) * [Step 8: Verifying the Example Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-8-verifying-the-example-plugin) * [Test Command](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#test-command) * [Example Recipe](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#example-recipe) * [Step 9: Building Your Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-9-building-your-plugin) * [Build with Gradle](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#build-with-gradle) * [Output Location](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#output-location) * [Step 10: Installing Plugins in Hytale](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#step-10-installing-plugins-in-hytale) * [Installation Path](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#installation-path) * [Installation Steps](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#installation-steps) * [Alternative IDE Support](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#alternative-ide-support) * [Using VSCode](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#using-vscode) * [Example Plugin Code](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#example-plugin-code) * [Plugin Development Tips](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#plugin-development-tips) * [1\. Use the Logger](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-1.-use-the-logger) * [2\. Register Event Listeners](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-2.-register-event-listeners) * [3\. Access the API](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-3.-access-the-api) * [4\. Bundle Assets](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#id-4.-bundle-assets) * [Debugging Tips](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#debugging-tips) * [Breakpoints](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#breakpoints) * [Console Output](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#console-output) * [Hot Reload](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#hot-reload) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#troubleshooting) * [Gradle sync fails](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#gradle-sync-fails) * [HytaleServer run config missing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#hytaleserver-run-config-missing) * [Plugin doesn't load](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#plugin-doesnt-load) * [Cannot connect to local server](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#cannot-connect-to-local-server) * [Breakpoints don't work](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#breakpoints-dont-work) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins#getting-help) sun-brightdesktopmoon Copy rootProject.name = 'your-plugin-name' Copy # Change maven_group to match your project maven_group = com.yourname # Update version before making new releases version = 1.0.0 # ... other properties Copy { "Group": "com.yourname", "Name": "YourPluginName", "Main": "com.yourname.yourplugin.YourPlugin", "Version": "1.0.0", "Description": "Description of your plugin", "Authors": [\ {\ "Name": "Your Name",\ "Email": "your.email@example.com",\ "Url": "https://your-website.com"\ }\ ], "Website": "https://your-plugin-website.com", "ServerVersion": "*", "Dependencies": {}, "OptionalDependencies": {}, "DisabledByDefault": false } Copy your-plugin-name/ |-- src/ | `-- main/ | |-- java/ | | `-- com/ | | `-- yourname/ | | `-- yourplugin/ | | `-- YourPlugin.java | `-- resources/ | |-- manifest.json | |-- Common/ # Assets (models, textures) | `-- Server/ # Server-side data |-- build.gradle |-- settings.gradle |-- gradle.properties |-- README.md `-- run/ # Generated when you run the server Copy auth login device Copy auth persistence Encrypted Copy @Override protected void start() { CommandManager.get().handleCommand(ConsoleSender.INSTANCE, "auth login device"); } Copy ./gradlew build Copy build/libs/your-plugin-name-1.0.0.jar Copy %appdata%/Hytale/UserData/Mods/ Copy C:\Users\YourUsername\AppData\Roaming\Hytale\UserData\Mods\ Copy ./gradlew generateVSCodeLaunch Copy package com.yourname.yourplugin; import com.hypixel.hytale.plugin.JavaPlugin; import com.hypixel.hytale.plugin.JavaPluginInit; import javax.annotation.Nonnull; public class YourPlugin extends JavaPlugin { public YourPlugin(@Nonnull JavaPluginInit init) { super(init); // Plugin initialization code getLogger().info("YourPlugin has been loaded!"); } @Override public void onEnable() { // Called when plugin is enabled getLogger().info("YourPlugin enabled!"); } @Override public void onDisable() { // Called when plugin is disabled getLogger().info("YourPlugin disabled!"); } } Copy getLogger().info("Information message"); getLogger().warn("Warning message"); getLogger().error("Error message"); Copy getServer().getPluginManager().registerEvents(new MyListener(), this); sun-brightdesktopmoon --- # Blockbench Modeling Guide | Hytale Modding Documentation **Source:** [An Introduction to Making Models for Hytalearrow-up-right](https://hytale.com/news/2025/12/an-introduction-to-making-models-for-hytale) **Last Modified:** Friday, January 10, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#introduction) Introduction -------------------------------------------------------------------------------------------------------------------------------------------------------------- This guide covers the official Hytale art style and best practices for creating models using Blockbench. Written by Thomas Frick (Art Director), this represents a decade of art direction for Hytale. > **Note:** _"These are best practices; you don't have to follow them strictly. You are the masters of your own craft, and there is no good or bad way to create as long as you are having fun."_ * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#hytale-art-style) Hytale Art Style ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#definition) Definition **"A modern, stylized voxel game, with retro pixel-art textures"** Hytale's art style combines: * Modern game engine capabilities * Charm of old-school pixel art * Intersection of low-definition pixel art and hand-painted 3D * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#the-four-art-pillars) The Four Art Pillars ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Every piece of content in Hytale is evaluated against these core pillars: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-1.-immersive) 1\. Immersive * World feels alive, digital nature vanishes * Motion and detail everywhere * Wind blows in leaves, creatures wander, clouds travel * World reacts to the player * Creatures interact, eyes express emotion * Lasting impression on players' memories ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-2.-fantasy) 2\. Fantasy * Deeply fantasy but not limited to medieval * Art style remains consistent across universes and themes * Each character has unique personality and twist * Popular archetypes are reimagined ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-3.-stylized) 3\. Stylized * Iconic and easily identifiable proportions * Carefully selected color palette * Players can read the world regardless of clutter * **Simplicity is key** - doesn't mean low quality * Takes many iterations to achieve consistency ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-4.-flexible) 4\. Flexible * Composed of primitive shapes (cubes and quads) * Easy to understand how models are made * Technical structure is simple to comprehend and iterate * **Empowering user creativity** - true goal of Hytale * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#getting-started) Getting Started -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#download-required-tools) Download Required Tools 1. **Blockbench** - [blockbench.netarrow-up-right](https://www.blockbench.net/) 2. **Hytale Blockbench Plugin** - [Hytale Pluginarrow-up-right](https://www.blockbench.net/plugins/hytale_plugin) 3. **Plugin Source Code** - [GitHubarrow-up-right](https://github.com/JannisX11/hytale-blockbench-plugin) > **Important:** The Blockbench plugin is in Early Access. You might encounter bugs, but it will continue to improve. **Plugin Features:** * Maintains consistent pixel ratio across textures * Exports models and animations in correct format * Quality-of-life improvements * Tailored to Hytale engine needs * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#geometry-constraints) Geometry Constraints ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#primitives) Primitives Hytale models use **only 2 primitives:** 1. **Cubes** (6 sides) 2. **Quads** (2 sides) **Not Allowed:** * ❌ Edge loops * ❌ Special topology * ❌ Triangles * ❌ Pyramids * ❌ Other traditional modeling shapes * ❌ **No spheres allowed!** **Benefits:** * Easy to make, unwrap, and animate * No weight painting required * No rigging required * No 3D art degree required to start * Blockbench plugin helps maintain simplicity * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#hytale-proportions) Hytale Proportions -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#character-bodies) Character Bodies * **Not realistic** - small, bulky, and cartoony * Supports chunky style used throughout the game * Blocks and furniture are "toylike" * Pure and iconic shapes ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#bone-naming-convention) Bone Naming Convention * Bones must be properly named for animation system * Once bones are correctly named, they animate in-game automatically * Refer to official player hierarchy for examples * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#triangle-count-polygon-budget) Triangle Count (Polygon Budget) -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#philosophy) Philosophy * Work as simply as possible * Increase geometry only when needed to improve silhouette * Stylistic choice + performance reasons ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#performance-context) Performance Context * Hytale renders **several thousand blocks and voxels simultaneously** * Results in **several million triangles per frame** * Triangles are major contributor to FPS loss ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#optimization-requirements) Optimization Requirements * Artists must ensure models are **highly optimized** * Minimize impact on GPU * Every triangle counts * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texture-size-and-density) Texture Size and Density -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texture-requirements) Texture Requirements * **Non-square textures allowed** * Must be **multiples of 32px** (32, 64, 96, 128, etc.) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texel-density-options) Texel Density Options You have **two options** when modeling: #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#option-1-character-attachment) Option 1: Character/Attachment * **Density:** 64px per unit * **Use For:** * Characters * Cosmetics * Tools * Weapons * Food items #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#option-2-prop-block) Option 2: Prop/Block * **Density:** 32px per unit * **Use For:** * Cubes * Furniture * Props * Any non-character objects ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#why-higher-density-for-characters) Why Higher Density for Characters? **Reasons for 64px density:** 1. **Emotion Conveyance** - Details on skin, tattoos, makeup, eye/mouth motion 2. **Close-Up Viewing** - Faces seen very close, especially in first-person 3. **Scene Readability** - Characters detach from environment, attract player's eyes 4. **Cosmetic Details** - More options for logos, materials, textures, ornaments 5. **First-Person Immersion** - Hand/weapon/tool looks better close to camera > **Note:** Many avatar customization features will unlock progressively during Early Access. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#stretching-geometry) Stretching Geometry ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#when-to-use-stretching) When to Use Stretching * Fine adjustments (e.g., avoid Z-fighting when geometry overlaps) * Slightly resize something * Work around pixel density limitations ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#stretching-limits) Stretching Limits * **Avoid:** Going under **0.7X** or over **1.3X** stretch on one axis * Beyond these limits, pixel stretching becomes obvious * Use sparingly and carefully * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texturing-brushes) Texturing Brushes ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#recommended-brushes) Recommended Brushes You don't need many special brushes! Use any painting software: * Photoshop * GIMP * Clip Studio * Affinity * Krita * Blockbench * Procreate **Two Simple Brushes:** 1. **Pencil Brush** * Opacity on for details * Use for color-blocking 2. **Round Soft Brush** * Opacity pressure on * For softening surfaces and creating volume * Use for smoothing and shading 3. **Opacity Pencil** * For polish and final details ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texturing-philosophy) Texturing Philosophy * Treat each texture as an **"illustration"** * Paint/bake shadows, ambient occlusion, and highlights directly into texture * Simulate more complex lighting than exists in-game * Create illusion of detail * **Avoid:** * Noise * Too much grain * Perfectly flat surfaces * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#color-picking-guidelines) Color Picking Guidelines -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#color-theory-rules) Color Theory Rules **Do:** * ✅ Add color in shadows (hint of purple makes models vibrant) * ✅ Use nuanced, saturated shadows * ✅ Test colors in-game once available **Don't:** * ❌ Use pure white (#FFFFFF) * ❌ Use pure black (#000000) * ❌ Create purely desaturated shadows **Why Avoid Pure White/Black:** * Breaks lighting in-game * Adds too much contrast * Ruins value balance * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#shading-mode-and-materials) Shading Mode and Materials ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#character-models) Character Models * **Recommendation:** Disable side shadows in Blockbench * Avoids hard edge effect on body * Better for simulating curvy organic volumes ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#in-game-materials) In-Game Materials * Tight set of material types (shading modes) * Performance and style reasons * Blockbench can't display shading modes yet * Can set and export shading modes for each node * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#hytale-renderer) Hytale Renderer -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#rendering-approach) Rendering Approach * **Not using PBR workflows** (no roughness, normal maps, displacement) * Tailored to elevate unique art style * Avoids effects that damage handcrafted texture style ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#rendering-features) Rendering Features * Paint lights and shadows inside textures * Real lights/shadows bring everything together * In-house light propagation techniques * Selective shaders and post-processing: * Bloom * Depth of Field * Ambient Occlusion (SSAO) * Shadowmap * Fog ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#quality-standard) Quality Standard * Models should look good **without any effects** * Effects are "cherry on top" * Makes Hytale feel cozy and vibrant ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#future-rendering-features) Future Rendering Features * Light propagation improvements * Colorimetry and gamma features * Color grading control * Godrays * Transparent glass * Many other surprises * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#official-tutorial-videos) Official Tutorial Videos -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Magma Golem Tutorial** by Thomas Frick (Art Director) * Concepting process * Modeling workflow * Available on official Hytale channels **Download Official Models:** * [Hytale Model Examples.ziparrow-up-right](https://cdn.hytale.com/Hytale%20Model%20Examples.zip) * Includes selection of official models for study and tinkering * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#best-practices-summary) Best Practices Summary ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#geometry) Geometry 1. Use only cubes and quads 2. Keep triangle count low 3. Optimize for performance 4. No spheres! ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#textures) Textures 1. Multiples of 32px only 2. Choose correct density (64px for characters, 32px for props) 3. Avoid pure white and pure black 4. Paint shadows and highlights into texture 5. Add color to shadows ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#workflow) Workflow 1. Start simple 2. Iterate to improve silhouette 3. Test in-game when possible 4. Follow art pillars (Immersive, Fantasy, Stylized, Flexible) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#character-models-1) Character Models 1. Name bones correctly for animation 2. Use 64px density 3. Disable side shadows in Blockbench 4. Keep proportions cartoony and bulky * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#common-mistakes-to-avoid) Common Mistakes to Avoid -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ❌ **Using too many triangles** - Impacts performance significantly ❌ **Pure white/black colors** - Breaks in-game lighting ❌ **Stretching beyond 0.7X-1.3X** - Obvious pixel distortion ❌ **Wrong texture density** - Inconsistent with game style ❌ **Complex topology** - Keep it simple with cubes and quads ❌ **Flat, noisy textures** - Add volume and avoid grain ❌ **Spheres** - Not supported! * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#learning-resources) Learning Resources -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#official) Official * **Blockbench Plugin** - Essential tool * **Model Examples** - Download from official site * **Tutorial Videos** - Art Director's workflow * **Official Blog** - Latest art direction updates ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#community) Community * **Discord** - [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Share Your Work** - Get feedback from community * **Learn from Others** - Study community creations * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#getting-started-checklist) Getting Started Checklist ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Download Blockbench * Install Hytale Blockbench Plugin * Download official model examples * Study art pillars * Practice with simple models * Choose correct texture density * Keep geometry simple (cubes and quads only) * Avoid pure white and black * Test stretching limits * Share with community for feedback * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#future-updates) Future Updates ------------------------------------------------------------------------------------------------------------------------------------------------------------------ The Hytale art team will share more about: * Advanced modeling techniques * Animation workflows * VFX creation * UI art Stay tuned for more comprehensive guides! * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#closing-words) Closing Words ---------------------------------------------------------------------------------------------------------------------------------------------------------------- > _"The Hytale art team's role is also to support the community by sharing our creative vision, our tools, and good practices, so you, whether you are an advanced creator or simply curious, can take the leap and have everything you need to dive into making beautiful models!"_ - Thomas Frick (Art Director) * * * **Related:** [Block Animations](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations) | [Useful Tools & Links](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#getting-help) Getting Help -------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousBlock Animationschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/06-block-animations) [NextGetting Started with Pluginschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins) Last updated 2 days ago * [Introduction](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#introduction) * [Hytale Art Style](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#hytale-art-style) * [Definition](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#definition) * [The Four Art Pillars](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#the-four-art-pillars) * [1\. Immersive](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-1.-immersive) * [2\. Fantasy](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-2.-fantasy) * [3\. Stylized](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-3.-stylized) * [4\. Flexible](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#id-4.-flexible) * [Getting Started](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#getting-started) * [Download Required Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#download-required-tools) * [Geometry Constraints](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#geometry-constraints) * [Primitives](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#primitives) * [Hytale Proportions](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#hytale-proportions) * [Character Bodies](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#character-bodies) * [Bone Naming Convention](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#bone-naming-convention) * [Triangle Count (Polygon Budget)](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#triangle-count-polygon-budget) * [Philosophy](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#philosophy) * [Performance Context](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#performance-context) * [Optimization Requirements](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#optimization-requirements) * [Texture Size and Density](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texture-size-and-density) * [Texture Requirements](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texture-requirements) * [Texel Density Options](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texel-density-options) * [Why Higher Density for Characters?](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#why-higher-density-for-characters) * [Stretching Geometry](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#stretching-geometry) * [When to Use Stretching](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#when-to-use-stretching) * [Stretching Limits](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#stretching-limits) * [Texturing Brushes](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texturing-brushes) * [Recommended Brushes](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#recommended-brushes) * [Texturing Philosophy](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#texturing-philosophy) * [Color Picking Guidelines](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#color-picking-guidelines) * [Color Theory Rules](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#color-theory-rules) * [Shading Mode and Materials](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#shading-mode-and-materials) * [Character Models](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#character-models) * [In-Game Materials](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#in-game-materials) * [Hytale Renderer](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#hytale-renderer) * [Rendering Approach](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#rendering-approach) * [Rendering Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#rendering-features) * [Quality Standard](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#quality-standard) * [Future Rendering Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#future-rendering-features) * [Official Tutorial Videos](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#official-tutorial-videos) * [Best Practices Summary](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#best-practices-summary) * [Geometry](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#geometry) * [Textures](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#textures) * [Workflow](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#workflow) * [Character Models](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#character-models-1) * [Common Mistakes to Avoid](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#common-mistakes-to-avoid) * [Learning Resources](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#learning-resources) * [Official](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#official) * [Community](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#community) * [Getting Started Checklist](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#getting-started-checklist) * [Future Updates](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#future-updates) * [Closing Words](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#closing-words) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/packs-content-creation/17-blockbench-modeling-guide#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Custom Config Files | Hytale Modding Documentation **Source:** [Custom Config Filesarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 9, 2026 at 12:01 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#overview) Overview -------------------------------------------------------------------------------------------------------------------------------------------------- This guide details how to create and register custom configuration files for your Hytale plugins using the server's **Codec system**. Configuration files allow users to customize your plugin's behavior without modifying code. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#what-are-config-files) What are Config Files? ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Configuration files: * Store plugin settings in JSON format * Allow users to customize plugin behavior * Persist across game sessions * Use Hytale's Codec system for serialization/deserialization * Auto-generate with default values if missing * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#understanding-the-codec-system) Understanding the Codec System ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Hytale uses **Codecs** to serialize (save) and deserialize (load) data: * **Codec:** Defines how data is converted to/from JSON * **BuilderCodec:** Fluent API for building complex codecs * **KeyedCodec:** Maps a JSON key to a Java field * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#step-1-create-the-config-class) Step 1: Create the Config Class ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The configuration class acts as a data model that defines: * Variables to be saved in JSON * How they are serialized/deserialized * Default values ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#basic-config-class-example) Basic Config Class Example: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#understanding-the-codec-builder) Understanding the Codec Builder ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Let's break down the codec definition: * **First parameter:** The config class type * **Second parameter:** Constructor reference (how to create new instances) * **KeyedCodec:** Maps JSON key to field * `"LuckIncreaseChance"` - JSON key name * `Codec.DOUBLE` - Data type codec * **Setter lambda:** How to set the value when loading * **Getter lambda:** How to get the value when saving * **add():** Finalizes the current field * **build():** Completes the codec * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#step-2-register-in-main-plugin) Step 2: Register in Main Plugin ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- For the server to recognize and load the configuration file, register it during plugin initialization: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#configuration-file-location) Configuration File Location: The config file will be generated at: **Format:** `{Group}_{Name}/{ConfigName}.example.json` Where: * `Group` and `Name` come from your plugin's `manifest.json` * `ConfigName` is the first parameter to `withConfig()` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#multiple-configuration-values) Multiple Configuration Values -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can add multiple fields to your config: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#common-codec-types) Common Codec Types ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Java Type Codec Example Value `Double` `Codec.DOUBLE` `0.40` `Integer` `Codec.INT` `100` `String` `Codec.STRING` `"Hello"` `Boolean` `Codec.BOOL` `true` `Long` `Codec.LONG` `1000000L` `Float` `Codec.FLOAT` `1.5f` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#generated-json-file-example) Generated JSON File Example ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- When your plugin runs, it generates a JSON file like this: Users can edit this file to customize settings, and changes take effect on plugin reload or server restart. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#accessing-config-values) Accessing Config Values -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#in-your-plugin-class) In Your Plugin Class: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#from-other-classes) From Other Classes: Pass the config or specific values as parameters: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#advanced-list-array-configurations) Advanced: List/Array Configurations ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- For more complex configs with lists or objects, you can use advanced codecs: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#config-reload) Config Reload ------------------------------------------------------------------------------------------------------------------------------------------------------------ If you want to support config reloading without restarting: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#best-practices) Best Practices -------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-1.-use-sensible-defaults) 1\. Use Sensible Defaults ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-2.-document-your-config) 2\. Document Your Config Add comments in your code explaining what each setting does: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-3.-validate-values) 3\. Validate Values ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-4.-provide-examples) 4\. Provide Examples Include an example config in your documentation showing all available options. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#config-file-not-generated) Config file not generated: * Verify `withConfig()` is called in plugin constructor * Check plugin manifest is correct * Ensure plugin loads successfully (check logs) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#values-not-loading) Values not loading: * Verify JSON syntax is valid * Check key names match exactly (case-sensitive) * Ensure data types match codec definitions ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#changes-not-taking-effect) Changes not taking effect: * Restart the server after editing config * If using reload, ensure reload method is properly implemented * Check for cached values ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#default-values-not-working) Default values not working: * Verify field initialization: `private double value = 0.40;` * Check constructor doesn't override defaults * Ensure codec is built correctly * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#complete-example) Complete Example ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Here's a full working example: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#getting-help) Getting Help ---------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousExample Command to Show Titlechevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/11-example-command-show-title) [NextCommon Plugin Featureschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features) Last updated 1 day ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#overview) * [What are Config Files?](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#what-are-config-files) * [Understanding the Codec System](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#understanding-the-codec-system) * [Step 1: Create the Config Class](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#step-1-create-the-config-class) * [Basic Config Class Example:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#basic-config-class-example) * [Understanding the Codec Builder](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#understanding-the-codec-builder) * [Step 2: Register in Main Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#step-2-register-in-main-plugin) * [Configuration File Location:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#configuration-file-location) * [Multiple Configuration Values](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#multiple-configuration-values) * [Common Codec Types](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#common-codec-types) * [Generated JSON File Example](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#generated-json-file-example) * [Accessing Config Values](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#accessing-config-values) * [In Your Plugin Class:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#in-your-plugin-class) * [From Other Classes:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#from-other-classes) * [Advanced: List/Array Configurations](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#advanced-list-array-configurations) * [Config Reload](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#config-reload) * [Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#best-practices) * [1\. Use Sensible Defaults](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-1.-use-sensible-defaults) * [2\. Document Your Config](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-2.-document-your-config) * [3\. Validate Values](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-3.-validate-values) * [4\. Provide Examples](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#id-4.-provide-examples) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#troubleshooting) * [Config file not generated:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#config-file-not-generated) * [Values not loading:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#values-not-loading) * [Changes not taking effect:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#changes-not-taking-effect) * [Default values not working:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#default-values-not-working) * [Complete Example](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#complete-example) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files#getting-help) sun-brightdesktopmoon Copy public class ExampleConfig { // 1. Codec definition for serialization/deserialization public static final BuilderCodec CODEC = BuilderCodec.builder(ExampleConfig.class, ExampleConfig::new) .append(new KeyedCodec("LuckIncreaseChance", Codec.DOUBLE), (exConfig, aDouble, extraInfo) -> exConfig.LuckIncreaseChance = aDouble, // Setter (exConfig, extraInfo) -> exConfig.LuckIncreaseChance) // Getter .add() .build(); // 2. Configuration variable with default value private double LuckIncreaseChance = 0.40; // 3. Constructor public ExampleConfig() { } // 4. Getter method (optional but recommended) public double getLuckIncreaseChance() { return LuckIncreaseChance; } } Copy BuilderCodec.builder(ExampleConfig.class, ExampleConfig::new) Copy .append(new KeyedCodec("LuckIncreaseChance", Codec.DOUBLE), (exConfig, aDouble, extraInfo) -> exConfig.LuckIncreaseChance = aDouble, // Setter (exConfig, extraInfo) -> exConfig.LuckIncreaseChance) // Getter Copy .add() .build(); Copy public class ExamplePlugin extends JavaPlugin { private final Config config; public ExamplePlugin(@Nonnull JavaPluginInit init) { super(init); // Registers the configuration with the filename "ExamplePlugin" this.config = this.withConfig("ExamplePlugin", ExampleConfig.CODEC); } // Access config values public double getLuckChance() { return this.config.get().getLuckIncreaseChance(); } } Copy plugins/com.yourgroup_YourPluginName/ExamplePlugin.example.json Copy public class AdvancedConfig { public static final BuilderCodec CODEC = BuilderCodec.builder(AdvancedConfig.class, AdvancedConfig::new) // Double field .append(new KeyedCodec("LuckIncreaseChance", Codec.DOUBLE), (config, value, info) -> config.luckIncreaseChance = value, (config, info) -> config.luckIncreaseChance) .add() // Integer field .append(new KeyedCodec("MaxPlayers", Codec.INT), (config, value, info) -> config.maxPlayers = value, (config, info) -> config.maxPlayers) .add() // String field .append(new KeyedCodec("ServerMessage", Codec.STRING), (config, value, info) -> config.serverMessage = value, (config, info) -> config.serverMessage) .add() // Boolean field .append(new KeyedCodec("EnableFeature", Codec.BOOL), (config, value, info) -> config.enableFeature = value, (config, info) -> config.enableFeature) .add() .build(); private double luckIncreaseChance = 0.40; private int maxPlayers = 100; private String serverMessage = "Welcome!"; private boolean enableFeature = true; public AdvancedConfig() { } // Getters public double getLuckIncreaseChance() { return luckIncreaseChance; } public int getMaxPlayers() { return maxPlayers; } public String getServerMessage() { return serverMessage; } public boolean isEnableFeature() { return enableFeature; } } Copy { "LuckIncreaseChance": 0.40, "MaxPlayers": 100, "ServerMessage": "Welcome!", "EnableFeature": true } Copy public class ExamplePlugin extends JavaPlugin { private final Config config; public ExamplePlugin(@Nonnull JavaPluginInit init) { super(init); this.config = this.withConfig("ExamplePlugin", ExampleConfig.CODEC); } public void someMethod() { // Access config value double luckChance = this.config.get().getLuckIncreaseChance(); // Use the value if (Math.random() < luckChance) { getLogger().info("Lucky event triggered!"); } } } Copy public class FeatureManager { private final double luckChance; public FeatureManager(double luckChance) { this.luckChance = luckChance; } public void checkLuck() { if (Math.random() < luckChance) { // Do something lucky } } } Copy // In your plugin FeatureManager manager = new FeatureManager( this.config.get().getLuckIncreaseChance() ); Copy // Example: List of strings .append(new KeyedCodec>("AllowedItems", Codec.STRING.listOf()), (config, value, info) -> config.allowedItems = value, (config, info) -> config.allowedItems) .add() Copy public void reloadConfig() { // The config automatically reloads from file getLogger().info("Config reloaded!"); // Access new values double newChance = this.config.get().getLuckIncreaseChance(); getLogger().info("New luck chance: " + newChance); } Copy private double luckIncreaseChance = 0.40; // 40% - balanced default Copy // Percentage chance (0.0 to 1.0) for luck increase events private double luckIncreaseChance = 0.40; Copy public double getLuckIncreaseChance() { // Ensure value is between 0 and 1 return Math.max(0.0, Math.min(1.0, luckIncreaseChance)); } Copy // Config class public class MyPluginConfig { public static final BuilderCodec CODEC = BuilderCodec.builder(MyPluginConfig.class, MyPluginConfig::new) .append(new KeyedCodec("DropRateMultiplier", Codec.DOUBLE), (cfg, val, info) -> cfg.dropRateMultiplier = val, (cfg, info) -> cfg.dropRateMultiplier) .add() .append(new KeyedCodec("EnableDebugMode", Codec.BOOL), (cfg, val, info) -> cfg.enableDebugMode = val, (cfg, info) -> cfg.enableDebugMode) .add() .build(); private double dropRateMultiplier = 1.0; private boolean enableDebugMode = false; public MyPluginConfig() { } public double getDropRateMultiplier() { return dropRateMultiplier; } public boolean isDebugMode() { return enableDebugMode; } } // Plugin class public class MyPlugin extends JavaPlugin { private final Config config; public MyPlugin(@Nonnull JavaPluginInit init) { super(init); this.config = this.withConfig("MyPlugin", MyPluginConfig.CODEC); // Log loaded values getLogger().info("Drop rate multiplier: " + config.get().getDropRateMultiplier()); getLogger().info("Debug mode: " + config.get().isDebugMode()); } } sun-brightdesktopmoon --- # Gradle Automation & Testing | Hytale Modding Documentation **Last Modified:** Friday, January 10, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#overview) Overview -------------------------------------------------------------------------------------------------------------------------------------------------------- This guide covers advanced Gradle automation techniques for Hytale plugin development, including creating custom Gradle tasks for automated server testing and streamlined development workflows. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#custom-gradle-plugin-for-server-testing) Custom Gradle Plugin for Server Testing ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- One of the most time-consuming parts of plugin development is manually: 1. Building your plugin 2. Copying it to the server's plugins folder 3. Starting the server 4. Testing your changes You can automate this entire workflow with a custom Gradle plugin! * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#creating-a-custom-gradle-plugin) Creating a Custom Gradle Plugin ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#project-structure) Project Structure ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-1-create-buildsrc-directory) Step 1: Create buildSrc Directory The `buildSrc/` directory is a special Gradle convention for custom build logic. Create `buildSrc/build.gradle.kts`: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-2-create-the-custom-plugin) Step 2: Create the Custom Plugin Create `buildSrc/src/main/kotlin/RunHytalePlugin.kt`: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-3-apply-the-plugin) Step 3: Apply the Plugin In your main `build.gradle.kts`: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-4-use-the-task) Step 4: Use the Task * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#how-it-works) How It Works ---------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-1.-smart-caching) 1\. **Smart Caching** * Downloads server JAR only once * Uses SHA-256 hash of URL as cache key * Subsequent runs use cached version ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-2.-automatic-build) 2\. **Automatic Build** * Depends on `shadowJar` task * Builds your plugin before running * Copies fresh plugin JAR to server ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-3.-interactive-console) 3\. **Interactive Console** * Forwards server output to your terminal * Allows typing commands directly * Handles Ctrl+C gracefully ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-4.-clean-workspace) 4\. **Clean Workspace** * Server runs in `run/` directory * Keeps your project root clean * Easy to delete and reset * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#advanced-gradle-tasks) Advanced Gradle Tasks ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#auto-reload-development-task) Auto-Reload Development Task Create a task that watches for changes and auto-reloads: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#quick-test-task) Quick Test Task Create a task for quick compilation checks: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#gradle-build-optimizations) Gradle Build Optimizations -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#enable-gradle-daemon) Enable Gradle Daemon Add to `gradle.properties`: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#optimize-shadowjar-task) Optimize ShadowJar Task * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#multi-environment-testing) Multi-Environment Testing ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#test-against-multiple-server-versions) Test Against Multiple Server Versions * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#continuous-integration) Continuous Integration ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#github-actions-workflow) GitHub Actions Workflow Create `.github/workflows/build.yml`: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#debugging-with-gradle) Debugging with Gradle ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#enable-debug-mode) Enable Debug Mode ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#remote-debugging) Remote Debugging Modify the RunServerTask to support remote debugging: Usage: Then connect your IDE debugger to `localhost:5005`. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#best-practices) Best Practices -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-1.-version-control) 1\. **Version Control** ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-2.-clean-task) 2\. **Clean Task** ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-3.-dependency-management) 3\. **Dependency Management** * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#common-issues) Common Issues **Issue: Server JAR not downloading** **Issue: Plugin not copying** **Issue: Server not starting** * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#summary) Summary ------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#benefits-of-gradle-automation) Benefits of Gradle Automation: * **Faster Development**: One command to build, deploy, and test * **Consistency**: Same environment every time * **Efficiency**: Smart caching saves time * **Professional**: Industry-standard build automation ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#key-tasks-created) Key Tasks Created: 1. `runServer` - Build and run server with plugin 2. `quickTest` - Fast compilation checks 3. `cleanRun` - Clean test environment 4. `runServer-{version}` - Test multiple versions * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#next-steps) Next Steps ------------------------------------------------------------------------------------------------------------------------------------------------------------ * Customize the RunHytalePlugin for your workflow * Add more automated checks (linting, formatting) * Set up CI/CD pipeline * Create release automation * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#getting-help) Getting Help ---------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousAdvanced Plugin Patternschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns) [NextBootstrap/Early Pluginschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#overview) * [Custom Gradle Plugin for Server Testing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#custom-gradle-plugin-for-server-testing) * [Creating a Custom Gradle Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#creating-a-custom-gradle-plugin) * [Project Structure](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#project-structure) * [Step 1: Create buildSrc Directory](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-1-create-buildsrc-directory) * [Step 2: Create the Custom Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-2-create-the-custom-plugin) * [Step 3: Apply the Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-3-apply-the-plugin) * [Step 4: Use the Task](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#step-4-use-the-task) * [How It Works](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#how-it-works) * [1\. Smart Caching](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-1.-smart-caching) * [2\. Automatic Build](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-2.-automatic-build) * [3\. Interactive Console](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-3.-interactive-console) * [4\. Clean Workspace](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-4.-clean-workspace) * [Advanced Gradle Tasks](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#advanced-gradle-tasks) * [Auto-Reload Development Task](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#auto-reload-development-task) * [Quick Test Task](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#quick-test-task) * [Gradle Build Optimizations](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#gradle-build-optimizations) * [Enable Gradle Daemon](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#enable-gradle-daemon) * [Optimize ShadowJar Task](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#optimize-shadowjar-task) * [Multi-Environment Testing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#multi-environment-testing) * [Test Against Multiple Server Versions](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#test-against-multiple-server-versions) * [Continuous Integration](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#continuous-integration) * [GitHub Actions Workflow](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#github-actions-workflow) * [Debugging with Gradle](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#debugging-with-gradle) * [Enable Debug Mode](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#enable-debug-mode) * [Remote Debugging](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#remote-debugging) * [Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#best-practices) * [1\. Version Control](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-1.-version-control) * [2\. Clean Task](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-2.-clean-task) * [3\. Dependency Management](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#id-3.-dependency-management) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#troubleshooting) * [Common Issues](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#common-issues) * [Summary](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#summary) * [Benefits of Gradle Automation:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#benefits-of-gradle-automation) * [Key Tasks Created:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#key-tasks-created) * [Next Steps](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#next-steps) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing#getting-help) sun-brightdesktopmoon Copy your-plugin/ ├── buildSrc/ │ ├── build.gradle.kts │ └── src/ │ └── main/ │ └── kotlin/ │ └── RunHytalePlugin.kt ├── build.gradle.kts └── src/ └── main/ └── java/ Copy plugins { `kotlin-dsl` } repositories { mavenCentral() } Copy import org.gradle.api.DefaultTask import org.gradle.api.Plugin import org.gradle.api.Project import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction import org.gradle.api.tasks.TaskProvider import java.io.File import java.net.URI import java.security.MessageDigest // Main plugin class open class RunHytalePlugin : Plugin { override fun apply(project: Project) { // Create extension for configuration val extension = project.extensions.create( "runHytale", RunHytaleExtension::class.java ) // Register the runServer task val runTask: TaskProvider = project.tasks.register( "runServer", RunServerTask::class.java ) { jarUrl.set(extension.jarUrl) group = "hytale" description = "Downloads and runs the Hytale server with your plugin" } // Make runServer depend on shadowJar (build plugin first) project.tasks.findByName("shadowJar")?.let { runTask.configure { dependsOn(it) } } } } // Extension for configuration open class RunHytaleExtension { var jarUrl: String = "https://example.com/hytale-server.jar" } // The actual task that runs the server open class RunServerTask : DefaultTask() { @Input val jarUrl = project.objects.property(String::class.java) @TaskAction fun run() { // Create directories val runDir = File(project.projectDir, "run").apply { mkdirs() } val pluginsDir = File(runDir, "plugins").apply { mkdirs() } val jarFile = File(runDir, "server.jar") // Cache directory for downloaded server JARs val cacheDir = File( project.layout.buildDirectory.asFile.get(), "hytale-cache" ).apply { mkdirs() } // Compute hash of URL for caching val urlHash = MessageDigest.getInstance("SHA-256") .digest(jarUrl.get().toByteArray()) .joinToString("") { "%02x".format(it) } val cachedJar = File(cacheDir, "$urlHash.jar") // Download server JAR if not cached if (!cachedJar.exists()) { println("Downloading Hytale server from ${jarUrl.get()}") URI.create(jarUrl.get()).toURL().openStream().use { input -> cachedJar.outputStream().use { output -> input.copyTo(output) } } println("Server JAR downloaded and cached") } else { println("Using cached server JAR") } // Copy server JAR to run directory cachedJar.copyTo(jarFile, overwrite = true) // Copy plugin JAR to plugins folder project.tasks.findByName("shadowJar")?.outputs?.files?.firstOrNull()?.let { shadowJar -> val targetFile = File(pluginsDir, shadowJar.name) shadowJar.copyTo(targetFile, overwrite = true) println("Plugin copied to: ${targetFile.absolutePath}") } println("Starting Hytale server...") // Start the server process val process = ProcessBuilder("java", "-jar", jarFile.name) .directory(runDir) .start() // Handle graceful shutdown project.gradle.buildFinished { if (process.isAlive) { println("Stopping server...") process.destroy() } } // Forward stdout to console Thread { process.inputStream.bufferedReader().useLines { lines -> lines.forEach { println(it) } } }.start() // Forward stderr to console Thread { process.errorStream.bufferedReader().useLines { lines -> lines.forEach { System.err.println(it) } } }.start() // Forward stdin to server (for commands) Thread { System.`in`.bufferedReader().useLines { lines -> lines.forEach { process.outputStream.write((it + "\n").toByteArray()) process.outputStream.flush() } } }.start() // Wait for server to exit val exitCode = process.waitFor() println("Server exited with code $exitCode") } } Copy plugins { id("java") id("com.gradleup.shadow") version "9.3.1" id("run-hytale") // Your custom plugin } // Configure the plugin runHytale { jarUrl = "https://example.com/hytale-server.jar" // Replace with actual URL } // Rest of your build configuration... Copy # Build and run server with your plugin ./gradlew runServer # On Windows: gradlew.bat runServer Copy // In buildSrc/src/main/kotlin/DevModeTask.kt import org.gradle.api.DefaultTask import org.gradle.api.tasks.TaskAction import java.nio.file.* open class DevModeTask : DefaultTask() { @TaskAction fun run() { val watchService = FileSystems.getDefault().newWatchService() val srcPath = project.file("src/main/java").toPath() srcPath.register( watchService, StandardWatchEventKinds.ENTRY_MODIFY, StandardWatchEventKinds.ENTRY_CREATE ) println("Watching for changes in src/main/java...") println("Press Ctrl+C to stop") while (true) { val key = watchService.take() for (event in key.pollEvents()) { println("Change detected: ${event.context()}") println("Rebuilding plugin...") // Trigger rebuild project.tasks.findByName("shadowJar")?.actions?.forEach { it.execute(project.tasks.getByName("shadowJar")) } println("Rebuild complete. Copy to server and reload.") } key.reset() } } } Copy tasks.register("quickTest") { group = "verification" description = "Quick compilation and basic checks" dependsOn("compileJava") doLast { println("✓ Compilation successful") println("✓ No syntax errors") // Check manifest exists val manifest = file("src/main/resources/manifest.json") if (manifest.exists()) { println("✓ Manifest file found") } else { throw GradleException("✗ Manifest file missing!") } // Check for common issues val srcDir = file("src/main/java") srcDir.walk().forEach { file -> if (file.extension == "java") { val content = file.readText() // Check for System.out.println (should use logger) if (content.contains("System.out.println")) { println("⚠ Warning: Found System.out.println in ${file.name}") println(" Consider using a logger instead") } } } println("\n✓ Quick test passed!") } } Copy # Enable daemon for faster builds org.gradle.daemon=true # Increase memory for large projects org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m # Enable parallel builds org.gradle.parallel=true # Enable build cache org.gradle.caching=true # Use configuration cache (Gradle 8+) org.gradle.configuration-cache=true Copy tasks.shadowJar { // Minimize JAR size minimize() // Relocate dependencies to avoid conflicts relocate("com.google.gson", "com.yourplugin.libs.gson") // Exclude unnecessary files exclude("META-INF/*.SF") exclude("META-INF/*.DSA") exclude("META-INF/*.RSA") // Set archive name archiveBaseName.set("YourPlugin") archiveClassifier.set("") archiveVersion.set(project.version.toString()) } Copy // In build.gradle.kts val serverVersions = mapOf( "latest" to "https://example.com/hytale-latest.jar", "stable" to "https://example.com/hytale-stable.jar", "beta" to "https://example.com/hytale-beta.jar" ) serverVersions.forEach { (name, url) -> tasks.register("runServer-$name", RunServerTask::class) { group = "hytale" description = "Run server with $name version" jarUrl.set(url) } } // Usage: // ./gradlew runServer-latest // ./gradlew runServer-stable // ./gradlew runServer-beta Copy name: Build Plugin on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up JDK 25 uses: actions/setup-java@v3 with: java-version: '25' distribution: 'temurin' - name: Grant execute permission for gradlew run: chmod +x gradlew - name: Build with Gradle run: ./gradlew build - name: Run tests run: ./gradlew test - name: Upload artifact uses: actions/upload-artifact@v3 with: name: plugin-jar path: build/libs/*.jar Copy # Run with debug output ./gradlew runServer --debug # Run with info output ./gradlew runServer --info # Run with stack traces ./gradlew runServer --stacktrace Copy // Add debug flag val debugMode = project.hasProperty("debug") val javaArgs = mutableListOf("-jar", jarFile.name) if (debugMode) { javaArgs.add(0, "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005") println("Debug mode enabled. Connect debugger to port 5005") } val process = ProcessBuilder("java", *javaArgs.toTypedArray()) .directory(runDir) .start() Copy ./gradlew runServer -Pdebug Copy # .gitignore build/ run/ .gradle/ *.jar !gradle-wrapper.jar Copy tasks.register("cleanRun") { group = "hytale" description = "Clean run directory" doLast { delete("run") println("Run directory cleaned") } } Copy dependencies { // Use compileOnly for server dependencies compileOnly(files("libs/hytale-server.jar")) // Use implementation for bundled dependencies implementation("com.google.code.gson:gson:2.10.1") // Use testImplementation for test dependencies testImplementation("org.junit.jupiter:junit-jupiter:5.10.0") } Copy // Add timeout and retry logic val connection = URI.create(jarUrl.get()).toURL().openConnection() connection.connectTimeout = 30000 connection.readTimeout = 30000 Copy // Verify shadowJar output tasks.shadowJar { doLast { println("Plugin JAR created: ${archiveFile.get().asFile.absolutePath}") } } Copy # Check Java version java -version # Check server JAR is valid java -jar run/server.jar --version sun-brightdesktopmoon --- # Useful Tools & Links | Hytale Modding Documentation **Source:** [Official Hytale Resourcesarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 10, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------ This page provides a curated collection of official tools, community resources, and development utilities for Hytale modding. Whether you're creating Packs, developing Plugins, or designing worlds, these resources will help streamline your workflow. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#official-hytale-tools) Official Hytale Tools -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#blockbench--hytale-plugin) Blockbench + Hytale Plugin **Website:** [https://www.blockbench.netarrow-up-right](https://www.blockbench.net/) **Hytale Plugin:** [https://www.blockbench.net/plugins/hytale\_pluginarrow-up-right](https://www.blockbench.net/plugins/hytale_plugin) **Plugin Source:** [GitHubarrow-up-right](https://github.com/JannisX11/hytale-blockbench-plugin) **Official Guide:** [Making Models for Hytalearrow-up-right](https://hytale.com/news/2025/12/an-introduction-to-making-models-for-hytale) **Description:** The **officially supported** tool for creating Hytale models, textures, and animations. Replaces Hytale's internal modeling tools to support established creative workflows. **Status:** Releasing soon (Early Access) #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#features) Features: * Create Hytale-compatible models, textures, and animations * Maintains consistent pixel ratio across textures * Exports in correct Hytale format * Quality-of-life improvements for Hytale workflow * Texture painting and UV mapping * Real-time preview #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#official-art-style-guidelines) Official Art Style Guidelines: * **Primitives:** Only cubes and quads (no spheres!) * **Texture Density:** 64px/unit for characters, 32px/unit for props/blocks * **Texture Size:** Multiples of 32px (32, 64, 96, 128, etc.) * **Stretching Limits:** 0.7X to 1.3X on any axis * **Colors:** Avoid pure white and pure black * **Triangle Count:** Keep optimized for performance **Official Models:** [Download Examplesarrow-up-right](https://cdn.hytale.com/Hytale%20Model%20Examples.zip) * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#hytale-asset-editor) Hytale Asset Editor **Access:** Built into Hytale (Creation Tools tab) **Official Info:** [Modding Strategyarrow-up-right](https://hytale.com/news/2025/11/hytale-modding-strategy-and-status) **Description:** Visual editor for data assets (JSON files). Supports most asset types with some limitations. **Status:** Available now in Early Access #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#features-1) Features: * Edit data assets visually (no coding required) * Supports blocks, items, and most asset types * Direct integration with Hytale * Live preview of changes * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#asset-graph-editor-node-editor) Asset Graph Editor (Node Editor) **Access:** Built into Hytale (after launch) **Official Info:** [World Generation Blogarrow-up-right](https://hytale.com/news/2026/1/the-future-of-world-generation) **Description:** Node-based editor for complex assets like world generation, NPCs, and creative tool brushes. **Status:** Currently being released #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#features-2) Features: * Visual node-graph interface * Live-reload in-game * Build advanced procedural content by linking simple nodes * Full control over biomes, terrain, props, and materials * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#creative-mode-tools) Creative Mode Tools **Access:** Built into Hytale (Creative Mode) **Official Info:** [Creative Mode Blogarrow-up-right](https://hytale.com/news/2025/11/hytale-creative-mode) **Description:** Interactive suite of in-game tools for world editing and content creation. **Status:** Available in Early Access #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#tools-available) Tools Available: * **Scripted Brushes:** Asset-defined brushes (mountains, paths, ruins) * **Shape Brush:** Paint pyramids, cones, squares, and more * **Selection Tool:** 3D selections, copy, paste, move, rotate * **Paste Tool:** Precise prefab placement * **Ruler Tool:** Measure distances and mark outlines * **Machinima Tool:** Camera animation and recording * **Prefab Browser/Editor:** Browse and edit prefabs * **Player Model Changer:** Become any NPC model * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#development-tools) Development Tools ------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#intellij-idea) IntelliJ IDEA **Website:** [https://www.jetbrains.com/idea/arrow-up-right](https://www.jetbrains.com/idea/) **Description:** The recommended IDE for Java plugin development. **Versions:** * **Community Edition:** Free, sufficient for Hytale plugin development * **Ultimate Edition:** Paid, includes additional features * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#java-development-kit-jdk) Java Development Kit (JDK) **Required Version:** Java 25 **Download:** * **Oracle JDK:** [https://www.oracle.com/java/arrow-up-right](https://www.oracle.com/java/) * **OpenJDK:** [https://openjdk.org/arrow-up-right](https://openjdk.org/) **Note:** Hytale plugins require Java 25 specifically. * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#gradle) Gradle **Website:** [https://gradle.org/arrow-up-right](https://gradle.org/) **Description:** Build automation tool used for compiling and packaging Hytale plugins. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#graphics-and-design-tools) Graphics & Design Tools -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#paint.net) Paint.NET **Website:** [https://www.getpaint.net/arrow-up-right](https://www.getpaint.net/) **Description:** Free image editing software for Windows, perfect for creating textures. * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#gimp) GIMP **Website:** [https://www.gimp.org/arrow-up-right](https://www.gimp.org/) **Description:** Free and open-source image editor, available for all platforms. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#version-control) Version Control -------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#git) Git **Website:** [https://git-scm.com/arrow-up-right](https://git-scm.com/) **Description:** Version control system to track changes in your mod projects. * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#github) GitHub **Website:** [https://github.com/arrow-up-right](https://github.com/) **Description:** Online platform for hosting Git repositories. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#quick-reference-links) Quick Reference Links -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Tool Type Link Cost Blockbench 3D Modeling [blockbench.netarrow-up-right](https://www.blockbench.net/) Free IntelliJ IDEA IDE [jetbrains.com/ideaarrow-up-right](https://www.jetbrains.com/idea/) Free/Paid Java 25 JDK Runtime [oracle.com/javaarrow-up-right](https://www.oracle.com/java/) Free Paint.NET Textures [getpaint.netarrow-up-right](https://www.getpaint.net/) Free GIMP Textures [gimp.orgarrow-up-right](https://www.gimp.org/) Free Git Version Control [git-scm.comarrow-up-right](https://git-scm.com/) Free GitHub Hosting [github.comarrow-up-right](https://github.com/) Free VS Code Editor [code.visualstudio.comarrow-up-right](https://code.visualstudio.com/) Free * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#getting-help) Getting Help -------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousPlugin Project Templatechevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template) [NextWorld Generation Moddingchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#overview) * [Official Hytale Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#official-hytale-tools) * [Blockbench + Hytale Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#blockbench--hytale-plugin) * [Hytale Asset Editor](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#hytale-asset-editor) * [Asset Graph Editor (Node Editor)](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#asset-graph-editor-node-editor) * [Creative Mode Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#creative-mode-tools) * [Development Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#development-tools) * [IntelliJ IDEA](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#intellij-idea) * [Java Development Kit (JDK)](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#java-development-kit-jdk) * [Gradle](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#gradle) * [Graphics & Design Tools](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#graphics-and-design-tools) * [Paint.NET](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#paint.net) * [GIMP](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#gimp) * [Version Control](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#version-control) * [Git](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#git) * [GitHub](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#github) * [Quick Reference Links](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#quick-reference-links) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Bootstrap/Early Plugins | Hytale Modding Documentation **Source:** [Bootstrap/Early Pluginsarrow-up-right](https://hytale.com/) **Last Modified:** Friday, January 9, 2026 at 12:01 PM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#important-warning) Important Warning ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Bootstrap/Early Plugins should only be used when absolutely necessary!** Early plugins run during a critical phase of the loading process and can significantly impact the game's stability and behavior. Most plugins do NOT need to be early plugins. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------------ Bootstrap/Early Plugins are a special type of plugin that executes **before** the main Hytale server starts. Their primary function is low-level modification, specifically performing **class transformations** that involve altering or injecting bytecode into classes as they are loaded. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#what-are-early-plugins) What are Early Plugins? ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#key-characteristics) Key Characteristics: * **Execute before main server:** Load during game initialization * **Outside standard plugin environment:** Cannot access regular plugin APIs * **No access to:** Event buses, registries, or lifecycle callbacks * **Primary purpose:** Class transformation and bytecode manipulation * **High risk:** Can cause stability issues if implemented incorrectly ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#when-to-use-early-plugins) When to Use Early Plugins: **Use early plugins for:** * Bytecode transformation/modification * Low-level core game modifications * Injecting code into existing classes * Changing fundamental game behavior **Do NOT use early plugins for:** * Adding new items, blocks, or mobs (use Packs instead) * Implementing game features (use regular Plugins) * Listening to events (use regular Plugins) * Configuration management (use regular Plugins) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#loading-early-plugins) Loading Early Plugins -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#default-location) Default Location: By default, the game loads early plugins from: **Important:** You must create this folder manually - the server does not create it automatically. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#custom-locations) Custom Locations: Additional paths can be defined using the `--early-plugins` launch argument: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#user-warning-system) User Warning System ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#warning-message) Warning Message: When launching with early plugins installed, users see: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#skipping-the-warning) Skipping the Warning: * **Manual skip:** Press ENTER key * **Auto-skip:** Add `--accept-early-plugins` launch argument * **Singleplayer:** Warning is NOT displayed * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#creating-early-plugins) Creating Early Plugins ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#basic-requirements) Basic Requirements: * Any `.jar` file can be loaded as an early plugin * **No manifest.json required** * **No standard entrypoints needed** * Must implement class transformers via service loader * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#class-transformers) Class Transformers -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Class transformers allow you to modify the bytecode of classes as they are loaded. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#how-they-work) How They Work: 1. Game starts loading classes 2. Before a class is loaded into the JVM 3. Bytes are passed through transformer chain 4. Your transformer modifies the bytes 5. Modified bytes are loaded by JVM * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-1-registration) Step 1: Registration ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Class transformers are loaded using the **Service Loader** pattern: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#id-1.1-create-transformer-class) 1.1 Create Transformer Class: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#id-1.2-create-service-loader-file) 1.2 Create Service Loader File: **Path:** `src/main/resources/META-INF/services/com.hypixel.hytale.plugin.early.ClassTransformer` **Contents:** Add the full qualified name of your transformer class to this file. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-2-transformer-priority) Step 2: Transformer Priority --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Transformers are executed in priority order: * **Higher priority** runs BEFORE lower priority * **Default priority:** 0 * **Negative numbers:** Run later * **Positive numbers:** Run earlier ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#setting-priority) Setting Priority: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#priority-examples) Priority Examples: * `100` - Very early (runs first) * `10` - Early * `0` - Default (most transformers) * `-10` - Late * `-100` - Very late (runs last) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-3-restricted-classes) Step 3: Restricted Classes ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- For safety reasons, transformers **cannot modify** classes from certain packages: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#restricted-packages) Restricted Packages: * `java.*` * `javax.*` * `jdk.*` * `sun.*` * `com.sun.*` * `org.bouncycastle.*` * `io.netty.*` * `org.objectweb.asm.*` * `com.google.gson.*` * `org.slf4j.*` * `org.apache.logging.*` * `ch.qos.logback.*` * `com.google.flogger.*` * `io.sentry.*` * `com.hypixel.protoplus.*` * `com.hypixel.fastutil.*` * `com.hypixel.hytale.plugin.early.*` Attempting to transform these will be ignored or cause errors. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-4-writing-transformers) Step 4: Writing Transformers --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#transform-method) Transform Method: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#basic-transformation-pattern) Basic Transformation Pattern: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#example-simple-string-replacement-transformer) Example: Simple String Replacement Transformer --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This example replaces the startup message with a custom one: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#advanced-using-asm-library) Advanced: Using ASM Library ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- For more complex transformations, use the **ASM library**: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#asm-benefits) ASM Benefits: * Structured bytecode manipulation * Visitor pattern for class modification * Less error-prone than raw byte manipulation * Better maintainability ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#example-asm-transformer) Example ASM Transformer: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#project-structure) Project Structure ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#building-early-plugins) Building Early Plugins ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Use Gradle to build: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#best-practices) Best Practices ------------------------------------------------------------------------------------------------------------------------------------------------------------------ 1. **Only use when necessary** - Regular plugins are sufficient for 99% of mods. 2. **Test thoroughly** - Early plugins can break the entire game. 3. **Use ASM or Mixins** - Don't manipulate raw bytes unless you're an expert. 4. **Document transformations** - Explain what you're modifying and why. 5. **Handle errors gracefully** - Return original bytes if transformation fails. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#getting-help) Getting Help -------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousGradle Automation & Testingchevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing) [NextPlugin Project Templatechevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template) Last updated 1 day ago * [Important Warning](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#important-warning) * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#overview) * [What are Early Plugins?](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#what-are-early-plugins) * [Key Characteristics:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#key-characteristics) * [When to Use Early Plugins:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#when-to-use-early-plugins) * [Loading Early Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#loading-early-plugins) * [Default Location:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#default-location) * [Custom Locations:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#custom-locations) * [User Warning System](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#user-warning-system) * [Warning Message:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#warning-message) * [Skipping the Warning:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#skipping-the-warning) * [Creating Early Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#creating-early-plugins) * [Basic Requirements:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#basic-requirements) * [Class Transformers](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#class-transformers) * [How They Work:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#how-they-work) * [Step 1: Registration](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-1-registration) * [1.1 Create Transformer Class:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#id-1.1-create-transformer-class) * [1.2 Create Service Loader File:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#id-1.2-create-service-loader-file) * [Step 2: Transformer Priority](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-2-transformer-priority) * [Setting Priority:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#setting-priority) * [Priority Examples:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#priority-examples) * [Step 3: Restricted Classes](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-3-restricted-classes) * [Restricted Packages:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#restricted-packages) * [Step 4: Writing Transformers](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#step-4-writing-transformers) * [Transform Method:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#transform-method) * [Basic Transformation Pattern:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#basic-transformation-pattern) * [Example: Simple String Replacement Transformer](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#example-simple-string-replacement-transformer) * [Advanced: Using ASM Library](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#advanced-using-asm-library) * [ASM Benefits:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#asm-benefits) * [Example ASM Transformer:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#example-asm-transformer) * [Project Structure](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#project-structure) * [Building Early Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#building-early-plugins) * [Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#best-practices) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins#getting-help) sun-brightdesktopmoon Copy earlyplugins/ Copy --early-plugins="C:/path/to/custom/earlyplugins" Copy =========================================================================== Loaded 2 class transformer(s)!! =========================================================================== This is unsupported and may cause stability issues. Use at your own risk!! =========================================================================== Press ENTER to accept and continue... Copy package com.example.early; import com.hypixel.hytale.plugin.early.ClassTransformer; public class ExampleTransformer implements ClassTransformer { @Override public byte[] transform(String name, String path, byte[] bytes) { // Transformation logic here return bytes; } } Copy com.example.early.ExampleTransformer Copy @Override public int priority() { return -100; // Run after most other transformers } Copy @Override public byte[] transform(String name, String path, byte[] bytes) { // name: Fully qualified class name (e.g., "com.hypixel.hytale.server.HytaleServer") // path: File path to the class // bytes: Original class bytecode // Return modified bytes, or original bytes if no changes return bytes; } Copy @Override public byte[] transform(String name, String path, byte[] bytes) { // Only transform specific class if (name.equals("com.hypixel.hytale.server.core.HytaleServer")) { // Modify the bytes return modifyBytes(bytes); } // Return unchanged for other classes return bytes; } Copy import com.hypixel.hytale.plugin.early.ClassTransformer; import java.nio.ByteBuffer; import java.nio.charset.StandardCharsets; public class ExampleTransformer implements ClassTransformer { @Override public byte[] transform(String name, String path, byte[] bytes) { if (name.equals("com.hypixel.hytale.server.core.HytaleServer")) { return patchString(bytes, "Starting HytaleServer", "Starting Patched HytaleServer >:)"); } return bytes; } public static byte[] patchString(byte[] bytes, String target, String replacement) { final byte[] targetBytes = encodeStringWithLength(target); final byte[] replacementBytes = encodeStringWithLength(replacement); final int index = indexOf(bytes, targetBytes); if (index == -1) { return bytes; // Target not found } final byte[] result = new byte[bytes.length - targetBytes.length + replacementBytes.length]; System.arraycopy(bytes, 0, result, 0, index); // Before the target System.arraycopy(replacementBytes, 0, result, index, replacementBytes.length); // Replacement System.arraycopy(bytes, index + targetBytes.length, result, index + replacementBytes.length, bytes.length - index - targetBytes.length); // After the target return result; } public static byte[] encodeStringWithLength(String str) { final byte[] utf8Bytes = str.getBytes(StandardCharsets.UTF_8); ByteBuffer buffer = ByteBuffer.allocate(2 + utf8Bytes.length); return buffer.putShort((short) utf8Bytes.length).put(utf8Bytes).array(); } private static int indexOf(byte[] array, byte[] target) { outer: for (int i = 0; i <= array.length - target.length; i++) { for (int j = 0; j < target.length; j++) { if (array[i + j] != target[j]) { continue outer; } } return i; } return -1; } } Copy import com.hypixel.hytale.plugin.early.ClassTransformer; import org.objectweb.asm.*; public class AsmTransformer implements ClassTransformer { @Override public byte[] transform(String name, String path, byte[] bytes) { if (name.equals("com.example.TargetClass")) { ClassReader reader = new ClassReader(bytes); ClassWriter writer = new ClassWriter(reader, 0); ClassVisitor visitor = new MyClassVisitor(Opcodes.ASM9, writer); reader.accept(visitor, 0); return writer.toByteArray(); } return bytes; } private static class MyClassVisitor extends ClassVisitor { public MyClassVisitor(int api, ClassVisitor cv) { super(api, cv); } @Override public MethodVisitor visitMethod(int access, String name, String descriptor, String signature, String[] exceptions) { MethodVisitor mv = super.visitMethod(access, name, descriptor, signature, exceptions); // Modify specific method if (name.equals("targetMethod")) { return new MethodModifier(api, mv); } return mv; } } private static class MethodModifier extends MethodVisitor { public MethodModifier(int api, MethodVisitor mv) { super(api, mv); } @Override public void visitCode() { // Inject code at method start super.visitCode(); // Add your bytecode instructions here } } } Copy your-early-plugin/ ├── src/ │ └── main/ │ ├── java/ │ │ └── com/ │ │ └── example/ │ │ └── early/ │ │ └── ExampleTransformer.java │ └── resources/ │ └── META-INF/ │ └── services/ │ └── com.hypixel.hytale.plugin.early.ClassTransformer ├── build.gradle └── README.md Copy plugins { id 'java' } group = 'com.example' version = '1.0.0' repositories { mavenCentral() } dependencies { // Add Hytale early plugin API compileOnly 'com.hypixel.hytale:early-plugin-api:VERSION' // ASM for bytecode manipulation (optional) implementation 'org.ow2.asm:asm:9.5' implementation 'org.ow2.asm:asm-commons:9.5' } jar { from { configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) } } } sun-brightdesktopmoon --- # Common Plugin Features | Hytale Modding Documentation **Last Modified:** Friday, January 10, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#overview) Overview ----------------------------------------------------------------------------------------------------------------------------------------------------- This guide provides practical implementations of common features found in Hytale server plugins. These are real-world examples that you can adapt for your own plugins. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#placeholder-system) Placeholder System ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Placeholders allow you to insert dynamic values into messages, like player names, balances, or timestamps. Format: `%placeholder_name%` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#basic-placeholder-implementation) Basic Placeholder Implementation Copy // Placeholder Provider Interface public interface PlaceholderProvider { String getName(); // Human-readable name String getIdentifier(); // Unique identifier (e.g., "player_name") String parse(Player player, String input); // Replace placeholder with value } // Example: Player Name Placeholder public class PlayerNamePlaceholder implements PlaceholderProvider { public static final PlayerNamePlaceholder INSTANCE = new PlayerNamePlaceholder(); private PlayerNamePlaceholder() {} // Singleton @Override public String getName() { return "Player Name"; } @Override public String getIdentifier() { return "player_name"; } @Override public String parse(Player player, String input) { return player.getUsername(); } } // Example: Player Balance Placeholder public class PlayerBalancePlaceholder implements PlaceholderProvider { public static final PlayerBalancePlaceholder INSTANCE = new PlayerBalancePlaceholder(); private PlayerBalancePlaceholder() {} @Override public String getName() { return "Player Balance"; } @Override public String getIdentifier() { return "player_balance"; } @Override public String parse(Player player, String input) { double balance = EconomyService.getBalance(player); return NumberUtils.formatNumber(balance); // "1.5k" instead of "1500" } } ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#placeholder-service) Placeholder Service ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#registering-placeholders) Registering Placeholders ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#using-placeholders) Using Placeholders * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#translation-i18n-system) Translation/i18n System ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Support multiple languages in your plugin with a translation system. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#message-class) Message Class ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#translation-service) Translation Service ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#loading-translations-from-json) Loading Translations from JSON ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#using-translations) Using Translations * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#utility-classes) Utility Classes ------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#time-formatting) Time Formatting ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#number-formatting) Number Formatting ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#color-utilities) Color Utilities * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#first-join-detection) First Join Detection ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Track when players join for the first time to show special messages or give rewards. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#implementation) Implementation ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#config-example) Config Example * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#ban-mute-check-on-join) Ban/Mute Check on Join --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Prevent banned or muted players from joining or chatting. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#join-check) Join Check ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-check) Chat Check * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-channels-rooms) Chat Channels/Rooms --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Allow players to switch between different chat channels (global, staff, trade, etc.). ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-room-class) Chat Room Class ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-service) Chat Service ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#usage) Usage * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#summary) Summary --------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#features-covered) Features Covered: 1. **Placeholder System** - Dynamic value insertion in messages 2. **Translation/i18n** - Multi-language support 3. **Utility Classes** - Time, number, and color formatting 4. **First Join Detection** - Special handling for new players 5. **Ban/Mute Checks** - Moderation enforcement 6. **Chat Channels** - Multiple chat rooms ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#benefits) Benefits: * **Reusable Code** - Copy and adapt for your plugin * **Professional Features** - Common server functionality * **Best Practices** - Production-tested patterns * **Extensible** - Easy to customize and expand * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#next-steps) Next Steps --------------------------------------------------------------------------------------------------------------------------------------------------------- * Implement these features in your plugin * Customize messages and formats * Add your own placeholders * Create additional chat rooms * Extend with more utility methods * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#getting-help) Getting Help ------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousCustom Config Fileschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/08-custom-config-files) [NextAdvanced Plugin Patternschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#overview) * [Placeholder System](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#placeholder-system) * [Basic Placeholder Implementation](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#basic-placeholder-implementation) * [Placeholder Service](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#placeholder-service) * [Registering Placeholders](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#registering-placeholders) * [Using Placeholders](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#using-placeholders) * [Translation/i18n System](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#translation-i18n-system) * [Message Class](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#message-class) * [Translation Service](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#translation-service) * [Loading Translations from JSON](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#loading-translations-from-json) * [Using Translations](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#using-translations) * [Utility Classes](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#utility-classes) * [Time Formatting](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#time-formatting) * [Number Formatting](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#number-formatting) * [Color Utilities](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#color-utilities) * [First Join Detection](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#first-join-detection) * [Implementation](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#implementation) * [Config Example](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#config-example) * [Ban/Mute Check on Join](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#ban-mute-check-on-join) * [Join Check](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#join-check) * [Chat Check](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-check) * [Chat Channels/Rooms](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-channels-rooms) * [Chat Room Class](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-room-class) * [Chat Service](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#chat-service) * [Usage](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#usage) * [Summary](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#summary) * [Features Covered:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#features-covered) * [Benefits:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#benefits) * [Next Steps](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#next-steps) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features#getting-help) sun-brightdesktopmoon Copy import java.util.Map; import java.util.concurrent.ConcurrentHashMap; public class PlaceholderService { private static PlaceholderService instance; private final Map providers; public PlaceholderService() { this.providers = new ConcurrentHashMap<>(); } public static PlaceholderService get() { if (instance == null) { instance = new PlaceholderService(); } return instance; } public void registerProvider(PlaceholderProvider provider) { if (providers.containsKey(provider.getIdentifier())) { throw new IllegalArgumentException( "Placeholder '" + provider.getIdentifier() + "' already registered" ); } providers.put(provider.getIdentifier(), provider); } public void unregisterProvider(PlaceholderProvider provider) { providers.remove(provider.getIdentifier()); } public String parse(Player player, String input) { String result = input; for (PlaceholderProvider provider : providers.values()) { String placeholder = "%" + provider.getIdentifier() + "%"; if (result.contains(placeholder)) { String replacement = provider.parse(player, result); result = result.replace(placeholder, replacement); } } return result; } } Copy public class MyPlugin extends JavaPlugin { @Override public void onEnable() { // Register built-in placeholders PlaceholderService service = PlaceholderService.get(); service.registerProvider(PlayerNamePlaceholder.INSTANCE); service.registerProvider(PlayerBalancePlaceholder.INSTANCE); service.registerProvider(PlayerUuidPlaceholder.INSTANCE); service.registerProvider(PlayerPlayTimePlaceholder.INSTANCE); getLogger().info("Registered " + service.getProviderCount() + " placeholders"); } } Copy // In your config String welcomeMessage = "Welcome %player_name%! Your balance: %player_balance%"; // Parse and send Player player = event.getPlayer(); String parsed = PlaceholderService.get().parse(player, welcomeMessage); player.sendMessage(parsed); // Output: "Welcome Steve! Your balance: 1.5k" Copy public class Message { private final String key; private final String raw; private String parsed; public Message(String key, String message) { this.key = key; this.raw = message; this.parsed = message; } // Replace placeholders (supports both {placeholder} and %placeholder%) public Message replace(String placeholder, String replacement) { this.parsed = this.parsed .replace("{" + placeholder + "}", replacement) .replace("%" + placeholder + "%", replacement); return this; } // Send to player public void sendTo(Player player) { if (player.isOnline()) { player.sendMessage(this.parsed); } } public String getKey() { return key; } public String getRawMessage() { return raw; } public String getParsedMessage() { return parsed; } } Copy import java.util.Map; import java.util.concurrent.ConcurrentHashMap; public class TranslationService { private final Map messages; public TranslationService() { this.messages = new ConcurrentHashMap<>(); } public TranslationService addMessage(String key, String message) { this.messages.put(key, new Message(key, message)); return this; } public Message getMessage(String key) { Message message = this.messages.get(key); if (message == null) { // Return default if missing return new Message(key, "Missing translation: " + key); } // Return copy to prevent external modification return new Message(message.getKey(), message.getRawMessage()); } } Copy { "messages": { "welcome": "Welcome {player_name} to the server!", "goodbye": "Goodbye {player_name}, see you soon!", "banned": "You are banned: {reason}", "muted": "You are muted for {duration}", "balance": "Your balance: {amount} coins" } } Copy import com.google.gson.JsonObject; import com.google.gson.JsonParser; import java.io.FileReader; public void loadTranslations(File file) { try (FileReader reader = new FileReader(file)) { JsonObject json = JsonParser.parseReader(reader).getAsJsonObject(); JsonObject messages = json.getAsJsonObject("messages"); for (String key : messages.keySet()) { String value = messages.get(key).getAsString(); translationService.addMessage(key, value); } getLogger().info("Loaded " + messages.size() + " translations"); } catch (Exception e) { e.printStackTrace(); } } Copy // Get message and replace placeholders Message msg = translationService.getMessage("welcome") .replace("player_name", player.getUsername()); // Send to player msg.sendTo(player); // Or get as string String text = msg.getParsedMessage(); Copy import java.text.SimpleDateFormat; import java.util.Date; public class TimeUtils { private static final SimpleDateFormat DATE_FORMAT = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); /** * Format milliseconds to human-readable duration * Example: 90061000 -> "1d 1h 1m 1s" */ public static String formatTime(long millis) { long seconds = millis / 1000; long minutes = seconds / 60; long hours = minutes / 60; long days = hours / 24; seconds %= 60; minutes %= 60; hours %= 24; StringBuilder result = new StringBuilder(); if (days > 0) result.append(days).append("d "); if (hours > 0 || days > 0) result.append(hours).append("h "); if (minutes > 0 || hours > 0 || days > 0) result.append(minutes).append("m "); result.append(seconds).append("s"); return result.toString().trim(); } /** * Format timestamp to date string * Example: 1704844800000 -> "2024-01-10 12:00:00" */ public static String formatDate(long timestamp) { return DATE_FORMAT.format(new Date(timestamp)); } } // Usage: long playTime = 3661000; // 1 hour, 1 minute, 1 second String formatted = TimeUtils.formatTime(playTime); player.sendMessage("Play time: " + formatted); // "Play time: 1h 1m 1s" Copy import java.text.DecimalFormat; import java.text.DecimalFormatSymbols; import java.util.Locale; public class NumberUtils { private static final String[] SUFFIXES = {"", "k", "m", "b", "t", "q", "Q"}; private static final DecimalFormat FORMAT; static { DecimalFormatSymbols symbols = new DecimalFormatSymbols(Locale.US); FORMAT = new DecimalFormat("#.##", symbols); } /** * Format large numbers with suffixes * Examples: * 1000 -> "1k" * 1500 -> "1.5k" * 1000000 -> "1m" * 1234567 -> "1.23m" */ public static String formatNumber(double value) { if (Double.isNaN(value) || Double.isInfinite(value)) { return String.valueOf(value); } double absValue = Math.abs(value); int suffixIndex = 0; if (absValue >= 1000) { suffixIndex = (int) (Math.log10(absValue) / 3); suffixIndex = Math.min(suffixIndex, SUFFIXES.length - 1); } double scaledValue = value / Math.pow(1000, suffixIndex); String formatted = FORMAT.format(scaledValue); return formatted + SUFFIXES[suffixIndex]; } } // Usage: double balance = 1234567.89; String formatted = NumberUtils.formatNumber(balance); player.sendMessage("Balance: " + formatted); // "Balance: 1.23m" Copy import java.awt.Color; public class ColorUtils { /** * Convert Color to hex string * Example: Color.RED -> "#ff0000" */ public static String toHex(Color color) { return String.format("#%02x%02x%02x", color.getRed(), color.getGreen(), color.getBlue() ); } /** * Parse hex string to Color * Example: "#ff0000" -> Color.RED */ public static Color fromHex(String hex) { hex = hex.replace("#", ""); return new Color( Integer.parseInt(hex.substring(0, 2), 16), Integer.parseInt(hex.substring(2, 4), 16), Integer.parseInt(hex.substring(4, 6), 16) ); } /** * Interpolate between two colors * @param ratio 0.0 to 1.0 */ public static Color lerp(Color start, Color end, double ratio) { ratio = Math.max(0, Math.min(1, ratio)); // Clamp 0-1 int r = (int) (start.getRed() + ratio * (end.getRed() - start.getRed())); int g = (int) (start.getGreen() + ratio * (end.getGreen() - start.getGreen())); int b = (int) (start.getBlue() + ratio * (end.getBlue() - start.getBlue())); return new Color(r, g, b); } } // Usage: Color playerColor = new Color(255, 100, 50); String hex = ColorUtils.toHex(playerColor); // "#ff6432" // Health bar color (red to green based on health percentage) double healthPercent = player.getHealth() / player.getMaxHealth(); Color healthColor = ColorUtils.lerp(Color.RED, Color.GREEN, healthPercent); Copy public class PlayerJoinListener { private final PlayerService playerService; private final PlaceholderService placeholders; private final PluginConfig config; public PlayerJoinListener(MyPlugin plugin) { this.playerService = plugin.getPlayerService(); this.placeholders = PlaceholderService.get(); this.config = plugin.getConfig(); } public void onPlayerJoin(PlayerJoinEvent event) { Player player = event.getPlayer(); UUID uuid = player.getUUID(); // Check if player exists in database PlayerData data = playerService.getPlayerData(uuid); boolean isFirstJoin = (data == null); if (isFirstJoin) { // Create new player data data = new PlayerData(uuid, player.getUsername()); data.setJoinedAt(System.currentTimeMillis()); playerService.savePlayerData(data); // Send first join message to all players String message = placeholders.parse( player, config.getFirstJoinMessage() ); for (Player online : playerService.getOnlinePlayers()) { online.sendMessage(message); } // Give first join rewards giveFirstJoinRewards(player); } else { // Regular join message String message = placeholders.parse( player, config.getJoinMessage() ); for (Player online : playerService.getOnlinePlayers()) { online.sendMessage(message); } // Update last seen data.setLastSeen(System.currentTimeMillis()); playerService.savePlayerData(data); } // Add to online players playerService.addOnlinePlayer(player); } private void giveFirstJoinRewards(Player player) { // Give starting items // player.getInventory().addItem(new ItemStack(Material.STONE_SWORD)); // Give starting money // economyService.deposit(player, 1000); // Send welcome message player.sendMessage("Welcome to the server!"); player.sendMessage("You've received starter items and 1000 coins!"); } } Copy { "joinMessage": "§e%player_name% joined the server", "firstJoinMessage": "§6Welcome %player_name% to the server for the first time!", "leaveMessage": "§e%player_name% left the server" } Copy public void onPlayerJoin(PlayerJoinEvent event) { Player player = event.getPlayer(); // Check if player is banned Punishment ban = punishmentService.getActiveBan(player.getUUID()); if (ban != null) { event.cancel(); // Prevent join String reason = ban.getReason(); long expiresAt = ban.getExpiresAt(); String message; if (expiresAt == -1) { // Permanent ban message = "You are permanently banned.\nReason: " + reason; } else { // Temporary ban long remaining = expiresAt - System.currentTimeMillis(); String duration = TimeUtils.formatTime(remaining); message = "You are banned for " + duration + ".\nReason: " + reason; } player.kick(message); return; } // Continue with normal join logic... } Copy public void onPlayerChat(PlayerChatEvent event) { Player player = event.getPlayer(); // Check if player is muted Punishment mute = punishmentService.getActiveMute(player.getUUID()); if (mute != null) { event.cancel(); // Prevent chat message long remaining = mute.getExpiresAt() - System.currentTimeMillis(); String duration = TimeUtils.formatTime(remaining); player.sendMessage("§cYou are muted for " + duration); player.sendMessage("§cReason: " + mute.getReason()); return; } // Continue with normal chat logic... } Copy public class ChatRoom { private final String id; private final String name; private final String format; private final Set members; public ChatRoom(String id, String name, String format) { this.id = id; this.name = name; this.format = format; // e.g., "[Global] %player_name%: %message%" this.members = new HashSet<>(); } public void addMember(UUID playerId) { members.add(playerId); } public void removeMember(UUID playerId) { members.remove(playerId); } public void sendMessage(Player sender, String message) { String formatted = format .replace("%player_name%", sender.getUsername()) .replace("%message%", message); // Send to all members for (UUID memberId : members) { Player member = playerService.getOnlinePlayer(memberId); if (member != null) { member.sendMessage(formatted); } } } public String getId() { return id; } public String getName() { return name; } public Set getMembers() { return members; } } Copy public class ChatService { private final Map rooms; private final Map playerRooms; // Player -> Current room ID public ChatService() { this.rooms = new ConcurrentHashMap<>(); this.playerRooms = new ConcurrentHashMap<>(); // Create default rooms createRoom("global", "Global", "§f[Global] %player_name%: %message%"); createRoom("staff", "Staff", "§c[Staff] %player_name%: %message%"); createRoom("trade", "Trade", "§e[Trade] %player_name%: %message%"); } public void createRoom(String id, String name, String format) { rooms.put(id, new ChatRoom(id, name, format)); } public void switchRoom(Player player, String roomId) { ChatRoom room = rooms.get(roomId); if (room == null) { player.sendMessage("§cChat room not found: " + roomId); return; } // Leave current room String currentRoomId = playerRooms.get(player.getUUID()); if (currentRoomId != null) { ChatRoom currentRoom = rooms.get(currentRoomId); currentRoom.removeMember(player.getUUID()); } // Join new room room.addMember(player.getUUID()); playerRooms.put(player.getUUID(), roomId); player.sendMessage("§aYou are now in: " + room.getName()); } public ChatRoom getCurrentRoom(Player player) { String roomId = playerRooms.getOrDefault(player.getUUID(), "global"); return rooms.get(roomId); } } Copy // Command: /chat public void onChatCommand(Player player, String[] args) { if (args.length < 1) { player.sendMessage("§cUsage: /chat "); return; } chatService.switchRoom(player, args[0].toLowerCase()); } // On chat event public void onPlayerChat(PlayerChatEvent event) { Player player = event.getPlayer(); String message = event.getMessage(); event.cancel(); // Cancel default chat // Send to current room ChatRoom room = chatService.getCurrentRoom(player); room.sendMessage(player, message); } sun-brightdesktopmoon --- # Advanced Plugin Patterns | Hytale Modding Documentation **Last Modified:** Friday, January 10, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------------- This guide covers advanced architectural patterns and best practices for building robust, scalable Hytale plugins. These patterns are commonly used in production plugins and will help you write cleaner, more maintainable code. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#plugin-architecture-patterns) Plugin Architecture Patterns ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#service-storage-pattern) Service-Storage Pattern A common pattern for managing data in plugins is to separate **business logic** (Service) from **data persistence** (Storage). #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#benefits) Benefits: * Clean separation of concerns * Easy to swap storage backends (JSON → Database) * Testable business logic * In-memory caching layer #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#example-structure) Example Structure: Copy // Storage Interface - Handles data persistence public interface PlayerStorage { PlayerData load(UUID uuid); void save(PlayerData data); List loadAll(); } // JSON Implementation public class PlayerJsonStorage implements PlayerStorage { private final File dataFolder; public PlayerJsonStorage(File dataFolder) { this.dataFolder = new File(dataFolder, "players"); this.dataFolder.mkdirs(); } @Override public PlayerData load(UUID uuid) { File file = new File(dataFolder, uuid.toString() + ".json"); if (!file.exists()) return null; try (FileReader reader = new FileReader(file)) { return new Gson().fromJson(reader, PlayerData.class); } catch (IOException e) { e.printStackTrace(); return null; } } @Override public void save(PlayerData data) { File file = new File(dataFolder, data.getUuid().toString() + ".json"); try (FileWriter writer = new FileWriter(file)) { new Gson().toJson(data, writer); } catch (IOException e) { e.printStackTrace(); } } @Override public List loadAll() { List players = new ArrayList<>(); File[] files = dataFolder.listFiles((dir, name) -> name.endsWith(".json")); if (files != null) { for (File file : files) { try (FileReader reader = new FileReader(file)) { players.add(new Gson().fromJson(reader, PlayerData.class)); } catch (IOException e) { e.printStackTrace(); } } } return players; } } // Service Layer - Business logic and caching public class PlayerService { private final PlayerStorage storage; private final Map cache; public PlayerService(PlayerStorage storage) { this.storage = storage; this.cache = new ConcurrentHashMap<>(); loadAll(); } private void loadAll() { for (PlayerData data : storage.loadAll()) { cache.put(data.getUuid(), data); } } public PlayerData getPlayer(UUID uuid) { return cache.computeIfAbsent(uuid, id -> { PlayerData data = storage.load(id); return data != null ? data : new PlayerData(id); }); } public void savePlayer(PlayerData data) { cache.put(data.getUuid(), data); storage.save(data); } public void saveAll() { for (PlayerData data : cache.values()) { storage.save(data); } } } * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#thread-pool-management) Thread Pool Management ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- For async operations, use a thread pool instead of creating new threads repeatedly. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#why-use-thread-pools) Why Use Thread Pools? * **Performance**: Reuses threads instead of creating new ones * **Resource Management**: Limits concurrent threads * **Scheduled Tasks**: Built-in support for delayed/periodic tasks ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#implementation) Implementation: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#singleton-pattern-for-plugin-access) Singleton Pattern for Plugin Access ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Allow other parts of your code (and other plugins) to access your plugin instance. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#implementation-1) Implementation: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#logging-best-practices) Logging Best Practices ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#structured-logging-with-log-levels) Structured Logging with Log Levels * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#configuration-management) Configuration Management --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#type-safe-configuration) Type-Safe Configuration Instead of accessing config values directly everywhere, create a configuration class: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#event-system-pattern) Event System Pattern ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a custom event system for your plugin to allow extensibility. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#basic-event-system) Basic Event System: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#periodic-save-pattern) Periodic Save Pattern --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Automatically save data at regular intervals to prevent data loss. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#cache-cleanup-pattern) Cache Cleanup Pattern --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Periodically clean up unused cached data to prevent memory leaks. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#plugin-lifecycle-best-practices) Plugin Lifecycle Best Practices ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#complete-plugin-template-with-all-patterns) Complete Plugin Template with All Patterns: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#summary) Summary ----------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#key-patterns-covered) Key Patterns Covered: 1. **Service-Storage Pattern** - Separate business logic from data persistence 2. **Thread Pool Management** - Efficient async operations 3. **Singleton Pattern** - Global plugin access 4. **Structured Logging** - Professional logging with levels and files 5. **Type-Safe Configuration** - Clean config management 6. **Custom Event System** - Extensible plugin architecture 7. **Periodic Save Pattern** - Automatic data persistence 8. **Cache Cleanup Pattern** - Memory management ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#benefits-1) Benefits: * **Maintainable**: Clear separation of concerns * **Scalable**: Easy to add new features * **Testable**: Services can be tested independently * **Professional**: Production-ready patterns * **Extensible**: Other plugins can integrate via your API * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#next-steps) Next Steps ----------------------------------------------------------------------------------------------------------------------------------------------------------- * Implement these patterns in your plugin * Create unit tests for your services * Document your public API * Consider creating a developer API for other plugins * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#getting-help) Getting Help --------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousCommon Plugin Featureschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features) [NextGradle Automation & Testingchevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#overview) * [Plugin Architecture Patterns](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#plugin-architecture-patterns) * [Service-Storage Pattern](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#service-storage-pattern) * [Thread Pool Management](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#thread-pool-management) * [Why Use Thread Pools?](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#why-use-thread-pools) * [Implementation:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#implementation) * [Singleton Pattern for Plugin Access](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#singleton-pattern-for-plugin-access) * [Implementation:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#implementation-1) * [Logging Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#logging-best-practices) * [Structured Logging with Log Levels](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#structured-logging-with-log-levels) * [Configuration Management](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#configuration-management) * [Type-Safe Configuration](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#type-safe-configuration) * [Event System Pattern](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#event-system-pattern) * [Basic Event System:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#basic-event-system) * [Periodic Save Pattern](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#periodic-save-pattern) * [Cache Cleanup Pattern](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#cache-cleanup-pattern) * [Plugin Lifecycle Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#plugin-lifecycle-best-practices) * [Complete Plugin Template with All Patterns:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#complete-plugin-template-with-all-patterns) * [Summary](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#summary) * [Key Patterns Covered:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#key-patterns-covered) * [Benefits:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#benefits-1) * [Next Steps](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#next-steps) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns#getting-help) sun-brightdesktopmoon Copy import java.util.concurrent.Executors; import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.TimeUnit; public class MyPlugin extends JavaPlugin { private ScheduledExecutorService threadPool; public MyPlugin(JavaPluginInit init) { super(init); // Create thread pool with 4 threads threadPool = Executors.newScheduledThreadPool(4, r -> { Thread thread = new Thread(r); thread.setName("MyPlugin-Thread-" + thread.threadId()); return thread; }); } @Override public void onEnable() { // Run task asynchronously threadPool.execute(() -> { // Heavy operation here loadDataFromDatabase(); }); // Schedule repeating task (every 5 minutes) threadPool.scheduleAtFixedRate( () -> saveAllData(), 5, 5, TimeUnit.MINUTES ); // Schedule delayed task (run once after 10 seconds) threadPool.schedule( () -> cleanupCache(), 10, TimeUnit.SECONDS ); } @Override public void onDisable() { // Shutdown thread pool gracefully threadPool.shutdown(); try { if (!threadPool.awaitTermination(10, TimeUnit.SECONDS)) { threadPool.shutdownNow(); } } catch (InterruptedException e) { threadPool.shutdownNow(); } } private void loadDataFromDatabase() { // Heavy operation } private void saveAllData() { // Periodic save } private void cleanupCache() { // Cache cleanup } } Copy public class MyPlugin extends JavaPlugin { private static MyPlugin instance; public MyPlugin(JavaPluginInit init) { super(init); instance = this; } public static MyPlugin getInstance() { return instance; } // Expose services public PlayerService getPlayerService() { return playerService; } public EconomyService getEconomyService() { return economyService; } } // Usage from anywhere: MyPlugin plugin = MyPlugin.getInstance(); PlayerService players = plugin.getPlayerService(); Copy import java.io.File; import java.io.FileWriter; import java.io.IOException; import java.text.SimpleDateFormat; import java.util.Date; public class PluginLogger { private final String pluginName; private final File logFile; private LogLevel currentLevel = LogLevel.INFO; public enum LogLevel { DEBUG(0), INFO(1), WARN(2), ERROR(3); private final int priority; LogLevel(int priority) { this.priority = priority; } public int getPriority() { return priority; } } public PluginLogger(String pluginName, File dataFolder) { this.pluginName = pluginName; // Create logs directory File logsDir = new File(dataFolder, "logs"); logsDir.mkdirs(); // Create log file with date String date = new SimpleDateFormat("yyyy-MM-dd").format(new Date()); this.logFile = new File(logsDir, pluginName + "-" + date + ".log"); try { logFile.createNewFile(); } catch (IOException e) { e.printStackTrace(); } } public void setLogLevel(LogLevel level) { this.currentLevel = level; } public void debug(String message) { log(LogLevel.DEBUG, message); } public void info(String message) { log(LogLevel.INFO, message); } public void warn(String message) { log(LogLevel.WARN, message); } public void error(String message) { log(LogLevel.ERROR, message); } public void error(String message, Throwable throwable) { log(LogLevel.ERROR, message + ": " + throwable.getMessage()); throwable.printStackTrace(); } private void log(LogLevel level, String message) { if (level.getPriority() < currentLevel.getPriority()) { return; // Skip if below current log level } String timestamp = new SimpleDateFormat("HH:mm:ss").format(new Date()); String logMessage = String.format("[%s] [%s] %s: %s", timestamp, pluginName, level.name(), message); // Console output System.out.println(logMessage); // File output try (FileWriter writer = new FileWriter(logFile, true)) { writer.write(logMessage + "\n"); } catch (IOException e) { e.printStackTrace(); } } } // Usage: PluginLogger logger = new PluginLogger("MyPlugin", getDataFolder()); logger.setLogLevel(LogLevel.INFO); // Only INFO and above logger.debug("This won't be logged"); logger.info("Plugin initialized"); logger.warn("Configuration file missing, using defaults"); logger.error("Failed to connect to database", exception); Copy public class PluginConfig { private final File configFile; private JsonObject config; // Default values private String serverName = "My Server"; private int maxPlayers = 100; private boolean debugMode = false; private String primaryCurrency = "coins"; public PluginConfig(File dataFolder) { this.configFile = new File(dataFolder, "config.json"); load(); } public void load() { if (!configFile.exists()) { saveDefaults(); return; } try (FileReader reader = new FileReader(configFile)) { config = new Gson().fromJson(reader, JsonObject.class); // Load values with defaults serverName = config.has("serverName") ? config.get("serverName").getAsString() : serverName; maxPlayers = config.has("maxPlayers") ? config.get("maxPlayers").getAsInt() : maxPlayers; debugMode = config.has("debugMode") ? config.get("debugMode").getAsBoolean() : debugMode; primaryCurrency = config.has("primaryCurrency") ? config.get("primaryCurrency").getAsString() : primaryCurrency; } catch (IOException e) { e.printStackTrace(); } } private void saveDefaults() { config = new JsonObject(); config.addProperty("serverName", serverName); config.addProperty("maxPlayers", maxPlayers); config.addProperty("debugMode", debugMode); config.addProperty("primaryCurrency", primaryCurrency); save(); } public void save() { try (FileWriter writer = new FileWriter(configFile)) { new GsonBuilder().setPrettyPrinting().create().toJson(config, writer); } catch (IOException e) { e.printStackTrace(); } } // Getters public String getServerName() { return serverName; } public int getMaxPlayers() { return maxPlayers; } public boolean isDebugMode() { return debugMode; } public String getPrimaryCurrency() { return primaryCurrency; } // Setters (with auto-save) public void setServerName(String name) { this.serverName = name; config.addProperty("serverName", name); save(); } } Copy // Base event interface public interface PluginEvent { String getEventName(); } // Example event public class PlayerDataLoadedEvent implements PluginEvent { private final UUID playerId; private final PlayerData data; public PlayerDataLoadedEvent(UUID playerId, PlayerData data) { this.playerId = playerId; this.data = data; } @Override public String getEventName() { return "PlayerDataLoaded"; } public UUID getPlayerId() { return playerId; } public PlayerData getData() { return data; } } // Event listener interface @FunctionalInterface public interface EventListener { void onEvent(T event); } // Event service public class EventService { private final Map, List>> listeners; public EventService() { this.listeners = new ConcurrentHashMap<>(); } public void registerListener( Class eventClass, EventListener listener) { listeners.computeIfAbsent(eventClass, k -> new ArrayList<>()).add(listener); } public void fireEvent(T event) { List> eventListeners = listeners.get(event.getClass()); if (eventListeners != null) { for (EventListener listener : eventListeners) { try { ((EventListener) listener).onEvent(event); } catch (Exception e) { e.printStackTrace(); } } } } } // Usage: EventService events = new EventService(); // Register listener events.registerListener(PlayerDataLoadedEvent.class, event -> { System.out.println("Player data loaded: " + event.getPlayerId()); }); // Fire event events.fireEvent(new PlayerDataLoadedEvent(playerId, data)); Copy public class AutoSaveTask implements Runnable { private final PlayerService playerService; private final PluginLogger logger; public AutoSaveTask(PlayerService playerService, PluginLogger logger) { this.playerService = playerService; this.logger = logger; } @Override public void run() { try { logger.info("Auto-saving player data..."); playerService.saveAll(); logger.info("Auto-save complete"); } catch (Exception e) { logger.error("Auto-save failed", e); } } public void schedule(ScheduledExecutorService executor) { // Save every 5 minutes executor.scheduleAtFixedRate(this, 5, 5, TimeUnit.MINUTES); } } // In your plugin: AutoSaveTask autoSave = new AutoSaveTask(playerService, logger); autoSave.schedule(threadPool); Copy public class CacheCleanupTask implements Runnable { private final Map playerCache; private final long maxIdleTime; private final PluginLogger logger; public CacheCleanupTask( Map cache, long maxIdleTimeMinutes, PluginLogger logger) { this.playerCache = cache; this.maxIdleTime = maxIdleTimeMinutes * 60 * 1000; // Convert to ms this.logger = logger; } @Override public void run() { long now = System.currentTimeMillis(); int removed = 0; Iterator> iterator = playerCache.entrySet().iterator(); while (iterator.hasNext()) { Map.Entry entry = iterator.next(); CachedPlayer player = entry.getValue(); // Remove if player is offline and idle too long if (!player.isOnline() && (now - player.getLastAccessTime()) > maxIdleTime) { iterator.remove(); removed++; } } if (removed > 0) { logger.info("Cleaned up " + removed + " cached players"); } } public void schedule(ScheduledExecutorService executor) { // Run cleanup every 10 minutes executor.scheduleAtFixedRate(this, 10, 10, TimeUnit.MINUTES); } } class CachedPlayer { private final UUID uuid; private boolean online; private long lastAccessTime; public CachedPlayer(UUID uuid) { this.uuid = uuid; this.online = false; this.lastAccessTime = System.currentTimeMillis(); } public void updateAccessTime() { this.lastAccessTime = System.currentTimeMillis(); } public boolean isOnline() { return online; } public void setOnline(boolean online) { this.online = online; } public long getLastAccessTime() { return lastAccessTime; } } Copy package com.example.myplugin; import com.hypixel.hytale.plugin.JavaPlugin; import com.hypixel.hytale.plugin.JavaPluginInit; import javax.annotation.Nonnull; import java.util.concurrent.ScheduledExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.TimeUnit; public class MyPlugin extends JavaPlugin { // Singleton instance private static MyPlugin instance; // Core services private PluginLogger logger; private PluginConfig config; private ScheduledExecutorService threadPool; private EventService eventService; // Feature services private PlayerStorage playerStorage; private PlayerService playerService; // Scheduled tasks private AutoSaveTask autoSaveTask; private CacheCleanupTask cacheCleanupTask; public MyPlugin(@Nonnull JavaPluginInit init) { super(init); instance = this; // Initialize core services this.logger = new PluginLogger("MyPlugin", getDataFolder()); this.config = new PluginConfig(getDataFolder()); // Set log level from config if (config.isDebugMode()) { logger.setLogLevel(PluginLogger.LogLevel.DEBUG); } // Create thread pool this.threadPool = Executors.newScheduledThreadPool(4, r -> { Thread thread = new Thread(r); thread.setName("MyPlugin-Thread-" + thread.threadId()); return thread; }); // Initialize event system this.eventService = new EventService(); // Initialize feature services this.playerStorage = new PlayerJsonStorage(getDataFolder()); this.playerService = new PlayerService(playerStorage); // Initialize scheduled tasks this.autoSaveTask = new AutoSaveTask(playerService, logger); this.cacheCleanupTask = new CacheCleanupTask( playerService.getCache(), 30, logger ); logger.info("MyPlugin initialized"); } @Override public void onEnable() { logger.info("MyPlugin is enabling..."); // Load configuration config.load(); // Schedule periodic tasks autoSaveTask.schedule(threadPool); cacheCleanupTask.schedule(threadPool); // Register event listeners registerListeners(); // Register commands registerCommands(); logger.info("MyPlugin has been enabled"); } @Override public void onDisable() { logger.info("MyPlugin is disabling..."); // Shutdown thread pool threadPool.shutdown(); try { if (!threadPool.awaitTermination(10, TimeUnit.SECONDS)) { threadPool.shutdownNow(); } } catch (InterruptedException e) { threadPool.shutdownNow(); } // Save all data playerService.saveAll(); logger.info("MyPlugin has been disabled"); } private void registerListeners() { // Register event listeners here } private void registerCommands() { // Register commands here } // Public API public static MyPlugin getInstance() { return instance; } public PluginLogger getPluginLogger() { return logger; } public PluginConfig getPluginConfig() { return config; } public ScheduledExecutorService getThreadPool() { return threadPool; } public EventService getEventService() { return eventService; } public PlayerService getPlayerService() { return playerService; } } sun-brightdesktopmoon --- # World Generation Modding | Hytale Modding Documentation **Source:** [The Future of World Generationarrow-up-right](https://hytale.com/news/2026/1/the-future-of-world-generation) **Last Modified:** Friday, January 10, 2026 * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#introduction) Introduction ---------------------------------------------------------------------------------------------------------------------------------------------------------- Hytale's world generation system is one of the most powerful modding features available. With the V2 world generator and visual node editor, you can create custom biomes, terrain, and procedural content without writing code. > **Official Statement:** _"Anyone can create content and modify world-gen without knowing how to code, as V2 can be edited directly in our node editor."_ - Dan (World Generation Engineer) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#world-generator-versions) World Generator Versions ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#v1-current-exploration-mode) V1 (Current - Exploration Mode) * **Development:** 2016-2020 * **Status:** Available at Early Access launch * **Purpose:** Prototype generator with many biomes ready * **Limitations:** Barriers when creating more zones and complex biomes * **Future:** Will eventually stop generating new chunks ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#v2-future-orbis) V2 (Future - Orbis) * **Development:** Since 2021 * **Status:** Under construction, accessible via Gateways * **Purpose:** Next-generation world generator * **Features:** Addresses V1 limitations, enables global design goals * **Release:** Will replace V1 once Orbis is complete * **Compatibility:** Old V1 worlds remain accessible > **Note:** V2 content is currently accessible through Gateways in Exploration mode, allowing early testing. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#key-features-of-v2) Key Features of V2 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#id-1.-pattern-scanning-system) 1\. Pattern Scanning System The pattern scanning system allows precise control over prop placement based on environmental context. **How It Works:** * Configure patterns that determine where props are placed * Search for specific block configurations (e.g., floor = empty block with solid below) * Add additional checks to gather more environmental context * Patterns are fully defined by creators **Example Use Cases:** #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#cave-markers) Cave Markers * **Dark ash trees** spawn only above caves in the deeproot biome * Pattern searches for empty blocks beneath the ground * Players learn that deeproot caves (with special resources) are found under dark ash trees * Creates "Heuristics" - deeper patterns that enhance immersion and gameplay #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#log-bridges) Log Bridges * Bridges spawn across rivers by searching for two shores * Automatically placed where appropriate #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#contextual-vegetation) Contextual Vegetation * Yellow mushrooms and sticks spawn around cedar tree bases * Glowing mushrooms appear only in sheltered areas * Meadows of flowers spawn in dips surrounded by trees and boulders * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#id-2.-code-mods-for-programmers) 2\. Code Mods (For Programmers) **API Features:** * Implement mods that automatically work with the node editor * Plug into vanilla and other modded features * Simple, interconnected components enable strong capabilities * Seamless integration between different mods and base game **Technical Benefits:** * **Automatic multithreading** - APIs handle threading for you * **Full read access** - Access to surrounding world context * **Simplified logic** - Focus on capabilities, not threading * **Extensibility** - Tweak, extend, and add functionality > **Note:** Detailed technical documentation will be released after launch. * * * ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#id-3.-visual-node-editor-no-coding-required) 3\. Visual Node Editor (No Coding Required) The node editor is the primary tool for creating and modifying world generation. **Key Features:** * **Live-Reload:** World updates in-game as you edit * **Visual Workflow:** Build advanced procedural content by linking simple nodes * **No Coding Required:** Accessible with just tutorials and practice * **Powerful:** Bridges gap between developers and creators **What You Can Control:** #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#terrain-shape) Terrain Shape * Control each biome's terrain shape independently * High precision control * Terrain transitions blend features seamlessly between biomes * Customize terrain at biome edges for better transitions #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#material-providers) Material Providers * Fully control which materials terrain is made of * Assemble Material Provider nodes with configurable rules * Access terrain context (block depth, empty space above, etc.) * Example: Grass material restricted to areas with 10+ blocks of air above #### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#props-system) Props System * Generate localized content (POIs, vegetation, decorations) * Precise control over placement rules and distribution * Custom procedural point grid * Customizable rules determine best placement at each point * Content from prefabs or procedural generation **Editing Workflow:** * Each biome is a separate tile (like a jigsaw piece) * Each zone is its own tile in the world patchwork * Adding new biomes or content is straightforward * Same tools used internally by Hytale team * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#official-biomes-available) Official Biomes Available ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **All Orbis biomes will be shared with the community!** You'll be able to: * View all biomes in the node editor * Modify existing biomes * Mix official content with your own creations * Learn from professional implementations **Regions Shown:** * **Emerald Wilds** - Plains-focused biomes * **Whisperfrost Frontier** - Taiga-focused river biomes * **Howling Sands** - Desert biomes with oases * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#experimental-feature-packs) Experimental Feature Packs -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Hytale developers have created experimental terrain packs to showcase possibilities: * **Chaotic Stacked Terrain** - Exploring vertical layering * **Underwater Caves** - Complex cave systems with bracket coral and shipwrecks * **Arches Terrain** - Natural stone arches theme * **Floating Islands** - Sky islands theme * **Procedural Rings** - Alien world with ring systems > **Note:** These are experimental examples, not Adventure mode content. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#modular-asset-structure) Modular Asset Structure -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Design Philosophy:** * Biomes are separate tiles in a zone puzzle * Zones are tiles in the world patchwork * Easy to add and edit terrain, props, biomes, and zones * Same tools creators use as the Hytale team **Benefits:** * Straightforward to add new biomes * Easy to integrate prefabs * Mix and match content from different sources * Modular and flexible system * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#future-roadmap) Future Roadmap -------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#short-term-after-launch) Short-Term (After Launch) * Performance improvements * Upgrading existing features * More modular and flexible asset structure * First-party tutorials and guides * In-depth systems documentation * Performance optimization best practices ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#long-term) Long-Term * **Procedural Rivers and Paths** - Guide players and connect places * **Procedural Architecture** - Generate dungeons, ruins, and buildings * **Organically Growing Fauna** - Increase diversity and coherence * **Waterfalls** - Dynamic water features * **Community Feedback Integration** - Shape future based on suggestions * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#world-designer-job-roles) World Designer Job Roles ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Exciting Opportunity:** > **Official Announcement:** _"Following the early access release, we plan to expand our team by hiring more than 15 World Designers. These roles will be filled primarily from the community."_ - Simon (CEO) **What This Means:** * New job role that hasn't existed in block games before * Artists and game designers can apply * Learn using the same tools Hytale uses internally * Community members can become professional world designers * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#getting-started-with-world-generation) Getting Started with World Generation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#prerequisites) Prerequisites * Understanding of basic Hytale modding concepts * Familiarity with the Asset Editor * Creative mindset for procedural design ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#learning-path) Learning Path 1. **Explore Existing Biomes** - Study official Orbis biomes in the node editor 2. **Start Simple** - Create basic terrain modifications 3. **Learn Patterns** - Experiment with pattern scanning for props 4. **Build Complexity** - Combine multiple systems 5. **Share and Iterate** - Get community feedback ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#tools-youll-use) Tools You'll Use * **Hytale Node Editor** - Primary world-gen tool * **Asset Editor** - For asset configuration * **In-Game Testing** - Live-reload for instant feedback * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#best-practices) Best Practices -------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#design-principles) Design Principles * **Intentional Design** - Curated and procedural balance * **Heuristics** - Create patterns that enhance immersion * **Gameplay First** - Design always serves gameplay * **Resource Balance** - Control resource distribution * **Breadcrumbing** - Guide players to meaningful content ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#technical-considerations) Technical Considerations * **Performance** - Keep generation efficient * **Modularity** - Make content easy to modify and extend * **Compatibility** - Ensure mods work with vanilla and other mods * **Testing** - Use live-reload for rapid iteration * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#community-support) Community Support -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#official-resources) Official Resources * **Tutorials** - First-party guides after launch * **Documentation** - In-depth systems documentation * **Best Practices** - Performance optimization guides * **Examples** - All official Orbis biomes available ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#community-channels) Community Channels * **Discord** - [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Feedback** - Community suggestions shape the future * **Collaboration** - Share techniques and discoveries * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#important-notes) Important Notes ---------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#early-access-reality) Early Access Reality * **Asset structure will change frequently** - Core features still being completed * **Deprecation over removal** - Features being replaced will be deprecated first * **Active development** - Systems under continuous improvement * **Support for creators** - Same support given to internal designers ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#compatibility) Compatibility * **V1 Worlds** - Will remain accessible after V2 launch * **Gateways** - Access V2 content during development * **Pre-release Testing** - Test Orbis before full release * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#vision-statement) Vision Statement ------------------------------------------------------------------------------------------------------------------------------------------------------------------ > _"This new approach to world generation will redefine the block-game genre. For the first time, artists and game designers can take full ownership of world generation, with complete control over the final result. This is a fundamental shift away from a world shaped almost solely by programmers."_ - Simon (CEO) **Goals:** * Hytale feels carefully handcrafted while remaining infinitely procedural * Design always serves gameplay first * Intentionally expansive - alternate worlds, new dimensions, different spaces * Beyond Orbis - new blocks, items, prefabs, zones, regions, biomes, NPCs, quests, stories * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#next-steps) Next Steps ------------------------------------------------------------------------------------------------------------------------------------------------------ 1. **Wait for Early Access** - V2 tools will be available after launch 2. **Study Official Biomes** - Learn from professional implementations 3. **Join Community** - Connect with other world designers 4. **Experiment** - Try creating simple modifications first 5. **Share Your Work** - Contribute to the ecosystem * * * **Related:** [Hytale Modding Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/getting-started/01-hytale-modding-overview) | [Useful Tools & Links](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links) * * * _The Echoes of Orbis and Orbis are just the beginning of an amazing journey._ [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#getting-help) Getting Help ---------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousUseful Tools & Linkschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links) Last updated 2 days ago * [Introduction](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#introduction) * [World Generator Versions](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#world-generator-versions) * [V1 (Current - Exploration Mode)](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#v1-current-exploration-mode) * [V2 (Future - Orbis)](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#v2-future-orbis) * [Key Features of V2](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#key-features-of-v2) * [1\. Pattern Scanning System](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#id-1.-pattern-scanning-system) * [2\. Code Mods (For Programmers)](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#id-2.-code-mods-for-programmers) * [3\. Visual Node Editor (No Coding Required)](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#id-3.-visual-node-editor-no-coding-required) * [Official Biomes Available](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#official-biomes-available) * [Experimental Feature Packs](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#experimental-feature-packs) * [Modular Asset Structure](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#modular-asset-structure) * [Future Roadmap](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#future-roadmap) * [Short-Term (After Launch)](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#short-term-after-launch) * [Long-Term](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#long-term) * [World Designer Job Roles](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#world-designer-job-roles) * [Getting Started with World Generation](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#getting-started-with-world-generation) * [Prerequisites](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#prerequisites) * [Learning Path](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#learning-path) * [Tools You'll Use](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#tools-youll-use) * [Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#best-practices) * [Design Principles](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#design-principles) * [Technical Considerations](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#technical-considerations) * [Community Support](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#community-support) * [Official Resources](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#official-resources) * [Community Channels](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#community-channels) * [Important Notes](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#important-notes) * [Early Access Reality](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#early-access-reality) * [Compatibility](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#compatibility) * [Vision Statement](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#vision-statement) * [Next Steps](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#next-steps) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/16-world-generation-modding#getting-help) sun-brightdesktopmoon sun-brightdesktopmoon --- # Plugin Project Template | Hytale Modding Documentation A minimal, production-ready template for creating Hytale plugins with modern build tools and automated testing. **GitHub Repository:** [realBritakee/hytale-template-pluginarrow-up-right](https://github.com/realBritakee/hytale-template-plugin) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#overview) Overview ------------------------------------------------------------------------------------------------------------------------------------------------------ The Hytale Plugin Template is a ready-to-use project structure that builds immediately without any modifications. It includes modern development tools, automated server testing, and CI/CD workflows to help you start developing plugins quickly. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#key-features) Key Features ✅ **Builds Out-of-the-Box** - Clone and run `./gradlew shadowJar` immediately ✅ **Modern Build System** - Gradle 9.2.0 with Kotlin DSL ✅ **Java 25 Support** - Latest Java features ✅ **Automated Server Testing** - Custom Gradle plugin for one-command testing ✅ **ShadowJar Integration** - Automatic dependency bundling ✅ **CI/CD Ready** - GitHub Actions workflow included ✅ **Minimal Structure** - Only essential files, write your own code * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#quick-start) Quick Start ------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#prerequisites) Prerequisites * **Java 25 JDK** - [Download herearrow-up-right](https://www.oracle.com/java/technologies/downloads/) * **IntelliJ IDEA** - [Download herearrow-up-right](https://www.jetbrains.com/idea/download/) (Community Edition works) * **Git** - [Download herearrow-up-right](https://git-scm.com/) ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-1.-clone-the-template) 1\. Clone the Template ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-2.-build-immediately-no-changes-needed) 2\. Build Immediately (No Changes Needed!) The template works out-of-the-box: Your plugin JAR will be in: `build/libs/TemplatePlugin-1.0.0.jar` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-3.-customize-your-plugin) 3\. Customize Your Plugin When ready to customize, edit these files: `**settings.gradle.kts**`**:** `**gradle.properties**`**:** `**src/main/resources/manifest.json**`**:** **Rename the main plugin class:** * Rename `src/main/java/com/example/templateplugin/TemplatePlugin.java` * Update package name to match your `pluginGroup` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-4.-implement-your-plugin) 4\. Implement Your Plugin Write your plugin code in `src/main/java/`: * Commands * Event listeners * Services * Storage * Utilities See [Advanced Plugin Patterns](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns) and [Common Plugin Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features) for examples. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#project-structure) Project Structure ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Note:** This is a minimal template. Create your own folder structure as needed: * `commands/` - For command implementations * `listeners/` - For event listeners * `services/` - For business logic * `storage/` - For data persistence * `utils/` - For utility classes * `config/` - For configuration management * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#automated-server-testing) Automated Server Testing -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The template includes a custom Gradle plugin for automated server testing. This feature is documented in detail in [Gradle Automation & Testing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing) . ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#quick-usage) Quick Usage **Configure in** `**build.gradle.kts**`**:** **Run the server:** ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#what-it-does) What It Does 1. ✅ Downloads the Hytale server JAR (cached for future runs) 2. ✅ Compiles your plugin with `shadowJar` 3. ✅ Copies the plugin to `run/plugins/` 4. ✅ Starts the server with interactive console 5. ✅ Supports debug mode: `./gradlew runServer -Pdebug` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#features) Features * **Smart Caching** - Downloads server JAR once, reuses forever * **Auto-Deploy** - Builds and deploys your plugin automatically * **Interactive Console** - Type commands directly in the terminal * **Debug Support** - Connect your IDE debugger to port 5005 * **Clean Workspace** - Server files in `run/` directory (gitignored) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#development-workflow) Development Workflow ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#building) Building ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#testing) Testing ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#debugging) Debugging * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#adding-dependencies) Adding Dependencies ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Edit `build.gradle.kts`: ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#dependency-relocation) Dependency Relocation To avoid conflicts with other plugins, relocate your dependencies: * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#ci-cd-with-github-actions) CI/CD with GitHub Actions ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The template includes a GitHub Actions workflow (`.github/workflows/build.yml`) that: 1. ✅ Builds your plugin on every push 2. ✅ Runs tests 3. ✅ Uploads artifacts 4. ✅ Creates releases when you tag ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#creating-a-release) Creating a Release GitHub Actions will automatically build and create a release with your plugin JAR. ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#workflow-features) Workflow Features * **Multi-OS Testing** - Builds on Ubuntu, Windows, and macOS * **Java 25 Support** - Uses the latest Java version * **Artifact Upload** - Saves built JARs for download * **Release Automation** - Automatically creates GitHub releases * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#customization-examples) Customization Examples ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#custom-build-configuration) Custom Build Configuration **Change Java version:** **Add custom repositories:** ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#custom-gradle-tasks) Custom Gradle Tasks **Add a custom task:** * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#recommended-folder-structure) Recommended Folder Structure ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Once you start developing, organize your code like this: See [Advanced Plugin Patterns](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns) for implementation details. * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#best-practices) Best Practices ------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#do) ✅ DO: * Use the Service-Storage pattern for data management * Write unit tests for your business logic * Use structured logging (not `System.out.println`) * Handle errors gracefully with try-catch blocks * Document your public API with JavaDoc * Version your releases semantically (1.0.0, 1.1.0, etc.) * Use dependency injection where possible * Keep your main class minimal ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#dont) ❌ DON'T: * Hardcode configuration values * Block the main thread with heavy operations * Ignore exceptions or use empty catch blocks * Use deprecated APIs * Commit sensitive data (API keys, passwords) * Mix business logic with storage logic * Use static variables for state management * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#build-fails) Build Fails ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#server-wont-start) Server Won't Start 1. Check that `jarUrl` in `build.gradle.kts` is correct 2. Verify Java 25 is installed: `java -version` 3. Check logs in `run/logs/` 4. Ensure the server JAR is compatible ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#plugin-not-loading) Plugin Not Loading 1. Verify `manifest.json` has correct `Main` class path 2. Check server logs for errors 3. Ensure all dependencies are bundled in JAR 4. Verify the plugin JAR is in `run/plugins/` ### [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#gradle-daemon-issues) Gradle Daemon Issues * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#migration-from-other-templates) Migration from Other Templates -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you're migrating from another template: 1. **Copy your source code** to `src/main/java/` 2. **Update** `**manifest.json**` with your plugin metadata 3. **Copy dependencies** to `build.gradle.kts` 4. **Update package names** to match your group 5. **Test the build** with `./gradlew shadowJar` * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#related-documentation) Related Documentation -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * [Getting Started with Plugins](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/07-getting-started-with-plugins) - Plugin basics * [Advanced Plugin Patterns](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/12-advanced-plugin-patterns) - Architecture patterns * [Common Plugin Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/14-common-plugin-features) - Practical features * [Gradle Automation & Testing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/13-gradle-automation-testing) - Server testing details * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#support-and-resources) Support and Resources -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **GitHub Repository:** [realBritakee/hytale-template-pluginarrow-up-right](https://github.com/realBritakee/hytale-template-plugin) * **Issues:** [GitHub Issuesarrow-up-right](https://github.com/realBritakee/hytale-template-plugin/issues) * **Documentation:** [Hytale Modding Documentation](https://britakee-studios.gitbook.io/hytale-modding-documentation) * * * [hashtag](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#getting-help) Getting Help -------------------------------------------------------------------------------------------------------------------------------------------------------------- **Official Channels:** * **Discord:** [Official Hytale Discordarrow-up-right](https://discord.gg/hytale) * **Blog:** [Hytale Newsarrow-up-right](https://hytale.com/news) [PreviousBootstrap/Early Pluginschevron-left](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/09-bootstrap-early-plugins) [NextUseful Tools & Linkschevron-right](https://britakee-studios.gitbook.io/hytale-modding-documentation/resources-and-tools/10-useful-tools-and-links) Last updated 2 days ago * [Overview](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#overview) * [Key Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#key-features) * [Quick Start](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#quick-start) * [Prerequisites](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#prerequisites) * [1\. Clone the Template](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-1.-clone-the-template) * [2\. Build Immediately (No Changes Needed!)](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-2.-build-immediately-no-changes-needed) * [3\. Customize Your Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-3.-customize-your-plugin) * [4\. Implement Your Plugin](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#id-4.-implement-your-plugin) * [Project Structure](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#project-structure) * [Automated Server Testing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#automated-server-testing) * [Quick Usage](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#quick-usage) * [What It Does](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#what-it-does) * [Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#features) * [Development Workflow](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#development-workflow) * [Building](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#building) * [Testing](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#testing) * [Debugging](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#debugging) * [Adding Dependencies](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#adding-dependencies) * [Dependency Relocation](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#dependency-relocation) * [CI/CD with GitHub Actions](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#ci-cd-with-github-actions) * [Creating a Release](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#creating-a-release) * [Workflow Features](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#workflow-features) * [Customization Examples](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#customization-examples) * [Custom Build Configuration](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#custom-build-configuration) * [Custom Gradle Tasks](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#custom-gradle-tasks) * [Recommended Folder Structure](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#recommended-folder-structure) * [Best Practices](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#best-practices) * [✅ DO:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#do) * [❌ DON'T:](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#dont) * [Troubleshooting](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#troubleshooting) * [Build Fails](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#build-fails) * [Server Won't Start](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#server-wont-start) * [Plugin Not Loading](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#plugin-not-loading) * [Gradle Daemon Issues](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#gradle-daemon-issues) * [Migration from Other Templates](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#migration-from-other-templates) * [Related Documentation](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#related-documentation) * [Support and Resources](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#support-and-resources) * [Getting Help](https://britakee-studios.gitbook.io/hytale-modding-documentation/plugins-java-development/15-plugin-project-template#getting-help) sun-brightdesktopmoon Copy git clone https://github.com/realBritakee/hytale-template-plugin.git cd hytale-template-plugin Copy # Windows gradlew.bat shadowJar # Linux/Mac ./gradlew shadowJar Copy rootProject.name = "your-plugin-name" Copy pluginGroup=com.yourname pluginVersion=1.0.0 pluginDescription=Your plugin description Copy { "Group": "YourName", "Name": "YourPluginName", "Main": "com.yourname.yourplugin.YourPlugin" } Copy hytale-template-plugin/ ├── .github/workflows/ │ └── build.yml # CI/CD workflow ├── buildSrc/ │ ├── build.gradle.kts # Custom plugin configuration │ └── src/main/kotlin/ │ └── RunHytalePlugin.kt # Automated server testing ├── gradle/wrapper/ │ ├── gradle-wrapper.jar # Gradle wrapper binary │ └── gradle-wrapper.properties # Gradle 9.2.0 configuration ├── src/main/ │ ├── java/com/example/templateplugin/ │ │ └── TemplatePlugin.java # Minimal main class (example) │ └── resources/ │ ├── manifest.json # Plugin metadata │ └── config.json # Example configuration ├── .gitignore # Git ignore rules ├── build.gradle.kts # Build configuration ├── gradle.properties # Project properties ├── gradlew # Gradle wrapper (Unix) ├── gradlew.bat # Gradle wrapper (Windows) ├── settings.gradle.kts # Project settings ├── LICENSE # MIT License └── README.md # Documentation Copy runHytale { jarUrl = "url to hytale server jar" } Copy # Windows gradlew.bat runServer # Linux/Mac ./gradlew runServer Copy # Compile only ./gradlew compileJava # Build plugin JAR ./gradlew shadowJar # Clean and rebuild ./gradlew clean shadowJar Copy # Run server with your plugin ./gradlew runServer # Run unit tests ./gradlew test # Clean test server rm -rf run/ Copy # Run server in debug mode ./gradlew runServer -Pdebug # Then connect your IDE debugger to localhost:5005 Copy dependencies { // Hytale API (provided by server) compileOnly(files("libs/hytale-server.jar")) // Your dependencies (will be bundled) implementation("com.google.code.gson:gson:2.10.1") implementation("org.jetbrains:annotations:24.1.0") // Test dependencies testImplementation("org.junit.jupiter:junit-jupiter:5.10.0") testRuntimeOnly("org.junit.platform:junit-platform-launcher") } Copy tasks { shadowJar { // Relocate dependencies to avoid conflicts relocate("com.google.gson", "com.yourplugin.libs.gson") relocate("org.apache.commons", "com.yourplugin.libs.commons") // Minimize JAR size (removes unused classes) minimize() } } Copy git tag v1.0.0 git push origin v1.0.0 Copy java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } } tasks { compileJava { options.release = 21 } } Copy repositories { mavenLocal() mavenCentral() maven("https://repo.example.com/releases") } Copy tasks.register("copyToServer") { group = "deployment" description = "Copy plugin to local server" doLast { val serverDir = File("C:/HytaleServer/plugins") val pluginJar = tasks.shadowJar.get().outputs.files.singleFile pluginJar.copyTo(File(serverDir, pluginJar.name), overwrite = true) println("Plugin copied to server!") } } Copy src/main/java/com/yourname/yourplugin/ ├── YourPlugin.java # Main class ├── commands/ │ ├── CommandManager.java # Command registration │ ├── HelpCommand.java │ └── ReloadCommand.java ├── listeners/ │ ├── PlayerJoinListener.java │ └── BlockBreakListener.java ├── services/ │ ├── PlayerService.java # Business logic │ └── DataService.java ├── storage/ │ ├── PlayerStorage.java # Data persistence │ └── ConfigStorage.java ├── config/ │ ├── PluginConfig.java # Configuration classes │ └── Messages.java └── utils/ ├── TextUtils.java # Utility methods └── TimeUtils.java Copy # Clean and rebuild ./gradlew clean build --refresh-dependencies # Check Gradle version ./gradlew --version # Update Gradle wrapper ./gradlew wrapper --gradle-version=9.2.0 Copy # Stop all Gradle daemons ./gradlew --stop # Rebuild ./gradlew clean shadowJar sun-brightdesktopmoon ---