System Architecture

​

Workspace Structure

[workspace]
members = [
    "pumpkin-api-macros",
    "pumpkin-config",
    "pumpkin-util",
    "pumpkin-inventory",
    "pumpkin-macros/",
    "pumpkin-protocol/",
    "pumpkin-world",
    "pumpkin/",
    "pumpkin-data",
]

​

Core Modules

​

pumpkin (Main Server)

• Server Management: Core server initialization and lifecycle management
• Network Handling: Player connection and protocol handling
• Game Logic: Block interactions, entity management, commands
• Plugin System: Dynamic plugin loading via libloading

• block/ - Block behavior implementations
• entity/ - Entity logic and AI
• command/ - Command implementations
• net/ - Network layer
• world/ - World management layer
• server/ - Server core

​

pumpkin-protocol

• Packet Serialization/Deserialization: Reading and writing Minecraft packets
• Encryption: AES/CFB8 encryption for secure connections
• Compression: Zlib compression for packet optimization
• Multi-version Support: Both Java and Bedrock editions

[features]
default = ["query"]
serverbound = []
clientbound = []
query = []

​

pumpkin-world

• Chunk Loading: Asynchronous chunk loading from disk
• Chunk Generation: Vanilla-compatible world generation
• Chunk Caching: In-memory chunk storage with DashMap
• Lighting Engine: Dynamic lighting calculations
• Multi-format Support: Anvil and Linear chunk formats

• Efficient chunk I/O with file caching
• Parallel chunk generation
• Chunk saving and autosave functionality
• Entity chunk data management

​

pumpkin-data

• Block States: All block state definitions
• Item Registry: Item IDs and properties
• Biome Data: Biome definitions and properties
• Entity Types: Entity type registry
• Dimension Data: Dimension configurations
• Game Rules: Minecraft game rule definitions

[features]
default = [
    "item", "packet", "translation", "registry",
    "particle", "sound", "recipes", "entity",
    "dimension", "enchantment", "world", ...
]

​

pumpkin-config

• TOML Parsing: Server configuration in TOML format
• Validation: Configuration validation on load
• Runtime Helpers: Optional test helpers for config manipulation

​

pumpkin-inventory

• Player Inventories: Player inventory handling
• Container GUIs: Chest, furnace, and other container interfaces
• Item Stack Operations: Item manipulation and validation

​

pumpkin-util

• Math Types: Vector2, Vector3, BlockPos, etc.
• Text Components: Rich text formatting
• Crypto Utilities: Encryption and hashing helpers
• NBT Helpers: Named Binary Tag utilities

​

pumpkin-macros

• Derive Macros: Custom derives for common patterns
• Block/Tag Helpers: Compile-time block and tag validation

​

pumpkin-api-macros

​

Concurrency Architecture

​

Tokio + Rayon Pattern

​

Tokio Runtime (Async I/O)

• Network I/O (player connections)
• File I/O (chunk loading/saving)
• Timers and scheduled tasks
• Async coordination

#[tokio::main]
async fn main() {
    // Multi-threaded runtime
    tokio = { features = [
        "rt-multi-thread",
        "net",
        "fs",
        "sync",
        "macros",
        "time",
    ]}
}

​

Rayon (CPU-Intensive Tasks)

• Parallel chunk generation
• World generation computations
• Data processing

​

Communication Between Runtimes

// Example from pumpkin_world::level::Level::fetch_chunks
let (send, mut recv) = mpsc::channel::<LoadedData>(1);

// Rayon computation sends results through channel
let computation = async move {
    // CPU-intensive work happens here
    send.send(result).await
};

// Tokio receives results asynchronously
while let Some(data) = recv.recv().await {
    // Process data on Tokio runtime
}

​

Synchronization Primitives

• DashMap: Concurrent hashmap for chunk storage
• Arc: Shared ownership for immutable data
• AtomicBool/AtomicU64: Lock-free atomic operations
• Mutex: For mutable state that needs exclusive access
• TaskTracker: Track and manage async tasks
• CancellationToken: Graceful shutdown coordination

​

Data Flow

​

Player Connection Flow

1. Connection → pumpkin/net receives TCP connection
2. Handshake → pumpkin-protocol handles protocol negotiation
3. Authentication → Validates player with Mojang API
4. Join Game → pumpkin/server initializes player state
5. Chunk Loading → pumpkin-world loads/generates chunks
6. Game Loop → pumpkin processes player actions

​

Chunk Loading Flow

1. Request → Player movement triggers chunk load
2. Cache Check → Check loaded_chunks DashMap
3. Disk Load → pumpkin-world async loads from disk
4. Generation → If not exists, generate with world generator
5. Lighting → Calculate lighting for chunk
6. Send → pumpkin-protocol serializes and sends to client

​

Packet Processing Flow

1. Receive → TCP stream receives encrypted/compressed data
2. Decrypt → pumpkin-protocol decrypts if encryption enabled
3. Decompress → Decompress if compression enabled
4. Deserialize → Parse into packet struct
5. Handle → pumpkin processes packet logic
6. Response → Send response packets back to client

​

Performance Considerations

​

Compilation Profiles

[profile.release]
lto = true              # Link-time optimization
strip = "debuginfo"     # Remove debug symbols
codegen-units = 1       # Better optimization

[profile.profiling]
inherits = "release"
debug = true           # Keep debug info for profiling
strip = false

​

Clippy Configuration

[workspace.lints.clippy]
all = { level = "deny", priority = -1 }
nursery = { level = "deny", priority = -1 }
pedantic = { level = "deny", priority = -1 }
cargo = { level = "deny", priority = -1 }

​

Module Dependencies

​

Next Steps

• Building from Source - Set up your development environment
• Contributing Guidelines - Learn how to contribute to Pumpkin