Making a Pack Icon That Reads at Thumbnail Size

Minecraft Bedrock does not ask you to declare your pack icon inside the manifest file. Instead, the game engine looks for a hardcoded filename, pack_icon.png, sitting in the exact root directory of your pack right alongside manifest.json. If the file is present and valid, the game displays it in the Global Resources list, the world edit menu, and the storage management screen. If the file is missing, misplaced inside a subfolder, or saved in an unsupported format, Bedrock silently falls back to the default dirt-and-grass cobblestone placeholder icon.

Because a complete add-on usually splits into two separate folders—one for the behavior pack and one for the resource pack—you must place a pack_icon.png at the root of both folders. Many creators use the exact same image for both, which works fine for distribution. However, when you are actively developing and toggling packs on and off in the world settings, having identical icons makes it easy to confuse the behavior pack with the resource pack if their titles are long enough to get cut off. A common quality-of-life practice during development is to put a small colored corner badge or a distinct border color on the behavior pack icon (such as red for behaviors and blue for resources) so you can tell them apart instantly without reading the subtext.

Even though the icon is not referenced inside manifest.json, the text defined in your manifest's header block sits directly next to the icon in every menu. The pack name and first line of the description frame the image, so your visual design and your manifest metadata always work together as a single unit in the user interface.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 0]
  },
  "modules": [
    {
      "type": "resources",
      "uuid": "f6e5d4c3-b2a1-4f5e-9d8c-7b6a5e4d3c2b",
      "version": [1, 0, 0]
    }
  ]
}

While Bedrock's UI renderer is somewhat forgiving about image dimensions, sticking to strict technical limits prevents visual artifacts, stretching, and wasted memory. Your image must have a 1:1 square aspect ratio. If you supply a rectangular image, the game will forcibly squash or stretch it to fit the square container in the pack list, ruining your proportions. Power-of-two dimensions are standard across game development and work best here: 128x128 pixels or 256x256 pixels are the ideal targets for a final release.

You might be tempted to export a 1024x1024 or 2048x2048 image thinking it will look sharper. In practice, the exact opposite happens. Bedrock's UI downsampler does not use advanced bicubic sharpening when shrinking textures on the fly for scrolling lists. When the engine forces a massive 1024x1024 image down into a 48x48 pixel box on a mobile screen, it drops adjacent pixels unevenly, producing jagged aliasing, shimmering edges, and muddy colors. Furthermore, every pack icon in a player's storage folder has to be loaded into UI memory when they open the settings menu; oversized icons bloat your .mcaddon archive size and slow down menu rendering on low-end Android and iOS devices.

The file format must be a genuine, standard PNG encoded in 8-bit per channel RGB or RGBA. Simply taking a JPEG or WEBP file and renaming the extension to .png in your file explorer will not work; the engine reads the binary header of the file, not just its name, and will reject a renamed JPEG. Avoid exporting 16-bit per channel PNGs or files with embedded CMYK print color profiles, as Bedrock's texture loader either fails to read them or shifts their colors unpredictably.

When a player opens their resource or behavior pack list, your icon is displayed at roughly 40 to 64 logical pixels tall depending on their GUI scale setting and device resolution. At that size, a screenshot of a custom biome with three custom trees, a structure, and a sunset sky does not look like a landscape—it looks like a smudge of green and orange noise. To make an icon that reads immediately, you have to abandon the idea of showing everything in your pack and instead design a single focal symbol.

Pick one hero subject that represents the core hook of your add-on. If you built a magic wand behavior pack, show one wand. If you built an industrial machinery add-on, show the front face of your most recognizable generator block or a single wrench icon. This hero object should occupy roughly 60% to 75% of the total canvas area. Leave a modest breathing margin around the edges so the subject does not feel cramped against the frame, but crop in tight enough that the silhouette is unmistakable from across the room.

Silhouette and value contrast do all the heavy lifting at thumbnail scale. Before worrying about intricate pixel-art shading, make sure the outer shape of your subject is clear. If you are rendering a 3D Blockbench model of a custom mob for your icon, pose it at a three-quarter angle where the limbs and head do not overlap into a confusing blob. Place a dark subject against a bright, desaturated background, or a bright, glowing subject against a deep, dark background. If your custom sword is dark iron gray and you place it over a dark stone brick background, the sword will vanish entirely when scaled down.

A subtle 1-pixel or 2-pixel inner border around the entire canvas—or a dark outline around your central subject—goes a long way toward separating your icon from the surrounding Minecraft interface. The Bedrock settings menu uses dark gray panels in the classic UI and varied slate tones in the newer Ore UI. An icon with dark, unbordered edges blends right into the menu background, making your artwork look lopsided or unfinished.

One of the most frequent mistakes new creators make is treating pack_icon.png like a YouTube thumbnail or a store banner by cramming the full title of the add-on into the image. In the Bedrock UI, the title of your pack is already rendered in crisp system font two millimeters to the right of the icon. Putting that same text inside the 64x64 thumbnail is not only redundant, it is almost always illegible. Small letters fill in, thin strokes disappear when the game scales the image down, and the text ends up eating valuable canvas space that should have gone to your focal object.

If your add-on is part of a larger series and you really want a brand mark or version number on the icon, limit yourself to a maximum of two or three huge, bold, blocky characters—such as a Roman numeral 'II' or a large monogram initial in the corner. Even then, test it at minimum GUI scale to be sure it does not turn into visual clutter.

The second trap is mixing incompatible pixel resolutions, often called 'mixels', or applying smooth high-resolution Photoshop layer styles (like soft drop shadows, lens flares, and thin bevels) over 16x16 vanilla-style pixel art. When a 256x256 canvas contains a 16x16 item scaled up with crisp nearest-neighbor edges, alongside a 256x256 smooth gradient background and a 64x64 anti-aliased text logo, the eye immediately notices the clashing texel densities. When the game downsamples that mixed composition, the crisp pixel art edges fight against the soft gradients, creating muddy halos around your item.

To keep the icon clean, pick one visual style and commit to it across the whole square. If you are making a pixel-art icon, work on a small native grid—such as 32x32 or 64x64 pixels—using deliberate, hand-placed clusters of color, and then scale the whole canvas up to 256x256 using Nearest Neighbor resampling right before exporting. If you are making a 3D rendered icon (for example, exporting a turntable frame from Blockbench), render the entire scene at 512x512, paint or composite a matching smooth background, and downsample the finished flat image to 256x256 using Bilinear or Bicubic resampling so all edges share the exact same softness.

Building a readable icon takes much less time when you preview it at its actual in-game size while you paint. Most image editors—including Aseprite, GIMP, Krita, and Photoshop—let you open a second view or navigator window of your active canvas. Set your main workspace zoomed in so you can place pixels comfortably, and keep the secondary preview window zoomed out so the image measures roughly 1.5 centimeters (about half an inch) across on your monitor. If you squint at that tiny preview and cannot immediately tell what the object is, stop adding detail and fix the silhouette and background contrast first.

A fast way to verify contrast is to temporarily add a black-and-white (desaturation) adjustment layer over the very top of your layer stack. Color contrast can trick your eyes when zoomed in: a bright red apple on a bright green leaf background looks distinct at full size because the hues are opposites, but both colors have almost the exact same luminance value. Under a grayscale filter, and when shrunk to thumbnail size, they merge into the same flat medium gray. Adjusting the brightness of your background or adding a dark rim around the foreground subject until the grayscale version pops guarantees the color version will read clearly.

When you export the final pack_icon.png into your BP and RP folders, pair it with clean localization names in your language file. Players see the icon and the text label simultaneously; keeping the pack name concise ensures the UI does not truncate your title with an ellipsis right next to your artwork.

pack.name=Aetherium Gear RP
pack.description=Textures and models for Aetherium tools and armor.

Applies to all Minecraft Bedrock Edition versions (1.16.0 through 1.21+). No experimental toggles are required.

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