World Management

Level architecture, chunk management, and world persistence

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

Related Systems

• Game Loop - Level updates within the tick cycle
• Entity System - Entities exist within chunks
• Multiplayer - Chunk synchronization over network

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