@cauldria.dev/minecraft-map

Utilities for Minecraft map item pixels: the 62 base colors (IDs 0-61, as of 1.21.x) with their 4 shade multipliers each, exact/shade color lookups, and nearest-color mapping.

const map = require("@cauldria.dev/minecraft-map");

map.nearestMapColor(r, g, b); // -> { id, shade, distance, color }
map.getMapColor(id, shade);   // -> packed 0x00BBGGRR little-endian color
map.parseMapColor("GRASS/1"); // -> same, by name
map.imageToMapColors({ width, height, data }); // RGBA -> 128x128 map color bytes
map.mapColorsToRGBA(colors);                  // map color bytes -> RGBA
map.scaleToMapSize({ width, height, data });  // nearest-neighbor to 128x128

Map color byte = base id * 4 + shade; imageToMapColors snaps every pixel to the nearest realizable map color (alpha < 128 becomes color 0, NONE — unexplored/transparent).

Map resolution

Every conversion takes an optional size as the last argument — 128 (the default), 256, 512, 1024 or 2048, the only resolutions a vanilla map item can have (128 x 128, doubled per zoom level up to zoom level 4):

map.imageToMapColors(img, 2048); // -> 2048x2048 map color bytes
map.mapColorsToRGBA(colors, 512); // -> 512x512 RGBA
map.scaleToMapSize(img, 256);     // -> 256x256 RGBA
map.MAP_SIZES;                    // [128, 256, 512, 1024, 2048]
map.isValidMapSize(1024);         // true

Any other size (e.g. 100, 4096, "128") throws an invalid map size error, so nothing downstream ever sees an unsupported resolution.

Sources (verified to agree exactly):

• https://minecraft.wiki/w/Map_item_format#Base_colors (data-checked 1.21.5)
• https://github.com/cerus/minecraft-map-colors (versions/1_21_9.md)