Skip to main content

​
Overview

The Dimension enum and dimension mapping configuration allow you to control how dimensions (Overworld, Nether, The End) are converted between Java and Bedrock editions. You can remap dimensions to different targets or skip conversion of specific dimensions.

​
Enum: Dimension

Package: com.hivemc.chunker.conversion.intermediate.world 
public enum Dimension
The different types of dimensions present in Minecraft.

​
Dimension Values

OVERWORLD

Java ID: 0
Bedrock ID: 0
Identifier: minecraft:overworld

NETHER

Java ID: -1
Bedrock ID: 1
Identifier: minecraft:the_nether

THE_END

Java ID: 1
Bedrock ID: 2
Identifier: minecraft:the_end

​
Methods

​
getJavaID()

The Java ID for the dimension.
​
return
byte
The ID based on 0 being overworld and -1 being the nether
Dimension.OVERWORLD.getJavaID();  // Returns 0
Dimension.NETHER.getJavaID();     // Returns -1
Dimension.THE_END.getJavaID();    // Returns 1

​
getBedrockID()

The Bedrock ID for the dimension.
​
return
byte
The indexed ID for the dimension
Dimension.OVERWORLD.getBedrockID();  // Returns 0
Dimension.NETHER.getBedrockID();     // Returns 1
Dimension.THE_END.getBedrockID();    // Returns 2

​
getIdentifier()

Get the namespaced identifier for the dimension.
​
return
String
The namespaced identifier
Dimension.OVERWORLD.getIdentifier();  // Returns "minecraft:overworld"
Dimension.NETHER.getIdentifier();     // Returns "minecraft:the_nether"
Dimension.THE_END.getIdentifier();    // Returns "minecraft:the_end"

​
Static Factory Methods

​
fromJava(byte id, Dimension fallback)

Create a dimension from a Java ID.
​
id
byte
required
The input Java dimension ID
​
fallback
Dimension
required
The fallback to use if the ID wasn’t found
​
return
Dimension
The dimension or fallback if it wasn’t found
Dimension dim = Dimension.fromJava((byte) 0, Dimension.OVERWORLD);

​
fromBedrock(byte id, Dimension fallback)

Create a dimension from a Bedrock ID.
​
id
byte
required
The input Bedrock dimension ID
​
fallback
Dimension
required
The fallback to use if the ID wasn’t found
​
return
Dimension
The dimension or fallback if it wasn’t found
Dimension dim = Dimension.fromBedrock((byte) 1, Dimension.NETHER);

​
fromJavaNBT(Tag tag, Dimension fallback)

Get the dimension based on a Java NBT tag.
​
tag
Tag<?>
required
The tag to use (string, byte or integer)
​
fallback
Dimension
required
The fallback dimension to use if the tag can’t be parsed or the ID is invalid
​
return
Dimension
The dimension if it was parsed, otherwise the fallback
StringTag tag = new StringTag("minecraft:the_nether");
Dimension dim = Dimension.fromJavaNBT(tag, Dimension.OVERWORLD);

​
fromBedrockNBT(Tag tag, Dimension fallback)

Get the dimension based on a Bedrock NBT tag.
​
tag
Tag<?>
required
The tag to use (string, byte or integer)
​
fallback
Dimension
required
The fallback dimension to use if the tag can’t be parsed or the ID is invalid
​
return
Dimension
The dimension if it was parsed, otherwise the fallback

​
Dimension Mapping Configuration

Dimension mappings control how input dimensions are converted to output dimensions. This is configured as a JSON object mapping input dimensions to output dimensions.

​
JSON Format

{
  "OVERWORLD": "OVERWORLD",
  "NETHER": "NETHER",
  "THE_END": "THE_END"
}

​
Usage Examples

​
Standard Mapping (Default)

Map each dimension to itself: 
{
  "OVERWORLD": "OVERWORLD",
  "NETHER": "NETHER",
  "THE_END": "THE_END"
}
This is the default behavior if no dimension mapping is specified.

​
Swap Nether and End

Swap the Nether and The End dimensions: 
{
  "OVERWORLD": "OVERWORLD",
  "NETHER": "THE_END",
  "THE_END": "NETHER"
}

​
Combine Dimensions

Merge all dimensions into the Overworld: 
{
  "OVERWORLD": "OVERWORLD",
  "NETHER": "OVERWORLD",
  "THE_END": "OVERWORLD"
}
Combining dimensions may cause chunk coordinate conflicts. Use with caution.

​
Skip Dimensions

Convert only the Overworld, skip Nether and End: 
{
  "OVERWORLD": "OVERWORLD"
}
Dimensions not listed in the mapping will not be converted.

​
Nether-Only Conversion

Convert only the Nether: 
{
  "NETHER": "NETHER"
}

​
CLI Integration

Provide dimension mappings to the CLI using the --dimensionMappings parameter: 
java -jar Chunker.jar \
  --inputDirectory myWorld \
  --outputFormat JAVA_1_20_5 \
  --outputDirectory converted \
  --dimensionMappings dimension_mappings.chunker.json

​
Programmatic Usage

Integrate dimension mapping into the WorldConverter: 
import com.hivemc.chunker.conversion.WorldConverter;
import com.hivemc.chunker.conversion.intermediate.world.Dimension;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

// Create converter
WorldConverter worldConverter = new WorldConverter(UUID.randomUUID());

// Create dimension mapping
Map<Dimension, Dimension> dimensionMapping = new HashMap<>();
dimensionMapping.put(Dimension.OVERWORLD, Dimension.OVERWORLD);
dimensionMapping.put(Dimension.NETHER, Dimension.NETHER);
dimensionMapping.put(Dimension.THE_END, Dimension.THE_END);

// Apply dimension mapping
worldConverter.setDimensionMapping(dimensionMapping);

​
Advanced Example: Conditional Mapping

import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.io.FileReader;
import java.lang.reflect.Type;

// Load from JSON file
Type type = new TypeToken<Map<Dimension, Dimension>>() {}.getType();
Map<Dimension, Dimension> dimensionMapping;

try (FileReader reader = new FileReader("dimension_mappings.chunker.json")) {
    dimensionMapping = new Gson().fromJson(reader, type);
    worldConverter.setDimensionMapping(dimensionMapping);
} catch (Exception e) {
    System.err.println("Failed to load dimension mappings: " + e.getMessage());
    // Use default mapping
    dimensionMapping = new HashMap<>();
    dimensionMapping.put(Dimension.OVERWORLD, Dimension.OVERWORLD);
    dimensionMapping.put(Dimension.NETHER, Dimension.NETHER);
    dimensionMapping.put(Dimension.THE_END, Dimension.THE_END);
    worldConverter.setDimensionMapping(dimensionMapping);
}

​
Dimension IDs Reference

Java and Bedrock use different ID schemes for dimensions. Chunker handles the conversion automatically.
DimensionJava IDBedrock IDIdentifier
Overworld00minecraft:overworld
Nether-11minecraft:the_nether
The End12minecraft:the_end

​
Common Use Cases

​
Server Migration

When migrating a server from Java to Bedrock, keep all dimensions: 
{
  "OVERWORLD": "OVERWORLD",
  "NETHER": "NETHER",
  "THE_END": "THE_END"
}

​
Creative World Export

Export only the Overworld for a creative build: 
{
  "OVERWORLD": "OVERWORLD"
}

​
Custom Dimension Layouts

For custom modpack/plugin worlds with alternative dimension usage: 
{
  "OVERWORLD": "OVERWORLD",
  "NETHER": "OVERWORLD",
  "THE_END": "OVERWORLD"
}

​
Combining with Pruning

Dimension mappings work together with pruning configurations: 
// Set up dimension mapping (convert only Overworld and Nether)
Map<Dimension, Dimension> dimMapping = new HashMap<>();
dimMapping.put(Dimension.OVERWORLD, Dimension.OVERWORLD);
dimMapping.put(Dimension.NETHER, Dimension.NETHER);
worldConverter.setDimensionMapping(dimMapping);

// Set up pruning for each dimension
Map<Dimension, PruningConfig> pruning = new HashMap<>();

// Prune Overworld to spawn area
List<PruningRegion> overworldRegions = new ArrayList<>();
overworldRegions.add(new PruningRegion(-20, -20, 20, 20));
pruning.put(Dimension.OVERWORLD, new PruningConfig(true, overworldRegions));

// Prune Nether to smaller area
List<PruningRegion> netherRegions = new ArrayList<>();
netherRegions.add(new PruningRegion(-10, -10, 10, 10));
pruning.put(Dimension.NETHER, new PruningConfig(true, netherRegions));

worldConverter.setPruningConfigs(pruning);

​
Best Practices

Avoid mapping multiple input dimensions to the same output dimension unless you understand the coordinate implications.
Always test dimension mappings on backup worlds first, as incorrect mappings can corrupt world data.
Remember that portals and other cross-dimension features may not work correctly with custom mappings.
If using non-standard dimension mappings, document why for future reference.

​
Limitations

Portal Connections: Custom dimension mappings may break portal links between dimensions.
Coordinate Systems: The Nether uses a 1:8 coordinate ratio with the Overworld. Remapping may affect portal calculations.
Structure Generation: Some structures depend on specific dimensions. Remapping may cause generation issues.

MappingsFile

Custom block and item mappings

Pruning Config

Control which regions to keep or remove

Build docs developers (and LLMs) love

Get started for freeTalk to us