About NBT (Named Binary Tag)

NBT is essentially a binary equivalent of JSON, designed to be compact and fast for the game engine to read and write. Every piece of data in an NBT tree is a tag consisting of a numeric type ID, a string name, and a payload. While JSON is used for static definitions inside your behaviour and resource packs, NBT is used by the engine to save the live state of a world.

Unlike Java Edition, which stores chunks in region files and uses Big-Endian byte ordering for its NBT, Bedrock Edition stores nearly all world, entity, and chunk NBT payloads inside a LevelDB key-value database using Little-Endian byte ordering. The only standalone NBT files you will regularly encounter on disk are level.dat (which holds global world settings and contains an 8-byte header before the binary payload begins) and exported .mcstructure files inside a behaviour pack.

When inspecting a .mcstructure file or a world save in an external NBT editor, every node in the tree has a specific data type. Unlike JSON, which treats all numbers as generic values, NBT strictly separates integers by bit width and distinguishes floating-point precision.

Understanding these types matters if you use external tools to modify structure files—for example, changing a tag from a Byte to an Int will cause the game engine to ignore the value when it loads the file.

Inside a standard behaviour pack, the only raw NBT files are structure files located in the BP/structures/ folder. When you save a region of blocks and entities using a Structure Block in-game and export it to disk, Bedrock writes an uncompressed Little-Endian TAG_Compound with the .mcstructure extension.

A .mcstructure file contains the dimensions of the saved volume, a block palette mapping runtime indices to block names and their block states, a 3D positional grid of those indices, block entity data (such as chest inventories or sign text), and full entity snapshots. Add-on creators occasionally open these files in an NBT editor to strip out unwanted entities, clean up temporary structure_void blocks, or manually edit a loot table path inside a saved container.

Creators coming from other platforms often try to pass raw NBT strings into commands like /give or /replaceitem to set item lore, enchantments, or custom names. Bedrock Edition does not parse raw NBT in commands. Instead, its command parser accepts a strict JSON object with a tiny set of supported item components.

Through commands, you can only assign minecraft:can_place_on, minecraft:can_destroy, minecraft:item_lock, and minecraft:keep_on_death. To apply custom names, lore, or enchantments without external NBT editors, you must use the Script API or define a loot table inside your behaviour pack.

{
  "pools": [
    {
      "rolls": 1,
      "entries": [
        {
          "type": "item",
          "name": "minecraft:diamond_pickaxe",
          "functions": [
            {
              "function": "set_name",
              "name": "Excavator's Pick"
            },
            {
              "function": "set_lore",
              "lore": [
                "Can break deepslate",
                "Soulbound to owner"
              ]
            },
            {
              "function": "enchant_with_levels",
              "levels": {
                "min": 20,
                "max": 30
              },
              "treasure": true
            }
          ]
        }
      ]
    }
  ]
}

Because you cannot read or write arbitrary NBT tags on entities, items, or worlds during gameplay, Bedrock provides two official systems to persist custom add-on state: Entity Properties (defined in the entity JSON and readable via Molang) and Dynamic Properties (read and written via the @minecraft/server Script API).

When you call setDynamicProperty in script, the Bedrock engine serializes your string, number, boolean, or Vector3 directly into the entity, item stack, or world NBT payload inside the LevelDB save. This gives you the permanence of NBT storage while keeping your data sandboxed to your behaviour pack's manifest UUID.

import { world } from "@minecraft/server";

world.afterEvents.entityHitEntity.subscribe((event) => {
  const { damagingEntity, hitEntity } = event;
  if (damagingEntity.typeId !== "minecraft:player") return;

  const currentHits = hitEntity.getDynamicProperty("my_pack:hit_count") ?? 0;
  const nextHits = currentHits + 1;

  hitEntity.setDynamicProperty("my_pack:hit_count", nextHits);
  damagingEntity.sendMessage(`Target hit count saved to NBT: ${nextHits}`);
});

Applies to all modern Bedrock Edition versions. Little-Endian NBT in .mcstructure files and LevelDB world saves is foundational to the engine. Script API Dynamic Properties (the supported way to write custom persistent data) are stable in @minecraft/server 1.7.0+ (Bedrock 1.20.50 and later) and do not require any experimental toggles.

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