Understanding Minecraft to Hytale mapping
Updated on February 16, 2026
The Hytale Converter is a tool designed to automatically convert Minecraft maps into Hytale maps.
The core idea and strength of the converter is to provide an exhaustive mapping of all Minecraft blocks to Hytale blocks. While the concept sounds simple, it actually comes with several challenges:
Hytale currently offers far fewer block variations than Minecraft and the two games have very different internal rules and structures, which forced us to dive deeply into how Hytale prefabs are built.
Why choose automatic mapping?
The Hytale Converter is designed to be as easy to use as possible, so users can convert maps quickly and effortlessly.
Our goal is to:
- Provide users with a ready-made automatic mapping
- Let them do only minor touch-ups in-game, instead of manually mapping ~6,600 blocks
and handling complex block states
This approach:
- Dramatically reduces friction
- Saves a huge amount of time
- Ensures a high-quality visual result by choosing the best-looking blocks by default
If users want full control, they can still replace blocks manually using the replace tool available in-game, more over we made 2 mappings in order to satisfy all users : the accuracy one and the color one for builders.
Mappings are showcased in the converter’s tutorial video.
How does the converter handle Minecraft to Hytale block matching?
Minecraft is not a simple “one block equals one block” system.
Each block can have multiple states (orientation, variant, level, etc.), leading to thousands of possible
combinations, far more than what Hytale currently supports. Our approach focuses on three key principles:
- Meaning and category first :
Blocks are grouped by purpose into large families such as wood, stone, ores, precious blocks and
decorative blocks.
- Visual similarity over perfect equivalence :
When no direct match exists, we prioritize color, overall appearance and visual coherence.
- Always favor completeness :
Minecraft blocks should never be converted into empty space.
For example, glass panes do not yet exist in Hytale, so they are replaced with ice blocks.
This ensures structures remain complete and usable in-game.
Handling rotations and orientations
Block conversion becomes significantly more complex once rotations and orientations are involved.
Some Minecraft blocks have dozens of possible states.
Stairs alone can have around 40 variants depending on direction, shape and position.
Minecraft uses explicit directional properties such as north, south, east and west,
while Hytale relies on numeric rotation values like: « rotation »:1
There is no universal mapping between these systems.
The same rotation value can represent different directions depending on the block.
Ladders are a good example where rotation logic differs from most other blocks.
To ensure reliability, rotations must often be tested block by block directly in-game.
Our internal mapping document now contains over 7,000 lines to guarantee consistent results.
Understanding Hytale prefabs
A Hytale prefab is a JSON file containing the list of blocks in a selection,
their coordinates and their properties such as rotation and attributes.Two main sections exist: « blocks » for standard blocks and « fluids » for water and lava
The converter explicitly separates these categories to ensure clean in-game results
and to properly handle special cases like waterlogged blocks.
Special cases and edge behaviors
Some blocks cannot be converted naively because their behavior depends on neighboring blocks.
These edge cases are what differentiate a basic converter from a tool that respects
Hytale’s actual in-game behavior.
- Chests can be single or double :
The converter automatically detects double chests and merges them
correctly during export. On the Hytale side, the « AllowViewing » attribute must be set to true, otherwise the chest cannot be opened in-game.
- Beds :
In Minecraft, beds are made of two blocks (head and foot).
The converter detects the correct part to avoid duplication and rebuilds a proper Hytale bed.
JSON optimization
Unlike Minecraft schematics (NBT), Hytale prefabs have no native compression.
Without optimization, prefab files can become very large.
To address this, the generated JSON is condensed and optimized as much as possible,
significantly reducing disk space usage on users’ servers.