Skip to main content

Overview

The WorldConverter class is the primary interface for converting Minecraft worlds between different formats. It provides comprehensive configuration options for controlling all aspects of the conversion process, including which game elements to process, dimension mapping, and pruning.

Class Definition

package com.hivemc.chunker.conversion;

public class WorldConverter implements Converter
Location: cli/src/main/java/com/hivemc/chunker/conversion/WorldConverter.java:44

Constructor

sessionID
UUID
required
Unique identifier for the conversion session
public WorldConverter(UUID sessionID)

Core Methods

convert()

Create and start the conversion task.
public TrackedTask<Void> convert(
    @NotNull LevelReader reader, 
    @NotNull LevelWriter writer
)
reader
LevelReader
required
The reader to use for reading the input world format
writer
LevelWriter
required
The writer to use for writing the output world format
TrackedTask<Void>
TrackedTask<Void>
A task that completes when the conversion finishes. Can be used for progress tracking.
Location: WorldConverter.java:518

cancel()

Cancel the conversion task.
public CompletableFuture<Void> cancel(@Nullable Throwable fatalException)
fatalException
Throwable
An exception to use as the reason for cancellation (optional)
CompletableFuture<Void>
CompletableFuture<Void>
A future that completes when the environment has fully cancelled
Location: WorldConverter.java:612

Configuration Methods

Processing Options

Control which game elements are converted:
public void setProcessMaps(boolean processMaps)

Advanced Options

setDimensionMapping()

Map input dimensions to output dimensions. Dimensions not in the map are discarded.
public void setDimensionMapping(
    @Nullable Map<Dimension, Dimension> dimensionMapping
)
dimensionMapping
Map<Dimension, Dimension>
Dimension mappings, or null to keep input dimensions as-is
Location: WorldConverter.java:128

setPruningConfigs()

Set regions to include or exclude from the conversion.
public void setPruningConfigs(
    @Nullable Map<Dimension, PruningConfig> pruningConfigs
)
pruningConfigs
Map<Dimension, PruningConfig>
Pruning configurations per dimension, or null for no pruning
Location: WorldConverter.java:118

setChangedSettings()

Apply custom settings to the output level.dat file.
public void setChangedSettings(@Nullable JsonObject changedSettings)
changedSettings
JsonObject
Key-value settings to override in the level.dat
Location: WorldConverter.java:498

setBlockMappings()

Provide custom block and item mappings.
public void setBlockMappings(@Nullable MappingsFileResolvers blockMappings)
blockMappings
MappingsFileResolvers
Custom mappings to use, or null for default mappings
Location: WorldConverter.java:420

setProcessColumnPreTransform()

Enable pre-transform processing for block connections and neighbor chunk fetching.
public void setProcessColumnPreTransform(boolean processColumnPreTransform)
processColumnPreTransform
boolean
Whether to enable pre-transform processing (default: true)
Location: WorldConverter.java:245

setLevelDBCompaction()

Enable LevelDB compaction after writing (Bedrock only).
public void setLevelDBCompaction(boolean levelDBCompaction)
levelDBCompaction
boolean
Whether to compact LevelDB after conversion
Location: WorldConverter.java:137

setPreventYBiomeBlending()

Prevent vertical biome blending (Java only).
public void setPreventYBiomeBlending(boolean preventYBiomeBlending)
preventYBiomeBlending
boolean
Whether to prevent Y-axis biome blending
Location: WorldConverter.java:155

setAllowNBTCopying()

Allow copying NBT data from input to output when formats match.
public void setAllowNBTCopying(boolean allowNBTCopying)
allowNBTCopying
boolean
Whether to allow NBT copying for same-format conversions
Location: WorldConverter.java:227

setDiscardEmptyChunks()

Remove empty chunks from the output.
public void setDiscardEmptyChunks(boolean discardEmptyChunks)
discardEmptyChunks
boolean
Whether to discard empty chunks
Location: WorldConverter.java:236

setCustomIdentifiers()

Allow conversion of custom block/item identifiers.
public void setCustomIdentifiers(boolean customIdentifiers)
customIdentifiers
boolean
Whether to allow custom identifiers (default: true)
Location: WorldConverter.java:254

Status Methods

isCancelled()

Check if the conversion was cancelled.
public boolean isCancelled()
Returns: true if the conversion was cancelled Location: WorldConverter.java:323

isExceptions()

Check if any exceptions occurred during conversion.
public boolean isExceptions()
Returns: true if any exceptions were logged during conversion Location: WorldConverter.java:332

getMissingIdentifiers()

Get all missing mappings found during conversion.
public Multimap<MissingMappingType, String> getMissingIdentifiers()
Returns: A multimap of missing identifiers grouped by type (BLOCK, ITEM, ENTITY, etc.) Location: WorldConverter.java:341

Usage Example

import com.hivemc.chunker.conversion.WorldConverter;
import com.hivemc.chunker.conversion.encoding.EncodingType;
import com.hivemc.chunker.conversion.encoding.base.Version;
import java.io.File;
import java.util.UUID;

// Create a converter with a unique session ID
WorldConverter converter = new WorldConverter(UUID.randomUUID());

// Configure the conversion
converter.setProcessMaps(true);
converter.setProcessEntities(true);
converter.setProcessBlockEntities(true);
converter.setLevelDBCompaction(true);
converter.setDiscardEmptyChunks(true);

// Create reader and writer
File inputDir = new File("path/to/java/world");
File outputDir = new File("path/to/bedrock/world");

LevelReader reader = EncodingType.JAVA
    .createReader(inputDir, converter)
    .orElseThrow();

LevelWriter writer = EncodingType.BEDROCK
    .createWriter(outputDir, new Version(1, 20, 0), converter)
    .orElseThrow();

// Start the conversion
TrackedTask<Void> task = converter.convert(reader, writer);

// Wait for completion
task.getFuture().join();

// Check for issues
if (converter.isExceptions()) {
    System.err.println("Conversion completed with errors");
    converter.getMissingIdentifiers().forEach((type, id) -> {
        System.err.println("Missing " + type + ": " + id);
    });
}

Constants

SIGNAL_COMPACTION
String
Signal name used to indicate compaction has started: "signal_compaction"
Location: WorldConverter.java:48

See Also

Build docs developers (and LLMs) love