Texture Atlases (terrain_texture.json and item_texture.json)

When Minecraft Bedrock loads a world, it avoids opening thousands of tiny PNG files one by one during gameplay. Instead, it reads two registry files in your resource pack's textures folder, gathers all the block and item images listed inside them, and packs them into large combined sheets in memory called atlases. Your block and item definitions only ever know the short alias you assign in these files, never the file path itself.

This separation applies exclusively to blocks and items. Entities, particles, and UI elements bypass the atlas system entirely and declare their file paths inside their own client definitions. If you are adding a custom block or a custom item, however, registering its texture shortname in the correct atlas file is mandatory.

The item atlas lives at RP/textures/item_texture.json and maps shortnames to 2D icons used by items in the inventory and in hand. Inside the top-level texture_data object, each key you add becomes a shortname that you can pass to the minecraft:icon component in your behavior pack item file (or resource pack item file on older format versions).

Always prefix your shortnames with your pack identifier or namespace, Using an underscore rather than a colon is common practice here, though colons are also accepted. If two loaded resource packs define the exact same key inside texture_data, the pack higher in the stack overwrites the lower one. A generic key like ruby or sword will almost certainly collide with another add-on, whereas mypack_ruby_sword is safe.

File paths inside the textures property are always written relative to the root of the resource pack, starting with textures/, and you must leave off the .png extension. The game resolves the extension automatically.

{
  "resource_pack_name": "mypack",
  "texture_name": "atlas.items",
  "texture_data": {
    "mypack_ruby": {
      "textures": "textures/items/ruby"
    },
    "mypack_ancient_coin": {
      "textures": "textures/items/ancient_coin"
    }
  }
}

The block atlas lives at RP/textures/terrain_texture.json and registers every surface texture used by custom blocks. It shares the same basic layout as the item atlas, but includes two extra header values: padding and num_mip_levels. Padding adds a pixel border around each tile in the generated sheet so neighboring textures do not bleed into each other at a distance, while num_mip_levels controls how many scaled-down versions the game generates for distant rendering. Keep padding at 8 and num_mip_levels at 4 to match vanilla behavior.

Once a shortname is defined under texture_data here, you can reference it inside the minecraft:material_instances component of a behavior pack block, or inside RP/blocks.json if you are using legacy per-face texture mappings.

{
  "resource_pack_name": "mypack",
  "texture_name": "atlas.terrain",
  "padding": 8,
  "num_mip_levels": 4,
  "texture_data": {
    "mypack_ruby_ore": {
      "textures": "textures/blocks/ruby_ore"
    },
    "mypack_chiseled_basalt_top": {
      "textures": "textures/blocks/chiseled_basalt_top"
    },
    "mypack_chiseled_basalt_side": {
      "textures": "textures/blocks/chiseled_basalt_side"
    }
  }
}

Defining an entry in an atlas does nothing on its own until a block or item asks for that key. In modern format versions, both block and item textures are linked directly from their behavior pack files using components, without needing an intermediate client file.

For blocks, open your block JSON in the behavior pack and add the minecraft:material_instances component. The wildcard key * sets the default texture for all faces of the block. Set its texture property to the exact key you created in terrain_texture.json.

For items, add the minecraft:icon component inside the components object of your behavior pack item file. In current format versions, you can pass an object containing a textures dictionary, where the default key points to the shortname you created in item_texture.json.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "mypack:ruby_ore"
    },
    "components": {
      "minecraft:material_instances": {
        "*": {
          "texture": "mypack_ruby_ore",
          "render_method": "opaque"
        }
      }
    }
  }
}

Instead of a single path string, the textures field inside an atlas entry can accept a JSON array of paths. This is used when a single block or item needs to switch between multiple images depending on its data or state, or when defining texture variations.

When you provide a list of paths in terrain_texture.json, each entry in the array is assigned an index starting at 0. Older blocks and certain Aux-value or permutation workflows select a specific image from the array by passing that index number, though for modern custom blocks it is usually clearer to give each state its own distinct shortname and swap them using block permutations.

{
  "resource_pack_name": "mypack",
  "texture_name": "atlas.terrain",
  "padding": 8,
  "num_mip_levels": 4,
  "texture_data": {
    "mypack_crate": {
      "textures": [
        "textures/blocks/crate_empty",
        "textures/blocks/crate_full"
      ]
    }
  }
}

Because every image in terrain_texture.json is packed onto a single shared sheet and mipmapped together, mixing wildly different resolutions in the same pack can cause visual glitches. If most of your blocks are 16x16 pixels and you drop a single 512x512 image into the terrain atlas, the game has to expand the sheet size in memory, and the mipmap calculations can make lower-resolution blocks look blurry at an angle.

Stick to powers of two for all block and item PNG dimensions (16x16, 32x32, 64x64) and keep the resolution consistent across your pack. Also ensure your PNG files are saved as standard 8-bit per channel RGB or RGBA images; unusual color profiles or 16-bit depth channels will fail to parse into the atlas.

Applies to all Minecraft Bedrock versions. No experimental toggles are required to use terrain_texture.json or item_texture.json.

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