The Hytale server is the engine of your virtual world, managing everything from player interactions to terrain generation. An in-depth knowledge of its structure will allow you to get the most out of the customization capabilities offered by the game.
Whether you want to add new blocks, unique items, or complex game mechanics, everything starts with the correct placement of files.
Essential Hytale server folders and files
Here are the main folders and files you will find at the root of your Hytale server installation, along with their roles.
| Folder/File | Function | Relevant details |
HytaleServer.jar | The main server executable program. | This is the heart of your Hytale world, launched via Java 25. It contains the fundamental code for game mechanics, world creation, and player connection management. |
Assets.zip | Compressed archive containing all essential game resources. | Includes 3D models, base textures, sounds, element configurations (blocks, items, non-player characters), and default world generation systems. Without this file, the server will not start correctly. |
config.json | Global server configuration file. | Contains general server settings, such as the server name, network port (default 5520 UDP), Java virtual machine arguments, and other tweaks related to performance and basic features. |
permissions.json | Manages player and group permissions. | Defines which players have access to which commands or features. The permission system allows assigning specific privileges (e.g., access to certain admin commands). It can also support custom storage mechanisms. |
whitelist.json | List of players allowed to connect to the server. | Allows restricting access to the server to a specific group of players using their unique identifiers. |
bans.json | List of players banned from the server. | Records bans, including reasons and duration. A player whose name appears here cannot connect. |
mods/ (or plugins/) | Contains server-side modifications (Java extensions). | This is the directory where you drop the .jar files of your extensions or other additions. These programs enrich server functionalities (mini-games, economy, chat management, for example a chat filter). The server loads them automatically at startup. |
earlyplugins/ | Folder for early-loading extensions. | Intended for extensions that must run very early in the server’s lifecycle, often for low-level modifications or complex integrations. Its use is more advanced and requires a fine understanding of server operations. |
logs/ | Contains server activity log files. | Records all events, messages, and errors generated by the server and its extensions. This folder is essential for debugging and tracking activities. Detailed information can help identify the source of problems. |
universe/ | Contains data for all playable worlds on the server. | This folder is the root of your world saves. Each world has its own subfolder here, containing its own configurations and specific data, such as player progress and saved structures. |
.cache/ | Cache for optimized server files. | Stores optimized versions of certain files to improve startup times and general server performance. It is generally unnecessary and inadvisable to modify this folder manually. |
World structure (universe/worlds/<WorldName>/)
Each world you create or use on your Hytale server has its own file tree, managing its particularities and specific data.
| Folder/File | Function | Relevant details |
<WorldName>/ | Folder dedicated to a specific world (e.g., lobby, creative, pvp_arena). | Each world runs on its own execution thread. It contains all information unique to that world, from how it is generated to its current state. |
config.json | World-specific configuration. | Defines world creation rules (generator type, seed, water level), game state (PvP enabled, fall damage), and required extensions for this world. This configuration is loaded at world startup. |
regions/ | Stores generated terrain region data. | Contains blocks, structures (prefabs), and information on world portions (chunks). This is where terrain and structure modifications are saved. Terrain creation uses density functions to define topography and material providers for block types. |
playerdata/ | Stores individual player data in this world. | Contains players’ inventories, their saved positions, their statistics, and other information specific to their progress in this world. |
entities/ | Saves for non-player entities (characters, creatures, special items). | Stores the state of dynamic entities that are not blocks or players, including their attributes, artificial intelligence, and movements. |
prefabs/ | Contains definitions of prefab structures specific to this world. | “Prefabs” are reusable constructions (villages, dungeons) that can be placed during world generation or via editing tools. |
logs/ | Logs specific to this world. | Records events and information unique to this world, useful for debugging or analyzing the performance of a specific world. |
data/ | Stores various world-specific data for extensions. | Can contain inventory information, quests, or other dynamic data managed by extensions for this world. |
Managing plugins/mods and custom content
Customizing your Hytale server involves adding content “packs” and “plugins” (mods).
| Folder/File | Function | Relevant details |
[ExtensionName].jar | Executable file of the Java extension. | This file is placed in the mods/ folder of the server. It contains all the compiled code of your extension, its logic, and sometimes included resources (graphic or data elements). |
manifest.json (in the .jar or pack) | Describes the extension and its requirements. | Indicates the extension name, version, author, description, main class (Main), and necessary dependencies. It also signals if the extension includes a resource set (IncludesAssetPack: true), which is common for custom content (blocks, items). |
Common/ (in the .jar or pack) | Shared resources (client-side). | Contains files that will be sent to clients for display: 3D models (.blockymodel), textures (.png), animations (.blockyanim), icons. These elements are essential for players to correctly see custom items and blocks. Textures can be stored in a block texture folder. |
Server/ (in the .jar or pack) | Resource definitions (server-side). | Contains JSON/YAML definitions for blocks (Item/Items/*.json), item categories (Item/Category/*.json), and translation files (Languages/en-US/*.lang). These files control the behavior and properties of game elements. Subfolders like Server/Languages/ and Server/Item/ are typical. |
Libs/ (in the .jar) | Included third-party Java libraries. | Often, Java extensions use external libraries. They are usually included directly in the extension’s .jar file (via packaging techniques) to avoid dependency conflicts between different extensions. |
assets/ (in the .jar) | Root for embedded resources. | If an extension includes its own resources, they are often structured like assets/[your_namespace]/. This allows the extension to distribute content (like models or textures) directly with its logic. |
earlyplugins/ | Early start extensions. | For extensions that require loading before most others, allowing deeper server modifications or management of critical features from the very beginning. |