Minecraft Atlas Guide: Add Textures to an Atlas

Written for Minecraft 26.3.

A minecraft atlas is one big image the game builds at load time by stitching many small textures together. An atlas file in your resource pack tells the game which textures to include. You only need one when your textures live somewhere the game does not already look.

Before you start

• A resource pack with working textures. See Pack basics.

• The name of the atlas you want to change. The most common is blocks.

• Your textures as PNG files under assets/<namespace>/textures/.

Which atlas file to edit

Atlas files live at assets/<namespace>/atlases/<id>.json. The file name must be an atlas the game knows. Custom atlas names are ignored. Packs merge: your sources add to the ones from other packs.

• blocks: block textures, plus a few others such as the bell and conduit. Has mipmaps.

• items: item textures.

• gui: GUI sprites and effect icons.

• particles, paintings, chests, decorated_pot, shield_patterns, banner_patterns, map_decorations, celestials, shulker_boxes: single-purpose atlases.

Atlases removed in recent versions include armor_trims (26.3), signs, and beds. If an old guide edits one of those, it no longer applies.

Add a folder of textures

1. Put your PNGs in a folder such as assets/minecraft/textures/block/mypack/.

2. Create assets/minecraft/atlases/blocks.json.

3. Add a directory source for the folder, as below.

{
  "sources": [
    {
      "type": "minecraft:directory",
      "source": "block/mypack",
      "prefix": "block/mypack/"
    }
  ]
}

The source is relative to the textures folder. The prefix is added to every sprite name, so a file oak_door.png becomes the sprite block/mypack/oak_door. Models refer to textures by that name.

Source types

• minecraft:directory: adds every PNG in a folder and its subfolders. Keys: source, prefix.

• minecraft:single: adds one texture. Keys: resource and an optional sprite name.

• minecraft:filter: removes sprites whose namespace or path matches a regular expression (namespace, path). Per the wiki it only affects sprites from lower-priority packs.

• minecraft:unstitch: cuts regions out of one image into named sprites. Keys: resource, divisor_x, divisor_y, regions (each with sprite, x, y, width, height).

• minecraft:paletted_permutations: recolours base textures using palettes. Keys: textures, palette_key, permutations, separator. Palettes are read from textures/palettes.

Sources run in order, so put a filter after the sources it should affect.

Check it worked

1. Reload the pack with F3 + T, or rejoin.

2. Open the model that uses the texture. The purple and black checkerboard should be gone.

3. Check the log for lines about missing sprites.

Common problems

The texture is still purple and black

The sprite name in the model does not match the folder plus prefix. Compare the model's texture path with prefix and the file name.

The file is ignored

The atlas ID must be one of the real ones. A file such as atlases/custom.json does nothing.

Textures from vanilla disappeared

A filter source was too broad. Anchor your regular expressions.

A guide tells you to edit armor_trims

That atlas was removed in 26.3. Palette textures moved into textures/palettes. See armor trims for current steps.

Do not replace the whole atlas file from another pack. Your file merges with others, so only list what you add.