Skip to main content

​
Overview

Block mappings allow you to customize how blocks and items are converted between Java and Bedrock editions. This is useful for:
  • Changing specific block types during conversion
  • Handling custom/modded blocks
  • Fixing unwanted conversion behaviors
  • Creating custom block transformations

​
File Structure

Block mappings are defined in block_mappings.chunker.json (MappingsFile.java:1-575): 
{
  "identifiers": [],
  "items": [],
  "state_lists": {},
  "types": {}
}

​
Core Components

The mapping system has three main components (MappingsFile.java:20-54):

​
1. Identifiers

Map block identifiers from one type to another: 
{
  "identifiers": [
    {
      "old_identifier": "minecraft:wool",
      "new_identifier": "minecraft:stone"
    }
  ]
}

​
2. State Lists

Groups of states that are commonly used together: 
{
  "state_lists": {
    "wool": [
      {
        "old_state": "color",
        "new_state": "color",
        "type": "color_changer"
      }
    ]
  }
}

​
3. Types

Mapping of input values to output values: 
{
  "types": {
    "color_changer": [
      {
        "input": "orange",
        "output": "red"
      }
    ]
  }
}

​
Complete Example

Here’s a complete example that changes orange wool to red wool (MappingsFile.java:26-54):
block_mappings.chunker.json
{
  "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"
      }
    ]
  }
}

​
Identifier Mapping

​
Basic Identifier Mapping

Simple identifier conversion: 
{
  "old_identifier": "minecraft:wool",
  "new_identifier": "minecraft:stone"
}

​
With State Values

Map specific block states: 
{
  "old_identifier": "minecraft:wool",
  "new_identifier": "minecraft:stone",
  "old_state_values": {
    "color": "orange"
  },
  "new_state_values": {
    "stone_type": "granite"
  }
}

​
Using State Lists

Reference a state list for complex mappings: 
{
  "old_identifier": "minecraft:wool",
  "new_identifier": "minecraft:wool",
  "state_list": "wool"
}

​
Wildcard State List

Pass through all states unchanged (MappingsFile.java:260): 
{
  "old_identifier": "minecraft:wool",
  "new_identifier": "minecraft:wool",
  "state_list": "*"
}
Using "state_list": "*" preserves all block states. Omitting state_list removes all states.

​
Custom Block Handler

Handle modded or custom blocks with the special identifier (MappingsFile.java:57, 209-218): 
{
  "identifiers": [
    {
      "old_identifier": "$custom_block",
      "new_identifier": "$custom_block",
      "state_list": "custom_handler"
    }
  ],
  "state_lists": {
    "custom_handler": [
      {
        "old_state": "facing",
        "new_state": "facing"
      }
    ]
  }
}
The $custom_block identifier matches any non-vanilla block (blocks not in the minecraft: namespace).

​
State Value Types

State values can be strings, integers, or booleans: 
{
  "old_state_values": {
    "color": "orange"
  },
  "new_state_values": {
    "color": "red"
  }
}

​
Special State Prefixes

Chunker uses special state prefixes for metadata (MappingsFile.java:115-119):
  • meta: - Additional metadata attached to a state
  • virtual: - State data inferred by Chunker that doesn’t have parity between editions
Special states are automatically preserved through conversions (MappingsFile.java:267-270).

​
Item Mappings

Map items separately from blocks: 
{
  "items": [
    {
      "old_identifier": "minecraft:golden_apple",
      "new_identifier": "minecraft:enchanted_golden_apple"
    }
  ]
}
If an item mapping isn’t found, Chunker falls back to block mappings (MappingsFile.java:174-184).

​
Multi-State Mappings

Map multiple states at once: 
{
  "state_lists": {
    "stairs": [
      {
        "old_state": ["facing", "half"],
        "new_state": ["facing", "half"]
      }
    ]
  }
}

​
Type Mappings

​
Simple Type Mapping

{
  "types": {
    "direction": [
      {
        "input": "north",
        "output": "south"
      },
      {
        "input": "south",
        "output": "north"
      }
    ]
  }
}

​
Multi-Value Type Mapping

Map one input to multiple outputs: 
{
  "types": {
    "complex_mapping": [
      {
        "input": "orange",
        "output": ["red", true]
      }
    ]
  }
}

​
Usage Examples

​
Replace All Stone with Dirt

{
  "identifiers": [
    {
      "old_identifier": "minecraft:stone",
      "new_identifier": "minecraft:dirt"
    }
  ]
}

​
Change Wool Colors

{
  "identifiers": [
    {
      "old_identifier": "minecraft:wool",
      "new_identifier": "minecraft:wool",
      "state_list": "wool_colors"
    }
  ],
  "state_lists": {
    "wool_colors": [
      {
        "old_state": "color",
        "new_state": "color",
        "type": "color_swap"
      }
    ]
  },
  "types": {
    "color_swap": [
      {
        "input": "white",
        "output": "black"
      },
      {
        "input": "black",
        "output": "white"
      }
    ]
  }
}

​
Preserve Custom Block States

{
  "identifiers": [
    {
      "old_identifier": "$custom_block",
      "state_list": "*"
    }
  ]
}

​
Loading Block Mappings

# Place in world directory
my_world/block_mappings.chunker.json

# Run conversion
java -jar chunker-cli.jar -i my_world -f BEDROCK_1_20_80 -o output

​
Validation

Chunker validates mappings during conversion (CLI.java:154-161):
  • State lists must exist if referenced
  • Type mappings must exist if referenced
  • JSON must be valid and properly formatted
Invalid mappings will cause the conversion to fail with a descriptive error message.

​
Advanced Features

​
Inverse Mappings

Mappings can be inverted programmatically (MappingsFile.java:277-305): 
MappingsFile inverse = mappingsFile.inverse();
This creates a reverse mapping where A → B becomes B → A.

​
Redundant Mappings

If multiple mappings match, the first one is used. Additional matches are stored as redundant mappings.

​
Best Practices

  1. Test mappings on a small world first
  2. Use state lists to organize complex mappings
  3. Document your mappings with comments in a separate README
  4. Export from web UI when possible for validated configurations
  5. Backup worlds before applying custom mappings

​
Troubleshooting

  • Check that old_identifier exactly matches the block in your world
  • Verify state_list exists if referenced
  • Ensure type mappings are defined
  • Validate JSON syntax
  • Check for missing commas or brackets
  • Remove trailing commas (not allowed in JSON)
  • Use $custom_block handler for non-minecraft namespace blocks
  • Verify the block identifier format

Configuration Overview

Learn about all configuration options

Converter Settings

Configure conversion behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us