Contributor Documentation
Welcome to the internal contributor and developer documentation for Pumpkin!
Pumpkin is an ultra-high-performance, extensible Minecraft server software written entirely in modern Rust. Designed from the ground up for concurrency, memory safety, and vanilla fidelity, Pumpkin supports both Minecraft: Java Edition and Minecraft: Bedrock Edition.
This section provides comprehensive documentation for contributors working on the core Pumpkin server, its internal crates, and supporting tooling.
Core Philosophy & Design Principles
Pumpkin is built on several foundational engineering principles:
- Zero-Cost Abstractions & Raw Performance: We leverage Rust's zero-cost abstractions, efficient memory layouts, and cache-friendly data structures to minimize CPU and RAM overhead.
- Strict Concurrency Model:
- Asynchronous I/O via Tokio: Network socket handling, client handshakes, packets streaming, and file I/O run efficiently on an asynchronous runtime.
- Parallel Compute via Rayon: Heavy, CPU-bound computations—such as terrain generation, lighting calculations, chunk serialization, and physics—are dispatched to Rayon thread pools to prevent blocking the async network loop.
- Thread-safe Communication: Non-blocking channels (
tokio::sync::mpsc, crossbeam) coordinate work seamlessly between async tasks and thread pools.
- Robust Quality & Panic Freedom: Pumpkin enforces strict Clippy rules. In production server code, panics,
unwrap(),expect(), and unhandled errors are denied at compile time. - Modular Workspace Architecture: Functionality is divided cleanly into focused crates (
pumpkin-protocol,pumpkin-world,pumpkin-inventory,pumpkin-command,pumpkin-data, etc.). Each crate has specific responsibilities and clear dependency boundaries. - Protocol Fidelity: We strive for strict vanilla compatibility while providing modern features like Linear region format support, Bedrock cross-play, and a polyglot WebAssembly plugin runtime.
Documentation Roadmap
Explore the contributor documentation to understand how Pumpkin works and how to contribute effectively:
| Section | Description |
|---|---|
| Contributing Guide | Step-by-step instructions for environment setup, building, testing, clippy rules, and PR standards. |
| Architecture & Crates | Deep dive into Pumpkin's multi-crate workspace structure, crate responsibilities, and data flow. |
| Data Extractor | Extracting hardcoded vanilla Minecraft registries, bounding boxes, and packet structures via our Fabric mod. |
| Networking Overview | Core networking architecture, transports, and multi-edition support. |
| Java Edition Networking | Protocol states, adding packets, and authentication. |
| Bedrock Edition Networking | RakNet/NetherNet transport, adding packets, authentication, and NetherNet. |
| Proxy Forwarding | Secure player info forwarding for BungeeCord, Velocity, and Vine. |
| Query Protocol | GameSpy4 UDP query implementation for external monitoring bots and server lists. |
| Blocks | Block architecture, states, collisions, properties, and adding block behaviors. |
| Items | Item architecture, data components, food, cooldowns, and adding item behaviors. |
| Entities & Mobs | Entity trait hierarchy, spawning & tracking, and mob AI & pathfinding. |
| Commands | Pure-Rust Brigadier command tree, adding commands, arguments & suggestions, and execution context. |
| Plugin Engine | Internal plugin engine architecture, adding plugin loaders, and WASM signing & licensing. |
| World Engine & Formats | Chunk loading, saving, Anvil/Linear/Slime/Pump formats, terrain generation, and lighting. |
| Code Generation | How tools/pumpkin-codegen processes vanilla Minecraft data to generate pumpkin-data. |
| Porting Minecraft Versions | End-to-end guide to upgrading Pumpkin: data extraction, assets & datapacks, codegen, compiler fixes, new block/item/entity logic, and ViaVersion remapping. |
| Mobile Development | Developing and compiling Pumpkin on mobile environments like Android (Termux). |
Plugin Development vs. Core Development
NOTE
If you are looking to build third-party plugins that extend Pumpkin rather than contributing to the server itself, please check out the dedicated Plugin Development section.
Pumpkin supports writing plugins in Rust, Python, C#, C, Go, and Kotlin powered by our WebAssembly (Wasmtime) runtime and WIT interfaces.