Skip to main content

​
Overview

Minecraft Community Edition uses a sophisticated world management system with multiple level types, chunk-based terrain, and support for multiple dimensions (Overworld, Nether, End).

​
Level Architecture

​
Base Level Class

The Level class provides core world functionality: 
class Level {
public:
    Dimension* dimension;
    ChunkSource* chunkSource;
    LevelData* levelData;
    shared_ptr<LevelStorage> levelStorage;
    
    bool isClientSide;
    int difficulty;
    static const int maxBuildHeight = 128;
    static const int minBuildHeight = 0;
};
Location: Level.cpp:561

​
Level Types

ServerLevel - Authoritative server-side world:
  • Handles entity logic and physics
  • Processes chunk generation
  • Manages world persistence
  • Runs AI and pathfinding
MultiPlayerLevel - Client-side world representation:
  • Receives updates from server
  • Handles client-side prediction
  • Manages local rendering
  • Caches server-sent data
Location: MultiPlayerLevel.cpp:26

​
Chunk Management

​
Chunk Structure

Chunks are 16×128×16 blocks: 
class LevelChunk {
public:
    int x, z;                    // Chunk coordinates
    byte* tiles;                 // Block IDs
    NibbleArray* data;          // Block metadata
    NibbleArray* skyLight;      // Sky light levels
    NibbleArray* blockLight;    // Block light levels
    int* heightmap;             // Height map
};
Key Features:
  • 16×16 horizontal grid
  • 128 blocks vertical height
  • Separate lighting for sky and blocks
  • Height map for fast sky visibility checks

​
Chunk Loading

LevelChunk* Level::getChunk(int x, int z) {
    return this->chunkSource->getChunk(x, z);
}

bool Level::hasChunk(int x, int z) {
    return this->chunkSource->hasChunk(x, z);
}
Location: Level.cpp:850-871

​
Chunk Sources

ServerChunkCache - Generates and loads chunks server-side: 
class ServerChunkCache : public ChunkSource {
    ChunkStorage* storage;
    ChunkSource* generator;
    map<int, LevelChunk*> chunks;
};
MultiPlayerChunkCache - Receives chunks from network: 
class MultiPlayerChunkCache : public ChunkSource {
    MultiPlayerLevel* level;
    LevelChunk* emptyChunk;
    map<int, LevelChunk*> chunkMap;
};
Location: MultiPlayerLevel.cpp:342

​
Dimension Support

​
Dimension System

Three dimensions with unique properties: 
Dimension* Dimension::getNew(int id) {
    switch(id) {
        case 0:  return new NormalDimension();     // Overworld
        case -1: return new HellDimension();       // Nether
        case 1:  return new TheEndDimension();     // The End
    }
}

​
Dimension Properties

Overworld (id = 0):
  • Full day/night cycle
  • Weather (rain, thunder)
  • Sky lighting
  • 256 block build height
Nether (id = -1):
  • No day/night cycle
  • Ceiling bedrock at Y=127
  • No weather
  • Different lighting
  • 8:1 coordinate scaling
The End (id = 1):
  • Void dimension
  • Fixed dark sky
  • No weather
  • Floating islands
Location: Level storage initializes dimensions in Level.cpp:654-666

​
Server Level Array

ServerLevelArray levels = ServerLevelArray(3);

for (int i = 0; i < 3; i++) {
    int dimension = (i == 1) ? -1 : (i == 2) ? 1 : 0;
    
    if (i == 0) {
        levels[i] = new ServerLevel(...);
    } else {
        levels[i] = new DerivedServerLevel(...);
    }
}
Location: MinecraftServer.cpp:449-476

​
World Generation

​
Spawn Area Generation

On world creation, the server pre-generates a spawn area: 
int r = 196;  // Radius in blocks

Pos* spawnPos = level->getSharedSpawnPos();

for (int x = -r; x <= r; x += 16) {
    for (int z = -r; z <= r; z += 16) {
        level->cache->create(
            (spawnPos->x + x) >> 4, 
            (spawnPos->z + z) >> 4,
            true  // Enable post-processing
        );
    }
}
Location: MinecraftServer.cpp:595-630

​
Post-Processing Thread

World generation uses a separate thread for expensive operations: 
m_postUpdateThread = new C4JThread(
    runPostUpdate, 
    this, 
    "Post processing",
    256*1024  // Stack size
);

m_postUpdateThread->SetProcessor(CPU_CORE_POST_PROCESSING);
m_postUpdateThread->SetPriority(THREAD_PRIORITY_ABOVE_NORMAL);
Post-Processing Tasks:
  • Light propagation
  • Structure generation (villages, strongholds)
  • Biome blending
  • Cave carving
Location: MinecraftServer.cpp:514-519

​
Save System

​
Level Data

class LevelData {
public:
    long seed;                  // World seed
    long time;                  // World time
    Pos spawnPos;              // Spawn location
    bool raining;              // Weather state
    int rainTime;
    bool thundering;
    int thunderTime;
    GameType gameType;         // Survival/Creative
    bool hardcore;
    bool mapFeatures;          // Structures enabled
};

​
Save Process

void MinecraftServer::saveAllChunks() {
    for (int i = 0; i < levels.length; i++) {
        ServerLevel* level = levels[levels.length - 1 - i];
        
        level->save(true, progressRenderer);
        
        if (i == levels.length - 1) {
            level->closeLevelStorage();
        }
    }
}
Save Order: Saves in reverse order (Nether, End, then Overworld) to ensure leveldata consistency. Location: MinecraftServer.cpp:753-778

​
Storage Formats

ConsoleSaveFileOriginal - Original format:
  • Single monolithic file
  • All chunks in one file
  • Used on older platforms
ConsoleSaveFileSplit - Split format:
  • Separate files per chunk region
  • Better performance on modern hardware
  • Enables parallel I/O
Location: MinecraftServer.cpp:400-445

​
Chunk Compression

The game implements compression for memory efficiency: 
void LevelChunk::compressLighting() {
    // Compress sky and block light
}

void LevelChunk::compressBlocks() {
    // Compress block data
}

void LevelChunk::compressData() {
    // Compress metadata
}
Compression Strategy:
  • Run-length encoding for uniform regions
  • Sparse storage for mostly empty chunks
  • Reduces memory by 50-70% in typical worlds
Location: MultiPlayerLevel.cpp:201-209

​
World Boundaries

The world has defined limits: 
static const int MAX_LEVEL_SIZE = dimension->getXZSize() * 16 / 2;

if (x < -MAX_LEVEL_SIZE || x >= MAX_LEVEL_SIZE) {
    return 0;  // Out of bounds
}
if (z < -MAX_LEVEL_SIZE || z >= MAX_LEVEL_SIZE) {
    return 0;  // Out of bounds
}
Default Sizes:
  • Overworld: 864×864 blocks (±432 from origin)
  • Nether: 864×864 blocks
  • The End: 864×864 blocks
Location: Level.cpp:749-752

​
Lighting System

Dual lighting system with optimization:

​
Sky Light

  • Propagates from sky downward
  • Affected by transparent blocks
  • Day/night cycle modulates intensity
  • Cached for performance

​
Block Light

  • Emitted by light sources (torches, lava, glowstone)
  • Fixed intensity regardless of time
  • Propagates in all directions
  • 16 light levels (0-15)

​
Lighting Cache

void Level::initCache(lightCache_t* cache) {
    cachewritten = false;
    if (cache == NULL) return;
    XMemSet128(cache, 0, 16*16*16*sizeof(lightCache_t));
}

void Level::flushCache(lightCache_t* cache, __uint64 cacheUse, 
                       LightLayer::variety layer) {
    // Write cached lighting updates
}
Location: Level.cpp:106-456

​
Level Ticking

The server updates levels at 20 TPS: 
for (int i = 0; i < levels.length; i++) {
    ServerLevel* level = levels[i];
    
    level->difficulty = options->difficulty;
    level->setSpawnSettings(difficulty > 0, animals);
    
    if (tickCount % 20 == 0) {
        // Broadcast time update
        players->broadcastAll(
            new SetTimePacket(level->getTime())
        );
    }
    
    level->tick();       // Physics, entities
    level->tickPending(); // Scheduled updates
}
Location: MinecraftServer.cpp:1462-1488

​
Chunk Visibility

The client tracks which chunks are visible: 
void MultiPlayerLevel::setChunkVisible(int x, int z, bool visible) {
    if (visible) {
        chunkCache->create(x, z);
    } else {
        chunkCache->drop(x, z);
        setTilesDirty(x*16, 0, z*16, x*16+15, maxBuildHeight, z*16+15);
    }
}
Location: MultiPlayerLevel.cpp:389-403

​
Key Takeaways

  1. Chunk-Based: World divided into 16×128×16 chunk units
  2. Multiple Dimensions: Three worlds with unique properties
  3. Dual Storage: Client and server maintain separate level instances
  4. Compression: Memory-efficient storage for chunks
  5. Threading: Post-processing offloaded to background threads
  6. Lighting Cache: Optimized lighting updates for performance

Build docs developers (and LLMs) love

Get started for freeTalk to us