Numerical Item IDs and AUX Values

In the earliest days of Bedrock Edition, every item had a hardcoded integer ID. When data-driven custom items were introduced, Mojang shifted creators toward string identifiers to prevent two different add-ons from claiming the same number and crashing the game. Under the hood, however, the game still builds a numerical lookup table every time a world loads.

Vanilla blocks and items occupy fixed slots or predictable ranges in this table, while custom items from behavior packs are assigned dynamic runtime IDs on the fly. Because these numbers are generated per world based on the active packs and the order in which items register, a custom item's numerical ID in one world is not guaranteed to match its ID in another world if the pack list changes.

The one place where add-on developers still actively calculate numerical item IDs is inside custom Resource Pack UI files. The UI engine includes a special renderer called inventory_item_renderer that draws a 2D item icon or 3D block model directly onto a screen panel. Instead of accepting a string identifier like minecraft:apple, this renderer looks for a single large integer property named #item_id_aux.

This value packs both the item's numerical runtime ID and its data value (formerly metadata or damage value) into a single 32-bit number by multiplying the base ID by 65536 (which is equivalent to a bitwise left shift of 16 bits) and adding the data value. If the item has no special data value, you simply multiply its runtime ID by 65536.

// Formula to calculate #item_id_aux for JSON UI:
// (Numerical_Runtime_ID * 65536) + Data_Value

// Example for an item with Runtime ID 260 (Apple) and Data 0:
// 260 * 65536 = 17039360

When you build a custom interface in RP/ui/, you can hardcode an AUX value into a property bag to display a fixed item icon, or bind it to a Molang expression. Because custom item runtime IDs can shift if a player installs another add-on, hardcoding a custom item's AUX number in UI is risky unless your pack is meant for a locked adventure map or a controlled server where the pack stack never changes.

Below is a standard JSON UI control definition that renders a vanilla apple using its calculated AUX integer inside a custom panel.

{
  "namespace": "custom_item_display",
  "apple_icon": {
    "type": "custom",
    "renderer": "inventory_item_renderer",
    "size": [ 16, 16 ],
    "property_bag": {
      "#item_id_aux": 17039360
    }
  }
}

A frequent point of confusion is why blocks held as items often have negative numerical IDs. Once Bedrock exceeded the original 255 block limit, new blocks were given IDs above 255 in the block registry. However, item IDs 256 and up were already taken by items like iron shovels and apples.

To keep block items from colliding with regular items, the engine converts any block ID above 255 into a negative item ID using the formula: 255 - Block_ID. For example, a block with a block runtime ID of 256 has an item runtime ID of -1. When multiplying a negative item ID by 65536 for #item_id_aux, the result is a negative number, which the UI renderer still accepts.

In behavior pack files—such as loot tables, crafting recipes, trading tables, and item JSON definitions—numerical IDs are completely deprecated. You must always declare and reference your item using its full namespace and identifier string inside the description block.

Similarly, the Script API (@minecraft/server) does not expose numerical runtime IDs on ItemStack or ItemType objects. Scripts interact exclusively with the typeId string property. If you need to bridge Script API data to a JSON UI screen to show an item icon, the most reliable workaround is passing the item name via a title or scoreboard string and matching textures manually, rather than trying to guess the runtime integer from JavaScript.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:max_stack_size": 64,
      "minecraft:icon": {
        "texture": "ruby"
      }
    }
  }
}

Applies to all modern Bedrock versions (1.16.100 through 1.21+). String identifiers are stable and require no experimental toggles. Dynamic runtime ID assignment happens automatically inside the engine.

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