Skip to main content

​
Overview

The MappingsFile class provides a powerful API for customizing how blocks and items are converted between Java and Bedrock editions. It uses a JSON-based format with three main components: identifier mappings, state mappings, and type mappings.

​
Class: MappingsFile

Package: com.hivemc.chunker.mapping 
public class MappingsFile
Represents a JSON formatted file which contains mappings that can turn item/block identifiers into another.

​
Components

Identifier Mappings

Turn an identifier into another and can introduce or filter based on old_state_values/new_state_values

State Mappings

Groups of states commonly used together (e.g., all stairs)

Type Mappings

Mapping of input values to output values

​
Loading Mappings

​
load(File file)

Load a MappingsFile from a JSON file.
​
file
File
required
The input JSON file in the format of a mappings file
​
return
MappingsFile
The loaded MappingsFile
MappingsFile mappings = MappingsFile.load(new File("custom_mappings.json"));

​
load(String json)

Load a MappingsFile from a JSON string.
​
json
String
required
The input JSON in the format of a mappings file
​
return
MappingsFile
The loaded MappingsFile
String json = "{\"identifiers\": [], \"state_lists\": {}, \"types\": {}}";
MappingsFile mappings = MappingsFile.load(json);

​
load(JsonElement jsonElement)

Load a MappingsFile from a JsonElement.
​
jsonElement
JsonElement
required
The input element in the format of a mappings file
​
return
MappingsFile
The loaded MappingsFile

​
Converting Identifiers

​
convertBlock(Identifier inputBlock)

Convert an input block identifier using this mappings file.
​
inputBlock
Identifier
required
The input block identifier to convert
​
return
Optional<Identifier>
Empty if there is no mapping found, otherwise an output identifier based on the mappings
Identifier inputBlock = new Identifier("minecraft:wool", states);
Optional<Identifier> outputBlock = mappings.convertBlock(inputBlock);

​
convertItem(Identifier inputItem, boolean fallback)

Convert an input item identifier using this mappings file.
​
inputItem
Identifier
required
The input item identifier to convert
​
fallback
boolean
required
Whether the block mappings should be tested if the item is not found
​
return
Optional<Identifier>
Empty if there is no mapping found, otherwise an output identifier based on the mappings

​
convertItem(Identifier inputItem)

Convert an input item identifier using this mappings file with block mappings as a fallback.
​
inputItem
Identifier
required
The input item identifier to convert
​
return
Optional<Identifier>
Empty if there is no mapping found, otherwise an output identifier based on the mappings

​
Accessors

​
getTypeMappings()

​
return
Map<String, TypeMappings>
The type mappings lookup used for converting types

​
getStateMappings()

​
return
Map<String, StateMappings>
The state mappings lookup used for converting different groupings of states

​
getBlockIdentifierLookup()

​
return
Map<String, IdentifierMappings>
The block lookup used for converting block identifiers

​
getItemIdentifierLookup()

​
return
Map<String, IdentifierMappings>
The item lookup used for converting item identifiers

​
Advanced Operations

​
inverse()

Generate the inverse of the current mapping file, where the current file is A → B, the result is B → A.
​
return
MappingsFile
A copy of the current mappings inverted to allow backwards mapping
// Create inverse mappings for reverse conversion
MappingsFile inverseMappings = mappings.inverse();

​
toJson() / toJsonString()

Convert the MappingsFile into a JSON representation.
​
toJson()
JsonElement
The JSON element representation of these mappings
​
toJsonString()
String
The JSON string representation (pretty-printed) of these mappings
String jsonOutput = mappings.toJsonString();

​
Special States

​
isSpecialState(String stateName)

Check whether a state is marked as special. Special states are used to hold additional data which should persist through conversion.
​
stateName
String
required
The state name to check
​
return
boolean
True if the state begins with meta: or virtual:
  • meta: - Used to attach additional metadata to a state
  • virtual: - Used to provide state data which does not have parity and is inferred by Chunker

​
JSON Format Example

Example which changes wool from orange to red: 
{
  "identifiers": [
    {
      "old_identifier": "minecraft:wool",
      "new_identifier": "minecraft:wool",
      "state_list": "wool"
    }
  ],
  "state_lists": {
    "wool": [
      {
        "old_state": "color",
        "new_state": "color",
        "type": "color_changer"
      }
    ]
  },
  "types": {
    "color_changer": [
      {
        "input": "orange",
        "output": "red"
      }
    ]
  }
}

​
CLI Integration

Mappings can be provided to the CLI using the --blockMappings parameter: 
java -jar Chunker.jar \
  --inputDirectory myWorld \
  --outputFormat JAVA_1_20_5 \
  --outputDirectory converted \
  --blockMappings custom_mappings.json

​
Programmatic Usage

Integrate custom mappings into the WorldConverter: 
import com.hivemc.chunker.mapping.MappingsFile;
import com.hivemc.chunker.mapping.resolver.MappingsFileResolvers;
import com.hivemc.chunker.conversion.WorldConverter;

// Load custom mappings
MappingsFile mappingsFile = MappingsFile.load(new File("custom_mappings.json"));

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

// Apply custom mappings
worldConverter.setBlockMappings(new MappingsFileResolvers(mappingsFile));

​
Custom Block Handler

The constant CUSTOM_BLOCK_HANDLER ("$custom_block") can be used as a special identifier to handle custom (non-vanilla) blocks: 
{
  "identifiers": [
    {
      "old_identifier": "$custom_block",
      "new_identifier": "minecraft:stone",
      "state_list": ""
    }
  ]
}
This will convert all custom blocks to stone. Custom blocks are any blocks not in the minecraft: namespace.

​
Best Practices

Group similar blocks (like stairs, slabs) that share state transformations into reusable state_lists.
Always test your custom mappings on a small test world before applying to your main world.
Special states (meta: and virtual:) are automatically preserved through conversion - use them for custom metadata.
Generate inverse mappings to verify your mappings work in both directions.

Dimension Mapping

Configure dimension conversion between editions

Pruning Config

Control which world regions to keep or remove

Build docs developers (and LLMs) love

Get started for freeTalk to us