World Engine & Formats

The world engine is managed primarily within the pumpkin-world crate. It handles world storage formats, chunk reading and writing, terrain generation, lighting calculations, and block ticking.

---

Supported World Formats

Pumpkin is designed to support multiple region and world formats, giving server administrators flexibility between vanilla compatibility and modern high-performance compression.

1. Anvil File Format (.mca)

The Anvil format is the standard format used by vanilla Minecraft: Java Edition.

• Structure: Chunks are grouped into 32×32 chunk regions stored in .mca files (r.{x}.{z}.mca).
• Data Layers: Each chunk contains block state palettes, biome palettes, heightmaps, tile entities, and light arrays.
• Compression: Individual chunks within the region file are compressed using ZLib or LZ4.
• Support: Pumpkin supports both loading and saving Anvil region files.

2. Linear Region Format (.linear)

Linear is a modern alternative to Anvil that drastically reduces world save sizes and speeds up disk I/O by utilizing Zstandard (zstd) compression across the entire region rather than per-chunk zlib blocks.

• Savings: Reduces disk usage by ~50% in the Overworld and Nether, and up to ~95% in the End.
• Performance: High decompression speeds and reduced disk writes make it ideal for high-throughput production servers.
• Support: Native read/write support is built into pumpkin-world.

3. Slime World Format (.slime)

Originally developed by Hypixel, the Slime format packages entire worlds into a single, compact, easily duplicable binary file. It is optimized for minigames and temporary instance-based worlds.

4. Pump Format

Pumpkin's native chunk storage format designed specifically for rapid serialization without the legacy overhead of the Anvil format.

---

The world engine organizes chunk management and ticking into hierarchical layers:

Hierarchy

1. World: Manages dimensions (overworld, the_nether, the_end), coordinates players within that dimension, and broadcasts updates.
2. Level: The core data structure holding chunk tables, height bounds (-64 to 320 for vanilla 1.18+ worlds), block registries, and tick schedulers.
3. Chunker: Manages view distances and player subscriptions. Uses CylindricalChunkIterator to compute which chunks to stream to players as they move.

Asynchronous Chunk Pipeline

To maintain steady 20 TPS tick rates:

• Chunks requested by players are checked in the memory cache.
• Uncached chunks are loaded from disk or generated via Rayon background tasks without stalling the main game tick loop.
• Completed chunks are dispatched through asynchronous channels to the player's connection stream.

---

World Generation Pipeline

When a world does not yet have saved chunks, or when players explore past generated boundaries, Pumpkin generates new chunks through a 6-stage pipeline:

1. Noise Routers: Multi-octave 3D Perlin and Simplex noise algorithms compute continentalness, erosion, and peaks/valleys.
2. Density Shaping: Transforms continuous 3D noise values into terrain density and solid vs. air voxel thresholds.
3. Biome Climate Mapping: Samples temperature, humidity, continentalness, and erosion to assign biome IDs.
4. Surface Rules: Evaluates layered rules to place grass, dirt, sand, sandstone, or deepslate depending on exposure and altitude.
5. Carvers: Carves 3D cave tunnels, ravines, and aquifers into solid rock.
6. Features & Decoration: Places ore veins, vegetation, trees, structures, and surface foliage.

1. Noise Routers & Density Functions

Pumpkin implements Minecraft's multi-octave 3D Perlin and Simplex noise algorithms:

• Calculates continentalness, erosion, peaks & valleys, and 3D density.
• Generates natural terrain shapes including overhangs, floating islands, mountains, and deep caves.

2. Biome Climate Parameters

Biomes are resolved dynamically based on multi-dimensional climate coordinates:

• Temperature
• Humidity
• Continentalness
• Erosion
• Depth
• Weirdness

The parameters match vanilla Minecraft biome palettes and generate smooth biome transitions.

3. Generators

• Vanilla-like Terrain Generator: Full 3D noise generation matching modern Minecraft world limits (Y = -64 to Y = 320).
• Superflat Generator: Configurable flat layers (e.g., Bedrock at Y=-64, Dirt, Grass Block top layer).

---

Lighting & Ticking

1. Lighting Engine

• Block Light: Propagated dynamically from light-emitting blocks (torches, glowstone, lava) up to level 15.
• Sky Light: Propagated vertically from the sky down through transparent and semi-transparent blocks (leaves, water).
• Light arrays are computed and serialized into clientbound chunk packets so clients render accurate shadows.

2. Block & Chunk Ticking

• Scheduled Ticks: Blocks requesting delayed execution (water flow, falling sand, redstone repeaters).
• Random Ticks: Random blocks selected per sub-chunk each tick to simulate plant growth, ice melting, and crop maturation.