@cauldria.dev/minecraft-nbt

NBT-related utilities specific to Minecraft, built on the @cauldria.dev/nbt codec: encoding and decoding vanilla map_*.dat files.

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

MCNBT.encodeMapColors(colors, { compression: "gzip" }); // -> map_*.dat bytes
MCNBT.encodeMap(value, opts);   // encode a full map NBT value (MAP_SCHEMA)
MCNBT.decodeMap(bytes);         // -> map NBT value (gunzips .dat input)
MCNBT.mapColors(value);         // -> 128x128 Int8Array (null if not a map)
MCNBT.buildMapValue(colors, { xCenter: 0, zCenter: 0, scale: 0 });

The wire format mirrors a real 1.21.5 server map (DataVersion int, scale/unlimitedTracking bytes, xCenter/zCenter ints, UUIDMost/UUIDLeast longs, dimension string, colors ByteArray) — see samples/0.dat for a real server map.

CLI

minecraft-nbt compile hand-drawn.png -o map_42.dat  # .png/.bmp -> map_*.dat
minecraft-nbt decompile map_42.dat                   # map_*.dat -> .png

compile imports a hand-drawn map (any .png/.bmp, any size — scaled nearest-neighbor to 128x128) using @cauldria.dev/minecraft-map's nearest-color mapping; alpha < 128 becomes unexplored/transparent. decompile renders it back to a .png; the round trip is byte-identical for every realizable map color.

Run the tests: npm test in minecraft-nbt/.