NBT Libraries and External Binary Parsers

It is important to understand a core boundary in Bedrock Edition: you cannot read or write raw NBT tags directly from JSON behavior files or the `@minecraft/server` Script API during gameplay. Unlike commands in other editions that accept inline curly-brace NBT strings, Bedrock exposes game state through structured JSON components, Entity Properties, and Script API `DynamicProperties`.

NBT libraries do not run inside your behavior pack. Instead, they run in external environments—typically Node.js, Python, or Rust—on your development machine. You use them to inspect or generate binary files that you subsequently place into your behavior pack (such as `BP/structures/*.mcstructure`), or to manipulate a test world's `level.dat` and LevelDB chunk database before packaging a map.

If you are configuring an external NBT library to read or write Bedrock files, you must select the correct binary format. While the underlying tag types (Byte, Short, Int, Long, Float, Double, ByteArray, String, List, Compound, IntArray, LongArray) are identical across Minecraft editions, Bedrock encodes the bytes differently than Java Edition.

Disk files in Bedrock—most notably `BP/structures/*.mcstructure` and `level.dat`—use uncommitted Little-Endian NBT (`little`). Furthermore, `level.dat` is not a compressed archive; it is an uncompressed Little-Endian NBT compound preceded by an 8-byte binary header (4 bytes for the storage version, 4 bytes for the payload length). Network packets and certain internal LevelDB entries use a third variant called `littleVarint`, which compresses integers using ZigZag VarInt encoding. Any library you choose must explicitly support the `little` format to generate valid behavior pack files.

Three open-source libraries dominate Bedrock tool development across JavaScript and Python ecosystems. Because Regolith (the standard Bedrock add-on compiler) runs on Node.js and Python, these libraries integrate directly into automated build filters.

In the Node.js ecosystem, `prismarine-nbt` is the standard parser. It automatically detects big-endian, little-endian, and varint encodings when parsing, and allows you to specify `'little'` when serializing buffers back to disk. In the Python ecosystem, `amulet-nbt` (maintained by the Amulet Map Editor team) and `nbtlib` both offer full support for uncompressed Little-Endian files. If your tool needs to modify world chunks rather than loose `.mcstructure` files, you will also need a LevelDB wrapper that supports Mojang's Zlib-raw compression, as NBT libraries only parse the byte buffers extracted from the database records.

The most practical use for an NBT library during add-on development is batch-processing `.mcstructure` files inside your behavior pack. For example, if you rename a custom block across your add-on, re-exporting dozens of structure files by hand in-game with a Structure Block is slow and error-prone. A short Node.js script using `prismarine-nbt` can parse the binary file, walk the block palette, replace the identifier string, and write the updated binary straight back into `BP/structures/`.

When serializing the modified object back to a Buffer, you must pass `'little'` as the second argument to `nbt.writeUncompressed()`. If you omit this argument, the library defaults to big-endian (`'big'`), and Bedrock will silently fail to load the structure.

const fs = require('fs');
const nbt = require('prismarine-nbt');

async function renameBlockInStructure(filePath, oldId, newId) {
  const rawBuffer = fs.readFileSync(filePath);
  
  // Parse the binary .mcstructure buffer (auto-detects 'little' endian)
  const { parsed, type } = await nbt.parse(rawBuffer);

  // Navigate to structure -> palette -> default -> block_palette
  const palette = parsed.value.structure.value.palette.value.default.value.block_palette.value.value;

  let modifiedCount = 0;
  for (const blockEntry of palette) {
    if (blockEntry.name && blockEntry.name.value === oldId) {
      blockEntry.name.value = newId;
      modifiedCount++;
    }
  }

  if (modifiedCount > 0) {
    // Write back as uncompressed Little-Endian NBT
    const outputBuffer = nbt.writeUncompressed(parsed, 'little');
    fs.writeFileSync(filePath, outputBuffer);
    console.log(`Updated ${modifiedCount} palette entries in ${filePath}`);
  }
}

renameBlockInStructure(
  'BP/structures/dungeon_room.mcstructure',
  'my_pack:old_brick',
  'my_pack:cracked_brick'
);

When generating or modifying block palettes in a `.mcstructure` via an NBT library, the `name` and `states` tags in your binary compound must exactly match the block definition in your behavior pack. If your script injects a state name or data type that does not exist in the behavior pack JSON, Bedrock will either revert the block to its default permutation or replace it with the `minecraft:info_update` block.

Below is a standard behavior pack block definition whose state (`my_pack:facing_direction`) is stored as a 32-bit `TAG_Int` inside the `states` compound of a `.mcstructure` palette entry.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "my_pack:cracked_brick",
      "states": {
        "my_pack:facing_direction": [0, 1, 2, 3]
      }
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.0
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6.0
      },
      "minecraft:geometry": "minecraft:geometry.full_block"
    }
  }
}

Bedrock's Little-Endian NBT format (`format_version: 1` for `.mcstructure` files) applies to all modern Bedrock versions (1.16.0 through 1.21+). No experimental toggles are required to load `.mcstructure` files modified by external NBT tools.

Read out of the game itself, so the ids match the version you are building for.