StateUpdater

Extracted state mappings from the Minecraft: Bedrock Edition used to update state NBT tags to the latest version.

All updaters are auto-generated!

Usage

repositories {
    mavenCentral()
}

dependencies {
    // block-updater
    implementation("org.allaymc.stateupdater:block-updater:<version>")
    // item-updater
    implementation("org.allaymc.stateupdater:item-updater:<version>")
}

Update Item

// Update legacy items to new latest items (example for update jungle planks)
NbtMap updatedNbt = ItemStateUpdaters.updateItemState(
        NbtMap.builder()
                .putString("Id", "5")
                .putInt("Damage", 3) // You can use int, short, long and byte
                .build(),
        ItemStateUpdaters.LATEST_VERSION
);

// or update new items to latest
NbtMap updatedNbt = ItemStateUpdaters.updateItemState(
        NbtMap.builder()
                .putString("Name", "minecraft:coal")
                .putInt("Damage", 1) // You can use int, short, long and byte
                .build(),
        ItemStateUpdaters.LATEST_VERSION
);

Update Block

// Update legacy block
NbtMap updatedNbt = BlockStateUpdaters.updateBlockState(
        NbtMap.builder()
                .putString("name", "minecraft:stone")
                .putInt("val", 1) // You can use int, short, long and byte
                .build(),
        BlockStateUpdaters.LATEST_VERSION
);

// or update block
NbtMap updatedNbt = BlockStateUpdaters.updateBlockState(
        NbtMap.builder()
                .putString("name", "minecraft:anvil")
                .putCompound("states", NbtMap.builder()
                        .putString("damage", "very_damaged")
                        .putInt("direction", 3)
                        .build())
                .build(),
        BlockStateUpdaters.LATEST_VERSION
);

Generating updaters

The generators in tools/ require Python 3.9 or newer and use only the standard library. Run the following commands from the repository root. On systems without the Windows py launcher, use python3 instead.

Item schemas

py tools/item_scheme_to_code.py "https://github.com/opencollab-incubator/BedrockItemUpgradeSchema/blob/master/id_meta_upgrade_schema/0261_1.26.10_to_1.26.20.json"

Block schemas

py tools/block_scheme_to_code.py "https://github.com/opencollab-incubator/BedrockBlockUpgradeSchema/blob/master/0351_1.26.40_to_1.26.50.json"

Both scripts accept GitHub blob/raw URLs, direct HTTP(S) JSON URLs, or local JSON paths. GitHub file links are converted to raw download URLs automatically. Omit the argument to enter a URL interactively:

py tools/item_scheme_to_code.py
py tools/block_scheme_to_code.py

For a local file, keep the original versioned filename:

py tools/item_scheme_to_code.py "C:/schemas/0271_1.26.20_to_1.26.40.31_beta.json"
py tools/block_scheme_to_code.py "C:/schemas/0351_1.26.40_to_1.26.50.json"

Version and generated files

The target version comes from the filename after _to_, using the format <major>.<minor>.<patch>[.<build>][_<suffix>].json. Build numbers and suffixes are omitted from the Java class and Gradle version: 1.26.40.31_beta becomes 1.26.40.

Each run performs these steps:

1. Downloads or reads the JSON and validates its structure, value types and mapping references before writing files.
2. Creates the complete Java class with imports, INSTANCE, the version constructor, registerUpdaters, and an automatic-generation comment.
3. Registers the class in version order, without adding duplicate registrations.
4. Updates the corresponding property in gradle.properties, preserving its revision suffix, for example 1.26.20-R1 -> 1.26.40-R1.

Generator	Generated class directory	Registration file	Gradle property
item_scheme_to_code.py	item-updater/src/main/java/org/allaymc/updater/item/ItemStateUpdater_<major>_<minor>_<patch>.java	ItemStateUpdaters.java in the same directory	item-updater.version
block_scheme_to_code.py	block-updater/src/main/java/org/allaymc/updater/block/BlockStateUpdater_<major>_<minor>_<patch>.java	BlockStateUpdaters.java in the same directory	block-updater.version

Running the generator again for the same normalized version replaces the generated class. Multiple input schemas targeting that version are not merged. Change the source JSON and regenerate instead of editing generated Java files manually. Output paths are resolved relative to the scripts, so they also work when invoked from another directory.

Publishing

Keep common.version at its published release version while common is unchanged. The CI workflow checks the exact version's POM on Maven Central before publishing: an existing version is skipped, and a missing version is automatically published and awaited before the block and item updaters are uploaded. Network errors and unexpected HTTP responses fail the workflow instead of being treated as a missing version. Publishing runs on the same branch are serialized.

To release a changed common module, increment common.version to a new release version without -SNAPSHOT and push to master. Keep the block and item updater versions suffixed with -SNAPSHOT during development. Their existing publication behavior is unchanged; formal updater releases still require confirmation in the Central Portal.

Acknowledgements

• BedrockItemUpgradeSchema
• BedrockBlockUpgradeSchema
• BlockStateUpdater