
World file format explained · Java · Advanced
Minecraft Chunk Heightmaps Explained: WORLD_SURFACE vs MOTION_BLOCKING
Minecraft stores precomputed 2D elevation grids inside every chunk called Heightmaps, allowing the game engine to skip scanning vertical columns of blocks from top to bottom. Understanding the difference between WORLD_SURFACE and MOTION_BLOCKING tags is essential for debugging lighting glitches, rain passing through roofs, map rendering, and mob spawning mechanics. This advanced guide shows you how to inspect and decode these 9-bit packed long arrays directly inside your browser using our client-side NBT Editor.
What you need
- A Minecraft Java Edition world folder or .zip backup (version 1.18+ recommended for standard 384-block height format)
- A duplicate backup copy of your world before touching any region files
- Access to the NBT Editor on world.9minecraft.net (processes files locally in your browser without uploading)
Step by step
1Back Up and Load Your World into the NBT Editor
Before inspecting or modifying chunk data, duplicate your world save folder so you have a clean fallback. Launch the NBT Editor on our site, click to open your world folder or .zip archive, and navigate into the region directory (for the Overworld, or DIM-1/region for the Nether). Select the .mca region file corresponding to the area you want to inspect, such as r.0.0.mca for chunks near positive spawn coordinates.
Tip: Divide a block coordinate by 512 and round down to find its region file number, or by 16 to find its chunk coordinate.
2Locate the Heightmaps Compound Tag in a Chunk
Expand the region file tree in the NBT Editor and click on a specific chunk slot (for example, Chunk [0, 0]). Inside the root compound tag of a modern chunk (versions 1.18 and newer), scroll down and expand the Heightmaps compound tag. In older versions prior to 1.18, you will find this tag nested inside the Level compound tag instead. Inside Heightmaps, you will see several Long Array tags marked by an [L] icon, each containing exactly 37 long integers.
Tip: If a chunk has not been fully generated yet (Check the Status tag to see if it says minecraft:full), you may also see _WG suffixed tags like WORLD_SURFACE_WG.
3Compare WORLD_SURFACE vs MOTION_BLOCKING Types
Examine the four primary arrays saved on disk: WORLD_SURFACE, MOTION_BLOCKING, MOTION_BLOCKING_NO_LEAVES, and OCEAN_FLOOR. WORLD_SURFACE records the highest non-air block at each X/Z column, which the game uses primarily for rendering top-down maps and world generation checks. MOTION_BLOCKING records the highest block that blocks entity movement or contains a fluid (such as water or lava), which directly controls where rain and snow stop falling and where surface lighting and mob spawning checks begin. MOTION_BLOCKING_NO_LEAVES works identically to MOTION_BLOCKING but ignores leaf blocks so tree canopies do not interfere with natural spawning or patrol placement, while OCEAN_FLOOR tracks the highest solid block beneath any water.
Tip: Fluids like water trigger MOTION_BLOCKING even though players can swim through them, because rain and falling snow must splash on the water surface.
4Decode a 9-Bit Packed Long Integer Manually
Because a chunk is 16x16 (256 columns), Minecraft packs the 256 height values into 37 64-bit Long integers using 9 bits per column (allowing values from 0 to 511, which covers the 384-block vertical span of modern worlds). Since 64 divided by 9 is 7 with a remainder of 1, each Long integer in the NBT Editor stores exactly 7 column height values, leaving the highest bit (bit 63) unused and padded with zero. To read the very first column (local X=0, Z=0) from the first Long in the array, take the integer value and apply a bitwise AND with 511 (0x1FF), then subtract 64 (the minimum Y level of the Overworld) to get the Y coordinate of the first block above the highest solid block.
Tip: If the extracted 9-bit number is 128, subtracting 64 gives Y = 64, meaning the highest solid block is at Y = 63 and the air block directly above it is at Y = 64.
5Force Minecraft to Recalculate Corrupted Heightmaps
Sometimes external world generators or custom terrain scripts place blocks in the sections array without updating the Heightmaps compound, causing rain to fall indoors or dark spots to linger under the open sky. Using the NBT Editor, you can safely delete the individual Long Array tags inside Heightmaps (such as deleting MOTION_BLOCKING and WORLD_SURFACE) while leaving the Heightmaps compound itself intact. Save the modified .mca file from the browser tool and replace the file in your world save folder; the next time Minecraft loads that chunk, it will notice the missing arrays and rebuild them accurately from the actual block data.
Tip: Always test heightmap resets on a backup copy first, and stand nearby in-game to trigger chunk loading.
How it works
Why does Minecraft bother storing heightmaps when all block states are already saved in the chunk sections? Scanning a 384-block vertical column from Y=319 down to Y=-64 for all 256 columns in a chunk requires up to 98,304 block lookups per chunk. By maintaining a 256-entry lookup table in memory and on disk, the server and client can check the sky exposure of any X/Z coordinate in constant O(1) time. This keeps tick times fast during heavy rainstorms, skylight propagation, and natural mob spawning loops.
The bit-packing format changed in Minecraft 1.16 to prevent values from spanning across two different 64-bit Long integers. In a 384-block-tall world, a height value requires 9 bits (since 2^9 = 512). Instead of splitting a 9-bit value across the boundary of Long 0 and Long 1, the game packs floor(64 / 9) = 7 values into each Long (using 63 bits and wasting 1 bit). For 256 columns, ceiling(256 / 7) equals 37 Longs, where the 37th Long stores the final 4 columns (indices 252 to 255) in its lowest 36 bits.
Remember that the number stored in the heightmap is not the Y coordinate itself, nor is it the top solid block. It represents the number of blocks above the minimum build height (which is -64 in standard Overworld dimensions, or 0 in the Nether and End), pointing to the bottom of the lowest open block above the highest matching obstacle. Therefore, a completely empty chunk column stores 0 (meaning Y = -64), while a column filled all the way to the top build limit of Y = 319 stores 384 (pointing to Y = 320).
Common mistakes
- Forgetting the -64 Y-offset in modern Overworld chunks and interpreting a raw 9-bit value of 130 as Y=130 instead of Y=66 (130 minus 64).
- Assuming values are packed continuously across 64-bit boundaries; since Minecraft 1.16, bit 63 of every Long in a 9-bit heightmap array is unused padding.
- Confusing WORLD_SURFACE with MOTION_BLOCKING when debugging mob farms; non-solid blocks like signs, carpets, or pressure plates affect WORLD_SURFACE differently than MOTION_BLOCKING depending on their collision and motion properties.
- Changing array lengths inside the NBT Editor; if a heightmap array does not contain exactly 37 Longs in a standard 384-height dimension, the game will reject the array and regenerate it.
FAQ
Why does my heightmap array have 36 Longs instead of 37?
If you are inspecting a chunk from the Nether, the End, or an older pre-1.18 world where the total vertical height is 256 blocks instead of 384, only 8 bits are needed per column (or 9 bits for 0-256 inclusive, which still uses 37 Longs in 1.16+). In pre-1.16 versions where bits spanned across Long boundaries, 256 columns at 9 bits packed tightly into exactly 36 Longs (256 * 9 / 64 = 36).
What are the WORLD_SURFACE_WG and OCEAN_FLOOR_WG tags?
Tags ending in _WG are temporary heightmaps used solely during the proto-chunk world generation stages (before features, trees, and structures are placed). Once a chunk reaches the minecraft:full status, the game typically removes the _WG arrays and keeps only the active runtime heightmaps.
How does the MOTION_BLOCKING heightmap affect mob farm rates?
During natural mob spawning, Minecraft picks a random X and Z column and checks the MOTION_BLOCKING heightmap value to determine the vertical range from the bottom of the world up to the highest block. A lower heightmap value shrinks the vertical random selection pool, dramatically increasing the probability that the game selects your farm's spawning platform.
Chunk heightmaps store 256 9-bit elevation offsets across 37 Long integers to give Minecraft instant top-down coordinate lookups for maps (WORLD_SURFACE) and weather, lighting, and mob spawning (MOTION_BLOCKING).