Chunk API

Overview

The Chunk API manages 16×256×16 sections of the world in Minecraft Community Edition. Chunks handle block storage, lighting, entity organization, and tile entities.

Class Hierarchy

ChunkSource (abstract)
  ├── ChunkStorage
  └── MultiPlayerChunkCache

LevelChunk

LevelChunk Class

Represents a 16×256×16 section of blocks in the world. Header: Minecraft.World/LevelChunk.h

Constants

static const int BLOCKS_LENGTH = 65536;  // 16 * 16 * 256

// Terrain population flags
static const int sTerrainPopulatedFromHere = 2;
static const int sTerrainPopulatedFromW = 4;
static const int sTerrainPopulatedFromS = 8;
static const int sTerrainPopulatedFromSW = 16;
static const int sTerrainPopulatedAllAffecting = 30;
static const int sTerrainPopulatedAllNeighbours = 1022;
static const int sTerrainPostPostProcessed = 1024;

Core Members

Level *level;                    // Parent world
int x, z;                        // Chunk coordinates

byteArray biomes;                // 16x16 biome data
byteArray heightmap;             // 16x16 height map
int minHeight;                   // Lowest non-air block

bool loaded;                     // Is chunk loaded?
bool seenByPlayer;               // Has any player seen this chunk?
short terrainPopulated;          // Population/decoration flags

unordered_map<TilePos, shared_ptr<TileEntity>> tileEntities;
vector<shared_ptr<Entity>>** entityBlocks;  // Entity storage grid

Internal Storage

Chunks use optimized compressed storage:

// Block data (split for memory efficiency)
CompressedTileStorage *lowerBlocks;  // Y: 0-127
CompressedTileStorage *upperBlocks;  // Y: 128-255

// Block metadata
SparseDataStorage *lowerData;        // Y: 0-127
SparseDataStorage *upperData;        // Y: 128-255

// Lighting data
SparseLightStorage *lowerSkyLight;   // Y: 0-127
SparseLightStorage *upperSkyLight;   // Y: 128-255
SparseLightStorage *lowerBlockLight; // Y: 0-127
SparseLightStorage *upperBlockLight; // Y: 128-255

Constructor

LevelChunk(Level* level, int x, int z)

constructor

Creates a new empty chunk.Parameters:

level - Parent world
x, z - Chunk coordinates (not block coordinates)

LevelChunk(Level* level, byteArray blocks, int x, int z)

constructor

Creates a chunk with pre-existing block data.Parameters:

blocks - Block data array (65536 bytes)

Block Access

getTile(int x, int y, int z)

int

Gets block ID at local chunk coordinates.Parameters:

x, z - Local coordinates (0-15)
y - Height coordinate (0-255)

Returns: Block/tile ID

setTile(int x, int y, int z, int tile)

bool

Sets block at local chunk coordinates.Returns: true if block was changed

getData(int x, int y, int z)

int

Gets block metadata at local coordinates.Returns: Metadata value (0-15)

setTileAndData(int x, int y, int z, int tile, int data)

bool

Sets both block and metadata.Parameters:

tile - Block ID
data - Metadata (0-15)

setData(int x, int y, int z, int val, int mask, bool* maskedBitsChanged)

bool

Sets block metadata with optional masking.Parameters:

val - New metadata value
mask - Bit mask for partial updates
maskedBitsChanged - Output: were masked bits actually changed?

Bulk Data Operations

setBlockData(byteArray data)

void

Sets all block data from a 32768-byte array.Format: Raw block IDs for entire 16×256×16 chunk

getBlockData(byteArray data)

void

Copies all block data into a 32768-byte array.

setDataData(byteArray data)

void

Sets all metadata from a 16384-byte array.

getDataData(byteArray data)

void

Copies all metadata into a 16384-byte array.

Lighting

getBrightness(LightLayer::variety layer, int x, int y, int z)

int

Gets light level at local coordinates.Parameters:

layer - LightLayer::Sky or LightLayer::Block

Returns: Light level (0-15)

setBrightness(LightLayer::variety layer, int x, int y, int z, int brightness)

void

Sets light level at local coordinates.

getSkyLightData(byteArray data)

void

Exports sky light data to 16384-byte array.

setSkyLightData(byteArray data)

void

Imports sky light data from 16384-byte array.

getBlockLightData(byteArray data)

void

Exports block light data to 16384-byte array.

setBlockLightData(byteArray data)

void

Imports block light data from 16384-byte array.

setSkyLightDataAllBright()

void

Sets all sky light to maximum (15).Use case: Initial chunk generation in overworld

recalcHeightmap()

void

Recalculates the heightmap array.Scans from top down to find highest non-air block in each column.

recalcBlockLights()

void

Recalculates all block (emissive) lighting in the chunk.

recheckGaps(bool force)

void

Rechecks and fixes lighting gaps.Parameters:

force - Force recheck even if gaps were already checked

Height & Terrain

getHeightmap(int x, int z)

int

Gets the Y coordinate of the highest non-air block.Parameters:

x, z - Local coordinates (0-15)

Returns: Y coordinate (0-255)

getTopRainBlock(int x, int z)

int

Gets Y coordinate where rain/snow would land.Returns: Y coordinate of topmost solid block

isEmpty()

bool

Checks if chunk is completely empty (all air).

isYSpaceEmpty(int y1, int y2)

bool

Checks if a vertical range is completely empty.Parameters:

y1, y2 - Y range to check

isRenderChunkEmpty(int y)

bool

Checks if a 16-block vertical section is empty.Parameters:

y - Section Y coordinate (0-15)

Use case: Render optimization - skip empty sections

Entity Management

addEntity(shared_ptr<Entity> e)

void

Adds an entity to this chunk’s entity list.Entities are organized into a grid for efficient spatial queries.

removeEntity(shared_ptr<Entity> e)

void

Removes an entity from this chunk.

removeEntity(shared_ptr<Entity> e, int yc)

void

Removes an entity from a specific Y section.Parameters:

yc - Y section index (0-15)

getEntities(shared_ptr<Entity> except, AABB* bb, vector<shared_ptr<Entity>>& es)

void

Adds entities within bounding box to output vector.Parameters:

except - Entity to exclude
bb - Bounding box in world coordinates
es - Output vector (entities appended)

getEntitiesOfClass(const type_info& ec, AABB* bb, vector<shared_ptr<Entity>>& es)

void

Adds entities of specific type within bounding box.

countEntities()

int

Gets total entity count in this chunk.

Tile Entities

getTileEntity(int x, int y, int z)

shared_ptr<TileEntity>

Gets the tile entity at local coordinates.Returns: Tile entity or null if none exists

setTileEntity(int x, int y, int z, shared_ptr<TileEntity> te)

void

Places a tile entity at local coordinates.

addTileEntity(shared_ptr<TileEntity> te)

void

Adds a tile entity to the chunk.

removeTileEntity(int x, int y, int z)

void

Removes the tile entity at local coordinates.

Biomes

getBiome(int x, int z, BiomeSource* biomeSource)

Biome*

Gets biome at local coordinates.Parameters:

x, z - Local coordinates (0-15)
biomeSource - Biome generator

getBiomes()

byteArray

Gets the 16×16 biome array.

setBiomes(byteArray biomes)

void

Sets the biome array.

Loading & Saving

load()

void

Marks chunk as loaded and initializes data structures.

unload(bool unloadTileEntities)

void

Unloads chunk and optionally removes tile entities.

shouldSave(bool force)

bool

Checks if chunk needs saving.Parameters:

force - Force save even if not modified

markUnsaved()

void

Marks chunk as modified and needing save.

setUnsaved(bool unsaved)

void

Sets the unsaved flag.

Compression & Memory

attemptCompression()

void

Attempts to compress block, data, and light storage.Use case: Memory optimization - called periodically on unused chunks

compressBlocks()

void

Compresses block storage.

compressData()

void

Compresses metadata storage.

compressLighting()

void

Compresses lighting data.

ChunkSource Class

Abstract interface for chunk loading and generation. Header: Minecraft.World/ChunkSource.h

Constants

// World size limits
#define LEVEL_MAX_WIDTH 320      // Large worlds: 5*64 chunks
#define LEVEL_MIN_WIDTH 54       // Classic size

#define HELL_LEVEL_MAX_SCALE 8   // Nether coordinate scale
#define END_LEVEL_MAX_WIDTH 18   // End dimension size

Methods

hasChunk(int x, int z)

bool

Checks if a chunk exists or can be generated.

getChunk(int x, int z)

LevelChunk*

Gets a chunk, loading or generating if needed.

create(int x, int z)

LevelChunk*

Generates a new chunk at the specified coordinates.

postProcess(ChunkSource* parent, int x, int z)

void

Runs terrain decoration/population on a chunk.Examples: Tree placement, ore generation, structure spawning

save(bool force, ProgressListener* progressListener)

bool

Saves all modified chunks.

Example Usage

Accessing Chunk Data

// Get chunk for block position
int chunkX = blockX >> 4;  // Divide by 16
int chunkZ = blockZ >> 4;
LevelChunk* chunk = level->getChunk(chunkX, chunkZ);

// Convert to local coordinates
int localX = blockX & 15;  // Modulo 16
int localZ = blockZ & 15;

// Access block
int blockId = chunk->getTile(localX, blockY, localZ);
int blockData = chunk->getData(localX, blockY, localZ);

Bulk Block Placement

LevelChunk* chunk = level->getChunk(chunkX, chunkZ);

// Fill a layer with stone
for (int x = 0; x < 16; x++) {
    for (int z = 0; z < 16; z++) {
        chunk->setTile(x, 64, z, Tile::STONE);
    }
}

chunk->markUnsaved();
chunk->recalcHeightmap();

Checking Chunk Population

bool isFullyPopulated = 
    (chunk->terrainPopulated & LevelChunk::sTerrainPopulatedAllAffecting) != 0;

bool isPostProcessed = 
    (chunk->terrainPopulated & LevelChunk::sTerrainPostPostProcessed) != 0;

Client

World

Rendering

Networking

Overview

Class Hierarchy

LevelChunk Class

Constants

Core Members

Internal Storage

Constructor

Block Access

Bulk Data Operations

Lighting

Height & Terrain

Entity Management

Tile Entities

Biomes

Loading & Saving

Compression & Memory

ChunkSource Class

Constants

Methods

Example Usage

Accessing Chunk Data

Bulk Block Placement

Checking Chunk Population

See Also

Build docs developers (and LLMs) love

Client

World

Rendering

Networking

​Overview

​Class Hierarchy

​LevelChunk Class

​Constants

​Core Members

​Internal Storage

​Constructor

​Block Access

​Bulk Data Operations

​Lighting

​Height & Terrain

​Entity Management

​Tile Entities

​Biomes

​Loading & Saving

​Compression & Memory

​ChunkSource Class

​Constants

​Methods

​Example Usage

​Accessing Chunk Data

​Bulk Block Placement

​Checking Chunk Population

​See Also

Build docs developers (and LLMs) love

Overview

Class Hierarchy

LevelChunk Class

Constants

Core Members

Internal Storage

Constructor

Block Access

Bulk Data Operations

Lighting

Height & Terrain

Entity Management

Tile Entities

Biomes

Loading & Saving

Compression & Memory

ChunkSource Class

Constants

Methods

Example Usage

Accessing Chunk Data

Bulk Block Placement

Checking Chunk Population

See Also